1# JSON-RPC {#jsonrpc} 2 3## Overview {#jsonrpc_overview} 4 5SPDK implements a [JSON-RPC 2.0](http://www.jsonrpc.org/specification) server 6to allow external management tools to dynamically configure SPDK components. 7 8## Parameters 9 10Most of the commands can take parameters. If present, parameter is validated against its domain. If this check fail 11whole command will fail with response error message [Invalid params](@ref jsonrpc_error_message). 12 13### Required parameters 14 15These parameters are mandatory. If any required parameter is missing RPC command will fail with proper error response. 16 17### Optional parameters 18 19Those parameters might be omitted. If an optional parameter is present it must be valid otherwise command will fail 20proper error response. 21 22## Error response message {#jsonrpc_error_message} 23 24Each error response will contain proper message. As much as possible the message should indicate what went wrong during 25command processing. 26 27There is ongoing effort to customize this messages but some RPC methods just return "Invalid parameters" as message body 28for any kind of error. 29 30Code | Description 31------ | ----------- 32-1 | Invalid state - given method exists but it is not callable in [current runtime state](@ref rpc_framework_start_init) 33-32600 | Invalid request - not compliant with JSON-RPC 2.0 Specification 34-32601 | Method not found 35-32602 | @ref jsonrpc_invalid_params 36-32603 | Internal error for e.g.: errors like out of memory 37-32700 | @ref jsonrpc_parser_error 38 39### Parser error {#jsonrpc_parser_error} 40 41Encountered some error during parsing request like: 42 43- the JSON object is malformed 44- parameter is too long 45- request is too long 46 47### Invalid params {#jsonrpc_invalid_params} 48 49This type of error is most common one. It mean that there is an error while processing the request like: 50 51- Parameters decoding in RPC method handler failed because required parameter is missing. 52- Unknown parameter present encountered. 53- Parameter type doesn't match expected type e.g.: given number when expected a string. 54- Parameter domain check failed. 55- Request is valid but some other error occurred during processing request. If possible message explains the error reason nature. 56 57## rpc.py {#rpc_py} 58 59SPDK provides a set of Python scripts which can invoke the JSON-RPC methods described in this document. 'rpc.py' in the scripts 60directory is the main script that users will invoke to execute a JSON-RPC method. The scripts/rpc directory contains modules 61that 'rpc.py' imports for definitions of each SPDK library's or module's methods. 62 63Example: 64 65~~~bash 66scripts/rpc.py bdev_nvme_attach_controller -b nvme0 -a 00:02.0 -t pcie 67~~~ 68 69A brief description of each of the RPC methods and optional 'rpc.py' arguments can be viewed with: 70 71~~~bash 72scripts/rpc.py --help 73~~~ 74 75A detailed description of each RPC method and its parameters is also available. For example: 76 77~~~bash 78scripts/rpc.py bdev_nvme_attach_controller --help 79~~~ 80 81### Generate JSON-RPC methods for current configuration {#jsonrpc_generate} 82 83An initial configuration can be specified for an SPDK application via the '-c' command line parameter. 84The configuration file is a JSON file containing all of the JSON-RPC method invocations necessary 85for the desired configuration. Writing these files by hand is extremely tedious however, so 'rpc.py' 86provides a mechanism to generate a JSON-RPC file based on the current configuration. 87 88~~~bash 89scripts/rpc.py save_config > config.json 90~~~ 91 92'config.json' can then be passed to a new SPDK application using the '-c' command line parameter 93to reproduce the same configuration. 94 95### JSON-RPC batching 96 97'rpc.py' also supports batching of multiple JSON-RPC methods with one invocation. So instead of 98calling 'rpc.py' once for each JSON-RPC method, such as: 99 100~~~bash 101scripts/rpc.py bdev_malloc_create -b malloc0 64 512 102scripts/rpc.py nvmf_create_subsystem nqn.2016-06.io.spdk:cnode1 -a 103scripts/rpc.py nvmf_subsystem_add_ns nqn.2016-06.io.spdk:cnode1 malloc0 104scripts/rpc.py nvmf_create_transport -t tcp 105scripts/rpc.py nvmf_subsystem_add_listener nqn.2016-06.io.spdk:cnode1 -t tcp -a 127.0.0.1 -s 4420 106~~~ 107 108you can put the following into a text file: 109 110~~~bash 111bdev_malloc_create -b malloc0 64 512 112nvmf_create_subsystem nqn.2016-06.io.spdk:cnode1 -a 113nvmf_subsystem_add_ns nqn.2016-06.io.spdk:cnode1 malloc0 114nvmf_create_transport -t tcp 115nvmf_subsystem_add_listener nqn.2016-06.io.spdk:cnode1 -t tcp -a 127.0.0.1 -s 4420 116~~~ 117 118and then just do: 119 120~~~bash 121scripts/rpc.py < rpc.txt 122~~~ 123 124### Adding external RPC methods 125 126SPDK includes both in-tree modules as well as the ability to use external modules. The in-tree modules include some python 127scripts to ease the process of sending RPCs to in-tree modules. External modules can utilize this same framework to add new RPC 128methods as follows: 129 130If PYTHONPATH doesn't include the location of the external RPC python script, it should be updated: 131 132~~~bash 133export PYTHONPATH=/home/user/plugin_example/ 134~~~ 135 136In provided location, create python module file (e.g. rpc_plugin.py) with new RPC methods. The file should contain 137spdk_rpc_plugin_initialize() method that will be called when the plugin is loaded to define new parsers for provided subparsers 138argument that adds new RPC calls (subparsers.add_parser()). The new parsers should use the client.call() method to call RPC 139functions registered within the external module using the SPDK_RPC_REGISTER() macro. Example: 140 141~~~python 142from spdk.rpc.client import print_json 143 144 145def example_create(client, num_blocks, block_size, name=None, uuid=None): 146 """Construct an example block device. 147 148 Args: 149 num_blocks: size of block device in blocks 150 block_size: block size of device; must be a power of 2 and at least 512 151 name: name of block device (optional) 152 uuid: UUID of block device (optional) 153 154 Returns: 155 Name of created block device. 156 """ 157 params = {'num_blocks': num_blocks, 'block_size': block_size} 158 if name: 159 params['name'] = name 160 if uuid: 161 params['uuid'] = uuid 162 return client.call('bdev_example_create', params) 163 164 165def example_delete(client, name): 166 """Delete example block device. 167 168 Args: 169 bdev_name: name of bdev to delete 170 """ 171 params = {'name': name} 172 return client.call('bdev_example_delete', params) 173 174 175def spdk_rpc_plugin_initialize(subparsers): 176 def bdev_example_create(args): 177 num_blocks = (args.total_size * 1024 * 1024) // args.block_size 178 print_json(example_create(args.client, 179 num_blocks=int(num_blocks), 180 block_size=args.block_size, 181 name=args.name, 182 uuid=args.uuid)) 183 184 p = subparsers.add_parser('bdev_example_create', 185 help='Create an example bdev') 186 p.add_argument('-b', '--name', help="Name of the bdev") 187 p.add_argument('-u', '--uuid', help="UUID of the bdev") 188 p.add_argument( 189 'total_size', help='Size of bdev in MB (float > 0)', type=float) 190 p.add_argument('block_size', help='Block size for this bdev', type=int) 191 p.set_defaults(func=bdev_example_create) 192 193 def bdev_example_delete(args): 194 example_delete(args.client, 195 name=args.name) 196 197 p = subparsers.add_parser('bdev_example_delete', 198 help='Delete an example disk') 199 p.add_argument('name', help='example bdev name') 200 p.set_defaults(func=bdev_example_delete) 201~~~ 202 203Finally, call the rpc.py script with '--plugin' parameter to provide above python module name: 204 205~~~bash 206./scripts/rpc.py --plugin rpc_plugin bdev_example_create 10 4096 207~~~ 208 209### Converting from legacy configuration {#jsonrpc_convert} 210 211Starting with SPDK 20.10, legacy configuration file support has been removed. 212Users with extensive configuration files already running in SPDK application, 213can [generate JSON-RPC for current configuration](@ref jsonrpc_generate). 214 215If binary for deploying the application is unavailable, the legacy configuration 216file can be converted to JSON-RPC using python tool: 217 218~~~bash 219./scripts/config_converter.py < config.ini > config.json 220~~~ 221 222## App Framework {#jsonrpc_components_app} 223 224### spdk_kill_instance {#rpc_spdk_kill_instance} 225 226Send a signal to the application. 227 228#### Parameters 229 230Name | Optional | Type | Description 231----------------------- | -------- | ----------- | ----------- 232sig_name | Required | string | Signal to send (SIGINT, SIGTERM, SIGQUIT, SIGHUP, or SIGKILL) 233 234#### Example 235 236Example request: 237 238~~~json 239{ 240 "jsonrpc": "2.0", 241 "id": 1, 242 "method": "spdk_kill_instance", 243 "params": { 244 "sig_name": "SIGINT" 245 } 246} 247~~~ 248 249Example response: 250 251~~~json 252{ 253 "jsonrpc": "2.0", 254 "id": 1, 255 "result": true 256} 257~~~ 258 259### framework_monitor_context_switch {#rpc_framework_monitor_context_switch} 260 261Query, enable, or disable the context switch monitoring functionality. 262 263#### Parameters 264 265Name | Optional | Type | Description 266----------------------- | -------- | ----------- | ----------- 267enabled | Optional | boolean | Enable (`true`) or disable (`false`) monitoring (omit this parameter to query the current state) 268 269#### Response 270 271Name | Type | Description 272----------------------- | ----------- | ----------- 273enabled | boolean | The current state of context switch monitoring 274 275#### Example 276 277Example request: 278 279~~~json 280{ 281 "jsonrpc": "2.0", 282 "id": 1, 283 "method": "framework_monitor_context_switch", 284 "params": { 285 "enabled": false 286 } 287} 288~~~ 289 290Example response: 291 292~~~json 293{ 294 "jsonrpc": "2.0", 295 "id": 1, 296 "result": { 297 "enabled": false 298 } 299} 300~~~ 301 302### framework_start_init {#rpc_framework_start_init} 303 304Start initialization of SPDK subsystems when it is deferred by starting SPDK application with option -w. 305During its deferral some RPCs can be used to set global parameters for SPDK subsystems. 306This RPC can be called only once. 307 308#### Parameters 309 310This method has no parameters. 311 312#### Response 313 314Completion status of SPDK subsystem initialization is returned as a boolean. 315 316#### Example 317 318Example request: 319 320~~~json 321{ 322 "jsonrpc": "2.0", 323 "id": 1, 324 "method": "framework_start_init" 325} 326~~~ 327 328Example response: 329 330~~~json 331{ 332 "jsonrpc": "2.0", 333 "id": 1, 334 "result": true 335} 336~~~ 337 338### framework_wait_init {#rpc_framework_wait_init} 339 340Do not return until all subsystems have been initialized and the RPC system state is running. 341If the application is already running, this call will return immediately. This RPC can be called at any time. 342 343#### Parameters 344 345This method has no parameters. 346 347#### Response 348 349Returns True when subsystems have been initialized. 350 351#### Example 352 353Example request: 354 355~~~json 356{ 357 "jsonrpc": "2.0", 358 "id": 1, 359 "method": "framework_wait_init" 360} 361~~~ 362 363Example response: 364 365~~~json 366{ 367 "jsonrpc": "2.0", 368 "id": 1, 369 "result": true 370} 371~~~ 372 373### rpc_get_methods {#rpc_rpc_get_methods} 374 375Get an array of supported RPC methods. 376 377#### Parameters 378 379Name | Optional | Type | Description 380----------------------- | -------- | ----------- | ----------- 381current | Optional | boolean | Get an array of RPC methods only callable in the current state. 382 383#### Response 384 385The response is an array of supported RPC methods. 386 387#### Example 388 389Example request: 390 391~~~json 392{ 393 "jsonrpc": "2.0", 394 "id": 1, 395 "method": "rpc_get_methods" 396} 397~~~ 398 399Example response: 400 401~~~json 402{ 403 "jsonrpc": "2.0", 404 "id": 1, 405 "result": [ 406 "framework_start_init", 407 "rpc_get_methods", 408 "scsi_get_devices", 409 "nbd_get_disks", 410 "nbd_stop_disk", 411 "nbd_start_disk", 412 "log_get_flags", 413 "log_clear_flag", 414 "log_set_flag", 415 "log_get_level", 416 "log_set_level", 417 "log_get_print_level", 418 "log_set_print_level", 419 "iscsi_get_options", 420 "iscsi_target_node_add_lun", 421 "iscsi_get_connections", 422 "iscsi_delete_portal_group", 423 "iscsi_create_portal_group", 424 "iscsi_get_portal_groups", 425 "iscsi_delete_target_node", 426 "iscsi_target_node_remove_pg_ig_maps", 427 "iscsi_target_node_add_pg_ig_maps", 428 "iscsi_create_target_node", 429 "iscsi_get_target_nodes", 430 "iscsi_delete_initiator_group", 431 "iscsi_initiator_group_remove_initiators", 432 "iscsi_initiator_group_add_initiators", 433 "iscsi_create_initiator_group", 434 "iscsi_get_initiator_groups", 435 "iscsi_set_options", 436 "bdev_set_options", 437 "bdev_set_qos_limit", 438 "bdev_get_bdevs", 439 "bdev_get_iostat", 440 "framework_get_config", 441 "framework_get_subsystems", 442 "framework_monitor_context_switch", 443 "spdk_kill_instance", 444 "accel_set_options", 445 "accel_set_driver", 446 "accel_crypto_key_create", 447 "accel_crypto_key_destroy", 448 "accel_crypto_keys_get", 449 "accel_assign_opc", 450 "accel_get_module_info", 451 "accel_get_opc_assignments", 452 "accel_error_inject_error", 453 "ioat_scan_accel_module", 454 "dsa_scan_accel_module", 455 "dpdk_cryptodev_scan_accel_module", 456 "dpdk_cryptodev_set_driver", 457 "dpdk_cryptodev_get_driver", 458 "mlx5_scan_accel_module", 459 "bdev_virtio_attach_controller", 460 "bdev_virtio_scsi_get_devices", 461 "bdev_virtio_detach_controller", 462 "bdev_virtio_blk_set_hotplug", 463 "bdev_aio_delete", 464 "bdev_aio_create", 465 "bdev_split_delete", 466 "bdev_split_create", 467 "bdev_error_inject_error", 468 "bdev_error_delete", 469 "bdev_error_create", 470 "bdev_passthru_create", 471 "bdev_passthru_delete" 472 "bdev_nvme_apply_firmware", 473 "bdev_nvme_get_transport_statistics", 474 "bdev_nvme_get_controller_health_info", 475 "bdev_nvme_detach_controller", 476 "bdev_nvme_attach_controller", 477 "bdev_null_create", 478 "bdev_malloc_delete", 479 "bdev_malloc_create", 480 "bdev_ftl_delete", 481 "bdev_ftl_unload", 482 "bdev_ftl_create", 483 "bdev_ftl_load", 484 "bdev_ftl_unmap", 485 "bdev_ftl_get_stats", 486 "bdev_ftl_get_properties", 487 "bdev_ftl_set_property", 488 "bdev_lvol_get_lvstores", 489 "bdev_lvol_delete", 490 "bdev_lvol_resize", 491 "bdev_lvol_set_read_only", 492 "bdev_lvol_decouple_parent", 493 "bdev_lvol_inflate", 494 "bdev_lvol_rename", 495 "bdev_lvol_clone", 496 "bdev_lvol_snapshot", 497 "bdev_lvol_create", 498 "bdev_lvol_delete_lvstore", 499 "bdev_lvol_rename_lvstore", 500 "bdev_lvol_create_lvstore", 501 "bdev_lvol_start_shallow_copy", 502 "bdev_lvol_check_shallow_copy", 503 "bdev_lvol_set_parent", 504 "bdev_lvol_set_parent_bdev", 505 "bdev_daos_delete", 506 "bdev_daos_create", 507 "bdev_daos_resize" 508 ] 509} 510~~~ 511 512### framework_get_subsystems {#rpc_framework_get_subsystems} 513 514Get an array of name and dependency relationship of SPDK subsystems in initialization order. 515 516#### Parameters 517 518None 519 520#### Response 521 522The response is an array of name and dependency relationship of SPDK subsystems in initialization order. 523 524#### Example 525 526Example request: 527 528~~~json 529{ 530 "jsonrpc": "2.0", 531 "id": 1, 532 "method": "framework_get_subsystems" 533} 534~~~ 535 536Example response: 537 538~~~json 539{ 540 "jsonrpc": "2.0", 541 "id": 1, 542 "result": [ 543 { 544 "subsystem": "accel", 545 "depends_on": [] 546 }, 547 { 548 "subsystem": "interface", 549 "depends_on": [] 550 }, 551 { 552 "subsystem": "net_framework", 553 "depends_on": [ 554 "interface" 555 ] 556 }, 557 { 558 "subsystem": "bdev", 559 "depends_on": [ 560 "accel" 561 ] 562 }, 563 { 564 "subsystem": "nbd", 565 "depends_on": [ 566 "bdev" 567 ] 568 }, 569 { 570 "subsystem": "nvmf", 571 "depends_on": [ 572 "bdev" 573 ] 574 }, 575 { 576 "subsystem": "scsi", 577 "depends_on": [ 578 "bdev" 579 ] 580 }, 581 { 582 "subsystem": "vhost", 583 "depends_on": [ 584 "scsi" 585 ] 586 }, 587 { 588 "subsystem": "iscsi", 589 "depends_on": [ 590 "scsi" 591 ] 592 } 593 ] 594} 595~~~ 596 597### framework_get_config {#rpc_framework_get_config} 598 599Get current configuration of the specified SPDK framework 600 601#### Parameters 602 603Name | Optional | Type | Description 604----------------------- | -------- | ----------- | ----------- 605name | Required | string | SPDK subsystem name 606 607#### Response 608 609The response is current configuration of the specified SPDK subsystem. 610Null is returned if it is not retrievable by the framework_get_config method and empty array is returned if it is empty. 611 612#### Example 613 614Example request: 615 616~~~json 617{ 618 "jsonrpc": "2.0", 619 "id": 1, 620 "method": "framework_get_config", 621 "params": { 622 "name": "bdev" 623 } 624} 625~~~ 626 627Example response: 628 629~~~json 630{ 631 "jsonrpc": "2.0", 632 "id": 1, 633 "result": [ 634 { 635 "params": { 636 "base_bdev": "Malloc2", 637 "split_size_mb": 0, 638 "split_count": 2 639 }, 640 "method": "bdev_split_create" 641 }, 642 { 643 "params": { 644 "trtype": "PCIe", 645 "name": "Nvme1", 646 "traddr": "0000:01:00.0" 647 }, 648 "method": "bdev_nvme_attach_controller" 649 }, 650 { 651 "params": { 652 "trtype": "PCIe", 653 "name": "Nvme2", 654 "traddr": "0000:03:00.0" 655 }, 656 "method": "bdev_nvme_attach_controller" 657 }, 658 { 659 "params": { 660 "block_size": 512, 661 "num_blocks": 131072, 662 "name": "Malloc0", 663 "uuid": "913fc008-79a7-447f-b2c4-c73543638c31" 664 }, 665 "method": "bdev_malloc_create" 666 }, 667 { 668 "params": { 669 "block_size": 512, 670 "num_blocks": 131072, 671 "name": "Malloc1", 672 "uuid": "dd5b8f6e-b67a-4506-b606-7fff5a859920" 673 }, 674 "method": "bdev_malloc_create" 675 } 676 ] 677} 678~~~ 679 680### framework_get_reactors {#rpc_framework_get_reactors} 681 682Retrieve an array of all reactors. 683 684#### Parameters 685 686This method has no parameters. 687 688#### Response 689 690The response is an array of all reactors. 691 692#### Example 693 694Example request: 695 696~~~json 697{ 698 "jsonrpc": "2.0", 699 "method": "framework_get_reactors", 700 "id": 1 701} 702~~~ 703 704Example response: 705 706~~~json 707{ 708 "jsonrpc": "2.0", 709 "id": 1, 710 "result": { 711 "tick_rate": 2400000000, 712 "pid": 5502, 713 "reactors": [ 714 { 715 "lcore": 0, 716 "tid": 5520, 717 "busy": 41289723495, 718 "idle": 3624832946, 719 "lw_threads": [ 720 { 721 "name": "app_thread", 722 "id", 1, 723 "cpumask": "1", 724 "elapsed": 44910853363 725 } 726 ] 727 } 728 ] 729 } 730} 731~~~ 732 733### framework_set_scheduler {#rpc_framework_set_scheduler} 734 735Select thread scheduler that will be activated. 736This feature is considered as experimental. 737 738#### Parameters 739 740Name | Optional | Type | Description 741----------------------- | -------- | ----------- | ----------- 742name | Required | string | Name of a scheduler 743period | Optional | number | Scheduler period 744load_limit | Optional | number | Thread load limit in % (dynamic only) 745core_limit | Optional | number | Load limit on the core to be considered full (dynamic only) 746core_busy | Optional | number | Indicates at what load on core scheduler should move threads to a different core (dynamic only) 747 748#### Response 749 750Completion status of the operation is returned as a boolean. 751 752#### Example 753 754Example request: 755 756~~~json 757{ 758 "jsonrpc": "2.0", 759 "method": "framework_set_scheduler", 760 "id": 1, 761 "params": { 762 "name": "static", 763 "period": "1000000" 764 } 765} 766~~~ 767 768Example response: 769 770~~~json 771{ 772 "jsonrpc": "2.0", 773 "id": 1, 774 "result": true 775} 776~~~ 777 778### framework_get_scheduler {#rpc_framework_get_scheduler} 779 780Retrieve currently set scheduler name and period, along with current governor name. 781 782#### Parameters 783 784This method has no parameters. 785 786#### Response 787 788Name | Description 789------------------------| ----------- 790scheduler_name | Current scheduler name 791scheduler_period | Currently set scheduler period in microseconds 792governor_name | Governor name 793 794#### Example 795 796Example request: 797 798~~~json 799{ 800 "jsonrpc": "2.0", 801 "method": "framework_set_scheduler", 802 "id": 1, 803} 804~~~ 805 806Example response: 807 808~~~json 809{ 810 "jsonrpc": "2.0", 811 "id": 1, 812 "result": { 813 "scheduler_name": "static", 814 "scheduler_period": 2800000000, 815 "governor_name": "default" 816 } 817} 818~~~ 819 820### framework_enable_cpumask_locks 821 822Enable CPU core lock files to block multiple SPDK applications from running on the same cpumask. 823The CPU core locks are enabled by default, unless user specified `--disable-cpumask-locks` command 824line option when launching SPDK. 825 826This RPC may be called after locks have already been enabled, with no effect and no error response. 827 828#### Parameters 829 830This method has no parameters. 831 832#### Response 833 834true on success 835 836#### Example 837 838Example request: 839 840~~~json 841{ 842 "jsonrpc": "2.0", 843 "id": 1, 844 "method": "framework_enable_cpumask_locks" 845} 846~~~ 847 848Example response: 849 850~~~json 851{ 852 "jsonrpc": "2.0", 853 "id": 1, 854 "result": true 855} 856~~~ 857 858### framework_disable_cpumask_locks 859 860Disable CPU core lock files. The locks can also be disabled during startup, when 861user specifies `--disable-cpumask-locks` command line option during SPDK launch. 862 863This RPC may be called after locks have already been disabled, with no effect and no error 864response. 865 866#### Parameters 867 868This method has no parameters. 869 870#### Response 871 872true on success 873 874#### Example 875 876Example request: 877 878~~~json 879{ 880 "jsonrpc": "2.0", 881 "id": 1, 882 "method": "framework_disable_cpumask_locks" 883} 884~~~ 885 886Example response: 887 888~~~json 889{ 890 "jsonrpc": "2.0", 891 "id": 1, 892 "result": true 893} 894~~~ 895 896### thread_get_stats {#rpc_thread_get_stats} 897 898Retrieve current statistics of all the threads. 899 900#### Parameters 901 902This method has no parameters. 903 904#### Response 905 906The response is an array of objects containing threads statistics. 907 908#### Example 909 910Example request: 911 912~~~json 913{ 914 "jsonrpc": "2.0", 915 "method": "thread_get_stats", 916 "id": 1 917} 918~~~ 919 920Example response: 921 922~~~json 923{ 924 "jsonrpc": "2.0", 925 "id": 1, 926 "result": { 927 "tick_rate": 2400000000, 928 "threads": [ 929 { 930 "name": "app_thread", 931 "id": 1, 932 "cpumask": "1", 933 "busy": 139223208, 934 "idle": 8641080608, 935 "in_interrupt": false, 936 "active_pollers_count": 1, 937 "timed_pollers_count": 2, 938 "paused_pollers_count": 0 939 } 940 ] 941 } 942} 943~~~ 944 945### thread_set_cpumask {#rpc_thread_set_cpumask} 946 947Set the cpumask of the thread to the specified value. The thread may be migrated 948to one of the specified CPUs. 949 950#### Parameters 951 952Name | Optional | Type | Description 953----------------------- | -------- | ----------- | ----------- 954id | Required | string | Thread ID 955cpumask | Required | string | Cpumask for this thread 956 957#### Response 958 959Completion status of the operation is returned as a boolean. 960 961#### Example 962 963Example request: 964 965~~~json 966{ 967 "jsonrpc": "2.0", 968 "method": "thread_set_cpumask", 969 "id": 1, 970 "params": { 971 "id": "1", 972 "cpumask": "1" 973 } 974} 975~~~ 976 977Example response: 978 979~~~json 980{ 981 "jsonrpc": "2.0", 982 "id": 1, 983 "result": true 984} 985~~~ 986 987### trace_enable_tpoint_group {#rpc_trace_enable_tpoint_group} 988 989Enable trace on a specific tpoint group. For example "bdev" for bdev trace group, 990"all" for all trace groups. 991 992#### Parameters 993 994Name | Optional | Type | Description 995----------------------- | -------- | ----------- | ----------- 996name | Required | string | bdev, nvmf_rdma, nvmf_tcp, blobfs, scsi, iscsi_conn, ftl, all 997 998#### Example 999 1000Example request: 1001 1002~~~json 1003{ 1004 "jsonrpc": "2.0", 1005 "method": "trace_enable_tpoint_group", 1006 "id": 1, 1007 "params": { 1008 "name": "bdev" 1009 } 1010} 1011~~~ 1012 1013Example response: 1014 1015~~~json 1016{ 1017 "jsonrpc": "2.0", 1018 "id": 1, 1019 "result": true 1020} 1021~~~ 1022 1023### trace_disable_tpoint_group {#rpc_trace_disable_tpoint_group} 1024 1025Disable trace on a specific tpoint group. For example "bdev" for bdev trace group, 1026"all" for all trace groups. 1027 1028#### Parameters 1029 1030Name | Optional | Type | Description 1031----------------------- | -------- | ----------- | ----------- 1032name | Required | string | bdev, nvmf_rdma, nvmf_tcp, blobfs, all 1033 1034#### Example 1035 1036Example request: 1037 1038~~~json 1039{ 1040 "jsonrpc": "2.0", 1041 "method": "trace_disable_tpoint_group", 1042 "id": 1, 1043 "params": { 1044 "name": "bdev" 1045 } 1046} 1047~~~ 1048 1049Example response: 1050 1051~~~json 1052{ 1053 "jsonrpc": "2.0", 1054 "id": 1, 1055 "result": true 1056} 1057~~~ 1058 1059### trace_set_tpoint_mask {#rpc_trace_set_tpoint_mask} 1060 1061Enable tracepoint mask on a specific tpoint group. For example "bdev" for bdev trace group, 1062and 0x1 to enable the first tracepoint inside the group (BDEV_IO_START). This command will not 1063disable already active tracepoints or those not specified in the mask. For a full description 1064of all available trace groups, see 1065[tracepoint documentation](https://spdk.io/doc/nvmf_tgt_tracepoints.html). 1066 1067#### Parameters 1068 1069Name | Optional | Type | Description 1070----------------------- | -------- | ----------- | ----------- 1071name | Required | string | bdev, nvmf_rdma, nvmf_tcp, blobfs, scsi, iscsi_conn, ftl 1072tpoint_mask | Required | number | mask to enable tracepoints inside a group 1073 1074#### Example 1075 1076Example request: 1077 1078~~~json 1079{ 1080 "jsonrpc": "2.0", 1081 "method": "trace_set_tpoint_mask", 1082 "id": 1, 1083 "params": { 1084 "name": "bdev", 1085 "tpoint_mask": 0x1 1086 } 1087} 1088~~~ 1089 1090Example response: 1091 1092~~~json 1093{ 1094 "jsonrpc": "2.0", 1095 "id": 1, 1096 "result": true 1097} 1098~~~ 1099 1100### trace_clear_tpoint_mask {#rpc_trace_clear_tpoint_mask} 1101 1102Disable tracepoint mask on a specific tpoint group. For example "bdev" for bdev trace group, 1103and 0x1 to disable the first tracepoint inside the group (BDEV_IO_START). For a full description 1104of all available trace groups, see 1105[tracepoint documentation](https://spdk.io/doc/nvmf_tgt_tracepoints.html). 1106 1107#### Parameters 1108 1109Name | Optional | Type | Description 1110----------------------- | -------- | ----------- | ----------- 1111name | Required | string | bdev, nvmf_rdma, nvmf_tcp, blobfs, scsi, iscsi_conn, ftl 1112tpoint_mask | Required | number | mask to diesable tracepoints inside a group 1113 1114#### Example 1115 1116Example request: 1117 1118~~~json 1119{ 1120 "jsonrpc": "2.0", 1121 "method": "trace_clear_tpoint_mask", 1122 "id": 1, 1123 "params": { 1124 "name": "bdev", 1125 "tpoint_mask": 0x1 1126 } 1127} 1128~~~ 1129 1130Example response: 1131 1132~~~json 1133{ 1134 "jsonrpc": "2.0", 1135 "id": 1, 1136 "result": true 1137} 1138~~~ 1139 1140### trace_get_tpoint_group_mask {#rpc_trace_get_tpoint_group_mask} 1141 1142Display mask info for every group. 1143 1144#### Parameters 1145 1146No parameters required 1147 1148#### Example 1149 1150Example request: 1151 1152~~~json 1153{ 1154 "jsonrpc": "2.0", 1155 "method": "trace_get_tpoint_group_mask", 1156 "id": 1 1157} 1158~~~ 1159 1160Example response: 1161 1162~~~json 1163{ 1164 "jsonrpc": "2.0", 1165 "id": 1, 1166 "result": { 1167 "tpoint_group_mask": "0x0", 1168 "iscsi_conn": { 1169 "enabled": false, 1170 "mask": "0x2" 1171 }, 1172 "scsi": { 1173 "enabled": false, 1174 "mask": "0x4" 1175 }, 1176 "bdev": { 1177 "enabled": false, 1178 "mask": "0x8" 1179 }, 1180 "nvmf_tcp": { 1181 "enabled": false, 1182 "mask": "0x20" 1183 }, 1184 "ftl": { 1185 "enabled": false, 1186 "mask": "0x40" 1187 }, 1188 "blobfs": { 1189 "enabled": false, 1190 "mask": "0x80" 1191 } 1192 } 1193} 1194~~~ 1195 1196### trace_get_info {#rpc_trace_get_info} 1197 1198Get name of shared memory file, list of the available trace point groups 1199and mask of the available trace points for each group 1200 1201#### Parameters 1202 1203No parameters required 1204 1205#### Example 1206 1207Example request: 1208 1209~~~json 1210{ 1211 "jsonrpc": "2.0", 1212 "method": "trace_get_info", 1213 "id": 1 1214} 1215~~~ 1216 1217Example response: 1218 1219~~~json 1220{ 1221 "jsonrpc": "2.0", 1222 "id": 1, 1223 "result": { 1224 "tpoint_shm_path": "/dev/shm/spdk_tgt_trace.pid3071944", 1225 "tpoint_group_mask": "0x8", 1226 "iscsi_conn": { 1227 "mask": "0x2", 1228 "tpoint_mask": "0x0" 1229 }, 1230 "scsi": { 1231 "mask": "0x4", 1232 "tpoint_mask": "0x0" 1233 }, 1234 "bdev": { 1235 "mask": "0x8", 1236 "tpoint_mask": "0xffffffffffffffff" 1237 }, 1238 "nvmf_tcp": { 1239 "mask": "0x20", 1240 "tpoint_mask": "0x0" 1241 }, 1242 "blobfs": { 1243 "mask": "0x80", 1244 "tpoint_mask": "0x0" 1245 }, 1246 "thread": { 1247 "mask": "0x400", 1248 "tpoint_mask": "0x0" 1249 }, 1250 "nvme_pcie": { 1251 "mask": "0x800", 1252 "tpoint_mask": "0x0" 1253 }, 1254 "nvme_tcp": { 1255 "mask": "0x2000", 1256 "tpoint_mask": "0x0" 1257 }, 1258 "bdev_nvme": { 1259 "mask": "0x4000", 1260 "tpoint_mask": "0x0" 1261 } 1262 } 1263} 1264~~~ 1265 1266### log_set_print_level {#rpc_log_set_print_level} 1267 1268Set the current level at which output will additionally be 1269sent to the current console. 1270 1271#### Parameters 1272 1273Name | Optional | Type | Description 1274----------------------- | -------- | ----------- | ----------- 1275level | Required | string | ERROR, WARNING, NOTICE, INFO, DEBUG 1276 1277#### Example 1278 1279Example request: 1280 1281~~~json 1282{ 1283 "jsonrpc": "2.0", 1284 "method": "log_set_print_level", 1285 "id": 1, 1286 "params": { 1287 "level": "ERROR" 1288 } 1289} 1290~~~ 1291 1292Example response: 1293 1294~~~json 1295{ 1296 "jsonrpc": "2.0", 1297 "id": 1, 1298 "result": true 1299} 1300~~~ 1301 1302### log_get_print_level {#rpc_log_get_print_level} 1303 1304Get the current level at which output will additionally be 1305sent to the current console. 1306 1307#### Example 1308 1309Example request: 1310 1311~~~json 1312{ 1313 "jsonrpc": "2.0", 1314 "method": "log_get_print_level", 1315 "id": 1, 1316} 1317~~~ 1318 1319Example response: 1320 1321~~~json 1322{ 1323 "jsonrpc": "2.0", 1324 "id": 1, 1325 "result": "NOTICE" 1326} 1327~~~ 1328 1329### log_set_level {#rpc_log_set_level} 1330 1331Set the current logging level output by the `log` module. 1332 1333#### Parameters 1334 1335Name | Optional | Type | Description 1336----------------------- | -------- | ----------- | ----------- 1337level | Required | string | ERROR, WARNING, NOTICE, INFO, DEBUG 1338 1339#### Example 1340 1341Example request: 1342 1343~~~json 1344{ 1345 "jsonrpc": "2.0", 1346 "method": "log_set_level", 1347 "id": 1, 1348 "params": { 1349 "level": "ERROR" 1350 } 1351} 1352~~~ 1353 1354Example response: 1355 1356~~~json 1357{ 1358 "jsonrpc": "2.0", 1359 "id": 1, 1360 "result": true 1361} 1362~~~ 1363 1364### log_get_level {#rpc_log_get_level} 1365 1366Get the current logging level output by the `log` module. 1367 1368#### Example 1369 1370Example request: 1371 1372~~~json 1373{ 1374 "jsonrpc": "2.0", 1375 "method": "log_get_level", 1376 "id": 1, 1377} 1378~~~ 1379 1380Example response: 1381 1382~~~json 1383{ 1384 "jsonrpc": "2.0", 1385 "id": 1, 1386 "result": "NOTICE" 1387} 1388~~~ 1389 1390### log_set_flag {#rpc_log_set_flag} 1391 1392Enable logging for specific portions of the application. The list of possible 1393log flags can be obtained using the `log_get_flags` RPC and may be different 1394for each application. 1395 1396#### Parameters 1397 1398Name | Optional | Type | Description 1399----------------------- | -------- | ----------- | ----------- 1400flag | Required | string | A log flag, or 'all' 1401 1402#### Example 1403 1404Example request: 1405 1406~~~json 1407{ 1408 "jsonrpc": "2.0", 1409 "method": "log_set_flag", 1410 "id": 1, 1411 "params": { 1412 "flag": "all" 1413 } 1414} 1415~~~ 1416 1417Example response: 1418 1419~~~json 1420{ 1421 "jsonrpc": "2.0", 1422 "id": 1, 1423 "result": true 1424} 1425~~~ 1426 1427### log_clear_flag {#rpc_log_clear_flag} 1428 1429Disable logging for specific portions of the application. The list of possible 1430log flags can be obtained using the `log_get_flags` RPC and may be different 1431for each application. 1432 1433#### Parameters 1434 1435Name | Optional | Type | Description 1436----------------------- | -------- | ----------- | ----------- 1437flag | Required | string | A log flag, or 'all' 1438 1439#### Example 1440 1441Example request: 1442 1443~~~json 1444{ 1445 "jsonrpc": "2.0", 1446 "method": "log_clear_flag", 1447 "id": 1, 1448 "params": { 1449 "flag": "all" 1450 } 1451} 1452~~~ 1453 1454Example response: 1455 1456~~~json 1457{ 1458 "jsonrpc": "2.0", 1459 "id": 1, 1460 "result": true 1461} 1462~~~ 1463 1464### log_get_flags {#rpc_log_get_flags} 1465 1466Get the list of valid flags for this application and whether 1467they are currently enabled. 1468 1469#### Example 1470 1471Example request: 1472 1473~~~json 1474{ 1475 "jsonrpc": "2.0", 1476 "method": "log_get_flags", 1477 "id": 1, 1478} 1479~~~ 1480 1481Example response: 1482 1483~~~json 1484{ 1485 "jsonrpc": "2.0", 1486 "id": 1, 1487 "result": { 1488 "nvmf": true, 1489 "nvme": true, 1490 "aio": false, 1491 "bdev" false 1492 } 1493} 1494~~~ 1495 1496### log_enable_timestamps {#rpc_log_enable_timestamps} 1497 1498Enable or disable timestamps. 1499 1500#### Parameters 1501 1502Name | Optional | Type | Description 1503----------------------- | -------- | ----------- | ----------- 1504enabled | Required | boolean | on or off 1505 1506#### Example 1507 1508Example request: 1509 1510~~~json 1511{ 1512 "jsonrpc": "2.0", 1513 "method": "log_enable_timestamps", 1514 "id": 1, 1515 "params": { 1516 "enabled": true 1517 } 1518} 1519~~~ 1520 1521Example response: 1522 1523~~~json 1524{ 1525 "jsonrpc": "2.0", 1526 "id": 1, 1527 "result": true 1528} 1529~~~ 1530 1531### thread_get_pollers {#rpc_thread_get_pollers} 1532 1533Retrieve current pollers of all the threads. 1534 1535#### Parameters 1536 1537This method has no parameters. 1538 1539### Response 1540 1541The response is an array of objects containing pollers of all the threads. 1542 1543#### Example 1544 1545Example request: 1546 1547~~~json 1548{ 1549 "jsonrpc": "2.0", 1550 "method": "thread_get_pollers", 1551 "id": 1 1552} 1553~~~ 1554 1555Example response: 1556 1557~~~json 1558{ 1559 "jsonrpc": "2.0", 1560 "id": 1, 1561 "result": { 1562 "tick_rate": 2500000000, 1563 "threads": [ 1564 { 1565 "name": "app_thread", 1566 "id": 1, 1567 "active_pollers": [], 1568 "timed_pollers": [ 1569 { 1570 "name": "spdk_rpc_subsystem_poll", 1571 "id": 1, 1572 "state": "waiting", 1573 "run_count": 12345, 1574 "busy_count": 10000, 1575 "period_ticks": 10000000 1576 } 1577 ], 1578 "paused_pollers": [] 1579 } 1580 ] 1581 } 1582} 1583~~~ 1584 1585### thread_get_io_channels {#rpc_thread_get_io_channels} 1586 1587Retrieve current IO channels of all the threads. 1588 1589#### Parameters 1590 1591This method has no parameters. 1592 1593#### Response 1594 1595The response is an array of objects containing IO channels of all the threads. 1596 1597#### Example 1598 1599Example request: 1600 1601~~~json 1602{ 1603 "jsonrpc": "2.0", 1604 "method": "thread_get_io_channels", 1605 "id": 1 1606} 1607~~~ 1608 1609Example response: 1610 1611~~~json 1612{ 1613 "jsonrpc": "2.0", 1614 "id": 1, 1615 "result": { 1616 "tick_rate": 2500000000, 1617 "threads": [ 1618 { 1619 "name": "app_thread", 1620 "io_channels": [ 1621 { 1622 "name": "nvmf_tgt", 1623 "ref": 1 1624 } 1625 ] 1626 } 1627 ] 1628 } 1629} 1630~~~ 1631 1632### env_dpdk_get_mem_stats {#rpc_env_dpdk_get_mem_stats} 1633 1634Write the dpdk memory stats to a file. 1635 1636#### Parameters 1637 1638This method has no parameters. 1639 1640#### Response 1641 1642The response is a pathname to a text file containing the memory stats. 1643 1644#### Example 1645 1646Example request: 1647 1648~~~json 1649{ 1650 "jsonrpc": "2.0", 1651 "method": "env_dpdk_get_mem_stats", 1652 "id": 1 1653} 1654~~~ 1655 1656Example response: 1657 1658~~~json 1659{ 1660 "jsonrpc": "2.0", 1661 "id": 1, 1662 "result": { 1663 "filename": "/tmp/spdk_mem_dump.txt" 1664 } 1665} 1666~~~ 1667 1668## Acceleration Framework Layer {#jsonrpc_components_accel_fw} 1669 1670### accel_get_module_info {#accel_get_module_info} 1671 1672Get a list of valid module names and their supported operations. 1673 1674#### Parameters 1675 1676None 1677 1678#### Example 1679 1680Example request: 1681 1682~~~json 1683{ 1684 "jsonrpc": "2.0", 1685 "method": "accel_get_module_info", 1686 "id": 1 1687} 1688~~~ 1689 1690Example response: 1691 1692~~~json 1693[ 1694 { 1695 "module": "software", 1696 "supported ops": [ 1697 "copy", 1698 "fill", 1699 "dualcast", 1700 "compare", 1701 "crc32c", 1702 "copy_crc32c", 1703 "compress", 1704 "decompress" 1705 ] 1706 }, 1707 { 1708 "module": "dsa", 1709 "supported ops": [ 1710 "copy", 1711 "fill", 1712 "dualcast", 1713 "compare", 1714 "crc32c", 1715 "copy_crc32c" 1716 ] 1717 } 1718] 1719~~~ 1720 1721### accel_get_opc_assignments {#rpc_accel_get_opc_assignments} 1722 1723Get a list of opcode names and their assigned accel_fw modules. 1724 1725#### Parameters 1726 1727None 1728 1729#### Example 1730 1731Example request: 1732 1733~~~json 1734{ 1735 "jsonrpc": "2.0", 1736 "method": "accel_get_opc_assignments", 1737 "id": 1 1738} 1739~~~ 1740 1741Example response: 1742 1743~~~json 1744{ 1745 "jsonrpc": "2.0", 1746 "id": 1, 1747 "result": [ 1748 { 1749 "copy": "software", 1750 "fill": "software", 1751 "dualcast": "software", 1752 "compare": "software", 1753 "crc32c": "software", 1754 "copy_crc32c": "software", 1755 "compress": "software", 1756 "decompress": "software" 1757 } 1758 ] 1759} 1760~~~ 1761 1762### accel_assign_opc {#rpc_accel_assign_opc} 1763 1764Manually assign an operation to a module. 1765 1766#### Parameters 1767 1768Name | Optional | Type | Description 1769----------------------- | -------- | ----------- | ----------------- 1770opname | Required | string | name of operation 1771module | Required | string | name of module 1772 1773#### Example 1774 1775Example request: 1776 1777~~~json 1778{ 1779 "jsonrpc": "2.0", 1780 "method": "accel_assign_opc", 1781 "id": 1, 1782 "params": { 1783 "opname": "copy", 1784 "module": "software" 1785 } 1786} 1787~~~ 1788 1789Example response: 1790 1791~~~json 1792{ 1793 "jsonrpc": "2.0", 1794 "id": 1, 1795 "result": true 1796} 1797~~~ 1798 1799### accel_crypto_key_create {#rpc_accel_crypto_key_create} 1800 1801Create a crypto key which will be used in accel framework 1802 1803#### Parameters 1804 1805Name | Optional | Type | Description 1806-----------|----------| ----------- | ----------------- 1807cipher | Required | string | crypto cipher to use 1808key | Required | string | Key in **hex** form 1809key2 | Optional | string | Optional 2nd part of the key or a tweak in **hex** form 1810tweak_mode | Optional | string | Tweak mode to use: SIMPLE_LBA, JOIN_NEG_LBA_WITH_LBA, INCR_512_FULL_LBA, INCR_512_UPPER_LBA. Default is SIMPLE_LBA 1811name | Required | string | The key name 1812 1813#### Example 1814 1815Example request: 1816 1817~~~json 1818{ 1819 "jsonrpc": "2.0", 1820 "method": "accel_crypto_key_create", 1821 "id": 1, 1822 "params": { 1823 "cipher": "AES_XTS", 1824 "key": "00112233445566778899001122334455", 1825 "key2": "00112233445566778899001122334455", 1826 "tweak_mode": "SIMPLE_LBA", 1827 "name": "super_key" 1828 } 1829} 1830~~~ 1831 1832Example response: 1833 1834~~~json 1835{ 1836 "jsonrpc": "2.0", 1837 "id": 1, 1838 "result": true 1839} 1840~~~ 1841 1842### accel_crypto_key_destroy {#rpc_accel_crypto_key_destroy} 1843 1844Destroy a crypto key. The user is responsible for ensuring that the deleted key is not used by acceleration modules. 1845 1846#### Parameters 1847 1848Name | Optional | Type | Description 1849-----------|----------| ----------- | ----------------- 1850name | Required | string | The key name 1851 1852#### Example 1853 1854Example request: 1855 1856~~~json 1857{ 1858 "jsonrpc": "2.0", 1859 "method": "accel_crypto_key_destroy", 1860 "id": 1, 1861 "params": { 1862 "name": "super_key" 1863 } 1864} 1865~~~ 1866 1867Example response: 1868 1869~~~json 1870{ 1871 "jsonrpc": "2.0", 1872 "id": 1, 1873 "result": true 1874} 1875~~~ 1876 1877### accel_crypto_keys_get {#rpc_accel_crypto_keys_get} 1878 1879Get information about existing crypto keys 1880 1881#### Parameters 1882 1883Name | Optional | Type | Description 1884----------------------- |----------| ----------- | ----------------- 1885key_name | Optional | string | If specified, return info about a specific key 1886 1887#### Example 1888 1889Example request: 1890 1891~~~json 1892{ 1893 "jsonrpc": "2.0", 1894 "method": "accel_crypto_keys_get", 1895 "id": 1 1896} 1897~~~ 1898 1899Example response: 1900 1901~~~json 1902{ 1903 "jsonrpc": "2.0", 1904 "id": 1, 1905 "result": [ 1906 { 1907 "name": "test_dek", 1908 "cipher": "AES_XTS", 1909 "key": "00112233445566778899001122334455", 1910 "key2": "11223344556677889900112233445500", 1911 "tweak_mode": "SIMPLE_LBA" 1912 }, 1913 { 1914 "name": "test_dek2", 1915 "cipher": "AES_XTS", 1916 "key": "11223344556677889900112233445500", 1917 "key2": "22334455667788990011223344550011", 1918 "tweak_mode": "SIMPLE_LBA" 1919 } 1920 ] 1921} 1922~~~ 1923 1924### accel_set_driver {#rpc_accel_set_driver} 1925 1926Select platform driver to execute operation chains. Until a driver is selected, all operations are 1927executed through accel modules. 1928 1929#### Parameters 1930 1931Name | Optional | Type | Description 1932----------------------- |----------| ----------- | ----------------- 1933name | Required | string | Name of the platform driver 1934 1935#### Example 1936 1937Example request: 1938 1939~~~json 1940{ 1941 "jsonrpc": "2.0", 1942 "method": "accel_set_driver", 1943 "id": 1 1944 "params": { 1945 "name": "xeon" 1946 } 1947} 1948~~~ 1949 1950Example response: 1951 1952~~~json 1953{ 1954 "jsonrpc": "2.0", 1955 "id": 1, 1956 "result": true 1957} 1958~~~ 1959 1960### accel_set_options {#rpc_accel_set_options} 1961 1962Set accel framework's options. 1963 1964#### Parameters 1965 1966Name | Optional | Type | Description 1967----------------------- |----------| ----------- | ----------------- 1968small_cache_size | Optional | number | Size of the small iobuf cache 1969large_cache_size | Optional | number | Size of the large iobuf cache 1970task_count | Optional | number | Maximum number of tasks per IO channel 1971sequence_count | Optional | number | Maximum number of sequences per IO channel 1972buf_count | Optional | number | Maximum number of accel buffers per IO channel 1973 1974#### Example 1975 1976Example request: 1977 1978~~~json 1979{ 1980 "jsonrpc": "2.0", 1981 "method": "accel_set_options", 1982 "id": 1, 1983 "params": { 1984 "small_cache_size": 128, 1985 "large_cache_size": 32 1986 } 1987} 1988~~~ 1989 1990Example response: 1991 1992~~~json 1993{ 1994 "jsonrpc": "2.0", 1995 "id": 1, 1996 "result": true 1997} 1998~~~ 1999 2000### accel_get_stats {#rpc_accel_get_stats} 2001 2002Retrieve accel framework's statistics. Statistics for opcodes that have never been executed (i.e. 2003all their stats are at 0) aren't included in the `operations` array. 2004 2005#### Parameters 2006 2007None. 2008 2009#### Example 2010 2011Example request: 2012 2013~~~json 2014{ 2015 "jsonrpc": "2.0", 2016 "method": "accel_get_stats", 2017 "id": 1 2018} 2019~~~ 2020 2021Example response: 2022 2023~~~json 2024{ 2025 "jsonrpc": "2.0", 2026 "id": 1, 2027 "result": { 2028 "sequence_executed": 256, 2029 "sequence_failed": 0, 2030 "operations": [ 2031 { 2032 "opcode": "copy", 2033 "executed": 256, 2034 "failed": 0 2035 }, 2036 { 2037 "opcode": "encrypt", 2038 "executed": 128, 2039 "failed": 0 2040 }, 2041 { 2042 "opcode": "decrypt", 2043 "executed": 128, 2044 "failed": 0 2045 } 2046 ] 2047 } 2048} 2049~~~ 2050 2051### accel_error_inject_error {#rpc_accel_error_inject_error} 2052 2053Inject an error to execution of a given operation. Note, that in order for the errors to be 2054actually injected, the error module must be assigned to that operation via `accel_assign_opc`. 2055 2056#### Parameters 2057 2058Name | Optional | Type | Description 2059----------------------- |----------| ----------- | ----------------- 2060opcode | Required | string | Operation to inject errors. 2061type | Required | string | Type of errors to inject ("corrupt": corrupt the data, "failure": fail the operation, "disable": disable error injection). 2062count | Optional | number | Numbers of errors to inject on each IO channel (`UINT64_MAX` by default). 2063interval | Optional | number | Interval between injections. 2064errcode | Optional | number | Error code to inject (only relevant for type=failure). 2065 2066#### Example 2067 2068Example request: 2069 2070~~~json 2071{ 2072 "method": "accel_error_inject_error", 2073 "params": { 2074 "opcode": "crc32c", 2075 "type": "corrupt", 2076 "count": 10000, 2077 "interval": 8 2078 } 2079} 2080~~~ 2081 2082Example response: 2083 2084~~~json 2085{ 2086 "jsonrpc": "2.0", 2087 "id": 1, 2088 "result": true 2089} 2090~~~ 2091 2092### compressdev_scan_accel_module {#rpc_compressdev_scan_accel_module} 2093 2094Set config and enable compressdev accel module offload. 2095Select the DPDK polled mode driver (pmd) for the accel compress module, 20960 = auto-select, 1= QAT only, 2 = mlx5_pci only. 2097 2098#### Parameters 2099 2100Name | Optional | Type | Description 2101----------------------- | -------- | ----------- | ----------- 2102pmd | Required | int | pmd selection 2103 2104#### Example 2105 2106Example request: 2107 2108~~~json 2109{ 2110 "params": { 2111 "pmd": 1 2112 }, 2113 "jsonrpc": "2.0", 2114 "method": "compressdev_scan_accel_module", 2115 "id": 1 2116} 2117~~~ 2118 2119Example response: 2120 2121~~~json 2122{ 2123 "jsonrpc": "2.0", 2124 "id": 1, 2125 "result": true 2126} 2127~~~ 2128 2129### dsa_scan_accel_module {#rpc_dsa_scan_accel_module} 2130 2131Set config and enable dsa accel module offload. 2132This feature is considered as experimental. 2133 2134#### Parameters 2135 2136Name | Optional | Type | Description 2137----------------------- | -------- | ----------- | ----------- 2138config_kernel_mode | Optional | Boolean | If set, will use kernel idxd driver. 2139 2140#### Example 2141 2142Example request: 2143 2144~~~json 2145{ 2146 "params": { 2147 "config_kernel_mode": false 2148 }, 2149 "jsonrpc": "2.0", 2150 "method": "dsa_scan_accel_module", 2151 "id": 1 2152} 2153~~~ 2154 2155Example response: 2156 2157~~~json 2158{ 2159 "jsonrpc": "2.0", 2160 "id": 1, 2161 "result": true 2162} 2163~~~ 2164 2165### iaa_scan_accel_module {#rpc_iaa_scan_accel_module} 2166 2167Enable IAA accel module offload. 2168This feature is considered as experimental. 2169 2170#### Parameters 2171 2172None 2173 2174#### Example 2175 2176Example request: 2177 2178~~~json 2179{ 2180 "jsonrpc": "2.0", 2181 "method": "iaa_scan_accel_module", 2182 "id": 1 2183} 2184~~~ 2185 2186Example response: 2187 2188~~~json 2189{ 2190 "jsonrpc": "2.0", 2191 "id": 1, 2192 "result": true 2193} 2194~~~ 2195 2196### ioat_scan_accel_module {#rpc_ioat_scan_accel_module} 2197 2198Enable ioat accel module offload. 2199 2200#### Parameters 2201 2202None 2203 2204#### Example 2205 2206Example request: 2207 2208~~~json 2209{ 2210 "jsonrpc": "2.0", 2211 "method": "ioat_scan_accel_module", 2212 "id": 1 2213} 2214~~~ 2215 2216Example response: 2217 2218~~~json 2219{ 2220 "jsonrpc": "2.0", 2221 "id": 1, 2222 "result": true 2223} 2224~~~ 2225 2226### dpdk_cryptodev_scan_accel_module {#rpc_dpdk_cryptodev_scan_accel_module} 2227 2228Enable dpdk_cryptodev accel offload 2229 2230#### Parameters 2231 2232None 2233 2234#### Example 2235 2236Example request: 2237 2238~~~json 2239{ 2240 "jsonrpc": "2.0", 2241 "method": "dpdk_cryptodev_scan_accel_module", 2242 "id": 1 2243} 2244~~~ 2245 2246Example response: 2247 2248~~~json 2249{ 2250 "jsonrpc": "2.0", 2251 "id": 1, 2252 "result": true 2253} 2254~~~ 2255 2256### dpdk_cryptodev_set_driver {#rpc_dpdk_cryptodev_set_driver} 2257 2258Set the DPDK cryptodev driver 2259 2260#### Parameters 2261 2262Name | Optional | Type | Description 2263----------------------- |----------|--------| ----------- 2264crypto_pmd | Required | string | The driver, can be one of crypto_aesni_mb, crypto_qat or mlx5_pci 2265 2266#### Example 2267 2268Example request: 2269 2270~~~json 2271{ 2272 "jsonrpc": "2.0", 2273 "method": "dpdk_cryptodev_set_driver", 2274 "id": 1, 2275 "params": { 2276 "crypto_pmd": "crypto_aesni_mb" 2277 } 2278} 2279~~~ 2280 2281Example response: 2282 2283~~~json 2284{ 2285 "jsonrpc": "2.0", 2286 "id": 1, 2287 "result": true 2288} 2289~~~ 2290 2291### dpdk_cryptodev_get_driver {#rpc_dpdk_cryptodev_get_driver} 2292 2293Get the DPDK cryptodev driver 2294 2295#### Parameters 2296 2297None 2298 2299#### Example 2300 2301Example request: 2302 2303~~~json 2304{ 2305 "jsonrpc": "2.0", 2306 "method": "dpdk_cryptodev_get_driver", 2307 "id": 1 2308} 2309~~~ 2310 2311Example response: 2312 2313~~~json 2314{ 2315 "jsonrpc": "2.0", 2316 "id": 1, 2317 "result": "crypto_aesni_mb" 2318} 2319~~~ 2320 2321### mlx5_scan_accel_module {#rpc_mlx5_scan_accel_module} 2322 2323Enable mlx5 accel offload 2324 2325#### Parameters 2326 2327Name | Optional | Type | Description 2328----------------------- | -------- |--------| ----------- 2329qp_size | Optional | number | qpair size 2330num_requests | Optional | number | Size of the shared requests pool 2331 2332#### Example 2333 2334Example request: 2335 2336~~~json 2337{ 2338 "jsonrpc": "2.0", 2339 "method": "mlx5_scan_accel_module", 2340 "id": 1, 2341 "params": { 2342 "qp_size": 256, 2343 "num_requests": 2047 2344 } 2345} 2346~~~ 2347 2348Example response: 2349 2350~~~json 2351{ 2352 "jsonrpc": "2.0", 2353 "id": 1, 2354 "result": true 2355} 2356~~~ 2357 2358## Block Device Abstraction Layer {#jsonrpc_components_bdev} 2359 2360### bdev_set_options {#rpc_bdev_set_options} 2361 2362Set global parameters for the block device (bdev) subsystem. This RPC may only be called 2363before SPDK subsystems have been initialized. 2364 2365#### Parameters 2366 2367Name | Optional | Type | Description 2368----------------------- | -------- | ----------- | ----------- 2369bdev_io_pool_size | Optional | number | Number of spdk_bdev_io structures in shared buffer pool 2370bdev_io_cache_size | Optional | number | Maximum number of spdk_bdev_io structures cached per thread 2371bdev_auto_examine | Optional | boolean | If set to false, the bdev layer will not examine every disks automatically 2372iobuf_small_cache_size | Optional | number | Size of the small iobuf per thread cache 2373iobuf_large_cache_size | Optional | number | Size of the large iobuf per thread cache 2374 2375#### Example 2376 2377Example request: 2378 2379~~~json 2380{ 2381 "jsonrpc": "2.0", 2382 "id": 1, 2383 "method": "bdev_set_options", 2384 "params": { 2385 "bdev_io_pool_size": 65536, 2386 "bdev_io_cache_size": 256 2387 } 2388} 2389~~~ 2390 2391Example response: 2392 2393~~~json 2394{ 2395 "jsonrpc": "2.0", 2396 "id": 1, 2397 "result": true 2398} 2399~~~ 2400 2401### bdev_get_bdevs {#rpc_bdev_get_bdevs} 2402 2403Get information about block devices (bdevs). 2404 2405#### Parameters 2406 2407The user may specify no parameters in order to list all block devices, or a block device may be 2408specified by name. If a timeout is specified, the method will block until a bdev with a specified 2409name appears or the timeout expires. By default, the timeout is zero, meaning the method returns 2410immediately whether the bdev exists or not. 2411 2412Name | Optional | Type | Description 2413----------------------- | -------- | ----------- | ----------- 2414name | Optional | string | Block device name 2415timeout | Optional | number | Time (ms) to wait for a bdev with specified name to appear 2416 2417#### Response 2418 2419The response is an array of objects containing information about the requested block devices. 2420 2421#### Example 2422 2423Example request: 2424 2425~~~json 2426{ 2427 "jsonrpc": "2.0", 2428 "id": 1, 2429 "method": "bdev_get_bdevs", 2430 "params": { 2431 "name": "Malloc0" 2432 } 2433} 2434~~~ 2435 2436Example response: 2437 2438~~~json 2439{ 2440 "jsonrpc": "2.0", 2441 "id": 1, 2442 "result": [ 2443 { 2444 "name": "Malloc0", 2445 "product_name": "Malloc disk", 2446 "block_size": 512, 2447 "num_blocks": 20480, 2448 "claimed": false, 2449 "zoned": false, 2450 "supported_io_types": { 2451 "read": true, 2452 "write": true, 2453 "unmap": true, 2454 "write_zeroes": true, 2455 "flush": true, 2456 "reset": true, 2457 "nvme_admin": false, 2458 "nvme_io": false 2459 }, 2460 "driver_specific": {} 2461 } 2462 ] 2463} 2464~~~ 2465 2466### bdev_examine {#rpc_bdev_examine} 2467 2468Request that the bdev layer examines the given bdev for metadata and creates 2469new bdevs if metadata is found. This is only necessary if `auto_examine` has 2470been set to false using `bdev_set_options`. By default, `auto_examine` is true 2471and bdev examination is automatic. 2472 2473#### Parameters 2474 2475Name | Optional | Type | Description 2476----------------------- | -------- | ----------- | ----------- 2477name | Required | string | Block device name 2478 2479#### Response 2480 2481The response is an array of objects containing I/O statistics of the requested block devices. 2482 2483#### Example 2484 2485Example request: 2486 2487~~~json 2488{ 2489 "jsonrpc": "2.0", 2490 "id": 1, 2491 "method": "bdev_examine", 2492 "params": { 2493 "name": "Nvme0n1" 2494 } 2495} 2496~~~ 2497 2498Example response: 2499 2500~~~json 2501{ 2502 "jsonrpc": "2.0", 2503 "id": 1, 2504 "result": true 2505} 2506~~~ 2507 2508### bdev_wait_for_examine {#rpc_bdev_wait_for_examine} 2509 2510Report when all bdevs have been examined by every bdev module. 2511 2512#### Parameters 2513 2514None 2515 2516#### Response 2517 2518The response is sent when all bdev modules had a chance to examine every bdev. 2519 2520#### Example 2521 2522Example request: 2523 2524~~~json 2525{ 2526 "jsonrpc": "2.0", 2527 "method": "bdev_wait_for_examine", 2528 "id": 1 2529} 2530~~~ 2531 2532Example response: 2533 2534~~~json 2535{ 2536 "jsonrpc": "2.0", 2537 "id": 1, 2538 "result": true 2539} 2540~~~ 2541 2542### bdev_get_iostat {#rpc_bdev_get_iostat} 2543 2544Get I/O statistics of block devices (bdevs). 2545 2546#### Parameters 2547 2548The user may specify no parameters in order to list all block devices, or a block device may be 2549specified by name. 2550 2551Name | Optional | Type | Description 2552----------------------- | -------- | ----------- | ----------- 2553name | Optional | string | Block device name 2554per_channel | Optional | bool | Display per channel data for specified block device. 2555 2556#### Response 2557 2558The response is an array of objects containing I/O statistics of the requested block devices. 2559 2560#### Example 2561 2562Example request: 2563 2564~~~json 2565{ 2566 "jsonrpc": "2.0", 2567 "id": 1, 2568 "method": "bdev_get_iostat", 2569 "params": { 2570 "name": "Nvme0n1", 2571 "per_channel": false 2572 } 2573} 2574~~~ 2575 2576Example response: 2577 2578~~~json 2579{ 2580 "jsonrpc": "2.0", 2581 "id": 1, 2582 "result": { 2583 "tick_rate": 2200000000, 2584 "bdevs" : [ 2585 { 2586 "name": "Nvme0n1", 2587 "bytes_read": 36864, 2588 "num_read_ops": 2, 2589 "bytes_written": 0, 2590 "num_write_ops": 0, 2591 "bytes_unmapped": 0, 2592 "num_unmap_ops": 0, 2593 "read_latency_ticks": 178904, 2594 "write_latency_ticks": 0, 2595 "unmap_latency_ticks": 0, 2596 "queue_depth_polling_period": 2, 2597 "queue_depth": 0, 2598 "io_time": 0, 2599 "weighted_io_time": 0 2600 } 2601 ] 2602 } 2603} 2604~~~ 2605 2606### bdev_reset_iostat {#rpc_bdev_reset_iostat} 2607 2608Reset I/O statistics of block devices (bdevs). Note that if one consumer resets I/O statistics, 2609it affects all other consumers. 2610 2611#### Parameters 2612 2613The user may specify no parameters in order to reset I/O statistics for all block devices, or 2614a block device may be specified by name. 2615 2616Name | Optional | Type | Description 2617----------------------- | -------- | ----------- | ----------- 2618name | Optional | string | Block device name 2619mode | Optional | string | Mode to reset I/O statistics: all, maxmin (default: all) 2620 2621#### Example 2622 2623Example request: 2624 2625~~~json 2626{ 2627 "jsonrpc": "2.0", 2628 "id": 1, 2629 "method": "bdev_reset_iostat", 2630 "params": { 2631 "name": "Nvme0n1" 2632 } 2633} 2634~~~ 2635 2636Example response: 2637 2638~~~json 2639{ 2640 "jsonrpc": "2.0", 2641 "id": 1, 2642 "result": true 2643} 2644~~~ 2645 2646### bdev_enable_histogram {#rpc_bdev_enable_histogram} 2647 2648Control whether collecting data for histogram is enabled for specified bdev. 2649 2650#### Parameters 2651 2652Name | Optional | Type | Description 2653----------------------- | -------- | ----------- | ----------- 2654name | Required | string | Block device name 2655enable | Required | boolean | Enable or disable histogram on specified device 2656 2657#### Example 2658 2659Example request: 2660 2661~~~json 2662{ 2663 "jsonrpc": "2.0", 2664 "id": 1, 2665 "method": "bdev_enable_histogram", 2666 "params": { 2667 "name": "Nvme0n1" 2668 "enable": true 2669 } 2670} 2671~~~ 2672 2673Example response: 2674 2675~~~json 2676{ 2677 "jsonrpc": "2.0", 2678 "id": 1, 2679 "result": true 2680} 2681~~~ 2682 2683### bdev_get_histogram {#rpc_bdev_get_histogram} 2684 2685Get latency histogram for specified bdev. 2686 2687#### Parameters 2688 2689Name | Optional | Type | Description 2690----------------------- | -------- | ----------- | ----------- 2691name | Required | string | Block device name 2692 2693#### Result 2694 2695Name | Description 2696------------------------| ----------- 2697histogram | Base64 encoded histogram 2698bucket_shift | Granularity of the histogram buckets 2699tsc_rate | Ticks per second 2700 2701#### Example 2702 2703Example request: 2704 2705~~~json 2706{ 2707 "jsonrpc": "2.0", 2708 "id": 1, 2709 "method": "bdev_get_histogram", 2710 "params": { 2711 "name": "Nvme0n1" 2712 } 2713} 2714~~~ 2715 2716Example response: 2717Note that histogram field is trimmed, actual encoded histogram length is ~80kb. 2718 2719~~~json 2720{ 2721 "jsonrpc": "2.0", 2722 "id": 1, 2723 "result": { 2724 "histogram": "AAAAAAAAAAAAAA...AAAAAAAAA==", 2725 "tsc_rate": 2300000000, 2726 "bucket_shift": 7 2727 } 2728} 2729~~~ 2730 2731### bdev_set_qos_limit {#rpc_bdev_set_qos_limit} 2732 2733Set the quality of service rate limit on a bdev. 2734 2735#### Parameters 2736 2737Name | Optional | Type | Description 2738----------------------- | -------- | ----------- | ----------- 2739name | Required | string | Block device name 2740rw_ios_per_sec | Optional | number | Number of R/W I/Os per second to allow. 0 means unlimited. 2741rw_mbytes_per_sec | Optional | number | Number of R/W megabytes per second to allow. 0 means unlimited. 2742r_mbytes_per_sec | Optional | number | Number of Read megabytes per second to allow. 0 means unlimited. 2743w_mbytes_per_sec | Optional | number | Number of Write megabytes per second to allow. 0 means unlimited. 2744 2745#### Example 2746 2747Example request: 2748 2749~~~json 2750{ 2751 "jsonrpc": "2.0", 2752 "id": 1, 2753 "method": "bdev_set_qos_limit", 2754 "params": { 2755 "name": "Malloc0" 2756 "rw_ios_per_sec": 20000 2757 "rw_mbytes_per_sec": 100 2758 "r_mbytes_per_sec": 50 2759 "w_mbytes_per_sec": 50 2760 } 2761} 2762~~~ 2763 2764Example response: 2765 2766~~~json 2767{ 2768 "jsonrpc": "2.0", 2769 "id": 1, 2770 "result": true 2771} 2772~~~ 2773 2774### bdev_set_qd_sampling_period {#rpc_bdev_set_qd_sampling_period} 2775 2776Enable queue depth tracking on a specified bdev. 2777 2778#### Parameters 2779 2780Name | Optional | Type | Description 2781----------------------- | -------- | ----------- | ----------- 2782name | Required | string | Block device name 2783period | Required | int | period (in microseconds).If set to 0, polling will be disabled. 2784 2785#### Example 2786 2787Example request: 2788 2789~~~json 2790{ 2791 "jsonrpc": "2.0", 2792 "method": "bdev_set_qd_sampling_period", 2793 "id": 1, 2794 "params": { 2795 "name": "Malloc0", 2796 "period": 20 2797 } 2798} 2799~~~ 2800 2801Example response: 2802 2803~~~json 2804{ 2805 "jsonrpc": "2.0", 2806 "id": 1, 2807 "result": true 2808} 2809~~~ 2810 2811### bdev_compress_create {#rpc_bdev_compress_create} 2812 2813Create a new compress bdev on a given base bdev. 2814 2815#### Parameters 2816 2817Name | Optional | Type | Description 2818----------------------- | -------- | ----------- | ----------- 2819base_bdev_name | Required | string | Name of the base bdev 2820pm_path | Required | string | Path to persistent memory 2821lb_size | Optional | int | Compressed vol logical block size (512 or 4096) 2822 2823#### Result 2824 2825Name of newly created bdev. 2826 2827#### Example 2828 2829Example request: 2830 2831~~~json 2832{ 2833 "params": { 2834 "base_bdev_name": "Nvme0n1", 2835 "pm_path": "/pm_files", 2836 "lb_size": 4096 2837 }, 2838 "jsonrpc": "2.0", 2839 "method": "bdev_compress_create", 2840 "id": 1 2841} 2842~~~ 2843 2844### bdev_compress_delete {#rpc_bdev_compress_delete} 2845 2846Delete a compressed bdev. 2847 2848#### Parameters 2849 2850Name | Optional | Type | Description 2851----------------------- | -------- | ----------- | ----------- 2852name | Required | string | Name of the compress bdev 2853 2854#### Example 2855 2856Example request: 2857 2858~~~json 2859{ 2860 "params": { 2861 "name": "COMP_Nvme0n1" 2862 }, 2863 "jsonrpc": "2.0", 2864 "method": "bdev_compress_delete", 2865 "id": 1 2866} 2867~~~ 2868 2869Example response: 2870 2871~~~json 2872{ 2873 "jsonrpc": "2.0", 2874 "id": 1, 2875 "result": true 2876} 2877~~~ 2878 2879### bdev_compress_get_orphans {#rpc_bdev_compress_get_orphans} 2880 2881Get a list of compressed volumes that are missing their pmem metadata. 2882 2883#### Parameters 2884 2885Name | Optional | Type | Description 2886----------------------- | -------- | ----------- | ----------- 2887name | Optional | string | Name of the compress bdev 2888 2889#### Example 2890 2891Example request: 2892 2893~~~json 2894{ 2895 "params": { 2896 "name": "COMP_Nvme0n1" 2897 }, 2898 "jsonrpc": "2.0", 2899 "method": "bdev_compress_get_orphans", 2900 "id": 1 2901} 2902~~~ 2903 2904Example response: 2905 2906~~~json 2907{ 2908 "jsonrpc": "2.0", 2909 "id": 1, 2910 "name": "COMP_Nvme0n1" 2911} 2912~~~ 2913 2914### bdev_crypto_create {#rpc_bdev_crypto_create} 2915 2916Create a new crypto bdev on a given base bdev. 2917 2918#### Parameters 2919 2920Name | Optional | Type | Description 2921----------------------- |----------| ----------- | ----------- 2922base_bdev_name | Required | string | Name of the base bdev 2923name | Required | string | Name of the crypto vbdev to create 2924crypto_pmd | Optional | string | Name of the crypto device driver. Obsolete, see accel_crypto_key_create 2925key | Optional | string | Key in hex form. Obsolete, see accel_crypto_key_create 2926cipher | Optional | string | Cipher to use, AES_CBC or AES_XTS (QAT and MLX5). Obsolete, see accel_crypto_key_create 2927key2 | Optional | string | 2nd key in hex form only required for cipher AET_XTS. Obsolete, see accel_crypto_key_create 2928key_name | Optional | string | Name of the key created with accel_crypto_key_create 2929 2930Both key and key2 must be passed in the hexlified form. For example, 256bit AES key may look like this: 2931afd9477abf50254219ccb75965fbe39f23ebead5676e292582a0a67f66b88215 2932 2933#### Result 2934 2935Name of newly created bdev. 2936 2937#### Example 2938 2939Example request: 2940 2941~~~json 2942{ 2943 "params": { 2944 "base_bdev_name": "Nvme0n1", 2945 "name": "my_crypto_bdev", 2946 "crypto_pmd": "crypto_aesni_mb", 2947 "key": "12345678901234561234567890123456", 2948 "cipher": "AES_CBC" 2949 }, 2950 "jsonrpc": "2.0", 2951 "method": "bdev_crypto_create", 2952 "id": 1 2953} 2954~~~ 2955 2956Example response: 2957 2958~~~json 2959{ 2960 2961 "jsonrpc": "2.0", 2962 "id": 1, 2963 "result": "my_crypto_bdev" 2964} 2965~~~ 2966 2967### bdev_crypto_delete {#rpc_bdev_crypto_delete} 2968 2969Delete a crypto bdev. 2970 2971#### Parameters 2972 2973Name | Optional | Type | Description 2974----------------------- | -------- | ----------- | ----------- 2975name | Required | string | Name of the crypto bdev 2976 2977#### Example 2978 2979Example request: 2980 2981~~~json 2982{ 2983 "params": { 2984 "name": "my_crypto_bdev" 2985 }, 2986 "jsonrpc": "2.0", 2987 "method": "bdev_crypto_delete", 2988 "id": 1 2989} 2990~~~ 2991 2992Example response: 2993 2994~~~json 2995{ 2996 "jsonrpc": "2.0", 2997 "id": 1, 2998 "result": true 2999} 3000~~~ 3001 3002### bdev_ocf_create {#rpc_bdev_ocf_create} 3003 3004Construct new OCF bdev. 3005Command accepts cache mode that is going to be used. 3006You can find more details about supported cache modes in the [OCF documentation](https://open-cas.github.io/cache_configuration.html#cache-mode) 3007 3008#### Parameters 3009 3010Name | Optional | Type | Description 3011----------------------- | -------- | ----------- | ----------- 3012name | Required | string | Bdev name to use 3013mode | Required | string | OCF cache mode: wb, wt, pt, wa, wi, wo 3014cache_line_size | Optional | int | OCF cache line size in KiB: 4, 8, 16, 32, 64 3015cache_bdev_name | Required | string | Name of underlying cache bdev 3016core_bdev_name | Required | string | Name of underlying core bdev 3017 3018#### Result 3019 3020Name of newly created bdev. 3021 3022#### Example 3023 3024Example request: 3025 3026~~~json 3027{ 3028 "params": { 3029 "name": "ocf0", 3030 "mode": "wt", 3031 "cache_line_size": 64, 3032 "cache_bdev_name": "Nvme0n1", 3033 "core_bdev_name": "aio0" 3034 }, 3035 "jsonrpc": "2.0", 3036 "method": "bdev_ocf_create", 3037 "id": 1 3038} 3039~~~ 3040 3041Example response: 3042 3043~~~json 3044{ 3045 "jsonrpc": "2.0", 3046 "id": 1, 3047 "result": "ocf0" 3048} 3049~~~ 3050 3051### bdev_ocf_delete {#rpc_bdev_ocf_delete} 3052 3053Delete the OCF bdev 3054 3055#### Parameters 3056 3057Name | Optional | Type | Description 3058----------------------- | -------- | ----------- | ----------- 3059name | Required | string | Bdev name 3060 3061#### Example 3062 3063Example request: 3064 3065~~~json 3066{ 3067 "params": { 3068 "name": "ocf0" 3069 }, 3070 "jsonrpc": "2.0", 3071 "method": "bdev_ocf_delete", 3072 "id": 1 3073} 3074~~~ 3075 3076Example response: 3077 3078~~~json 3079{ 3080 "jsonrpc": "2.0", 3081 "id": 1, 3082 "result": true 3083} 3084~~~ 3085 3086### bdev_ocf_get_stats {#rpc_bdev_ocf_get_stats} 3087 3088Get statistics of chosen OCF block device. 3089 3090#### Parameters 3091 3092Name | Optional | Type | Description 3093----------------------- | -------- | ----------- | ----------- 3094name | Required | string | Block device name 3095 3096#### Response 3097 3098Statistics as json object. 3099 3100#### Example 3101 3102Example request: 3103 3104~~~json 3105{ 3106 "params": { 3107 "name": "ocf0" 3108 }, 3109 "jsonrpc": "2.0", 3110 "method": "bdev_ocf_get_stats", 3111 "id": 1 3112} 3113~~~ 3114 3115Example response: 3116 3117~~~json 3118{ 3119 "jsonrpc": "2.0", 3120 "id": 1, 3121 "result": [ 3122 "usage": { 3123 "clean": { 3124 "count": 76033, 3125 "units": "4KiB blocks", 3126 "percentage": "100.0" 3127 }, 3128 "free": { 3129 "count": 767, 3130 "units": "4KiB blocks", 3131 "percentage": "0.9" 3132 }, 3133 "occupancy": { 3134 "count": 76033, 3135 "units": "4KiB blocks", 3136 "percentage": "99.0" 3137 }, 3138 "dirty": { 3139 "count": 0, 3140 "units": "4KiB blocks", 3141 "percentage": "0.0" 3142 } 3143 }, 3144 "requests": { 3145 "rd_total": { 3146 "count": 2, 3147 "units": "Requests", 3148 "percentage": "0.0" 3149 }, 3150 "wr_full_misses": { 3151 "count": 76280, 3152 "units": "Requests", 3153 "percentage": "35.6" 3154 }, 3155 "rd_full_misses": { 3156 "count": 1, 3157 "units": "Requests", 3158 "percentage": "0.0" 3159 }, 3160 "rd_partial_misses": { 3161 "count": 0, 3162 "units": "Requests", 3163 "percentage": "0.0" 3164 }, 3165 "wr_total": { 3166 "count": 212416, 3167 "units": "Requests", 3168 "percentage": "99.2" 3169 }, 3170 "wr_pt": { 3171 "count": 1535, 3172 "units": "Requests", 3173 "percentage": "0.7" 3174 }, 3175 "wr_partial_misses": { 3176 "count": 0, 3177 "units": "Requests", 3178 "percentage": "0.0" 3179 }, 3180 "serviced": { 3181 "count": 212418, 3182 "units": "Requests", 3183 "percentage": "99.2" 3184 }, 3185 "rd_pt": { 3186 "count": 0, 3187 "units": "Requests", 3188 "percentage": "0.0" 3189 }, 3190 "total": { 3191 "count": 213953, 3192 "units": "Requests", 3193 "percentage": "100.0" 3194 }, 3195 "rd_hits": { 3196 "count": 1, 3197 "units": "Requests", 3198 "percentage": "0.0" 3199 }, 3200 "wr_hits": { 3201 "count": 136136, 3202 "units": "Requests", 3203 "percentage": "63.6" 3204 } 3205 }, 3206 "errors": { 3207 "total": { 3208 "count": 0, 3209 "units": "Requests", 3210 "percentage": "0.0" 3211 }, 3212 "cache_obj_total": { 3213 "count": 0, 3214 "units": "Requests", 3215 "percentage": "0.0" 3216 }, 3217 "core_obj_total": { 3218 "count": 0, 3219 "units": "Requests", 3220 "percentage": "0.0" 3221 }, 3222 "cache_obj_rd": { 3223 "count": 0, 3224 "units": "Requests", 3225 "percentage": "0.0" 3226 }, 3227 "core_obj_wr": { 3228 "count": 0, 3229 "units": "Requests", 3230 "percentage": "0.0" 3231 }, 3232 "core_obj_rd": { 3233 "count": 0, 3234 "units": "Requests", 3235 "percentage": "0.0" 3236 }, 3237 "cache_obj_wr": { 3238 "count": 0, 3239 "units": "Requests", 3240 "percentage": "0.0" 3241 } 3242 }, 3243 "blocks": { 3244 "volume_rd": { 3245 "count": 9, 3246 "units": "4KiB blocks", 3247 "percentage": "0.0" 3248 }, 3249 "volume_wr": { 3250 "count": 213951, 3251 "units": "4KiB blocks", 3252 "percentage": "99.9" 3253 }, 3254 "cache_obj_total": { 3255 "count": 212425, 3256 "units": "4KiB blocks", 3257 "percentage": "100.0" 3258 }, 3259 "core_obj_total": { 3260 "count": 213959, 3261 "units": "4KiB blocks", 3262 "percentage": "100.0" 3263 }, 3264 "cache_obj_rd": { 3265 "count": 1, 3266 "units": "4KiB blocks", 3267 "percentage": "0.0" 3268 }, 3269 "core_obj_wr": { 3270 "count": 213951, 3271 "units": "4KiB blocks", 3272 "percentage": "99.9" 3273 }, 3274 "volume_total": { 3275 "count": 213960, 3276 "units": "4KiB blocks", 3277 "percentage": "100.0" 3278 }, 3279 "core_obj_rd": { 3280 "count": 8, 3281 "units": "4KiB blocks", 3282 "percentage": "0.0" 3283 }, 3284 "cache_obj_wr": { 3285 "count": 212424, 3286 "units": "4KiB blocks", 3287 "percentage": "99.9" 3288 } 3289 ] 3290} 3291~~~ 3292 3293### bdev_ocf_reset_stats {#rpc_bdev_ocf_reset_stats} 3294 3295Reset statistics of chosen OCF block device. 3296 3297#### Parameters 3298 3299Name | Optional | Type | Description 3300----------------------- | -------- | ----------- | ----------- 3301name | Required | string | Block device name 3302 3303#### Response 3304 3305Completion status of reset statistics operation returned as a boolean. 3306 3307#### Example 3308 3309Example request: 3310 3311~~~json 3312{ 3313 "params": { 3314 "name": "ocf0" 3315 }, 3316 "jsonrpc": "2.0", 3317 "method": "bdev_ocf_reset_stats", 3318 "id": 1 3319} 3320~~~ 3321 3322Example response: 3323 3324~~~json 3325{ 3326 "jsonrpc": "2.0", 3327 "id": 1, 3328 "result": true 3329} 3330~~~ 3331 3332### bdev_ocf_get_bdevs {#rpc_bdev_ocf_get_bdevs} 3333 3334Get list of OCF devices including unregistered ones. 3335 3336#### Parameters 3337 3338Name | Optional | Type | Description 3339----------------------- | -------- | ----------- | ----------- 3340name | Optional | string | Name of OCF vbdev or name of cache device or name of core device 3341 3342#### Response 3343 3344Array of OCF devices with their current status, along with core and cache bdevs. 3345 3346#### Example 3347 3348Example request: 3349 3350~~~json 3351{ 3352 "jsonrpc": "2.0", 3353 "method": "bdev_ocf_get_bdevs", 3354 "id": 1 3355} 3356~~~ 3357 3358Example response: 3359 3360~~~json 3361{ 3362 "jsonrpc": "2.0", 3363 "id": 1, 3364 "result": [ 3365 { 3366 "name": "PartCache", 3367 "started": false, 3368 "cache": { 3369 "name": "Malloc0", 3370 "attached": true 3371 }, 3372 "core": { 3373 "name": "Malloc1", 3374 "attached": false 3375 } 3376 } 3377 ] 3378} 3379~~~ 3380 3381### bdev_ocf_set_cache_mode {#rpc_bdev_ocf_set_cache_mode} 3382 3383Set new cache mode on OCF bdev. 3384 3385#### Parameters 3386 3387Name | Optional | Type | Description 3388----------------------- | -------- | ----------- | ----------- 3389name | Required | string | Bdev name 3390mode | Required | string | OCF cache mode: wb, wt, pt, wa, wi, wo 3391 3392#### Response 3393 3394New cache mode name. 3395 3396#### Example 3397 3398Example request: 3399 3400~~~json 3401{ 3402 "params": { 3403 "name": "ocf0", 3404 "mode": "pt", 3405 }, 3406 "jsonrpc": "2.0", 3407 "method": "bdev_ocf_set_cache_mode", 3408 "id": 1 3409} 3410~~~ 3411 3412Example response: 3413 3414~~~json 3415{ 3416 "jsonrpc": "2.0", 3417 "id": 1, 3418 "result": "pt" 3419} 3420~~~ 3421 3422### bdev_ocf_set_seqcutoff {#rpc_bdev_ocf_set_seqcutoff} 3423 3424Set sequential cutoff parameters on all cores for the given OCF cache device. 3425A brief description of this functionality can be found in [OpenCAS documentation](https://open-cas.github.io/guide_tool_details.html#seq-cutoff). 3426 3427#### Parameters 3428 3429Name | Optional | Type | Description 3430----------------------- | -------- | ----------- | ----------- 3431name | Required | string | Bdev name 3432policy | Required | string | Sequential cutoff policy: always, full, never 3433threshold | Optional | int | Activation threshold in KiB 3434promotion_count | Optional | int | Promotion request count 3435 3436#### Example 3437 3438Example request: 3439 3440~~~json 3441{ 3442 "params": { 3443 "name": "ocf0", 3444 "policy": "full", 3445 "threshold": 4, 3446 "promotion_count": 2 3447 }, 3448 "jsonrpc": "2.0", 3449 "method": "bdev_ocf_set_seqcutoff", 3450 "id": 1 3451} 3452~~~ 3453 3454Example response: 3455 3456~~~json 3457{ 3458 "jsonrpc": "2.0", 3459 "id": 1, 3460 "result": true 3461} 3462~~~ 3463 3464### bdev_ocf_flush_start {#rpc_bdev_ocf_flush_start} 3465 3466Start flushing OCF cache device. 3467 3468Automatic flushes of dirty data are managed by OCF cleaning policy settings. 3469In addition to that, all dirty data is flushed to core device when there is 3470an attempt to stop caching. 3471On the other hand, this RPC call gives a possibility to flush dirty data manually 3472when there is a need for it, e.g. to speed up the shutdown process when data 3473hasn't been flushed for a long time. 3474This RPC returns immediately, and flush is then being performed in the 3475background. To see the status of flushing operation use bdev_ocf_flush_status. 3476 3477#### Parameters 3478 3479Name | Optional | Type | Description 3480----------------------- | -------- | ----------- | ----------- 3481name | Required | string | Bdev name 3482 3483#### Example 3484 3485Example request: 3486 3487~~~json 3488{ 3489 "params": { 3490 "name": "ocf0" 3491 }, 3492 "jsonrpc": "2.0", 3493 "method": "bdev_ocf_flush_start", 3494 "id": 1 3495} 3496~~~ 3497 3498Example response: 3499 3500~~~json 3501{ 3502 "jsonrpc": "2.0", 3503 "id": 1, 3504 "result": true 3505} 3506~~~ 3507 3508### bdev_ocf_flush_status {#rpc_bdev_ocf_flush_status} 3509 3510Get flush status of OCF cache device. 3511 3512Automatic flushes of dirty data are managed by OCF cleaning policy settings. 3513In addition to that, all dirty data is flushed to core device when there is 3514an attempt to stop caching. 3515On the other hand, there is a possibility to flush dirty data manually 3516when there is a need for it, e.g. to speed up the shutdown process when data 3517hasn't been flushed for a long time. 3518This RPC reports if such manual flush is still in progress and if the operation 3519was successful. To start manual flush use bdev_ocf_flush_start. 3520 3521#### Parameters 3522 3523Name | Optional | Type | Description 3524----------------------- | -------- | ----------- | ----------- 3525name | Required | string | Bdev name 3526 3527#### Response 3528 3529Status of OCF cache device flush. 3530 3531#### Example 3532 3533Example request: 3534 3535~~~json 3536{ 3537 "params": { 3538 "name": "ocf0" 3539 }, 3540 "jsonrpc": "2.0", 3541 "method": "bdev_ocf_flush_status", 3542 "id": 1 3543} 3544~~~ 3545 3546Example response: 3547 3548~~~json 3549{ 3550 "jsonrpc": "2.0", 3551 "id": 1, 3552 "result": { 3553 "in_progress": false, 3554 "status": 0 3555 } 3556} 3557~~~ 3558 3559### bdev_malloc_create {#rpc_bdev_malloc_create} 3560 3561Construct @ref bdev_config_malloc 3562 3563The `dif_type` parameter can have 0, 1, 2, or 3, and controls the check of the guard tag and the reference tag. 3564If the `dif_type` is 1, 2, or 3, the malloc bdev compares the guard tag to the CRC-16 computed over the block data. 3565If the `dif_type` is 1 or 2, the malloc bdev compares the reference tag to the computed reference tag. 3566The computed reference tag for the first block of the I/O is the `init_ref_tag` of the DIF context, and 3567the computed reference tag is incremented for each subsequent block. 3568If the `dif_type` is 3, the malloc bdev does not check the reference tag. 3569The application tag is not checked by the malloc bdev because the current block device API does not expose 3570it to the upper layer yet. 3571 3572#### Parameters 3573 3574Name | Optional | Type | Description 3575----------------------- | -------- | ----------- | ----------- 3576name | Optional | string | Bdev name to use 3577block_size | Required | number | Data block size in bytes -must be multiple of 512 3578num_blocks | Required | number | Number of blocks 3579uuid | Optional | string | UUID of new bdev 3580optimal_io_boundary | Optional | number | Split on optimal IO boundary, in number of blocks, default 0 3581md_size | Optional | number | Metadata size for this bdev (0, 8, 16, 32, 64, or 128). Default is 0. 3582md_interleave | Optional | boolean | Metadata location, interleaved if true, and separated if false. Default is false. 3583dif_type | Optional | number | Protection information type. Parameter --md-size needs to be set along --dif-type. Default=0 - no protection. 3584dif_is_head_of_md | Optional | boolean | Protection information is in the first 8 bytes of metadata. Default=false. 3585physical_block_size | Optional | number | Physical block size of device; must be a power of 2 and at least 512 3586 3587#### Result 3588 3589Name of newly created bdev. 3590 3591#### Example 3592 3593Example request: 3594 3595~~~json 3596{ 3597 "params": { 3598 "block_size": 4096, 3599 "num_blocks": 16384, 3600 "name": "Malloc0", 3601 "uuid": "2b6601ba-eada-44fb-9a83-a20eb9eb9e90", 3602 "optimal_io_boundary": 16 3603 }, 3604 "jsonrpc": "2.0", 3605 "method": "bdev_malloc_create", 3606 "id": 1 3607} 3608~~~ 3609 3610Example response: 3611 3612~~~json 3613{ 3614 "jsonrpc": "2.0", 3615 "id": 1, 3616 "result": "Malloc0" 3617} 3618~~~ 3619 3620### bdev_malloc_delete {#rpc_bdev_malloc_delete} 3621 3622Delete @ref bdev_config_malloc 3623 3624#### Parameters 3625 3626Name | Optional | Type | Description 3627----------------------- | -------- | ----------- | ----------- 3628name | Required | string | Bdev name 3629 3630#### Example 3631 3632Example request: 3633 3634~~~json 3635{ 3636 "params": { 3637 "name": "Malloc0" 3638 }, 3639 "jsonrpc": "2.0", 3640 "method": "bdev_malloc_delete", 3641 "id": 1 3642} 3643~~~ 3644 3645Example response: 3646 3647~~~json 3648{ 3649 "jsonrpc": "2.0", 3650 "id": 1, 3651 "result": true 3652} 3653~~~ 3654 3655### bdev_null_create {#rpc_bdev_null_create} 3656 3657Construct @ref bdev_config_null 3658 3659#### Parameters 3660 3661Name | Optional | Type | Description 3662----------------------- | -------- | ----------- | ----------- 3663name | Required | string | Bdev name to use 3664block_size | Required | number | Block size in bytes 3665num_blocks | Required | number | Number of blocks 3666uuid | Optional | string | UUID of new bdev 3667md_size | Optional | number | Metadata size for this bdev. Default=0. 3668dif_type | Optional | number | Protection information type. Parameter --md-size needs to be set along --dif-type. Default=0 - no protection. 3669dif_is_head_of_md | Optional | boolean | Protection information is in the first 8 bytes of metadata. Default=false. 3670 3671#### Result 3672 3673Name of newly created bdev. 3674 3675#### Example 3676 3677Example request: 3678 3679~~~json 3680{ 3681 "params": { 3682 "block_size": 4104, 3683 "num_blocks": 16384, 3684 "name": "Null0", 3685 "uuid": "2b6601ba-eada-44fb-9a83-a20eb9eb9e90", 3686 "md_size": 8, 3687 "dif_type": 1, 3688 "dif_is_head_of_md": true 3689 }, 3690 "jsonrpc": "2.0", 3691 "method": "bdev_null_create", 3692 "id": 1 3693} 3694~~~ 3695 3696Example response: 3697 3698~~~json 3699{ 3700 "jsonrpc": "2.0", 3701 "id": 1, 3702 "result": "Null0" 3703} 3704~~~ 3705 3706### bdev_null_delete {#rpc_bdev_null_delete} 3707 3708Delete @ref bdev_config_null. 3709 3710#### Parameters 3711 3712Name | Optional | Type | Description 3713----------------------- | -------- | ----------- | ----------- 3714name | Required | string | Bdev name 3715 3716#### Example 3717 3718Example request: 3719 3720~~~json 3721{ 3722 "params": { 3723 "name": "Null0" 3724 }, 3725 "jsonrpc": "2.0", 3726 "method": "bdev_null_delete", 3727 "id": 1 3728} 3729~~~ 3730 3731Example response: 3732 3733~~~json 3734{ 3735 "jsonrpc": "2.0", 3736 "id": 1, 3737 "result": true 3738} 3739~~~ 3740 3741### bdev_null_resize {#rpc_bdev_null_resize} 3742 3743Resize @ref bdev_config_null. 3744 3745#### Parameters 3746 3747Name | Optional | Type | Description 3748----------------------- | -------- | ----------- | ----------- 3749name | Required | string | Bdev name 3750new_size | Required | number | Bdev new capacity in MiB 3751 3752#### Example 3753 3754Example request: 3755 3756~~~json 3757{ 3758 "params": { 3759 "name": "Null0", 3760 "new_size": 4096 3761 }, 3762 "jsonrpc": "2.0", 3763 "method": "bdev_null_resize", 3764 "id": 1 3765} 3766~~~ 3767 3768Example response: 3769 3770~~~json 3771{ 3772 "jsonrpc": "2.0", 3773 "id": 1, 3774 "result": true 3775} 3776~~~ 3777 3778### bdev_aio_create {#rpc_bdev_aio_create} 3779 3780Construct @ref bdev_config_aio. 3781 3782#### Parameters 3783 3784Name | Optional | Type | Description 3785----------------------- | -------- | ----------- | ----------- 3786name | Required | string | Bdev name to use 3787filename | Required | number | Path to device or file 3788block_size | Optional | number | Block size in bytes 3789readonly | Optional | boolean | set aio bdev as read-only 3790fallocate | Optional | boolean | Enable UNMAP and WRITE ZEROES support. Intended only for testing purposes due to synchronous syscall. 3791 3792#### Result 3793 3794Name of newly created bdev. 3795 3796#### Example 3797 3798Example request: 3799 3800~~~json 3801{ 3802 "params": { 3803 "block_size": 4096, 3804 "name": "Aio0", 3805 "filename": "/tmp/aio_bdev_file" 3806 }, 3807 "jsonrpc": "2.0", 3808 "method": "bdev_aio_create", 3809 "id": 1 3810} 3811~~~ 3812 3813Example response: 3814 3815~~~json 3816{ 3817 "jsonrpc": "2.0", 3818 "id": 1, 3819 "result": "Aio0" 3820} 3821~~~ 3822 3823### bdev_aio_rescan {#rpc_bdev_aio_rescan} 3824 3825Rescan the size of @ref bdev_config_aio. 3826 3827#### Parameters 3828 3829Name | Optional | Type | Description 3830----------------------- | -------- | ----------- | ----------- 3831name | Required | string | Bdev name 3832 3833#### Example 3834 3835Example request: 3836 3837~~~json 3838{ 3839 "params": { 3840 "name": "Aio0" 3841 }, 3842 "jsonrpc": "2.0", 3843 "method": "bdev_aio_rescan", 3844 "id": 1 3845} 3846~~~ 3847 3848Example response: 3849 3850~~~json 3851{ 3852 "jsonrpc": "2.0", 3853 "id": 1, 3854 "result": true 3855} 3856~~~ 3857 3858### bdev_aio_delete {#rpc_bdev_aio_delete} 3859 3860Delete @ref bdev_config_aio. 3861 3862#### Parameters 3863 3864Name | Optional | Type | Description 3865----------------------- | -------- | ----------- | ----------- 3866name | Required | string | Bdev name 3867 3868#### Example 3869 3870Example request: 3871 3872~~~json 3873{ 3874 "params": { 3875 "name": "Aio0" 3876 }, 3877 "jsonrpc": "2.0", 3878 "method": "bdev_aio_delete", 3879 "id": 1 3880} 3881~~~ 3882 3883Example response: 3884 3885~~~json 3886{ 3887 "jsonrpc": "2.0", 3888 "id": 1, 3889 "result": true 3890} 3891~~~ 3892 3893### bdev_nvme_set_options {#rpc_bdev_nvme_set_options} 3894 3895Set global parameters for all bdev NVMe. This RPC may only be called before SPDK subsystems have been initialized 3896or any bdev NVMe has been created. 3897 3898Parameters, ctrlr_loss_timeout_sec, reconnect_delay_sec, and fast_io_fail_timeout_sec, are for I/O error resiliency. 3899They can be overridden if they are given by the RPC bdev_nvme_attach_controller. 3900 3901#### Parameters 3902 3903Name | Optional | Type | Description 3904-------------------------- | -------- | ----------- | ----------- 3905action_on_timeout | Optional | string | Action to take on command time out: none, reset or abort 3906timeout_us | Optional | number | Timeout for each command, in microseconds. If 0, don't track timeouts 3907timeout_admin_us | Optional | number | Timeout for each admin command, in microseconds. If 0, treat same as io timeouts ('timeout_us') 3908keep_alive_timeout_ms | Optional | number | Keep alive timeout period in milliseconds, default is 10s 3909arbitration_burst | Optional | number | The value is expressed as a power of two, a value of 111b indicates no limit 3910low_priority_weight | Optional | number | The maximum number of commands that the controller may launch at one time from a low priority queue 3911medium_priority_weight | Optional | number | The maximum number of commands that the controller may launch at one time from a medium priority queue 3912high_priority_weight | Optional | number | The maximum number of commands that the controller may launch at one time from a high priority queue 3913nvme_adminq_poll_period_us | Optional | number | How often the admin queue is polled for asynchronous events in microseconds 3914nvme_ioq_poll_period_us | Optional | number | How often I/O queues are polled for completions, in microseconds. Default: 0 (as fast as possible). 3915io_queue_requests | Optional | number | The number of requests allocated for each NVMe I/O queue. Default: 512. 3916delay_cmd_submit | Optional | boolean | Enable delaying NVMe command submission to allow batching of multiple commands. Default: `true`. 3917transport_retry_count | Optional | number | The number of attempts per I/O in the transport layer before an I/O fails. 3918bdev_retry_count | Optional | number | The number of attempts per I/O in the bdev layer before an I/O fails. -1 means infinite retries. 3919transport_ack_timeout | Optional | number | Time to wait ack until retransmission for RDMA or connection close for TCP. Range 0-31 where 0 means use default. 3920ctrlr_loss_timeout_sec | Optional | number | Time to wait until ctrlr is reconnected before deleting ctrlr. -1 means infinite reconnects. 0 means no reconnect. 3921reconnect_delay_sec | Optional | number | Time to delay a reconnect trial. 0 means no reconnect. 3922fast_io_fail_timeout_sec | Optional | number | Time to wait until ctrlr is reconnected before failing I/O to ctrlr. 0 means no such timeout. 3923disable_auto_failback | Optional | boolean | Disable automatic failback. The RPC bdev_nvme_set_preferred_path can be used to do manual failback. 3924generate_uuids | Optional | boolean | Enable generation of UUIDs for NVMe bdevs that do not provide this value themselves. 3925transport_tos | Optional | number | IPv4 Type of Service value. Only applicable for RDMA transport. Default: 0 (no TOS is applied). 3926nvme_error_stat | Optional | boolean | Enable collecting NVMe error counts. 3927rdma_srq_size | Optional | number | Set the size of a shared rdma receive queue. Default: 0 (disabled). 3928io_path_stat | Optional | boolean | Enable collecting I/O stat of each nvme bdev io path. Default: `false`. 3929allow_accel_sequence | Optional | boolean | Allow NVMe bdevs to advertise support for accel sequences if the controller also supports them. Default: `false`. 3930rdma_max_cq_size | Optional | number | Set the maximum size of a rdma completion queue. Default: 0 (unlimited) 3931rdma_cm_event_timeout_ms | Optional | number | Time to wait for RDMA CM events. Default: 0 (0 means using default value of driver). 3932dhchap_digests | Optional | list | List of allowed DH-HMAC-CHAP digests. 3933dhchap_dhgroups | Optional | list | List of allowed DH-HMAC-CHAP DH groups. 3934 3935#### Example 3936 3937Example request: 3938 3939~~~json 3940request: 3941{ 3942 "params": { 3943 "transport_retry_count": 5, 3944 "arbitration_burst": 3, 3945 "low_priority_weight": 8, 3946 "medium_priority_weight":8, 3947 "high_priority_weight": 8, 3948 "nvme_adminq_poll_period_us": 2000, 3949 "timeout_us": 10000000, 3950 "timeout_admin_us": 20000000, 3951 "keep_alive_timeout_ms": 600000, 3952 "action_on_timeout": "reset", 3953 "io_queue_requests" : 2048, 3954 "delay_cmd_submit": true 3955 "dhchap_digests": [ 3956 "sha384", 3957 "sha512" 3958 ], 3959 "dhchap_dhgroups": [ 3960 "ffdhe6144", 3961 "ffdhe8192" 3962 ] 3963 }, 3964 "jsonrpc": "2.0", 3965 "method": "bdev_nvme_set_options", 3966 "id": 1 3967} 3968~~~ 3969 3970Example response: 3971 3972~~~json 3973{ 3974 "jsonrpc": "2.0", 3975 "id": 1, 3976 "result": true 3977} 3978~~~ 3979 3980### bdev_nvme_set_hotplug {#rpc_bdev_nvme_set_hotplug} 3981 3982Change settings of the NVMe hotplug feature. If enabled, PCIe NVMe bdevs will be automatically discovered on insertion 3983and deleted on removal. 3984 3985#### Parameters 3986 3987Name | Optional | Type | Description 3988----------------------- | -------- | ----------- | ----------- 3989enable | Required | string | True to enable, false to disable 3990period_us | Optional | number | How often to poll for hot-insert and hot-remove events. Values: 0 - reset/use default or 1 to 10000000. 3991 3992#### Example 3993 3994Example request: 3995 3996~~~json 3997request: 3998{ 3999 "params": { 4000 "enable": true, 4001 "period_us": 2000 4002 }, 4003 "jsonrpc": "2.0", 4004 "method": "bdev_nvme_set_hotplug", 4005 "id": 1 4006} 4007~~~ 4008 4009Example response: 4010 4011~~~json 4012{ 4013 "jsonrpc": "2.0", 4014 "id": 1, 4015 "result": true 4016} 4017~~~ 4018 4019### bdev_nvme_attach_controller {#rpc_bdev_nvme_attach_controller} 4020 4021Construct @ref bdev_config_nvme. This RPC can also be used to add additional paths to an existing controller to enable 4022multipathing. This is done by specifying the `name` parameter as an existing controller. When adding an additional 4023path, the hostnqn, hostsvcid, hostaddr, prchk_reftag, and prchk_guard_arguments must not be specified and are assumed 4024to have the same value as the existing path. 4025 4026The parameters, `ctrlr_loss_timeout_sec`, `reconnect_delay_sec`, and `fast_io_fail_timeout_sec`, are mutually dependent. 4027If `reconnect_delay_sec` is non-zero, `ctrlr_loss_timeout_sec` has to be -1 or not less than `reconnect_delay_sec`. 4028If `reconnect_delay_sec` is zero, `ctrlr_loss_timeout_sec` has to be zero. 4029If `fast_io_fail_timeout_sec` is not zero, it has to be not less than `reconnect_delay_sec` and less than `ctrlr_loss_timeout_sec` if `ctrlr_loss_timeout_sec` is not -1. 4030 4031#### Result 4032 4033Array of names of newly created bdevs. 4034 4035#### Parameters 4036 4037Name | Optional | Type | Description 4038-------------------------- | -------- | ----------- | ----------- 4039name | Required | string | Name of the NVMe controller, prefix for each bdev name 4040trtype | Required | string | NVMe-oF target trtype: rdma or pcie 4041traddr | Required | string | NVMe-oF target address: ip or BDF 4042adrfam | Optional | string | NVMe-oF target adrfam: ipv4, ipv6, ib, fc, intra_host 4043trsvcid | Optional | string | NVMe-oF target trsvcid: port number 4044priority | Optional | string | Transport connection priority. Supported by TCP transport with POSIX sock module (see socket(7) man page). 4045subnqn | Optional | string | NVMe-oF target subnqn 4046hostnqn | Optional | string | NVMe-oF target hostnqn 4047hostaddr | Optional | string | NVMe-oF host address: ip address 4048hostsvcid | Optional | string | NVMe-oF host trsvcid: port number 4049prchk_reftag | Optional | bool | Enable checking of PI reference tag for I/O processing 4050prchk_guard | Optional | bool | Enable checking of PI guard for I/O processing 4051hdgst | Optional | bool | Enable TCP header digest 4052ddgst | Optional | bool | Enable TCP data digest 4053fabrics_connect_timeout_us | Optional | bool | Timeout for fabrics connect (in microseconds) 4054multipath | Optional | string | Multipathing behavior: disable, failover, multipath. Default is failover. 4055num_io_queues | Optional | number | The number of IO queues to request during initialization. Range: (0, UINT16_MAX + 1], Default is 1024. 4056ctrlr_loss_timeout_sec | Optional | number | Time to wait until ctrlr is reconnected before deleting ctrlr. -1 means infinite reconnects. 0 means no reconnect. 4057reconnect_delay_sec | Optional | number | Time to delay a reconnect trial. 0 means no reconnect. 4058fast_io_fail_timeout_sec | Optional | number | Time to wait until ctrlr is reconnected before failing I/O to ctrlr. 0 means no such timeout. 4059psk | Optional | string | Name of the pre-shared key to be used for TLS (Enables SSL socket implementation for TCP) 4060max_bdevs | Optional | number | The size of the name array for newly created bdevs. Default is 128. 4061dhchap_key | Optional | string | DH-HMAC-CHAP key name. 4062dhchap_ctrlr_key | Optional | string | DH-HMAC-CHAP controller key name. 4063 4064#### Example 4065 4066Example request: 4067 4068~~~json 4069{ 4070 "params": { 4071 "trtype": "pcie", 4072 "name": "Nvme0", 4073 "traddr": "0000:0a:00.0" 4074 }, 4075 "jsonrpc": "2.0", 4076 "method": "bdev_nvme_attach_controller", 4077 "id": 1 4078} 4079~~~ 4080 4081Example response: 4082 4083~~~json 4084{ 4085 "jsonrpc": "2.0", 4086 "id": 1, 4087 "result": [ 4088 "Nvme0n1" 4089 ] 4090} 4091~~~ 4092 4093### bdev_nvme_get_controllers {#rpc_bdev_nvme_get_controllers} 4094 4095Get information about NVMe controllers. 4096 4097#### Parameters 4098 4099The user may specify no parameters in order to list all NVMe controllers, or one NVMe controller may be 4100specified by name. 4101 4102Name | Optional | Type | Description 4103----------------------- | -------- | ----------- | ----------- 4104name | Optional | string | NVMe controller name 4105 4106#### Response 4107 4108The response is an array of objects containing information about the requested NVMe controllers. 4109 4110#### Example 4111 4112Example request: 4113 4114~~~json 4115{ 4116 "jsonrpc": "2.0", 4117 "id": 1, 4118 "method": "bdev_nvme_get_controllers", 4119 "params": { 4120 "name": "Nvme0" 4121 } 4122} 4123~~~ 4124 4125Example response: 4126 4127~~~json 4128{ 4129 "jsonrpc": "2.0", 4130 "id": 1, 4131 "result": [ 4132 { 4133 "name": "Nvme0", 4134 "trid": { 4135 "trtype": "PCIe", 4136 "traddr": "0000:05:00.0" 4137 }, 4138 "cntlid": 0 4139 } 4140 ] 4141} 4142~~~ 4143 4144### bdev_nvme_detach_controller {#rpc_bdev_nvme_detach_controller} 4145 4146Detach NVMe controller and delete any associated bdevs. Optionally, 4147If all of the transport ID options are specified, only remove that 4148transport path from the specified controller. If that is the only 4149available path for the controller, this will also result in the 4150controller being detached and the associated bdevs being deleted. 4151 4152returns true if the controller and bdevs were successfully destroyed 4153or the address was properly removed, false otherwise. 4154 4155#### Parameters 4156 4157Name | Optional | Type | Description 4158----------------------- | -------- | ----------- | ----------- 4159name | Required | string | Controller name 4160trtype | Optional | string | NVMe-oF target trtype: rdma or tcp 4161traddr | Optional | string | NVMe-oF target address: ip or BDF 4162adrfam | Optional | string | NVMe-oF target adrfam: ipv4, ipv6, ib, fc, intra_host 4163trsvcid | Optional | string | NVMe-oF target trsvcid: port number 4164subnqn | Optional | string | NVMe-oF target subnqn 4165hostaddr | Optional | string | NVMe-oF host address: ip 4166hostsvcid | Optional | string | NVMe-oF host svcid: port number 4167 4168#### Example 4169 4170Example requests: 4171 4172~~~json 4173{ 4174 "params": { 4175 "name": "Nvme0" 4176 }, 4177 "jsonrpc": "2.0", 4178 "method": "bdev_nvme_detach_controller", 4179 "id": 1 4180} 4181~~~ 4182 4183Example response: 4184 4185~~~json 4186{ 4187 "jsonrpc": "2.0", 4188 "id": 1, 4189 "result": true 4190} 4191~~~ 4192 4193### bdev_nvme_reset_controller {#rpc_bdev_nvme_reset_controller} 4194 4195For non NVMe multipath, reset an NVMe controller whose name is given by the `name` parameter. 4196 4197For NVMe multipath, an NVMe bdev controller is created and it aggregates multiple NVMe controllers. 4198The `name` parameter is an NVMe bdev controller name and the `cntlid` parameter is used to identify 4199an NVMe controller in the NVMe bdev controller. Reset only one NVMe-oF controller if the `cntlid` 4200parameter is specified, or all NVMe-oF controllers in an NVMe bdev controller if it is omitted. 4201 4202Returns true if the controller reset was successful, false otherwise. 4203 4204#### Parameters 4205 4206Name | Optional | Type | Description 4207----------------------- | -------- | ----------- | ----------- 4208name | Required | string | NVMe controller name (or NVMe bdev controller name for multipath) 4209cntlid | Optional | number | NVMe controller ID (used as NVMe controller name for multipath) 4210 4211#### Example 4212 4213Example request: 4214 4215~~~json 4216{ 4217 "jsonrpc": "2.0", 4218 "id": 1, 4219 "method": "bdev_nvme_reset_controller", 4220 "params": { 4221 "name": "Nvme0" 4222 } 4223} 4224~~~ 4225 4226Example response: 4227 4228~~~json 4229{ 4230 "jsonrpc": "2.0", 4231 "id": 1, 4232 "result": true 4233} 4234~~~ 4235 4236### bdev_nvme_enable_controller {#rpc_bdev_nvme_enable_controller} 4237 4238For non NVMe multipath, enable an NVMe controller whose name is given by the `name` parameter. 4239 4240For NVMe multipath, an NVMe bdev controller is created and it aggregates multiple NVMe controllers. 4241The `name` parameter is an NVMe bdev controller name and the `cntlid` parameter is used to identify 4242an NVMe controller in the NVMe bdev controller. Enable only one NVMe-oF controller if the `cntlid` 4243parameter is specified, or all NVMe-oF controllers in an NVMe bdev controller if it is omitted. 4244 4245Returns true if the controller enablement was successful or a controller was already enabled, false otherwise. 4246 4247#### Parameters 4248 4249Name | Optional | Type | Description 4250----------------------- | -------- | ----------- | ----------- 4251name | Required | string | NVMe controller name (or NVMe bdev controller name for multipath) 4252cntlid | Optional | number | NVMe controller ID (used as NVMe controller name for multipath) 4253 4254#### Example 4255 4256Example request: 4257 4258~~~json 4259{ 4260 "jsonrpc": "2.0", 4261 "id": 1, 4262 "method": "bdev_nvme_enable_controller", 4263 "params": { 4264 "name": "Nvme0" 4265 } 4266} 4267~~~ 4268 4269Example response: 4270 4271~~~json 4272{ 4273 "jsonrpc": "2.0", 4274 "id": 1, 4275 "result": true 4276} 4277~~~ 4278 4279### bdev_nvme_disable_controller {#rpc_bdev_nvme_disable_controller} 4280 4281For non NVMe multipath, disable an NVMe controller whose name is given by the `name` parameter. 4282 4283For NVMe multipath, an NVMe bdev controller is created and it aggregates multiple NVMe controllers. 4284The `name` parameter is an NVMe bdev controller name and the `cntlid` parameter is used to identify 4285an NVMe controller in the NVMe bdev controller. Disable only one NVMe-oF controller if the `cntlid` 4286parameter is specified, or all NVMe-oF controllers in an NVMe bdev controller if it is omitted. 4287 4288Returns true if the controller disablement was successful or a controller was already disabled, false otherwise. 4289 4290#### Parameters 4291 4292Name | Optional | Type | Description 4293----------------------- | -------- | ----------- | ----------- 4294name | Required | string | NVMe controller name (or NVMe bdev controller name for multipath) 4295cntlid | Optional | number | NVMe controller ID (used as NVMe controller name for multipath) 4296 4297#### Example 4298 4299Example request: 4300 4301~~~json 4302{ 4303 "jsonrpc": "2.0", 4304 "id": 1, 4305 "method": "bdev_nvme_disable_controller", 4306 "params": { 4307 "name": "Nvme0" 4308 } 4309} 4310~~~ 4311 4312Example response: 4313 4314~~~json 4315{ 4316 "jsonrpc": "2.0", 4317 "id": 1, 4318 "result": true 4319} 4320~~~ 4321 4322### bdev_nvme_start_discovery {#rpc_bdev_nvme_start_discovery} 4323 4324Start a discovery service for the discovery subsystem of the specified transport ID. 4325 4326The discovery service will read the discovery log page for the specified 4327discovery subsystem, and automatically attach to any subsystems found in the 4328log page. When determining a controller name to use when attaching, it will use 4329the 'name' parameter as a prefix, followed by a unique integer for that discovery 4330service. If the discovery service identifies a subsystem that has been previously 4331attached but is listed with a different path, it will use the same controller name 4332as the previous entry, and connect as a multipath. 4333 4334When the discovery service sees that a subsystem entry has been removed 4335from the log page, it will automatically detach from that controller as well. 4336 4337The 'name' is also used to later stop the discovery service. 4338 4339#### Parameters 4340 4341Name | Optional | Type | Description 4342-------------------------- | -------- | ----------- | ----------- 4343name | Required | string | Prefix for NVMe controllers 4344trtype | Required | string | NVMe-oF target trtype: rdma or tcp 4345traddr | Required | string | NVMe-oF target address: ip 4346adrfam | Optional | string | NVMe-oF target adrfam: ipv4, ipv6 4347trsvcid | Optional | string | NVMe-oF target trsvcid: port number 4348hostnqn | Optional | string | NVMe-oF target hostnqn 4349wait_for_attach | Optional | bool | Wait to complete until all discovered NVM subsystems are attached 4350attach_timeout_ms | Optional | number | Time to wait until the discovery and all discovered NVM subsystems are attached 4351ctrlr_loss_timeout_sec | Optional | number | Time to wait until ctrlr is reconnected before deleting ctrlr. -1 means infinite reconnects. 0 means no reconnect. 4352reconnect_delay_sec | Optional | number | Time to delay a reconnect trial. 0 means no reconnect. 4353fast_io_fail_timeout_sec | Optional | number | Time to wait until ctrlr is reconnected before failing I/O to ctrlr. 0 means no such timeout. 4354 4355#### Example 4356 4357Example request: 4358 4359~~~json 4360{ 4361 "jsonrpc": "2.0", 4362 "method": "bdev_nvme_start_discovery", 4363 "id": 1, 4364 "params": { 4365 "name": "nvme_auto", 4366 "trtype": "tcp", 4367 "traddr": "127.0.0.1", 4368 "hostnqn": "nqn.2021-12.io.spdk:host1", 4369 "adrfam": "ipv4", 4370 "trsvcid": "4420" 4371 } 4372} 4373~~~ 4374 4375Example response: 4376 4377~~~json 4378{ 4379 "jsonrpc": "2.0", 4380 "id": 1, 4381 "result": true 4382} 4383~~~ 4384 4385### bdev_nvme_stop_discovery {#rpc_bdev_nvme_stop_discovery} 4386 4387Stop a discovery service. This includes detaching any controllers that were 4388discovered via the service that is being stopped. 4389 4390#### Parameters 4391 4392Name | Optional | Type | Description 4393-------------------------- | -------- | ----------- | ----------- 4394name | Required | string | Name of service to stop 4395 4396#### Example 4397 4398Example request: 4399 4400~~~json 4401{ 4402 "jsonrpc": "2.0", 4403 "method": "bdev_nvme_stop_discovery", 4404 "id": 1, 4405 "params": { 4406 "name": "nvme_auto" 4407 } 4408} 4409~~~ 4410 4411Example response: 4412 4413~~~json 4414{ 4415 "jsonrpc": "2.0", 4416 "id": 1, 4417 "result": true 4418} 4419~~~ 4420 4421### bdev_nvme_get_discovery_info {#rpc_bdev_nvme_get_discovery_info} 4422 4423Get information about the discovery service. 4424 4425#### Example 4426 4427Example request: 4428~~~json 4429{ 4430 "jsonrpc": "2.0", 4431 "method": "bdev_nvme_get_discovery_info", 4432 "id": 1 4433} 4434~~~ 4435 4436Example response: 4437 4438~~~json 4439{ 4440 "jsonrpc": "2.0", 4441 "id": 1, 4442 "result": [ 4443 { 4444 "name": "nvme-disc", 4445 "trid": { 4446 "trtype": "TCP", 4447 "adrfam": "IPv4", 4448 "traddr": "127.0.0.1", 4449 "trsvcid": "8009", 4450 "subnqn": "nqn.2014-08.org.nvmexpress.discovery" 4451 }, 4452 "referrals": [] 4453 } 4454 ] 4455} 4456~~~ 4457 4458### bdev_nvme_get_io_paths {#rpc_bdev_nvme_get_io_paths} 4459 4460Display all or the specified NVMe bdev's active I/O paths. 4461 4462#### Parameters 4463 4464Name | Optional | Type | Description 4465----------------------- | -------- | ----------- | ----------- 4466name | Optional | string | Name of the NVMe bdev 4467 4468#### Example 4469 4470Example request: 4471 4472~~~json 4473{ 4474 "jsonrpc": "2.0", 4475 "method": "bdev_nvme_get_io_paths", 4476 "id": 1, 4477 "params": { 4478 "name": "Nvme0n1" 4479 } 4480} 4481~~~ 4482 4483Example response: 4484 4485~~~json 4486{ 4487 "jsonrpc": "2.0", 4488 "id": 1, 4489 "result": { 4490 "poll_groups": [ 4491 { 4492 "thread": "app_thread", 4493 "io_paths": [ 4494 { 4495 "bdev_name": "Nvme0n1", 4496 "cntlid": 0, 4497 "current": true, 4498 "connected": true, 4499 "accessible": true, 4500 "transport": { 4501 "trtype": "RDMA", 4502 "traddr": "1.2.3.4", 4503 "trsvcid": "4420", 4504 "adrfam": "IPv4" 4505 } 4506 } 4507 ] 4508 } 4509 ] 4510 } 4511} 4512~~~ 4513 4514### bdev_nvme_set_preferred_path {#rpc_bdev_nvme_set_preferred_path} 4515 4516Set the preferred I/O path for an NVMe bdev in multipath mode. 4517 4518NOTE: This RPC does not support NVMe bdevs in failover mode. 4519 4520#### Parameters 4521 4522Name | Optional | Type | Description 4523----------------------- | -------- | ----------- | ----------- 4524name | Required | string | Name of the NVMe bdev 4525cntlid | Required | number | NVMe-oF controller ID 4526 4527#### Example 4528 4529Example request: 4530 4531~~~json 4532{ 4533 "jsonrpc": "2.0", 4534 "method": "bdev_nvme_set_preferred_path", 4535 "id": 1, 4536 "params": { 4537 "name": "Nvme0n1", 4538 "cntlid": 0 4539 } 4540} 4541~~~ 4542 4543Example response: 4544 4545~~~json 4546{ 4547 "jsonrpc": "2.0", 4548 "id": 1, 4549 "result": true 4550} 4551~~~ 4552 4553### bdev_nvme_set_multipath_policy {#rpc_bdev_nvme_set_multipath_policy} 4554 4555Set multipath policy of the NVMe bdev in multipath mode or set multipath 4556selector for active-active multipath policy. 4557 4558#### Parameters 4559 4560Name | Optional | Type | Description 4561----------------------- | -------- | ----------- | ----------- 4562name | Required | string | Name of the NVMe bdev 4563policy | Required | string | Multipath policy: active_active or active_passive 4564selector | Optional | string | Multipath selector: round_robin or queue_depth, used in active-active mode. Default is round_robin 4565rr_min_io | Optional | number | Number of I/Os routed to current io path before switching to another for round-robin selector. The min value is 1. 4566 4567#### Example 4568 4569Example request: 4570 4571~~~json 4572{ 4573 "jsonrpc": "2.0", 4574 "method": "bdev_nvme_set_multipath_policy", 4575 "id": 1, 4576 "params": { 4577 "name": "Nvme0n1", 4578 "policy": "active_passive" 4579 } 4580} 4581~~~ 4582 4583Example response: 4584 4585~~~json 4586{ 4587 "jsonrpc": "2.0", 4588 "id": 1, 4589 "result": true 4590} 4591~~~ 4592 4593### bdev_nvme_get_path_iostat {#rpc_bdev_nvme_get_path_iostat} 4594 4595Get I/O statistics for IO paths of the block device. Call RPC bdev_nvme_set_options to set enable_io_path_stat 4596true before using this RPC. 4597 4598#### Parameters 4599 4600Name | Optional | Type | Description 4601----------------------- | -------- | ----------- | ----------- 4602name | Required | string | Name of the NVMe bdev 4603 4604#### Example 4605 4606Example request: 4607 4608~~~json 4609{ 4610 "jsonrpc": "2.0", 4611 "method": "bdev_nvme_get_path_iostat", 4612 "id": 1, 4613 "params": { 4614 "name": "NVMe0n1" 4615 } 4616} 4617~~~ 4618 4619Example response: 4620 4621~~~json 4622{ 4623 "jsonrpc": "2.0", 4624 "id": 1, 4625 "result": { 4626 "name": "NVMe0n1", 4627 "stats": [ 4628 { 4629 "trid": { 4630 "trtype": "TCP", 4631 "adrfam": "IPv4", 4632 "traddr": "10.169.204.201", 4633 "trsvcid": "4420", 4634 "subnqn": "nqn.2016-06.io.spdk:cnode1" 4635 }, 4636 "stat": { 4637 "bytes_read": 676691968, 4638 "num_read_ops": 165201, 4639 "bytes_written": 0, 4640 "num_write_ops": 0, 4641 "bytes_unmapped": 0, 4642 "num_unmap_ops": 0, 4643 "max_read_latency_ticks": 521487, 4644 "min_read_latency_ticks": 0, 4645 "write_latency_ticks": 0, 4646 "max_write_latency_ticks": 0, 4647 "min_write_latency_ticks": 0, 4648 "unmap_latency_ticks": 0, 4649 "max_unmap_latency_ticks": 0, 4650 "min_unmap_latency_ticks": 0, 4651 "copy_latency_ticks": 0, 4652 "max_copy_latency_ticks": 0, 4653 "min_copy_latency_ticks": 0 4654 } 4655 }, 4656 { 4657 "trid": { 4658 "trtype": "TCP", 4659 "adrfam": "IPv4", 4660 "traddr": "8.8.8.6", 4661 "trsvcid": "4420", 4662 "subnqn": "nqn.2016-06.io.spdk:cnode1" 4663 }, 4664 "stat": { 4665 "bytes_read": 677138432, 4666 "num_read_ops": 165317, 4667 "bytes_written": 0, 4668 "num_write_ops": 0, 4669 "bytes_unmapped": 0, 4670 "num_unmap_ops": 0, 4671 "max_read_latency_ticks": 108525, 4672 "min_read_latency_ticks": 0, 4673 "write_latency_ticks": 0, 4674 "max_write_latency_ticks": 0, 4675 "min_write_latency_ticks": 0, 4676 "unmap_latency_ticks": 0, 4677 "max_unmap_latency_ticks": 0, 4678 "min_unmap_latency_ticks": 0, 4679 "copy_latency_ticks": 0, 4680 "max_copy_latency_ticks": 0, 4681 "min_copy_latency_ticks": 0 4682 } 4683 } 4684 ] 4685 } 4686} 4687~~~ 4688 4689### bdev_nvme_cuse_register {#rpc_bdev_nvme_cuse_register} 4690 4691Register CUSE device on NVMe controller. 4692 4693#### Parameters 4694 4695Name | Optional | Type | Description 4696----------------------- | -------- | ----------- | ----------- 4697name | Required | string | Name of the NVMe controller 4698 4699#### Example 4700 4701Example request: 4702 4703~~~json 4704{ 4705 "jsonrpc": "2.0", 4706 "method": "bdev_nvme_cuse_register", 4707 "id": 1, 4708 "params": { 4709 "name": "Nvme0" 4710 } 4711} 4712~~~ 4713 4714Example response: 4715 4716~~~json 4717{ 4718 "jsonrpc": "2.0", 4719 "id": 1, 4720 "result": true 4721} 4722~~~ 4723 4724### bdev_nvme_cuse_unregister {#rpc_bdev_nvme_cuse_unregister} 4725 4726Unregister CUSE device on NVMe controller. 4727 4728#### Parameters 4729 4730Name | Optional | Type | Description 4731----------------------- | -------- | ----------- | ----------- 4732name | Required | string | Name of the NVMe controller 4733 4734#### Example 4735 4736Example request: 4737 4738~~~json 4739{ 4740 "params": { 4741 "name": "Nvme0" 4742 }, 4743 "jsonrpc": "2.0", 4744 "method": "bdev_nvme_cuse_unregister", 4745 "id": 1 4746} 4747~~~ 4748 4749Example response: 4750 4751~~~json 4752{ 4753 "jsonrpc": "2.0", 4754 "id": 1, 4755 "result": true 4756} 4757~~~ 4758 4759### bdev_zone_block_create {#rpc_bdev_zone_block_create} 4760 4761Creates a virtual zone device on top of existing non-zoned bdev. 4762 4763#### Parameters 4764 4765Name | Optional | Type | Description 4766----------------------- | -------- | ----------- | ----------- 4767name | Required | string | Name of the Zone device 4768base_bdev | Required | string | Name of the Base bdev 4769zone_capacity | Required | number | Zone capacity in blocks 4770optimal_open_zones | Required | number | Number of zones required to reach optimal write speed 4771 4772#### Example 4773 4774Example request: 4775 4776~~~json 4777{ 4778 "jsonrpc": "2.0", 4779 "method": "bdev_zone_block_create", 4780 "id": 1, 4781 "params": { 4782 "name": "zone1", 4783 "base_bdev": "NVMe0n1", 4784 "zone_capacity": 4096, 4785 "optimal_open_zones": 32 4786 } 4787} 4788~~~ 4789 4790Example response: 4791 4792~~~json 4793{ 4794 "jsonrpc": "2.0", 4795 "id": 1, 4796 "result": "zone1" 4797} 4798~~~ 4799 4800### bdev_zone_block_delete {#rpc_bdev_zone_block_delete} 4801 4802Deletes a virtual zone device. 4803 4804#### Parameters 4805 4806Name | Optional | Type | Description 4807----------------------- | -------- | ----------- | ----------- 4808name | Required | string | Name of the Zone device 4809 4810#### Example 4811 4812Example request: 4813 4814~~~json 4815{ 4816 "jsonrpc": "2.0", 4817 "method": "bdev_zone_block_delete", 4818 "id": 1, 4819 "params": { 4820 "name": "zone1" 4821 } 4822} 4823~~~ 4824 4825Example response: 4826 4827~~~json 4828{ 4829 "jsonrpc": "2.0", 4830 "id": 1, 4831 "result": true 4832} 4833~~~ 4834 4835### bdev_nvme_apply_firmware {#rpc_bdev_nvme_apply_firmware} 4836 4837Download and commit firmware to NVMe device. 4838 4839#### Parameters 4840 4841Name | Optional | Type | Description 4842----------------------- | -------- | ----------- | ----------- 4843filename | Required | string | filename of the firmware to download 4844bdev_name | Required | string | Name of the NVMe block device 4845 4846#### Example 4847 4848Example request: 4849 4850~~~json 4851{ 4852 "jsonrpc": "2.0", 4853 "method": "bdev_nvme_apply_firmware", 4854 "id": 1, 4855 "params": { 4856 "filename": "firmware_file", 4857 "bdev_name": "NVMe0n1" 4858 } 4859} 4860~~~ 4861 4862### bdev_nvme_get_transport_statistics {#rpc_bdev_nvme_get_transport_statistics} 4863 4864Get bdev_nvme poll group transport statistics. 4865 4866#### Parameters 4867 4868This RPC method accepts no parameters 4869 4870#### Response 4871 4872The response is an array of objects containing information about transport statistics per NVME poll group. 4873 4874#### Example 4875 4876Example request: 4877 4878~~~json 4879{ 4880 "jsonrpc": "2.0", 4881 "id": 1, 4882 "method": "bdev_nvme_get_transport_statistics", 4883} 4884~~~ 4885 4886Example response: 4887 4888~~~json 4889{ 4890 "jsonrpc": "2.0", 4891 "id": 1, 4892 "result": { 4893 "poll_groups": [ 4894 { 4895 "thread": "nvmf_tgt_poll_group_000", 4896 "transports": [ 4897 { 4898 "trname": "RDMA", 4899 "devices": [ 4900 { 4901 "dev_name": "mlx5_1", 4902 "polls": 137492169, 4903 "idle_polls": 137492169, 4904 "completions": 0, 4905 "queued_requests": 0, 4906 "total_send_wrs": 0, 4907 "send_sq_doorbell_updates": 0, 4908 "total_recv_wrs": 0, 4909 "recv_sq_doorbell_updates": 0 4910 }, 4911 { 4912 "dev_name": "mlx5_0", 4913 "polls": 137985185, 4914 "idle_polls": 137492169, 4915 "completions": 1474593, 4916 "queued_requests": 0, 4917 "total_send_wrs": 1474593, 4918 "send_sq_doorbell_updates": 426147, 4919 "total_recv_wrs": 1474721, 4920 "recv_sq_doorbell_updates": 348445 4921 } 4922 ] 4923 }, 4924 { 4925 "trname": "PCIE", 4926 "polls": 435419831, 4927 "idle_polls": 434901004, 4928 "completions": 1485543, 4929 "cq_doorbell_updates": 518827, 4930 "queued_requests": 0, 4931 "submitted_requests": 1485543, 4932 "sq_doorbell_updates": 516081 4933 } 4934 ] 4935 }, 4936 { 4937 "thread": "nvmf_tgt_poll_group_001", 4938 "transports": [ 4939 { 4940 "trname": "RDMA", 4941 "devices": [ 4942 { 4943 "dev_name": "mlx5_1", 4944 "polls": 140245630, 4945 "idle_polls": 140245630, 4946 "completions": 0, 4947 "queued_requests": 0, 4948 "total_send_wrs": 0, 4949 "send_sq_doorbell_updates": 0, 4950 "total_recv_wrs": 0, 4951 "recv_sq_doorbell_updates": 0 4952 }, 4953 { 4954 "dev_name": "mlx5_0", 4955 "polls": 140751844, 4956 "idle_polls": 140245630, 4957 "completions": 1489298, 4958 "queued_requests": 0, 4959 "total_send_wrs": 1489298, 4960 "send_sq_doorbell_updates": 433510, 4961 "total_recv_wrs": 1489426, 4962 "recv_sq_doorbell_updates": 357956 4963 } 4964 ] 4965 }, 4966 { 4967 "trname": "PCIE", 4968 "polls": 429044294, 4969 "idle_polls": 428525658, 4970 "completions": 1478730, 4971 "cq_doorbell_updates": 518636, 4972 "queued_requests": 0, 4973 "submitted_requests": 1478730, 4974 "sq_doorbell_updates": 511658 4975 } 4976 ] 4977 } 4978 ] 4979 } 4980} 4981~~~ 4982 4983### bdev_nvme_get_controller_health_info {#rpc_bdev_nvme_get_controller_health_info} 4984 4985Display health log of the required NVMe bdev device. 4986 4987#### Parameters 4988 4989Name | Optional | Type | Description 4990----------------------- | -------- | ----------- | ----------- 4991name | Required | string | Name of the NVMe bdev controller 4992 4993#### Response 4994 4995The response is the object containing information about health log of the NVMe controller. 4996 4997#### Example 4998 4999Example request: 5000 5001~~~json 5002{ 5003 "jsonrpc": "2.0", 5004 "method": "bdev_nvme_get_controller_health_info", 5005 "id": 1, 5006 "params": { 5007 "name": "Nvme0" 5008 } 5009} 5010~~~ 5011 5012Example response: 5013 5014~~~json 5015{ 5016 "model_number": "INTEL SSDPE2KX020T8", 5017 "serial_number": "BTLJ72430ARH2P0BGN", 5018 "firmware_revision": "VDV10110", 5019 "traddr": "0000:08:00.0", 5020 "temperature_celsius": 32, 5021 "available_spare_percentage": 99, 5022 "available_spare_threshold_percentage": 10, 5023 "percentage_used": 2, 5024 "data_units_read": 1013408619, 5025 "data_units_written": 346792685, 5026 "host_read_commands": 30457773282, 5027 "host_write_commands": 18949677715, 5028 "controller_busy_time": 4979, 5029 "power_cycles": 49, 5030 "power_on_hours": 31118, 5031 "unsafe_shutdowns": 18, 5032 "media_errors": 17, 5033 "num_err_log_entries": 19, 5034 "warning_temperature_time_minutes": 0, 5035 "critical_composite_temperature_time_minutes": 0 5036} 5037~~~ 5038 5039### bdev_rbd_register_cluster {#rpc_bdev_rbd_register_cluster} 5040 5041This method is available only if SPDK was build with Ceph RBD support. 5042 5043#### Parameters 5044 5045Name | Optional | Type | Description 5046----------------------- | -------- | ----------- | ----------- 5047name | Optional | string | Registered Rados cluster object name 5048user_id | Optional | string | Ceph ID (i.e. admin, not client.admin) 5049config_param | Optional | string map | Explicit librados configuration 5050config_file | Optional | string | File path of librados configuration file 5051key_file | Optional | string | File path of librados key file 5052core_mask | Optional | string | Core mask for librados IO context threads 5053 5054This RPC registers a Rados Cluster object handle which is only known 5055to rbd module, it uses user_id + config_param or user_id + config_file + 5056key_file or user_id + config_param + config_file + key_file to identify 5057a Rados cluster object. 5058 5059When accessing the Ceph cluster as some user other than "admin" (the 5060default), the "user_id" has to be set. 5061 5062The configuration items and secret key can be specified by setting config_param, 5063config_file and key_file, all of them, or none of them. If only config_param is 5064passed, all key/value pairs are passed to rados_conf_set to configure cluster access. 5065In practice, "mon_host" (= list of monitor address+port) and "key" (= the secret key 5066stored in Ceph keyrings) are enough. If config_file and key_file are specified, they must 5067exist with all relevant settings for accessing the Ceph cluster. If config_param, config_file 5068and key_file are specified, get the key/value pairs from config_file first and set to 5069rados_conf_set function, then set pairs in config_param and keyring in key_file. If nothing 5070is specified, it will get configuration file and key file from the default location 5071/etc/ceph/ceph.conf and /etc/ceph/ceph.client.user_id.keyring. 5072 5073#### Result 5074 5075Name of newly created Rados cluster object. 5076 5077#### Example 5078 5079Example request: 5080 5081~~ 5082{ 5083 "params": { 5084 "name": "rbd_cluster", 5085 "user_id": cinder, 5086 "config_file": "/root/ceph_conf/ceph.conf", 5087 "key_file": "/root/ceph_conf/ceph.client.cinder.keyring" 5088 }, 5089 "jsonrpc": "2.0", 5090 "method": "bdev_rbd_register_cluster", 5091 "id": 1 5092} 5093~~ 5094 5095Example response: 5096 5097~~ 5098response: 5099{ 5100 "jsonrpc": "2.0", 5101 "id": 1, 5102 "result": "rbd_cluster" 5103} 5104~~ 5105 5106### bdev_rbd_unregister_cluster {#rpc_bdev_rbd_unregister_cluster} 5107 5108This method is available only if SPDK was build with Ceph RBD support. 5109If there is still rbd bdev using this cluster, the unregisteration operation 5110will fail. 5111 5112#### Result 5113 5114`true` if Rados cluster object with provided name was deleted or `false` otherwise. 5115 5116#### Parameters 5117 5118Name | Optional | Type | Description 5119----------------------- | -------- | ----------- | ------------------------- 5120name | Required | string | Rados cluster object name 5121 5122#### Example 5123 5124Example request: 5125 5126~~ 5127{ 5128 "params": { 5129 "name": "rbd_cluster" 5130 }, 5131 "jsonrpc": "2.0", 5132 "method": "bdev_rbd_unregister_cluster", 5133 "id": 1 5134} 5135~~ 5136 5137Example response: 5138 5139~~ 5140{ 5141 "jsonrpc": "2.0", 5142 "id": 1, 5143 "result": true 5144} 5145~~ 5146 5147### bdev_rbd_get_clusters_info {#rpc_bdev_rbd_get_clusters_info} 5148 5149This method is available only if SPDK was build with Ceph RBD support. 5150 5151#### Result 5152 5153Returns the cluster info of the Rados Cluster name if provided. Otherwise, it 5154returns the cluster info of every registered Raods Cluster name. 5155 5156#### Parameters 5157 5158Name | Optional | Type | Description 5159----------------------- | -------- | ----------- | ------------------------- 5160name | Optional | string | Rados cluster object name 5161 5162#### Example 5163 5164Example request: 5165 5166~~ 5167{ 5168 "params": { 5169 "name": "rbd_cluster" 5170 }, 5171 "jsonrpc": "2.0", 5172 "method": "bdev_rbd_get_clusters_info", 5173 "id": 1 5174} 5175~~ 5176 5177Example response: 5178 5179~~ 5180{ 5181 "jsonrpc": "2.0", 5182 "cluster_name": "rbd_cluster" 5183} 5184~~ 5185 5186### bdev_rbd_create {#rpc_bdev_rbd_create} 5187 5188Create @ref bdev_config_rbd bdev 5189 5190This method is available only if SPDK was build with Ceph RBD support. 5191 5192#### Parameters 5193 5194Name | Optional | Type | Description 5195----------------------- | -------- | ----------- | ----------- 5196name | Optional | string | Bdev name 5197user_id | Optional | string | Ceph ID (i.e. admin, not client.admin) 5198pool_name | Required | string | Pool name 5199rbd_name | Required | string | Image name 5200block_size | Required | number | Block size 5201config | Optional | string map | Explicit librados configuration 5202cluster_name | Optional | string | Rados cluster object name created in this module. 5203uuid | Optional | string | UUID of new bdev 5204 5205If no config is specified, Ceph configuration files must exist with 5206all relevant settings for accessing the pool. If a config map is 5207passed, the configuration files are ignored and instead all key/value 5208pairs are passed to rados_conf_set to configure cluster access. In 5209practice, "mon_host" (= list of monitor address+port) and "key" (= the 5210secret key stored in Ceph keyrings) are enough. 5211 5212When accessing the image as some user other than "admin" (the 5213default), the "user_id" has to be set. 5214 5215If provided with cluster_name option, it will use the Rados cluster object 5216referenced by the name (created by bdev_rbd_register_cluster RPC) and ignores 5217"user_id + config" combination to create its own Rados cluster. In this scenario, 5218all the bdevs will share the same cluster with one connection of Ceph in librbd module. 5219Performance tuning on the I/O workload could be done by estimating how many io_contxt 5220threads and messager threads in Ceph side and how many cores would be reasonable to provide 5221for SPDK to get up to your projections. 5222 5223#### Result 5224 5225Name of newly created bdev. 5226 5227#### Example 5228 5229Example request with `key` from `/etc/ceph/ceph.client.admin.keyring`: 5230 5231~~~json 5232{ 5233 "params": { 5234 "pool_name": "rbd", 5235 "rbd_name": "foo", 5236 "config": { 5237 "mon_host": "192.168.7.1:6789,192.168.7.2:6789", 5238 "key": "AQDwf8db7zR1GRAA5k7NKXjS5S5V4mntwUDnGQ==", 5239 } 5240 "block_size": 4096, 5241 "uuid": "76210ea4-7920-40a0-a07b-8992a7443c76" 5242 }, 5243 "jsonrpc": "2.0", 5244 "method": "bdev_rbd_create", 5245 "id": 1 5246} 5247~~~ 5248 5249Example response: 5250 5251~~~json 5252response: 5253{ 5254 "jsonrpc": "2.0", 5255 "id": 1, 5256 "result": "Ceph0" 5257} 5258~~~ 5259 5260Example request with `cluster_name`: 5261 5262~~ 5263{ 5264 "params": { 5265 "pool_name": "rbd", 5266 "rbd_name": "foo", 5267 "block_size": 4096, 5268 "cluster_name": "rbd_cluster" 5269 }, 5270 "jsonrpc": "2.0", 5271 "method": "bdev_rbd_create", 5272 "id": 1 5273} 5274~~ 5275 5276Example response: 5277 5278~~ 5279response: 5280{ 5281 "jsonrpc": "2.0", 5282 "id": 1, 5283 "result": "Ceph0" 5284} 5285~~ 5286 5287### bdev_rbd_delete {#rpc_bdev_rbd_delete} 5288 5289Delete @ref bdev_config_rbd bdev 5290 5291This method is available only if SPDK was build with Ceph RBD support. 5292 5293#### Result 5294 5295`true` if bdev with provided name was deleted or `false` otherwise. 5296 5297#### Parameters 5298 5299Name | Optional | Type | Description 5300----------------------- | -------- | ----------- | ----------- 5301name | Required | string | Bdev name 5302 5303#### Example 5304 5305Example request: 5306 5307~~~json 5308{ 5309 "params": { 5310 "name": "Rbd0" 5311 }, 5312 "jsonrpc": "2.0", 5313 "method": "bdev_rbd_delete", 5314 "id": 1 5315} 5316~~~ 5317 5318Example response: 5319 5320~~~json 5321{ 5322 "jsonrpc": "2.0", 5323 "id": 1, 5324 "result": true 5325} 5326~~~ 5327 5328### bdev_rbd_resize {#rpc_bdev_rbd_resize} 5329 5330Resize @ref bdev_config_rbd bdev 5331 5332This method is available only if SPDK was build with Ceph RBD support. 5333 5334#### Result 5335 5336`true` if bdev with provided name was resized or `false` otherwise. 5337 5338#### Parameters 5339 5340Name | Optional | Type | Description 5341----------------------- | -------- | ----------- | ----------- 5342name | Required | string | Bdev name 5343new_size | Required | int | New bdev size for resize operation in MiB 5344 5345#### Example 5346 5347Example request: 5348 5349~~~json 5350{ 5351 "params": { 5352 "name": "Rbd0" 5353 "new_size": "4096" 5354 }, 5355 "jsonrpc": "2.0", 5356 "method": "bdev_rbd_resize", 5357 "id": 1 5358} 5359~~~ 5360 5361Example response: 5362 5363~~~json 5364{ 5365 "jsonrpc": "2.0", 5366 "id": 1, 5367 "result": true 5368} 5369~~~ 5370 5371### bdev_delay_create {#rpc_bdev_delay_create} 5372 5373Create delay bdev. This bdev type redirects all IO to it's base bdev and inserts a delay on the completion 5374path to create an artificial drive latency. All latency values supplied to this bdev should be in microseconds. 5375 5376#### Parameters 5377 5378Name | Optional | Type | Description 5379----------------------- | -------- | ----------- | ----------- 5380name | Required | string | Bdev name 5381base_bdev_name | Required | string | Base bdev name 5382avg_read_latency | Required | number | average read latency (us) 5383p99_read_latency | Required | number | p99 read latency (us) 5384avg_write_latency | Required | number | average write latency (us) 5385p99_write_latency | Required | number | p99 write latency (us) 5386uuid | Optional | string | UUID of new bdev 5387 5388#### Result 5389 5390Name of newly created bdev. 5391 5392#### Example 5393 5394Example request: 5395 5396~~~json 5397{ 5398 "params": { 5399 "base_bdev_name": "Null0", 5400 "name": "Delay0", 5401 "avg_read_latency": "15", 5402 "p99_read_latency": "50", 5403 "avg_write_latency": "40", 5404 "p99_write_latency": "110", 5405 }, 5406 "jsonrpc": "2.0", 5407 "method": "bdev_delay_create", 5408 "id": 1 5409} 5410~~~ 5411 5412Example response: 5413 5414~~~json 5415{ 5416 "jsonrpc": "2.0", 5417 "id": 1, 5418 "result": "Delay0" 5419} 5420~~~ 5421 5422### bdev_delay_delete {#rpc_bdev_delay_delete} 5423 5424Delete delay bdev. 5425 5426#### Parameters 5427 5428Name | Optional | Type | Description 5429----------------------- | -------- | ----------- | ----------- 5430name | Required | string | Bdev name 5431 5432#### Example 5433 5434Example request: 5435 5436~~~json 5437{ 5438 "params": { 5439 "name": "Delay0" 5440 }, 5441 "jsonrpc": "2.0", 5442 "method": "bdev_delay_delete", 5443 "id": 1 5444} 5445 5446~~~ 5447 5448Example response: 5449 5450~~~json 5451{ 5452 "jsonrpc": "2.0", 5453 "id": 1, 5454 "result": true 5455} 5456~~~ 5457 5458### bdev_delay_update_latency {#rpc_bdev_delay_update_latency} 5459 5460Update a target latency value associated with a given delay bdev. Any currently 5461outstanding I/O will be completed with the old latency. 5462 5463#### Parameters 5464 5465Name | Optional | Type | Description 5466----------------------- | -------- | ----------- | ----------- 5467delay_bdev_name | Required | string | Name of the delay bdev 5468latency_type | Required | string | One of: avg_read, avg_write, p99_read, p99_write 5469latency_us | Required | number | The new latency value in microseconds 5470 5471#### Result 5472 5473Name of newly created bdev. 5474 5475#### Example 5476 5477Example request: 5478 5479~~~json 5480{ 5481 "params": { 5482 "delay_bdev_name": "Delay0", 5483 "latency_type": "avg_read", 5484 "latency_us": "100", 5485 }, 5486 "jsonrpc": "2.0", 5487 "method": "bdev_delay_update_latency", 5488 "id": 1 5489} 5490~~~ 5491 5492Example response: 5493 5494~~~json 5495{ 5496 "result": "true" 5497} 5498~~~ 5499 5500### bdev_error_create {#rpc_bdev_error_create} 5501 5502Construct error bdev. 5503 5504#### Parameters 5505 5506Name | Optional | Type | Description 5507----------------------- | -------- | ----------- | ----------- 5508base_name | Required | string | Base bdev name 5509uuid | Optional | string | UUID for this bdev 5510 5511#### Example 5512 5513Example request: 5514 5515~~~json 5516{ 5517 "params": { 5518 "base_name": "Malloc0" 5519 }, 5520 "jsonrpc": "2.0", 5521 "method": "bdev_error_create", 5522 "id": 1 5523} 5524~~~ 5525 5526Example response: 5527 5528~~~json 5529{ 5530 "jsonrpc": "2.0", 5531 "id": 1, 5532 "result": true 5533} 5534~~~ 5535 5536### bdev_error_delete {#rpc_bdev_error_delete} 5537 5538Delete error bdev 5539 5540#### Result 5541 5542`true` if bdev with provided name was deleted or `false` otherwise. 5543 5544#### Parameters 5545 5546Name | Optional | Type | Description 5547----------------------- | -------- | ----------- | ----------- 5548name | Required | string | Error bdev name 5549 5550#### Example 5551 5552Example request: 5553 5554~~~json 5555{ 5556 "params": { 5557 "name": "EE_Malloc0" 5558 }, 5559 "jsonrpc": "2.0", 5560 "method": "bdev_error_delete", 5561 "id": 1 5562} 5563~~~ 5564 5565Example response: 5566 5567~~~json 5568{ 5569 "jsonrpc": "2.0", 5570 "id": 1, 5571 "result": true 5572} 5573~~~ 5574 5575### bdev_error_inject_error {#rpc_bdev_error_inject_error} 5576 5577Inject an error via an error bdev. Create an error bdev on base bdev first. Default 'num' 5578value is 1 and if 'num' is set to zero, the specified injection is disabled. 5579 5580#### Parameters 5581 5582Name | Optional | Type | Description 5583----------------------- | -------- | ----------- | ----------- 5584name | Required | string | Name of the error injection bdev 5585io_type | Required | string | io type 'clear' 'read' 'write' 'unmap' 'flush' 'all' 5586error_type | Required | string | error type 'failure' 'pending' 'corrupt_data' 'nomem' 5587num | Optional | int | the number of commands you want to fail.(default:1) 5588queue_depth | Optional | int | the queue depth at which to trigger the error 5589corrupt_offset | Optional | int | the offset in bytes to xor with corrupt_value 5590corrupt_value | Optional | int | the value for xor (1-255, 0 is invalid) 5591 5592#### Example 5593 5594Example request: 5595 5596~~~json 5597{ 5598 "jsonrpc": "2.0", 5599 "method": "bdev_error_inject_error", 5600 "id": 1, 5601 "params": { 5602 "name": "EE_Malloc0", 5603 "io_type": "write", 5604 "error_type": "pending", 5605 "num": 1 5606 } 5607} 5608~~~ 5609 5610Example response: 5611 5612~~~json 5613{ 5614 "jsonrpc": "2.0", 5615 "id": 1, 5616 "result": true 5617} 5618~~~ 5619 5620### bdev_iscsi_set_options {#rpc_bdev_iscsi_set_options} 5621 5622This RPC can be called at any time, but the new value will only take effect for new iSCSI bdevs. 5623 5624#### Parameters 5625 5626Name | Optional | Type | Description 5627-------------------------- | -------- | ----------- | ----------- 5628timeout_sec | Optional | number | Timeout for command, in seconds, if 0, don't track timeout 5629 5630#### Example 5631 5632Example request: 5633 5634~~~json 5635request: 5636{ 5637 "params": { 5638 "timeout_sec": 30 5639 }, 5640 "jsonrpc": "2.0", 5641 "method": "bdev_iscsi_set_options", 5642 "id": 1 5643} 5644~~~ 5645 5646Example response: 5647 5648~~~json 5649{ 5650 "jsonrpc": "2.0", 5651 "id": 1, 5652 "result": true 5653} 5654~~~ 5655 5656### bdev_iscsi_create {#rpc_bdev_iscsi_create} 5657 5658Connect to iSCSI target and create bdev backed by this connection. 5659 5660This method is available only if SPDK was build with iSCSI initiator support. 5661 5662#### Parameters 5663 5664Name | Optional | Type | Description 5665----------------------- | -------- | ----------- | ----------- 5666name | Required | string | Bdev name 5667initiator_iqn | Required | string | IQN name used during connection 5668url | Required | string | iSCSI resource URI 5669 5670#### Result 5671 5672Name of newly created bdev. 5673 5674#### Example 5675 5676Example request: 5677 5678~~~json 5679{ 5680 "params": { 5681 "url": "iscsi://127.0.0.1/iqn.2016-06.io.spdk:disk1/0", 5682 "initiator_iqn": "iqn.2016-06.io.spdk:init", 5683 "name": "iSCSI0" 5684 }, 5685 "jsonrpc": "2.0", 5686 "method": "bdev_iscsi_create", 5687 "id": 1 5688} 5689~~~ 5690 5691Example response: 5692 5693~~~json 5694{ 5695 "jsonrpc": "2.0", 5696 "id": 1, 5697 "result": "iSCSI0" 5698} 5699~~~ 5700 5701### bdev_iscsi_delete {#rpc_bdev_iscsi_delete} 5702 5703Delete iSCSI bdev and terminate connection to target. 5704 5705This method is available only if SPDK was built with iSCSI initiator support. 5706 5707#### Parameters 5708 5709Name | Optional | Type | Description 5710----------------------- | -------- | ----------- | ----------- 5711name | Required | string | Bdev name 5712 5713#### Example 5714 5715Example request: 5716 5717~~~json 5718{ 5719 "params": { 5720 "name": "iSCSI0" 5721 }, 5722 "jsonrpc": "2.0", 5723 "method": "bdev_iscsi_delete", 5724 "id": 1 5725} 5726~~~ 5727 5728Example response: 5729 5730~~~json 5731{ 5732 "jsonrpc": "2.0", 5733 "id": 1, 5734 "result": true 5735} 5736~~~ 5737 5738### bdev_ftl_create {#rpc_bdev_ftl_create} 5739 5740Create FTL bdev. 5741 5742This RPC is subject to change. 5743 5744#### Parameters 5745 5746Name | Optional | Type | Description 5747----------------------- | -------- | ----------- | ----------- 5748name | Required | string | Bdev name 5749base_bdev | Required | string | Name of the base device 5750cache | Required | string | Name of the cache device 5751uuid | Optional | string | UUID of restored bdev (not applicable when creating new instance) 5752core_mask | Optional | string | CPU core(s) possible for placement of the ftl core thread, application main thread by default 5753overprovisioning | Optional | int | Percentage of base device used for relocation, 20% by default 5754fast_shutdown | Optional | bool | When set FTL will minimize persisted data on target application shutdown and rely on shared memory during next load 5755l2p_dram_limit | Optional | int | DRAM limit for most recent L2P addresses (default 2048 MiB) 5756 5757#### Result 5758 5759Name of newly created bdev. 5760 5761#### Example 5762 5763Example request: 5764 5765~~~json 5766{ 5767 "params": { 5768 "name": "ftl0", 5769 "base_bdev": "nvme0n1", 5770 "cache": "nvme1n1", 5771 "uuid": "4a7481ce-786f-41a0-9b86-8f7465c8f4d3", 5772 "core_mask": "[0]", 5773 "overprovisioning": 10 5774 }, 5775 "jsonrpc": "2.0", 5776 "method": "bdev_ftl_create", 5777 "id": 1 5778} 5779~~~ 5780 5781Example response: 5782 5783~~~json 5784{ 5785 "jsonrpc": "2.0", 5786 "id": 1, 5787 "result": { 5788 "name" : "ftl0" 5789 "uuid" : "4a7481ce-786f-41a0-9b86-8f7465c8f4d3" 5790 } 5791} 5792~~~ 5793 5794### bdev_ftl_load {#rpc_bdev_ftl_load} 5795 5796Loads FTL bdev. 5797 5798This RPC is subject to change. 5799 5800#### Parameters 5801 5802Name | Optional | Type | Description 5803----------------------- | -------- | ----------- | ----------- 5804name | Required | string | Bdev name 5805base_bdev | Required | string | Name of the base device 5806cache | Required | string | Name of the cache device 5807uuid | Required | string | UUID of restored bdev 5808core_mask | Optional | string | CPU core(s) possible for placement of the ftl core thread, application main thread by default 5809overprovisioning | Optional | int | Percentage of base device used for relocation, 20% by default 5810fast_shutdown | Optional | bool | When set FTL will minimize persisted data on target application shutdown and rely on shared memory during next load 5811l2p_dram_limit | Optional | int | DRAM limit for most recent L2P addresses (default 2048 MiB) 5812 5813#### Result 5814 5815Name of loaded bdev. 5816 5817#### Example 5818 5819Example request: 5820 5821~~~json 5822{ 5823 "params": { 5824 "name": "ftl0", 5825 "base_bdev": "nvme0n1", 5826 "cache": "nvme1n1", 5827 "uuid": "4a7481ce-786f-41a0-9b86-8f7465c8f4d3", 5828 "core_mask": "[0]", 5829 "overprovisioning": 10 5830 }, 5831 "jsonrpc": "2.0", 5832 "method": "bdev_ftl_load", 5833 "id": 1 5834} 5835~~~ 5836 5837Example response: 5838 5839~~~json 5840{ 5841 "jsonrpc": "2.0", 5842 "id": 1, 5843 "result": { 5844 "name" : "ftl0" 5845 "uuid" : "4a7481ce-786f-41a0-9b86-8f7465c8f4d3" 5846 } 5847} 5848~~~ 5849 5850### bdev_ftl_delete {#rpc_bdev_ftl_delete} 5851 5852Delete FTL bdev. 5853 5854This RPC is subject to change. 5855 5856#### Parameters 5857 5858Name | Optional | Type | Description 5859----------------------- | -------- | ----------- | ----------- 5860name | Required | string | Bdev name 5861fast_shutdown | Optional | bool | When set FTL will minimize persisted data during deletion and rely on shared memory during next load 5862 5863#### Example 5864 5865Example request: 5866 5867~~~json 5868{ 5869 "params": { 5870 "name": "ftl0" 5871 }, 5872 "jsonrpc": "2.0", 5873 "method": "bdev_ftl_delete", 5874 "id": 1 5875} 5876~~~ 5877 5878Example response: 5879 5880~~~json 5881{ 5882 "jsonrpc": "2.0", 5883 "id": 1, 5884 "result": true 5885} 5886~~~ 5887 5888### bdev_ftl_unload {#rpc_bdev_ftl_unload} 5889 5890Unloads FTL bdev. 5891 5892This RPC is subject to change. 5893 5894#### Parameters 5895 5896Name | Optional | Type | Description 5897----------------------- | -------- | ----------- | ----------- 5898name | Required | string | Bdev name 5899fast_shutdown | Optional | bool | When set FTL will minimize persisted data during deletion and rely on shared memory during next load 5900 5901#### Example 5902 5903Example request: 5904 5905~~~json 5906{ 5907 "params": { 5908 "name": "ftl0" 5909 }, 5910 "jsonrpc": "2.0", 5911 "method": "bdev_ftl_unload", 5912 "id": 1 5913} 5914~~~ 5915 5916Example response: 5917 5918~~~json 5919{ 5920 "jsonrpc": "2.0", 5921 "id": 1, 5922 "result": true 5923} 5924~~~ 5925 5926### bdev_ftl_unmap {#rpc_bdev_ftl_unmap} 5927 5928Unmap range of LBAs. 5929 5930This RPC is subject to change. 5931 5932#### Parameters 5933 5934Name | Optional | Type | Description 5935----------------------- | -------- | ----------- | ----------- 5936name | Required | string | Bdev name 5937lba | Required | number | start lba, aligned to 1024 5938num_blocks | Required | number | number of blocks, aligned to 1024 5939 5940#### Example 5941 5942Example request: 5943 5944~~~json 5945{ 5946 "params": { 5947 "name": "ftl0" 5948 "lba": "0" 5949 "num_blocks": "1024" 5950 }, 5951 "jsonrpc": "2.0", 5952 "method": "bdev_ftl_unmap", 5953 "id": 1 5954} 5955~~~ 5956 5957Example response: 5958 5959~~~json 5960{ 5961 "jsonrpc": "2.0", 5962 "id": 1, 5963 "result": true 5964} 5965~~~ 5966 5967### bdev_ftl_get_stats {#rpc_bdev_ftl_get_stats} 5968 5969Get IO statistics for FTL bdev 5970 5971This RPC is subject to change. 5972 5973#### Parameters 5974 5975Name | Optional | Type | Description 5976----------------------- | -------- | ----------- | ----------- 5977name | Required | string | Bdev name 5978 5979#### Response 5980 5981The response is an object containing IO statistics for an FTL instance, split into multiple subobjects: 5982 5983- `user` - contains information about number of IOs, and errors for any incoming requests, 5984- `cmp` - information about IO for the compaction process, 5985- `gc` - information about IO for the garbage collection process, 5986- `md_base` - internal metadata requests to the base FTL device, 5987- `md_nv_cache` - internal metadata requests to the cache device, 5988- `l2p` - requests done on the L2P cache region. 5989 5990Each subobject contains the following information: 5991 5992- `ios` - describes the total number of IOs requested, 5993- `blocks` - the total number of requested blocks, 5994- `errors` - describes the number of detected errors for a given operation, with the following distinctions: 5995 - `media` - media errors, 5996 - `crc` - mismatch in calculated CRC versus saved checksum in the metadata, 5997 - `other` - any other errors. 5998 5999#### Example 6000 6001Example request: 6002 6003~~~json 6004{ 6005 "params": { 6006 "name": "ftl0" 6007 }, 6008 "jsonrpc": "2.0", 6009 "method": "bdev_ftl_get_stats", 6010 "id": 1 6011} 6012~~~ 6013 6014Example response: 6015 6016~~~json 6017{ 6018 "jsonrpc": "2.0", 6019 "id": 1, 6020 "result": { 6021 "name": "ftl0", 6022 "user": { 6023 "read": { 6024 "ios": 0, 6025 "blocks": 0, 6026 "errors": { 6027 "media": 0, 6028 "crc": 0, 6029 "other": 0 6030 } 6031 }, 6032 "write": { 6033 "ios": 318707, 6034 "blocks": 318707, 6035 "errors": { 6036 "media": 0, 6037 "other": 0 6038 } 6039 } 6040 }, 6041 "cmp": { 6042 "read": { 6043 "ios": 0, 6044 "blocks": 0, 6045 "errors": { 6046 "media": 0, 6047 "crc": 0, 6048 "other": 0 6049 } 6050 }, 6051 "write": { 6052 "ios": 0, 6053 "blocks": 0, 6054 "errors": { 6055 "media": 0, 6056 "other": 0 6057 } 6058 } 6059 }, 6060 "gc": { 6061 "read": { 6062 "ios": 0, 6063 "blocks": 0, 6064 "errors": { 6065 "media": 0, 6066 "crc": 0, 6067 "other": 0 6068 } 6069 }, 6070 "write": { 6071 "ios": 0, 6072 "blocks": 0, 6073 "errors": { 6074 "media": 0, 6075 "other": 0 6076 } 6077 } 6078 }, 6079 "md_base": { 6080 "read": { 6081 "ios": 0, 6082 "blocks": 0, 6083 "errors": { 6084 "media": 0, 6085 "crc": 0, 6086 "other": 0 6087 } 6088 }, 6089 "write": { 6090 "ios": 1, 6091 "blocks": 32, 6092 "errors": { 6093 "media": 0, 6094 "other": 0 6095 } 6096 } 6097 }, 6098 "md_nv_cache": { 6099 "read": { 6100 "ios": 0, 6101 "blocks": 0, 6102 "errors": { 6103 "media": 0, 6104 "crc": 0, 6105 "other": 0 6106 } 6107 }, 6108 "write": { 6109 "ios": 1064, 6110 "blocks": 1073896, 6111 "errors": { 6112 "media": 0, 6113 "other": 0 6114 } 6115 } 6116 }, 6117 "l2p": { 6118 "read": { 6119 "ios": 240659, 6120 "blocks": 240659, 6121 "errors": { 6122 "media": 0, 6123 "crc": 0, 6124 "other": 0 6125 } 6126 }, 6127 "write": { 6128 "ios": 235745, 6129 "blocks": 235745, 6130 "errors": { 6131 "media": 0, 6132 "other": 0 6133 } 6134 } 6135 } 6136 } 6137} 6138~~~ 6139 6140### bdev_ftl_get_properties {#rpc_bdev_ftl_get_properties} 6141 6142Get FTL properties 6143 6144#### Parameters 6145 6146Name | Optional | Type | Description 6147----------------------- | -------- | ----------- | ----------- 6148name | Required | string | Bdev name 6149 6150#### Response 6151 6152The response contains FTL bdev properties. Some of them can be modified, other 6153reported as read only. 6154 6155#### Example 6156 6157Example request: 6158 6159~~~json 6160{ 6161 "params": { 6162 "name": "ftl0" 6163 }, 6164 "jsonrpc": "2.0", 6165 "method": "bdev_ftl_get_properties", 6166 "id": 1 6167} 6168~~~ 6169 6170Example response: 6171 6172~~~json 6173{ 6174 "jsonrpc": "2.0", 6175 "id": 1, 6176 "result": { 6177 "name": "ftl0", 6178 "properties": [ 6179 { 6180 "name": "property1", 6181 "value": "Property Value 1", 6182 "unit": "MiB/s", 6183 "desc": "This is an example of read-only property", 6184 "read-only": true 6185 }, 6186 { 6187 "name": "property2", 6188 "value": 17, 6189 "unit": "s", 6190 "desc": "This is an example of FTL modifiable property", 6191 "read-only": false 6192 } 6193 ] 6194 } 6195} 6196~~~ 6197 6198### bdev_ftl_set_property {#rpc_bdev_ftl_set_property} 6199 6200Set FTL property. Trying to set a read-only property will result in an error. 6201 6202#### Parameters 6203 6204Name | Optional | Type | Description 6205----------------------- | -------- | ----------- | ----------- 6206name | Required | string | Bdev name 6207property | Required | string | Name of the property to modify 6208value | Required | string | New value of the property to be set 6209 6210#### Example 6211 6212Example request: 6213 6214~~~json 6215{ 6216 "params": { 6217 "name": "ftl0" 6218 "property": "nv_cache.flush" 6219 "value": "true" 6220 }, 6221 "jsonrpc": "2.0", 6222 "method": "bdev_ftl_set_property", 6223 "id": 1 6224} 6225~~~ 6226 6227Example response: 6228 6229~~~json 6230{ 6231 "jsonrpc": "2.0", 6232 "id": 1, 6233 "result": true 6234} 6235~~~ 6236 6237### bdev_passthru_create {#rpc_bdev_passthru_create} 6238 6239Create passthru bdev. This bdev type redirects all IO to it's base bdev. It has no other purpose than being an example 6240and a starting point in development of new bdev type. 6241 6242#### Parameters 6243 6244Name | Optional | Type | Description 6245----------------------- | -------- | ----------- | ----------- 6246name | Required | string | Bdev name 6247base_bdev_name | Required | string | Base bdev name 6248uuid | Optional | string | UUID of new bdev 6249 6250#### Result 6251 6252Name of newly created bdev. 6253 6254#### Example 6255 6256Example request: 6257 6258~~~json 6259{ 6260 "params": { 6261 "base_bdev_name": "Malloc0", 6262 "name": "Passsthru0" 6263 }, 6264 "jsonrpc": "2.0", 6265 "method": "bdev_passthru_create", 6266 "id": 1 6267} 6268~~~ 6269 6270Example response: 6271 6272~~~json 6273{ 6274 "jsonrpc": "2.0", 6275 "id": 1, 6276 "result": "Passsthru0" 6277} 6278~~~ 6279 6280### bdev_passthru_delete {#rpc_bdev_passthru_delete} 6281 6282Delete passthru bdev. 6283 6284#### Parameters 6285 6286Name | Optional | Type | Description 6287----------------------- | -------- | ----------- | ----------- 6288name | Required | string | Bdev name 6289 6290#### Example 6291 6292Example request: 6293 6294~~~json 6295{ 6296 "params": { 6297 "name": "Passsthru0" 6298 }, 6299 "jsonrpc": "2.0", 6300 "method": "bdev_passthru_delete", 6301 "id": 1 6302} 6303 6304~~~ 6305 6306Example response: 6307 6308~~~json 6309{ 6310 "jsonrpc": "2.0", 6311 "id": 1, 6312 "result": true 6313} 6314~~~ 6315 6316### bdev_xnvme_create {#rpc_bdev_xnvme_create} 6317 6318Create xnvme bdev. This bdev type redirects all IO to its underlying backend. 6319 6320#### Parameters 6321 6322Name | Optional | Type | Description 6323----------------------- | -------- | ----------- | ----------- 6324name | Required | string | name of xNVMe bdev to create 6325filename | Required | string | path to device or file (ex: /dev/nvme0n1) 6326io_mechanism | Required | string | IO mechanism to use (ex: libaio, io_uring, io_uring_cmd, etc.) 6327conserve_cpu | Optional | boolean | Whether or not to conserve CPU when polling (default: false) 6328 6329#### Result 6330 6331Name of newly created bdev. 6332 6333#### Example 6334 6335Example request: 6336 6337~~~json 6338{ 6339 "jsonrpc": "2.0", 6340 "method": "bdev_xnvme_create", 6341 "id": 1, 6342 "params": { 6343 "name": "bdev_ng0n1", 6344 "filename": "/dev/ng0n1", 6345 "io_mechanism": "io_uring_cmd", 6346 "conserve_cpu": false, 6347 } 6348} 6349~~~ 6350 6351Example response: 6352 6353~~~json 6354{ 6355 "jsonrpc": "2.0", 6356 "id": 1, 6357 "result": "bdev_ng0n1" 6358} 6359~~~ 6360 6361### bdev_xnvme_delete {#rpc_bdev_xnvme_delete} 6362 6363Delete xnvme bdev. 6364 6365#### Parameters 6366 6367Name | Optional | Type | Description 6368----------------------- | -------- | ----------- | ----------- 6369name | Required | string | name of xnvme bdev to delete 6370 6371#### Example 6372 6373Example request: 6374 6375~~~json 6376{ 6377 "params": { 6378 "name": "bdev_ng0n1" 6379 }, 6380 "jsonrpc": "2.0", 6381 "method": "bdev_xnvme_delete", 6382 "id": 1 6383} 6384 6385~~~ 6386 6387Example response: 6388 6389~~~json 6390{ 6391 "jsonrpc": "2.0", 6392 "id": 1, 6393 "result": true 6394} 6395~~~ 6396 6397### bdev_virtio_attach_controller {#rpc_bdev_virtio_attach_controller} 6398 6399Create new initiator @ref bdev_config_virtio_scsi or @ref bdev_config_virtio_blk and expose all found bdevs. 6400 6401#### Parameters 6402 6403Name | Optional | Type | Description 6404----------------------- | -------- | ----------- | ----------- 6405name | Required | string | Virtio SCSI base bdev name or Virtio Blk bdev name 6406trtype | Required | string | Virtio target trtype: pci or user 6407traddr | Required | string | target address: BDF or UNIX socket file path 6408dev_type | Required | string | Virtio device type: blk or scsi 6409vq_count | Optional | number | Number of queues this controller will utilize (default: 1) 6410vq_size | Optional | number | Size of each queue. Must be power of 2. (default: 512) 6411 6412In case of Virtio SCSI the `name` parameter will be base name for new created bdevs. For Virtio Blk `name` will be the 6413name of created bdev. 6414 6415`vq_count` and `vq_size` parameters are valid only if `trtype` is `user`. 6416 6417#### Result 6418 6419Array of names of newly created bdevs. 6420 6421#### Example 6422 6423Example request: 6424 6425~~~json 6426{ 6427 "params": { 6428 "name": "VirtioScsi0", 6429 "trtype": "user", 6430 "vq_size": 128, 6431 "dev_type": "scsi", 6432 "traddr": "/tmp/VhostScsi0", 6433 "vq_count": 4 6434 }, 6435 "jsonrpc": "2.0", 6436 "method": "bdev_virtio_attach_controller", 6437 "id": 1 6438} 6439~~~ 6440 6441Example response: 6442 6443~~~json 6444{ 6445 "jsonrpc": "2.0", 6446 "id": 1, 6447 "result": ["VirtioScsi0t2", "VirtioScsi0t4"] 6448} 6449~~~ 6450 6451### bdev_virtio_scsi_get_devices {#rpc_bdev_virtio_scsi_get_devices} 6452 6453Show information about all available Virtio SCSI devices. 6454 6455#### Parameters 6456 6457This method has no parameters. 6458 6459#### Result 6460 6461Array of Virtio SCSI information objects. 6462 6463#### Example 6464 6465Example request: 6466 6467~~~json 6468{ 6469 "jsonrpc": "2.0", 6470 "method": "bdev_virtio_scsi_get_devices", 6471 "id": 1 6472} 6473~~~ 6474 6475Example response: 6476 6477~~~json 6478{ 6479 "jsonrpc": "2.0", 6480 "id": 1, 6481 "result": [ 6482 { 6483 "name": "VirtioScsi0", 6484 "virtio": { 6485 "vq_size": 128, 6486 "vq_count": 4, 6487 "type": "user", 6488 "socket": "/tmp/VhostScsi0" 6489 } 6490 } 6491 ] 6492} 6493~~~ 6494 6495### bdev_virtio_detach_controller {#rpc_bdev_virtio_detach_controller} 6496 6497Remove a Virtio device. This command can be used to remove any type of virtio device. 6498 6499#### Parameters 6500 6501Name | Optional | Type | Description 6502----------------------- | -------- | ----------- | ----------- 6503name | Required | string | Virtio name 6504 6505#### Example 6506 6507Example request: 6508 6509~~~json 6510{ 6511 "params": { 6512 "name": "VirtioUser0" 6513 }, 6514 "jsonrpc": "2.0", 6515 "method": "bdev_virtio_detach_controller", 6516 "id": 1 6517} 6518 6519~~~ 6520 6521Example response: 6522 6523~~~json 6524{ 6525 "jsonrpc": "2.0", 6526 "id": 1, 6527 "result": true 6528} 6529~~~ 6530 6531### bdev_virtio_blk_set_hotplug {#rpc_bdev_virtio_blk_set_hotplug} 6532 6533Enable/Disable the virtio blk hotplug monitor or change the monitor period time 6534 6535#### Parameters 6536 6537Name | Optional | Type | Description 6538----------------------- | -------- | ----------- | ----------- 6539enable | Required | bool | Enable or disable the virtio blk hotplug monitor 6540period-us | Optional | number | The period time of the monitor 6541 6542When the enable is true then the period-us is optional. If user don't set the period time then use the default 6543value. When the enable is false then the period-us is not required. 6544 6545#### Result 6546 6547True the rpc is successful otherwise false 6548 6549#### Example 6550 6551Example request: 6552 6553~~~json 6554{ 6555 "params": { 6556 "enable": "true", 6557 "period-us": "1000000" 6558 }, 6559 "jsonrpc": "2.0", 6560 "method": "bdev_virtio_blk_set_hotplug", 6561 "id": 1 6562} 6563~~~ 6564 6565Example response: 6566 6567~~~json 6568{ 6569 "jsonrpc": "2.0", 6570 "id": 1, 6571 "result": true 6572} 6573~~~ 6574 6575## iSCSI Target {#jsonrpc_components_iscsi_tgt} 6576 6577### iscsi_set_options method {#rpc_iscsi_set_options} 6578 6579Set global parameters for iSCSI targets. 6580 6581This RPC may only be called before SPDK subsystems have been initialized. This RPC can be called only once. 6582 6583#### Parameters 6584 6585Name | Optional | Type | Description 6586------------------------------- | -------- | ------- | ----------- 6587auth_file | Optional | string | Path to CHAP shared secret file (default: "") 6588node_base | Optional | string | Prefix of the name of iSCSI target node (default: "iqn.2016-06.io.spdk") 6589nop_timeout | Optional | number | Timeout in seconds to nop-in request to the initiator (default: 60) 6590nop_in_interval | Optional | number | Time interval in secs between nop-in requests by the target (default: 30) 6591disable_chap | Optional | boolean | CHAP for discovery session should be disabled (default: `false`) 6592require_chap | Optional | boolean | CHAP for discovery session should be required (default: `false`) 6593mutual_chap | Optional | boolean | CHAP for discovery session should be unidirectional (`false`) or bidirectional (`true`) (default: `false`) 6594chap_group | Optional | number | CHAP group ID for discovery session (default: 0) 6595max_sessions | Optional | number | Maximum number of sessions in the host (default: 128) 6596max_queue_depth | Optional | number | Maximum number of outstanding I/Os per queue (default: 64) 6597max_connections_per_session | Optional | number | Session specific parameter, MaxConnections (default: 2) 6598default_time2wait | Optional | number | Session specific parameter, DefaultTime2Wait (default: 2) 6599default_time2retain | Optional | number | Session specific parameter, DefaultTime2Retain (default: 20) 6600first_burst_length | Optional | number | Session specific parameter, FirstBurstLength (default: 8192) 6601immediate_data | Optional | boolean | Session specific parameter, ImmediateData (default: `true`) 6602error_recovery_level | Optional | number | Session specific parameter, ErrorRecoveryLevel (default: 0) 6603allow_duplicated_isid | Optional | boolean | Allow duplicated initiator session ID (default: `false`) 6604max_large_datain_per_connection | Optional | number | Max number of outstanding split read I/Os per connection (default: 64) 6605max_r2t_per_connection | Optional | number | Max number of outstanding R2Ts per connection (default: 4) 6606pdu_pool_size | Optional | number | Number of PDUs in the pool (default: approximately 2 * max_sessions * (max_queue_depth + max_connections_per_session)) 6607immediate_data_pool_size | Optional | number | Number of immediate data buffers in the pool (default: 128 * max_sessions) 6608data_out_pool_size | Optional | number | Number of data out buffers in the pool (default: 16 * max_sessions) 6609 6610To load CHAP shared secret file, its path is required to specify explicitly in the parameter `auth_file`. 6611 6612Parameters `disable_chap` and `require_chap` are mutually exclusive. Parameters `no_discovery_auth`, `req_discovery_auth`, 6613`req_discovery_auth_mutual`, and `discovery_auth_group` are still available instead of `disable_chap`, `require_chap`, 6614`mutual_chap`, and `chap_group`, respectivey but will be removed in future releases. 6615 6616#### Example 6617 6618Example request: 6619 6620~~~json 6621{ 6622 "params": { 6623 "allow_duplicated_isid": true, 6624 "default_time2retain": 60, 6625 "first_burst_length": 8192, 6626 "immediate_data": true, 6627 "node_base": "iqn.2016-06.io.spdk", 6628 "max_sessions": 128, 6629 "nop_timeout": 30, 6630 "nop_in_interval": 30, 6631 "auth_file": "/usr/local/etc/spdk/auth.conf", 6632 "disable_chap": true, 6633 "default_time2wait": 2 6634 }, 6635 "jsonrpc": "2.0", 6636 "method": "iscsi_set_options", 6637 "id": 1 6638} 6639~~~ 6640 6641Example response: 6642 6643~~~json 6644{ 6645 "jsonrpc": "2.0", 6646 "id": 1, 6647 "result": true 6648} 6649~~~ 6650 6651### iscsi_get_options method {#rpc_iscsi_get_options} 6652 6653Show global parameters of iSCSI targets. 6654 6655#### Parameters 6656 6657This method has no parameters. 6658 6659#### Example 6660 6661Example request: 6662 6663~~~json 6664request: 6665{ 6666 "jsonrpc": "2.0", 6667 "method": "iscsi_get_options", 6668 "id": 1 6669} 6670~~~ 6671 6672Example response: 6673 6674~~~json 6675{ 6676 "jsonrpc": "2.0", 6677 "id": 1, 6678 "result": { 6679 "allow_duplicated_isid": true, 6680 "default_time2retain": 60, 6681 "first_burst_length": 8192, 6682 "immediate_data": true, 6683 "node_base": "iqn.2016-06.io.spdk", 6684 "mutual_chap": false, 6685 "nop_in_interval": 30, 6686 "chap_group": 0, 6687 "max_connections_per_session": 2, 6688 "max_queue_depth": 64, 6689 "nop_timeout": 30, 6690 "max_sessions": 128, 6691 "error_recovery_level": 0, 6692 "auth_file": "/usr/local/etc/spdk/auth.conf", 6693 "disable_chap": true, 6694 "default_time2wait": 2, 6695 "require_chap": false, 6696 "max_large_datain_per_connection": 64, 6697 "max_r2t_per_connection": 4 6698 } 6699} 6700~~~ 6701 6702### scsi_get_devices {#rpc_scsi_get_devices} 6703 6704Display SCSI devices 6705 6706#### Parameters 6707 6708This method has no parameters. 6709 6710#### Example 6711 6712Example request: 6713 6714~~~json 6715{ 6716 "jsonrpc": "2.0", 6717 "method": "scsi_get_devices", 6718 "id": 1 6719} 6720~~~ 6721 6722Example response: 6723 6724~~~json 6725{ 6726 "jsonrpc": "2.0", 6727 "id": 1, 6728 "result": [ 6729 { 6730 "id": 0, 6731 "device_name": "iqn.2016-06.io.spdk:Target3" 6732 } 6733 ] 6734} 6735~~~ 6736 6737### iscsi_set_discovery_auth method {#rpc_iscsi_set_discovery_auth} 6738 6739Set CHAP authentication for sessions dynamically. 6740 6741#### Parameters 6742 6743Name | Optional | Type | Description 6744--------------------------- | -------- | --------| ----------- 6745disable_chap | Optional | boolean | CHAP for discovery session should be disabled (default: `false`) 6746require_chap | Optional | boolean | CHAP for discovery session should be required (default: `false`) 6747mutual_chap | Optional | boolean | CHAP for discovery session should be unidirectional (`false`) or bidirectional (`true`) (default: `false`) 6748chap_group | Optional | number | CHAP group ID for discovery session (default: 0) 6749 6750Parameters `disable_chap` and `require_chap` are mutually exclusive. 6751 6752#### Example 6753 6754Example request: 6755 6756~~~json 6757request: 6758{ 6759 "params": { 6760 "chap_group": 1, 6761 "require_chap": true, 6762 "mutual_chap": true 6763 }, 6764 "jsonrpc": "2.0", 6765 "method": "iscsi_set_discovery_auth", 6766 "id": 1 6767} 6768~~~ 6769 6770Example response: 6771 6772~~~json 6773{ 6774 "jsonrpc": "2.0", 6775 "id": 1, 6776 "result": true 6777} 6778~~~ 6779 6780### iscsi_create_auth_group method {#rpc_iscsi_create_auth_group} 6781 6782Create an authentication group for CHAP authentication. 6783 6784#### Parameters 6785 6786Name | Optional | Type | Description 6787--------------------------- | -------- | --------| ----------- 6788tag | Required | number | Authentication group tag (unique, integer > 0) 6789secrets | Optional | array | Array of @ref rpc_iscsi_create_auth_group_secret objects 6790 6791#### secret {#rpc_iscsi_create_auth_group_secret} 6792 6793Name | Optional | Type | Description 6794--------------------------- | ---------| --------| ----------- 6795user | Required | string | Unidirectional CHAP name 6796secret | Required | string | Unidirectional CHAP secret 6797muser | Optional | string | Bidirectional CHAP name 6798msecret | Optional | string | Bidirectional CHAP secret 6799 6800#### Example 6801 6802Example request: 6803 6804~~~json 6805{ 6806 "params": { 6807 "secrets": [ 6808 { 6809 "muser": "mu1", 6810 "secret": "s1", 6811 "user": "u1", 6812 "msecret": "ms1" 6813 } 6814 ], 6815 "tag": 2 6816 }, 6817 "jsonrpc": "2.0", 6818 "method": "iscsi_create_auth_group", 6819 "id": 1 6820} 6821~~~ 6822 6823Example response: 6824 6825~~~json 6826{ 6827 "jsonrpc": "2.0", 6828 "id": 1, 6829 "result": true 6830} 6831~~~ 6832 6833### iscsi_delete_auth_group method {#rpc_iscsi_delete_auth_group} 6834 6835Delete an existing authentication group for CHAP authentication. 6836 6837#### Parameters 6838 6839Name | Optional | Type | Description 6840--------------------------- | -------- | --------| ----------- 6841tag | Required | number | Authentication group tag (unique, integer > 0) 6842 6843#### Example 6844 6845Example request: 6846 6847~~~json 6848{ 6849 "params": { 6850 "tag": 2 6851 }, 6852 "jsonrpc": "2.0", 6853 "method": "iscsi_delete_auth_group", 6854 "id": 1 6855} 6856~~~ 6857 6858Example response: 6859 6860~~~json 6861{ 6862 "jsonrpc": "2.0", 6863 "id": 1, 6864 "result": true 6865} 6866~~~ 6867 6868### iscsi_get_auth_groups {#rpc_iscsi_get_auth_groups} 6869 6870Show information about all existing authentication group for CHAP authentication. 6871 6872#### Parameters 6873 6874This method has no parameters. 6875 6876#### Result 6877 6878Array of objects describing authentication group. 6879 6880Name | Type | Description 6881--------------------------- | --------| ----------- 6882tag | number | Authentication group tag 6883secrets | array | Array of @ref rpc_iscsi_create_auth_group_secret objects 6884 6885#### Example 6886 6887Example request: 6888 6889~~~json 6890{ 6891 "jsonrpc": "2.0", 6892 "method": "iscsi_get_auth_groups", 6893 "id": 1 6894} 6895~~~ 6896 6897Example response: 6898 6899~~~json 6900{ 6901 "jsonrpc": "2.0", 6902 "id": 1, 6903 "result": [ 6904 { 6905 "secrets": [ 6906 { 6907 "muser": "mu1", 6908 "secret": "s1", 6909 "user": "u1", 6910 "msecret": "ms1" 6911 } 6912 ], 6913 "tag": 1 6914 }, 6915 { 6916 "secrets": [ 6917 { 6918 "secret": "s2", 6919 "user": "u2" 6920 } 6921 ], 6922 "tag": 2 6923 } 6924 ] 6925} 6926~~~ 6927 6928### iscsi_auth_group_add_secret {#rpc_iscsi_auth_group_add_secret} 6929 6930Add a secret to an existing authentication group for CHAP authentication. 6931 6932#### Parameters 6933 6934Name | Optional | Type | Description 6935--------------------------- | -------- | --------| ----------- 6936tag | Required | number | Authentication group tag (unique, integer > 0) 6937user | Required | string | Unidirectional CHAP name 6938secret | Required | string | Unidirectional CHAP secret 6939muser | Optional | string | Bidirectional CHAP name 6940msecret | Optional | string | Bidirectional CHAP secret 6941 6942#### Example 6943 6944Example request: 6945 6946~~~json 6947{ 6948 "params": { 6949 "muser": "mu3", 6950 "secret": "s3", 6951 "tag": 2, 6952 "user": "u3", 6953 "msecret": "ms3" 6954 }, 6955 "jsonrpc": "2.0", 6956 "method": "iscsi_auth_group_add_secret", 6957 "id": 1 6958} 6959~~~json 6960 6961Example response: 6962 6963~~~json 6964{ 6965 "jsonrpc": "2.0", 6966 "id": 1, 6967 "result": true 6968} 6969~~~ 6970 6971### iscsi_auth_group_remove_secret {#rpc_iscsi_auth_group_remove_secret} 6972 6973Remove a secret from an existing authentication group for CHAP authentication. 6974 6975#### Parameters 6976 6977Name | Optional | Type | Description 6978--------------------------- | -------- | --------| ----------- 6979tag | Required | number | Authentication group tag (unique, integer > 0) 6980user | Required | string | Unidirectional CHAP name 6981 6982#### Example 6983 6984Example request: 6985 6986~~~json 6987{ 6988 "params": { 6989 "tag": 2, 6990 "user": "u3" 6991 }, 6992 "jsonrpc": "2.0", 6993 "method": "iscsi_auth_group_remove_secret", 6994 "id": 1 6995} 6996~~~ 6997 6998Example response: 6999 7000~~~json 7001{ 7002 "jsonrpc": "2.0", 7003 "id": 1, 7004 "result": true 7005} 7006~~~ 7007 7008### iscsi_get_initiator_groups method {#rpc_iscsi_get_initiator_groups} 7009 7010Show information about all available initiator groups. 7011 7012#### Parameters 7013 7014This method has no parameters. 7015 7016#### Result 7017 7018Array of objects describing initiator groups. 7019 7020Name | Type | Description 7021--------------------------- | --------| ----------- 7022tag | number | Initiator group tag 7023initiators | array | Array of initiator hostnames or IP addresses 7024netmasks | array | Array of initiator netmasks 7025 7026#### Example 7027 7028Example request: 7029 7030~~~json 7031{ 7032 "jsonrpc": "2.0", 7033 "method": "iscsi_get_initiator_groups", 7034 "id": 1 7035} 7036~~~ 7037 7038Example response: 7039 7040~~~json 7041{ 7042 "jsonrpc": "2.0", 7043 "id": 1, 7044 "result": [ 7045 { 7046 "initiators": [ 7047 "iqn.2016-06.io.spdk:host1", 7048 "iqn.2016-06.io.spdk:host2" 7049 ], 7050 "tag": 1, 7051 "netmasks": [ 7052 "192.168.1.0/24" 7053 ] 7054 } 7055 ] 7056} 7057~~~ 7058 7059### iscsi_create_initiator_group method {#rpc_iscsi_create_initiator_group} 7060 7061Add an initiator group. 7062 7063#### Parameters 7064 7065Name | Optional | Type | Description 7066--------------------------- | -------- | --------| ----------- 7067tag | Required | number | Initiator group tag (unique, integer > 0) 7068initiators | Required | array | Not empty array of initiator hostnames or IP addresses 7069netmasks | Required | array | Not empty array of initiator netmasks 7070 7071#### Example 7072 7073Example request: 7074 7075~~~json 7076{ 7077 "params": { 7078 "initiators": [ 7079 "iqn.2016-06.io.spdk:host1", 7080 "iqn.2016-06.io.spdk:host2" 7081 ], 7082 "tag": 1, 7083 "netmasks": [ 7084 "192.168.1.0/24" 7085 ] 7086 }, 7087 "jsonrpc": "2.0", 7088 "method": "iscsi_create_initiator_group", 7089 "id": 1 7090} 7091~~~ 7092 7093Example response: 7094 7095~~~json 7096response: 7097{ 7098 "jsonrpc": "2.0", 7099 "id": 1, 7100 "result": true 7101} 7102~~~ 7103 7104### iscsi_delete_initiator_group method {#rpc_iscsi_delete_initiator_group} 7105 7106Delete an existing initiator group. 7107 7108#### Parameters 7109 7110Name | Optional | Type | Description 7111--------------------------- | -------- | --------| ----------- 7112tag | Required | number | Initiator group tag (unique, integer > 0) 7113 7114#### Example 7115 7116Example request: 7117 7118~~~json 7119{ 7120 "params": { 7121 "tag": 1 7122 }, 7123 "jsonrpc": "2.0", 7124 "method": "iscsi_delete_initiator_group", 7125 "id": 1 7126} 7127~~~ 7128 7129Example response: 7130 7131~~~json 7132{ 7133 "jsonrpc": "2.0", 7134 "id": 1, 7135 "result": true 7136} 7137~~~ 7138 7139### iscsi_initiator_group_add_initiators method {#rpc_iscsi_initiator_group_add_initiators} 7140 7141Add initiators to an existing initiator group. 7142 7143#### Parameters 7144 7145Name | Optional | Type | Description 7146--------------------------- | -------- | --------| ----------- 7147tag | Required | number | Existing initiator group tag. 7148initiators | Optional | array | Array of initiator hostnames or IP addresses 7149netmasks | Optional | array | Array of initiator netmasks 7150 7151#### Example 7152 7153Example request: 7154 7155~~~json 7156request: 7157{ 7158 "params": { 7159 "initiators": [ 7160 "iqn.2016-06.io.spdk:host3" 7161 ], 7162 "tag": 1, 7163 "netmasks": [ 7164 "255.255.255.1" 7165 ] 7166 }, 7167 "jsonrpc": "2.0", 7168 "method": "iscsi_initiator_group_add_initiators", 7169 "id": 1 7170} 7171~~~ 7172 7173Example response: 7174 7175~~~json 7176response: 7177{ 7178 "jsonrpc": "2.0", 7179 "id": 1, 7180 "result": true 7181} 7182~~~ 7183 7184### iscsi_initiator_group_remove_initiators method {#rpc_iscsi_initiator_group_remove_initiators} 7185 7186Remove initiators from an initiator group. 7187 7188#### Parameters 7189 7190Name | Optional | Type | Description 7191--------------------------- | -------- | --------| ----------- 7192tag | Required | number | Existing initiator group tag. 7193initiators | Optional | array | Array of initiator hostnames or IP addresses 7194netmasks | Optional | array | Array of initiator netmasks 7195 7196#### Example 7197 7198Example request: 7199 7200~~~json 7201request: 7202{ 7203 "params": { 7204 "initiators": [ 7205 "iqn.2016-06.io.spdk:host3" 7206 ], 7207 "tag": 1, 7208 "netmasks": [ 7209 "255.255.255.1" 7210 ] 7211 }, 7212 "jsonrpc": "2.0", 7213 "method": "iscsi_initiator_group_remove_initiators", 7214 "id": 1 7215} 7216~~~ 7217 7218Example response: 7219 7220~~~json 7221response: 7222{ 7223 "jsonrpc": "2.0", 7224 "id": 1, 7225 "result": true 7226} 7227~~~ 7228 7229### iscsi_get_target_nodes method {#rpc_iscsi_get_target_nodes} 7230 7231Show information about all available iSCSI target nodes. 7232 7233#### Parameters 7234 7235This method has no parameters. 7236 7237#### Result 7238 7239Array of objects describing target node. 7240 7241Name | Type | Description 7242--------------------------- | --------| ----------- 7243name | string | Target node name (ASCII) 7244alias_name | string | Target node alias name (ASCII) 7245pg_ig_maps | array | Array of Portal_Group_Tag:Initiator_Group_Tag mappings 7246luns | array | Array of Bdev names to LUN ID mappings 7247queue_depth | number | Target queue depth 7248disable_chap | boolean | CHAP authentication should be disabled for this target 7249require_chap | boolean | CHAP authentication should be required for this target 7250mutual_chap | boolean | CHAP authentication should be bidirectional (`true`) or unidirectional (`false`) 7251chap_group | number | Authentication group ID for this target node 7252header_digest | boolean | Header Digest should be required for this target node 7253data_digest | boolean | Data Digest should be required for this target node 7254 7255#### Example 7256 7257Example request: 7258 7259~~~json 7260{ 7261 "jsonrpc": "2.0", 7262 "method": "iscsi_get_target_nodes", 7263 "id": 1 7264} 7265~~~ 7266 7267Example response: 7268 7269~~~json 7270{ 7271 "jsonrpc": "2.0", 7272 "id": 1, 7273 "result": [ 7274 { 7275 "luns": [ 7276 { 7277 "lun_id": 0, 7278 "bdev_name": "Nvme0n1" 7279 } 7280 ], 7281 "mutual_chap": false, 7282 "name": "iqn.2016-06.io.spdk:target1", 7283 "alias_name": "iscsi-target1-alias", 7284 "require_chap": false, 7285 "chap_group": 0, 7286 "pg_ig_maps": [ 7287 { 7288 "ig_tag": 1, 7289 "pg_tag": 1 7290 } 7291 ], 7292 "data_digest": false, 7293 "disable_chap": false, 7294 "header_digest": false, 7295 "queue_depth": 64 7296 } 7297 ] 7298} 7299~~~ 7300 7301### iscsi_create_target_node method {#rpc_iscsi_create_target_node} 7302 7303Add an iSCSI target node. 7304 7305#### Parameters 7306 7307Name | Optional | Type | Description 7308--------------------------- | -------- | --------| ----------- 7309name | Required | string | Target node name (ASCII) 7310alias_name | Required | string | Target node alias name (ASCII) 7311pg_ig_maps | Required | array | Array of (Portal_Group_Tag:Initiator_Group_Tag) mappings 7312luns | Required | array | Array of Bdev names to LUN ID mappings 7313queue_depth | Required | number | Target queue depth 7314disable_chap | Optional | boolean | CHAP authentication should be disabled for this target 7315require_chap | Optional | boolean | CHAP authentication should be required for this target 7316mutual_chap | Optional | boolean | CHAP authentication should be bidirectional (`true`) or unidirectional (`false`) 7317chap_group | Optional | number | Authentication group ID for this target node 7318header_digest | Optional | boolean | Header Digest should be required for this target node 7319data_digest | Optional | boolean | Data Digest should be required for this target node 7320 7321Parameters `disable_chap` and `require_chap` are mutually exclusive. 7322 7323#### Example 7324 7325Example request: 7326 7327~~~json 7328{ 7329 "params": { 7330 "luns": [ 7331 { 7332 "lun_id": 0, 7333 "bdev_name": "Nvme0n1" 7334 } 7335 ], 7336 "mutual_chap": true, 7337 "name": "target2", 7338 "alias_name": "iscsi-target2-alias", 7339 "pg_ig_maps": [ 7340 { 7341 "ig_tag": 1, 7342 "pg_tag": 1 7343 }, 7344 { 7345 "ig_tag": 2, 7346 "pg_tag": 2 7347 } 7348 ], 7349 "data_digest": true, 7350 "disable_chap": true, 7351 "header_digest": true, 7352 "queue_depth": 24 7353 }, 7354 "jsonrpc": "2.0", 7355 "method": "iscsi_create_target_node", 7356 "id": 1 7357} 7358~~~ 7359 7360Example response: 7361 7362~~~json 7363{ 7364 "jsonrpc": "2.0", 7365 "id": 1, 7366 "result": true 7367} 7368~~~ 7369 7370### iscsi_target_node_set_auth method {#rpc_iscsi_target_node_set_auth} 7371 7372Set CHAP authentication to an existing iSCSI target node. 7373 7374#### Parameters 7375 7376Name | Optional | Type | Description 7377--------------------------- | -------- | --------| ----------- 7378name | Required | string | Target node name (ASCII) 7379disable_chap | Optional | boolean | CHAP authentication should be disabled for this target 7380require_chap | Optional | boolean | CHAP authentication should be required for this target 7381mutual_chap | Optional | boolean | CHAP authentication should be bidirectional (`true`) or unidirectional (`false`) 7382chap_group | Optional | number | Authentication group ID for this target node 7383 7384Parameters `disable_chap` and `require_chap` are mutually exclusive. 7385 7386#### Example 7387 7388Example request: 7389 7390~~~json 7391{ 7392 "params": { 7393 "chap_group": 1, 7394 "require_chap": true, 7395 "name": "iqn.2016-06.io.spdk:target1", 7396 "mutual_chap": true 7397 }, 7398 "jsonrpc": "2.0", 7399 "method": "iscsi_target_node_set_auth", 7400 "id": 1 7401} 7402~~~ 7403 7404Example response: 7405 7406~~~json 7407{ 7408 "jsonrpc": "2.0", 7409 "id": 1, 7410 "result": true 7411} 7412~~~ 7413 7414### iscsi_target_node_add_pg_ig_maps method {#rpc_iscsi_target_node_add_pg_ig_maps} 7415 7416Add initiator group to portal group mappings to an existing iSCSI target node. 7417 7418#### Parameters 7419 7420Name | Optional | Type | Description 7421--------------------------- | -------- | --------| ----------- 7422name | Required | string | Target node name (ASCII) 7423pg_ig_maps | Required | array | Not empty array of initiator to portal group mappings objects 7424 7425Portal to Initiator group mappings object: 7426 7427Name | Optional | Type | Description 7428--------------------------- | -------- | --------| ----------- 7429ig_tag | Required | number | Existing initiator group tag 7430pg_tag | Required | number | Existing portal group tag 7431 7432#### Example 7433 7434Example request: 7435 7436~~~json 7437{ 7438 "params": { 7439 "pg_ig_maps": [ 7440 { 7441 "ig_tag": 1, 7442 "pg_tag": 1 7443 }, 7444 { 7445 "ig_tag": 2, 7446 "pg_tag": 2 7447 }, 7448 { 7449 "ig_tag": 3, 7450 "pg_tag": 3 7451 } 7452 ], 7453 "name": "iqn.2016-06.io.spdk:target3" 7454 }, 7455 "jsonrpc": "2.0", 7456 "method": "iscsi_target_node_add_pg_ig_maps", 7457 "id": 1 7458} 7459~~~ 7460 7461Example response: 7462 7463~~~json 7464{ 7465 "jsonrpc": "2.0", 7466 "id": 1, 7467 "result": true 7468} 7469~~~ 7470 7471### iscsi_target_node_remove_pg_ig_maps method {#rpc_iscsi_target_node_remove_pg_ig_maps} 7472 7473Delete initiator group to portal group mappings from an existing iSCSI target node. 7474 7475#### Parameters 7476 7477Name | Optional | Type | Description 7478--------------------------- | -------- | --------| ----------- 7479name | Required | string | Target node name (ASCII) 7480pg_ig_maps | Required | array | Not empty array of Portal to Initiator group mappings objects 7481 7482Portal to Initiator group mappings object: 7483 7484Name | Optional | Type | Description 7485--------------------------- | -------- | --------| ----------- 7486ig_tag | Required | number | Existing initiator group tag 7487pg_tag | Required | number | Existing portal group tag 7488 7489#### Example 7490 7491Example request: 7492 7493~~~json 7494{ 7495 "params": { 7496 "pg_ig_maps": [ 7497 { 7498 "ig_tag": 1, 7499 "pg_tag": 1 7500 }, 7501 { 7502 "ig_tag": 2, 7503 "pg_tag": 2 7504 }, 7505 { 7506 "ig_tag": 3, 7507 "pg_tag": 3 7508 } 7509 ], 7510 "name": "iqn.2016-06.io.spdk:target3" 7511 }, 7512 "jsonrpc": "2.0", 7513 "method": "iscsi_target_node_remove_pg_ig_maps", 7514 "id": 1 7515} 7516~~~ 7517 7518Example response: 7519 7520~~~json 7521{ 7522 "jsonrpc": "2.0", 7523 "id": 1, 7524 "result": true 7525} 7526~~~ 7527 7528### iscsi_delete_target_node method {#rpc_iscsi_delete_target_node} 7529 7530Delete an iSCSI target node. 7531 7532#### Parameters 7533 7534Name | Optional | Type | Description 7535--------------------------- | -------- | --------| ----------- 7536name | Required | string | Target node name (ASCII) 7537 7538#### Example 7539 7540Example request: 7541 7542~~~json 7543{ 7544 "params": { 7545 "name": "iqn.2016-06.io.spdk:target1" 7546 }, 7547 "jsonrpc": "2.0", 7548 "method": "iscsi_delete_target_node", 7549 "id": 1 7550} 7551~~~ 7552 7553Example response: 7554 7555~~~json 7556{ 7557 "jsonrpc": "2.0", 7558 "id": 1, 7559 "result": true 7560} 7561~~~ 7562 7563### iscsi_get_portal_groups method {#rpc_iscsi_get_portal_groups} 7564 7565Show information about all available portal groups. 7566 7567#### Parameters 7568 7569This method has no parameters. 7570 7571#### Example 7572 7573Example request: 7574 7575~~~json 7576request: 7577{ 7578 "jsonrpc": "2.0", 7579 "method": "iscsi_get_portal_groups", 7580 "id": 1 7581} 7582~~~ 7583 7584Example response: 7585 7586~~~json 7587{ 7588 "jsonrpc": "2.0", 7589 "id": 1, 7590 "result": [ 7591 { 7592 "portals": [ 7593 { 7594 "host": "127.0.0.1", 7595 "port": "3260" 7596 } 7597 ], 7598 "tag": 1, 7599 "private": false 7600 } 7601 ] 7602} 7603~~~ 7604 7605### iscsi_create_portal_group method {#rpc_iscsi_create_portal_group} 7606 7607Add a portal group. 7608 7609#### Parameters 7610 7611Name | Optional | Type | Description 7612--------------------------- | -------- | --------| ----------- 7613tag | Required | number | Portal group tag 7614portals | Required | array | Not empty array of portals 7615private | Optional | boolean | When true, portals in this group are not returned by a discovery session. Used for login redirection. (default: `false`) 7616wait | Optional | boolean | When true, do not listen on portals until it is started explicitly. (default: `false`) 7617 7618Portal object 7619 7620Name | Optional | Type | Description 7621--------------------------- | -------- | --------| ----------- 7622host | Required | string | Hostname or IP address 7623port | Required | string | Port number 7624 7625#### Example 7626 7627Example request: 7628 7629~~~json 7630{ 7631 "params": { 7632 "portals": [ 7633 { 7634 "host": "127.0.0.1", 7635 "port": "3260" 7636 } 7637 ], 7638 "tag": 1 7639 }, 7640 "jsonrpc": "2.0", 7641 "method": "iscsi_create_portal_group", 7642 "id": 1 7643} 7644~~~ 7645 7646Example response: 7647 7648~~~json 7649{ 7650 "jsonrpc": "2.0", 7651 "id": 1, 7652 "result": true 7653} 7654~~~ 7655 7656### iscsi_start_portal_group method {#rpc_iscsi_start_portal_group} 7657 7658Start listening on portals if the portal group is not started yet, or do nothing 7659if the portal group already started. Return a success response for both cases. 7660 7661#### Parameters 7662 7663Name | Optional | Type | Description 7664--------------------------- | -------- | --------| ----------- 7665tag | Required | number | Existing portal group tag 7666 7667#### Example 7668 7669Example request: 7670 7671~~~json 7672{ 7673 "params": { 7674 "tag": 1 7675 }, 7676 "jsonrpc": "2.0", 7677 "method": "iscsi_start_portal_group", 7678 "id": 1 7679} 7680~~~ 7681 7682Example response: 7683 7684~~~json 7685{ 7686 "jsonrpc": "2.0", 7687 "id": 1, 7688 "result": true 7689} 7690~~~ 7691 7692### iscsi_delete_portal_group method {#rpc_iscsi_delete_portal_group} 7693 7694Delete an existing portal group. 7695 7696#### Parameters 7697 7698Name | Optional | Type | Description 7699--------------------------- | -------- | --------| ----------- 7700tag | Required | number | Existing portal group tag 7701 7702#### Example 7703 7704Example request: 7705 7706~~~json 7707{ 7708 "params": { 7709 "tag": 1 7710 }, 7711 "jsonrpc": "2.0", 7712 "method": "iscsi_delete_portal_group", 7713 "id": 1 7714} 7715~~~ 7716 7717Example response: 7718 7719~~~json 7720{ 7721 "jsonrpc": "2.0", 7722 "id": 1, 7723 "result": true 7724} 7725~~~ 7726 7727### iscsi_portal_group_set_auth method {#rpc_iscsi_portal_group_set_auth} 7728 7729Set CHAP authentication for discovery sessions specific for the existing iSCSI portal group. 7730This RPC overwrites the setting by the global parameters for the iSCSI portal group. 7731 7732#### Parameters 7733 7734Name | Optional | Type | Description 7735--------------------------- | -------- | --------| ----------- 7736disable_chap | Optional | boolean | CHAP for discovery session should be disabled (default: `false`) 7737require_chap | Optional | boolean | CHAP for discovery session should be required (default: `false`) 7738mutual_chap | Optional | boolean | CHAP for discovery session should be unidirectional (`false`) or bidirectional (`true`) (default: `false`) 7739chap_group | Optional | number | CHAP group ID for discovery session (default: 0) 7740 7741Parameters `disable_chap` and `require_chap` are mutually exclusive. 7742 7743#### Example 7744 7745Example request: 7746 7747~~~json 7748request: 7749{ 7750 "params": { 7751 "tag": 1, 7752 "chap_group": 1, 7753 "require_chap": true, 7754 "mutual_chap": true 7755 }, 7756 "jsonrpc": "2.0", 7757 "method": "iscsi_portal_group_set_auth", 7758 "id": 1 7759} 7760~~~ 7761 7762Example response: 7763 7764~~~json 7765{ 7766 "jsonrpc": "2.0", 7767 "id": 1, 7768 "result": true 7769} 7770~~~ 7771 7772### iscsi_get_connections method {#rpc_iscsi_get_connections} 7773 7774Show information about all active connections. 7775 7776#### Parameters 7777 7778This method has no parameters. 7779 7780#### Results 7781 7782Array of objects describing iSCSI connection. 7783 7784Name | Type | Description 7785--------------------------- | --------| ----------- 7786id | number | Index (used for TTT - Target Transfer Tag) 7787cid | number | CID (Connection ID) 7788tsih | number | TSIH (Target Session Identifying Handle) 7789lcore_id | number | Core number on which the iSCSI connection runs 7790initiator_addr | string | Initiator address 7791target_addr | string | Target address 7792target_node_name | string | Target node name (ASCII) without prefix 7793 7794#### Example 7795 7796Example request: 7797 7798~~~json 7799{ 7800 "jsonrpc": "2.0", 7801 "method": "iscsi_get_connections", 7802 "id": 1 7803} 7804~~~ 7805 7806Example response: 7807 7808~~~json 7809{ 7810 "jsonrpc": "2.0", 7811 "id": 1, 7812 "result": [ 7813 { 7814 "tsih": 4, 7815 "cid": 0, 7816 "target_node_name": "target1", 7817 "lcore_id": 0, 7818 "initiator_addr": "10.0.0.2", 7819 "target_addr": "10.0.0.1", 7820 "id": 0 7821 } 7822 ] 7823} 7824~~~ 7825 7826### iscsi_get_stats method {#iscsi_get_stats} 7827 7828Show stat information of iSCSI connections. 7829 7830#### Parameters 7831 7832This method has no parameters. 7833 7834#### Results 7835 7836Stat information of iSCSI connections. 7837 7838Name | Type | Description 7839--------------------------- | --------| ----------- 7840invalid | number | The number of invalid connections 7841running | number | The number of running connections 7842exiting | number | The number of exiting connections 7843exited | number | The number of exited connections 7844 7845#### Example 7846 7847Example request: 7848 7849~~~json 7850{ 7851 "jsonrpc": "2.0", 7852 "method": "iscsi_get_stats", 7853 "id": 1 7854} 7855~~~ 7856 7857Example response: 7858 7859~~~json 7860{ 7861 "jsonrpc": "2.0", 7862 "id": 1, 7863 "result": 7864 { 7865 "invalid": 0, 7866 "running": 5, 7867 "exiting": 0, 7868 "exited": 0 7869 } 7870 7871} 7872~~~ 7873 7874### iscsi_target_node_add_lun method {#rpc_iscsi_target_node_add_lun} 7875 7876Add an LUN to an existing iSCSI target node. 7877 7878#### Parameters 7879 7880Name | Optional | Type | Description 7881--------------------------- | -------- | --------| ----------- 7882name | Required | string | Target node name (ASCII) 7883bdev_name | Required | string | bdev name to be added as a LUN 7884lun_id | Optional | number | LUN ID (default: first free ID) 7885 7886#### Example 7887 7888Example request: 7889 7890~~~json 7891{ 7892 "params": { 7893 "lun_id": 2, 7894 "name": "iqn.2016-06.io.spdk:target1", 7895 "bdev_name": "Malloc0" 7896 }, 7897 "jsonrpc": "2.0", 7898 "method": "iscsi_target_node_add_lun", 7899 "id": 1 7900} 7901~~~ 7902 7903Example response: 7904 7905~~~json 7906{ 7907 "jsonrpc": "2.0", 7908 "id": 1, 7909 "result": true 7910} 7911~~~ 7912 7913### iscsi_target_node_set_redirect method {#rpc_iscsi_target_node_set_redirect} 7914 7915Update redirect portal of the primary portal group for the target node, 7916 7917#### Parameters 7918 7919Name | Optional | Type | Description 7920--------------------------- | -------- | --------| ----------- 7921name | Required | string | Target node name (ASCII) 7922pg_tag | Required | number | Existing portal group tag 7923redirect_host | Optional | string | Numeric IP address to which the target node is redirected 7924redirect_port | Optional | string | Numeric TCP port to which the target node is redirected 7925 7926If both redirect_host and redirect_port are omitted, clear the redirect portal. 7927 7928#### Example 7929 7930Example request: 7931 7932~~~json 7933{ 7934 "params": { 7935 "name": "iqn.2016-06.io.spdk:target1", 7936 "pg_tag": 1, 7937 "redirect_host": "10.0.0.3", 7938 "redirect_port": "3260" 7939 }, 7940 "jsonrpc": "2.0", 7941 "method": "iscsi_target_node_set_redirect", 7942 "id": 1 7943} 7944~~~ 7945 7946Example response: 7947 7948~~~json 7949{ 7950 "jsonrpc": "2.0", 7951 "id": 1, 7952 "result": true 7953} 7954~~~ 7955 7956### iscsi_target_node_request_logout method {#rpc_iscsi_target_node_request_logout} 7957 7958For the target node, request connections whose portal group tag match to logout, 7959or request all connections to logout if portal group tag is omitted. 7960 7961#### Parameters 7962 7963Name | Optional | Type | Description 7964--------------------------- | -------- | --------| ----------- 7965name | Required | string | Target node name (ASCII) 7966pg_tag | Optional | number | Existing portal group tag 7967 7968#### Example 7969 7970Example request: 7971 7972~~~json 7973{ 7974 "params": { 7975 "name": "iqn.2016-06.io.spdk:target1", 7976 "pg_tag": 1 7977 }, 7978 "jsonrpc": "2.0", 7979 "method": "iscsi_target_node_request_logout", 7980 "id": 1 7981} 7982~~~ 7983 7984Example response: 7985 7986~~~json 7987{ 7988 "jsonrpc": "2.0", 7989 "id": 1, 7990 "result": true 7991} 7992~~~ 7993 7994### iscsi_enable_histogram {#rpc_iscsi_enable_histogram} 7995 7996Control whether collecting data for histogram is enabled for specified iscsi target node. 7997 7998#### Parameters 7999 8000Name | Optional | Type | Description 8001----------------------- | -------- | ----------- | ----------- 8002name | Required | string | Iscsi target node name 8003enable | Required | boolean | Enable or disable histogram on specified target node 8004 8005#### Example 8006 8007Example request: 8008 8009~~~json 8010{ 8011 "jsonrpc": "2.0", 8012 "id": 1, 8013 "method": "iscsi_enable_histogram", 8014 "params": { 8015 "name": "iqn.2016-06.io.spdk:target1" 8016 "enable": true 8017 } 8018} 8019~~~ 8020 8021Example response: 8022 8023~~~json 8024{ 8025 "jsonrpc": "2.0", 8026 "id": 1, 8027 "result": true 8028} 8029~~~ 8030 8031### iscsi_get_histogram {#rpc_iscsi_get_histogram} 8032 8033Get latency histogram for specified iscsi target node. 8034 8035#### Parameters 8036 8037Name | Optional | Type | Description 8038----------------------- | -------- | ----------- | ----------- 8039name | Required | string | Iscsi target node name 8040 8041#### Result 8042 8043Name | Description 8044------------------------| ----------- 8045histogram | Base64 encoded histogram 8046bucket_shift | Granularity of the histogram buckets 8047tsc_rate | Ticks per second 8048 8049#### Example 8050 8051Example request: 8052 8053~~~json 8054{ 8055 "jsonrpc": "2.0", 8056 "id": 1, 8057 "method": "iscsi_get_histogram", 8058 "params": { 8059 "name": "iqn.2016-06.io.spdk:target1" 8060 } 8061} 8062~~~ 8063 8064Example response: 8065Note that histogram field is trimmed, actual encoded histogram length is ~80kb. 8066 8067~~~json 8068{ 8069 "jsonrpc": "2.0", 8070 "id": 1, 8071 "result": { 8072 "histogram": "AAAAAAAAAAAAAA...AAAAAAAAA==", 8073 "tsc_rate": 2300000000, 8074 "bucket_shift": 7 8075 } 8076} 8077~~~ 8078 8079## NVMe-oF Target {#jsonrpc_components_nvmf_tgt} 8080 8081### nvmf_create_transport method {#rpc_nvmf_create_transport} 8082 8083Initialize an NVMe-oF transport with the given options. 8084 8085#### Parameters 8086 8087Name | Optional | Type | Description 8088--------------------------- | -------- | --------| ----------- 8089trtype | Required | string | Transport type (ex. RDMA) 8090tgt_name | Optional | string | Parent NVMe-oF target name. 8091max_queue_depth | Optional | number | Max number of outstanding I/O per queue 8092max_io_qpairs_per_ctrlr | Optional | number | Max number of IO qpairs per controller 8093in_capsule_data_size | Optional | number | Max number of in-capsule data size 8094max_io_size | Optional | number | Max I/O size (bytes) 8095io_unit_size | Optional | number | I/O unit size (bytes) 8096max_aq_depth | Optional | number | Max number of admin cmds per AQ 8097num_shared_buffers | Optional | number | The number of pooled data buffers available to the transport 8098buf_cache_size | Optional | number | The number of shared buffers to reserve for each poll group 8099num_cqe | Optional | number | The number of CQ entries. Only used when no_srq=true (RDMA only) 8100max_srq_depth | Optional | number | The number of elements in a per-thread shared receive queue (RDMA only) 8101no_srq | Optional | boolean | Disable shared receive queue even for devices that support it. (RDMA only) 8102c2h_success | Optional | boolean | Disable C2H success optimization (TCP only) 8103dif_insert_or_strip | Optional | boolean | Enable DIF insert for write I/O and DIF strip for read I/O DIF 8104sock_priority | Optional | number | The socket priority of the connection owned by this transport (TCP only) 8105acceptor_backlog | Optional | number | The number of pending connections allowed in backlog before failing new connection attempts (RDMA only) 8106abort_timeout_sec | Optional | number | Abort execution timeout value, in seconds 8107no_wr_batching | Optional | boolean | Disable work requests batching (RDMA only) 8108control_msg_num | Optional | number | The number of control messages per poll group (TCP only) 8109disable_mappable_bar0 | Optional | boolean | disable client mmap() of BAR0 (VFIO-USER only) 8110disable_adaptive_irq | Optional | boolean | Disable adaptive interrupt feature (VFIO-USER only) 8111disable_shadow_doorbells | Optional | boolean | disable shadow doorbell support (VFIO-USER only) 8112zcopy | Optional | boolean | Use zero-copy operations if the underlying bdev supports them 8113ack_timeout | Optional | number | ACK timeout in milliseconds 8114data_wr_pool_size | Optional | number | RDMA data WR pool size (RDMA only) 8115 8116#### Example 8117 8118Example request: 8119 8120~~~json 8121{ 8122 "jsonrpc": "2.0", 8123 "method": "nvmf_create_transport", 8124 "id": 1, 8125 "params": { 8126 "trtype": "RDMA", 8127 "max_queue_depth": 32 8128 } 8129} 8130~~~ 8131 8132Example response: 8133 8134~~~json 8135{ 8136 "jsonrpc": "2.0", 8137 "id": 1, 8138 "result": true 8139} 8140~~~ 8141 8142### nvmf_get_subsystems method {#rpc_nvmf_get_subsystems} 8143 8144#### Parameters 8145 8146Name | Optional | Type | Description 8147--------------------------- | -------- | ------------| ----------- 8148tgt_name | Optional | string | Parent NVMe-oF target name. 8149 8150#### Example 8151 8152Example request: 8153 8154~~~json 8155{ 8156 "jsonrpc": "2.0", 8157 "id": 1, 8158 "method": "nvmf_get_subsystems" 8159} 8160~~~ 8161 8162Example response: 8163 8164~~~json 8165{ 8166 "jsonrpc": "2.0", 8167 "id": 1, 8168 "result": [ 8169 { 8170 "nqn": "nqn.2014-08.org.nvmexpress.discovery", 8171 "subtype": "Discovery" 8172 "listen_addresses": [], 8173 "hosts": [], 8174 "allow_any_host": true 8175 }, 8176 { 8177 "nqn": "nqn.2016-06.io.spdk:cnode1", 8178 "subtype": "NVMe", 8179 "listen_addresses": [ 8180 { 8181 "trtype": "RDMA", 8182 "adrfam": "IPv4", 8183 "traddr": "192.168.0.123", 8184 "trsvcid": "4420" 8185 } 8186 ], 8187 "hosts": [ 8188 {"nqn": "nqn.2016-06.io.spdk:host1"} 8189 ], 8190 "allow_any_host": false, 8191 "serial_number": "abcdef", 8192 "model_number": "ghijklmnop", 8193 "namespaces": [ 8194 {"nsid": 1, "name": "Malloc2"}, 8195 {"nsid": 2, "name": "Nvme0n1"} 8196 ] 8197 } 8198 ] 8199} 8200~~~ 8201 8202### nvmf_create_subsystem method {#rpc_nvmf_create_subsystem} 8203 8204Construct an NVMe over Fabrics target subsystem. 8205 8206#### Parameters 8207 8208Name | Optional | Type | Description 8209-------------------------- | -------- | ----------- | ----------- 8210nqn | Required | string | Subsystem NQN 8211tgt_name | Optional | string | Parent NVMe-oF target name. 8212serial_number | Optional | string | Serial number of virtual controller 8213model_number | Optional | string | Model number of virtual controller 8214max_namespaces | Optional | number | Maximum number of namespaces that can be attached to the subsystem. Default: 32 (also used if user specifies 0) 8215allow_any_host | Optional | boolean | Allow any host (`true`) or enforce allowed host list (`false`). Default: `false`. 8216ana_reporting | Optional | boolean | Enable ANA reporting feature (default: `false`). 8217min_cntlid | Optional | number | Minimum controller ID. Default: 1 8218max_cntlid | Optional | number | Maximum controller ID. Default: 0xffef 8219max_discard_size_kib | Optional | number | Maximum discard size (Kib). Default: 0 8220max_write_zeroes_size_kib | Optional | number | Maximum write_zeroes size (Kib). Default: 0 8221 8222#### Example 8223 8224Example request: 8225 8226~~~json 8227{ 8228 "jsonrpc": "2.0", 8229 "id": 1, 8230 "method": "nvmf_create_subsystem", 8231 "params": { 8232 "nqn": "nqn.2016-06.io.spdk:cnode1", 8233 "allow_any_host": false, 8234 "serial_number": "abcdef", 8235 "model_number": "ghijklmnop" 8236 } 8237} 8238~~~ 8239 8240Example response: 8241 8242~~~json 8243{ 8244 "jsonrpc": "2.0", 8245 "id": 1, 8246 "result": true 8247} 8248~~~ 8249 8250### nvmf_delete_subsystem method {#rpc_nvmf_delete_subsystem} 8251 8252Delete an existing NVMe-oF subsystem. 8253 8254#### Parameters 8255 8256Parameter | Optional | Type | Description 8257---------------------- | -------- | ----------- | ----------- 8258nqn | Required | string | Subsystem NQN to delete. 8259tgt_name | Optional | string | Parent NVMe-oF target name. 8260 8261#### Example 8262 8263Example request: 8264 8265~~~json 8266{ 8267 "jsonrpc": "2.0", 8268 "id": 1, 8269 "method": "nvmf_delete_subsystem", 8270 "params": { 8271 "nqn": "nqn.2016-06.io.spdk:cnode1" 8272 } 8273} 8274~~~ 8275 8276Example response: 8277 8278~~~json 8279{ 8280 "jsonrpc": "2.0", 8281 "id": 1, 8282 "result": true 8283} 8284~~~ 8285 8286### nvmf_subsystem_add_listener method {#rpc_nvmf_subsystem_add_listener} 8287 8288Add a new listen address to an NVMe-oF subsystem. 8289 8290This method will fail if listener with given address already exists. 8291 8292#### Parameters 8293 8294Name | Optional | Type | Description 8295----------------------- | -------- | ----------- | ----------- 8296nqn | Required | string | Subsystem NQN 8297tgt_name | Optional | string | Parent NVMe-oF target name. 8298listen_address | Required | object | @ref rpc_nvmf_listen_address object 8299secure_channel | Optional | bool | Whether all connections immediately attempt to establish a secure channel 8300 8301#### listen_address {#rpc_nvmf_listen_address} 8302 8303The listen_address is used for adding the listeners to the NVMe-oF target 8304and for referring to discovery services on other targets. 8305 8306Name | Optional | Type | Description 8307----------------------- | -------- | ----------- | ----------- 8308trtype | Required | string | Transport type ("RDMA") 8309adrfam | Optional | string | Address family ("IPv4", "IPv6", "IB", or "FC") 8310traddr | Required | string | Transport address 8311trsvcid | Optional | string | Transport service ID (required for RDMA or TCP) 8312 8313#### Example 8314 8315Example request: 8316 8317~~~json 8318{ 8319 "jsonrpc": "2.0", 8320 "id": 1, 8321 "method": "nvmf_subsystem_add_listener", 8322 "params": { 8323 "nqn": "nqn.2016-06.io.spdk:cnode1", 8324 "listen_address": { 8325 "trtype": "RDMA", 8326 "adrfam": "IPv4", 8327 "traddr": "192.168.0.123", 8328 "trsvcid": "4420" 8329 } 8330 } 8331} 8332~~~ 8333 8334Example response: 8335 8336~~~json 8337{ 8338 "jsonrpc": "2.0", 8339 "id": 1, 8340 "result": true 8341} 8342~~~ 8343 8344### nvmf_subsystem_remove_listener method {#rpc_nvmf_subsystem_remove_listener} 8345 8346Remove a listen address from an NVMe-oF subsystem. 8347 8348#### Parameters 8349 8350Name | Optional | Type | Description 8351----------------------- | -------- | ----------- | ----------- 8352nqn | Required | string | Subsystem NQN 8353tgt_name | Optional | string | Parent NVMe-oF target name. 8354listen_address | Required | object | @ref rpc_nvmf_listen_address object 8355 8356#### Example 8357 8358Example request: 8359 8360~~~json 8361{ 8362 "jsonrpc": "2.0", 8363 "id": 1, 8364 "method": "nvmf_subsystem_remove_listener", 8365 "params": { 8366 "nqn": "nqn.2016-06.io.spdk:cnode1", 8367 "listen_address": { 8368 "trtype": "RDMA", 8369 "adrfam": "IPv4", 8370 "traddr": "192.168.0.123", 8371 "trsvcid": "4420" 8372 } 8373 } 8374} 8375~~~ 8376 8377Example response: 8378 8379~~~json 8380{ 8381 "jsonrpc": "2.0", 8382 "id": 1, 8383 "result": true 8384} 8385~~~ 8386 8387### nvmf_subsystem_listener_set_ana_state method {#rpc_nvmf_subsystem_listener_set_ana_state} 8388 8389Set ANA state of a listener for an NVMe-oF subsystem. Only the ANA state of the specified ANA 8390group is updated, or ANA states of all ANA groups if ANA group is not specified. 8391 8392#### Parameters 8393 8394Name | Optional | Type | Description 8395----------------------- | -------- | ----------- | ----------- 8396nqn | Required | string | Subsystem NQN 8397tgt_name | Optional | string | Parent NVMe-oF target name. 8398listen_address | Required | object | @ref rpc_nvmf_listen_address object 8399ana_state | Required | string | ANA state to set ("optimized", "non_optimized", or "inaccessible") 8400anagrpid | Optional | number | ANA group ID 8401 8402#### Example 8403 8404Example request: 8405 8406~~~json 8407{ 8408 "jsonrpc": "2.0", 8409 "id": 1, 8410 "method": "nvmf_subsystem_listener_set_ana_state", 8411 "params": { 8412 "nqn": "nqn.2016-06.io.spdk:cnode1", 8413 "listen_address": { 8414 "trtype": "RDMA", 8415 "adrfam": "IPv4", 8416 "traddr": "192.168.0.123", 8417 "trsvcid": "4420" 8418 }, 8419 "ana_state", "inaccessible" 8420 } 8421} 8422~~~ 8423 8424Example response: 8425 8426~~~json 8427{ 8428 "jsonrpc": "2.0", 8429 "id": 1, 8430 "result": true 8431} 8432~~~ 8433 8434### nvmf_subsystem_add_ns method {#rpc_nvmf_subsystem_add_ns} 8435 8436Add a namespace to a subsystem. The namespace ID is returned as the result. 8437 8438### Parameters 8439 8440Name | Optional | Type | Description 8441----------------------- | -------- | ----------- | ----------- 8442nqn | Required | string | Subsystem NQN 8443namespace | Required | object | @ref rpc_nvmf_namespace object 8444tgt_name | Optional | string | Parent NVMe-oF target name. 8445no_auto_visible | Optional | bool | Namespace is not automatically visible to controllers (default: false) 8446 8447#### namespace {#rpc_nvmf_namespace} 8448 8449Name | Optional | Type | Description 8450----------------------- | -------- | ----------- | ----------- 8451nsid | Optional | number | Namespace ID between 1 and 4294967294, inclusive. Default: Automatically assign NSID. 8452bdev_name | Required | string | Name of bdev to expose as a namespace. 8453nguid | Optional | string | 16-byte namespace globally unique identifier in hexadecimal (e.g. "ABCDEF0123456789ABCDEF0123456789") 8454eui64 | Optional | string | 8-byte namespace EUI-64 in hexadecimal (e.g. "ABCDEF0123456789") 8455uuid | Optional | string | RFC 4122 UUID (e.g. "ceccf520-691e-4b46-9546-34af789907c5") 8456ptpl_file | Optional | string | File path to save/restore persistent reservation information 8457anagrpid | Optional | number | ANA group ID. Default: Namespace ID. 8458 8459#### Example 8460 8461Example request: 8462 8463~~~json 8464{ 8465 "jsonrpc": "2.0", 8466 "id": 1, 8467 "method": "nvmf_subsystem_add_ns", 8468 "params": { 8469 "nqn": "nqn.2016-06.io.spdk:cnode1", 8470 "namespace": { 8471 "nsid": 3, 8472 "bdev_name": "Nvme0n1", 8473 "ptpl_file": "/opt/Nvme0n1PR.json" 8474 } 8475 } 8476} 8477~~~ 8478 8479Example response: 8480 8481~~~json 8482{ 8483 "jsonrpc": "2.0", 8484 "id": 1, 8485 "result": 3 8486} 8487~~~ 8488 8489### nvmf_subsystem_remove_ns method {#rpc_nvmf_subsystem_remove_ns} 8490 8491Remove a namespace from a subsystem. 8492 8493#### Parameters 8494 8495Name | Optional | Type | Description 8496----------------------- | -------- | ----------- | ----------- 8497nqn | Required | string | Subsystem NQN 8498nsid | Required | number | Namespace ID 8499tgt_name | Optional | string | Parent NVMe-oF target name. 8500 8501#### Example 8502 8503Example request: 8504 8505~~~json 8506{ 8507 "jsonrpc": "2.0", 8508 "id": 1, 8509 "method": "nvmf_subsystem_remove_ns", 8510 "params": { 8511 "nqn": "nqn.2016-06.io.spdk:cnode1", 8512 "nsid": 1 8513 } 8514} 8515~~~ 8516 8517Example response: 8518 8519~~~json 8520{ 8521 "jsonrpc": "2.0", 8522 "id": 1, 8523 "result": true 8524} 8525~~~ 8526 8527### nvmf_subsystem_add_host method {#rpc_nvmf_subsystem_add_host} 8528 8529Add a host NQN to the list of allowed hosts. Adding an already allowed host will result in an 8530error. 8531 8532#### Parameters 8533 8534Name | Optional | Type | Description 8535----------------------- | -------- | ----------- | ----------- 8536nqn | Required | string | Subsystem NQN 8537host | Required | string | Host NQN to add to the list of allowed host NQNs 8538tgt_name | Optional | string | Parent NVMe-oF target name. 8539psk | Optional | string | Path to a file containing PSK for TLS connection 8540dhchap_key | Optional | string | DH-HMAC-CHAP key name. 8541dhchap_ctrlr_key | Optional | string | DH-HMAC-CHAP controller key name. 8542 8543#### Example 8544 8545Example request: 8546 8547~~~json 8548{ 8549 "jsonrpc": "2.0", 8550 "id": 1, 8551 "method": "nvmf_subsystem_add_host", 8552 "params": { 8553 "nqn": "nqn.2016-06.io.spdk:cnode1", 8554 "host": "nqn.2016-06.io.spdk:host1", 8555 "dhchap_key": "key0" 8556 } 8557} 8558~~~ 8559 8560Example response: 8561 8562~~~json 8563{ 8564 "jsonrpc": "2.0", 8565 "id": 1, 8566 "result": true 8567} 8568~~~ 8569 8570### nvmf_subsystem_remove_host method {#rpc_nvmf_subsystem_remove_host} 8571 8572Remove a host NQN from the list of allowed hosts. 8573 8574#### Parameters 8575 8576Name | Optional | Type | Description 8577----------------------- | -------- | ----------- | ----------- 8578nqn | Required | string | Subsystem NQN 8579host | Required | string | Host NQN to remove from the list of allowed host NQNs 8580tgt_name | Optional | string | Parent NVMe-oF target name. 8581 8582#### Example 8583 8584Example request: 8585 8586~~~json 8587{ 8588 "jsonrpc": "2.0", 8589 "id": 1, 8590 "method": "nvmf_subsystem_remove_host", 8591 "params": { 8592 "nqn": "nqn.2016-06.io.spdk:cnode1", 8593 "host": "nqn.2016-06.io.spdk:host1" 8594 } 8595} 8596~~~ 8597 8598Example response: 8599 8600~~~json 8601{ 8602 "jsonrpc": "2.0", 8603 "id": 1, 8604 "result": true 8605} 8606~~~ 8607 8608### nvmf_subsystem_allow_any_host method {#rpc_nvmf_subsystem_allow_any_host} 8609 8610Configure a subsystem to allow any host to connect or to enforce the host NQN list. 8611 8612#### Parameters 8613 8614Name | Optional | Type | Description 8615----------------------- | -------- | ----------- | ----------- 8616nqn | Required | string | Subsystem NQN 8617allow_any_host | Required | boolean | Allow any host (`true`) or enforce allowed host list (`false`). 8618tgt_name | Optional | string | Parent NVMe-oF target name. 8619 8620#### Example 8621 8622Example request: 8623 8624~~~json 8625{ 8626 "jsonrpc": "2.0", 8627 "id": 1, 8628 "method": "nvmf_subsystem_allow_any_host", 8629 "params": { 8630 "nqn": "nqn.2016-06.io.spdk:cnode1", 8631 "allow_any_host": true 8632 } 8633} 8634~~~ 8635 8636Example response: 8637 8638~~~json 8639{ 8640 "jsonrpc": "2.0", 8641 "id": 1, 8642 "result": true 8643} 8644~~~ 8645 8646### nvmf_subsystem_get_controllers {#rpc_nvmf_subsystem_get_controllers} 8647 8648#### Parameters 8649 8650Name | Optional | Type | Description 8651----------------------- | -------- | ----------- | ----------- 8652nqn | Required | string | Subsystem NQN 8653tgt_name | Optional | string | Parent NVMe-oF target name. 8654 8655#### Example 8656 8657Example request: 8658 8659~~~json 8660{ 8661 "jsonrpc": "2.0", 8662 "id": 1, 8663 "method": "nvmf_subsystem_get_controllers", 8664 "params": { 8665 "nqn": "nqn.2016-06.io.spdk:cnode1" 8666 } 8667} 8668~~~ 8669 8670Example response: 8671 8672~~~json 8673{ 8674 "jsonrpc": "2.0", 8675 "id": 1, 8676 "result": [ 8677 { 8678 "cntlid": 1, 8679 "hostnqn": "nqn.2016-06.io.spdk:host1", 8680 "hostid": "27dad528-6368-41c3-82d3-0b956b49025d", 8681 "num_io_qpairs": 5 8682 } 8683 ] 8684} 8685~~~ 8686 8687### nvmf_subsystem_get_qpairs {#rpc_nvmf_subsystem_get_qpairs} 8688 8689#### Parameters 8690 8691Name | Optional | Type | Description 8692----------------------- | -------- | ----------- | ----------- 8693nqn | Required | string | Subsystem NQN 8694tgt_name | Optional | string | Parent NVMe-oF target name. 8695 8696#### Example 8697 8698Example request: 8699 8700~~~json 8701{ 8702 "jsonrpc": "2.0", 8703 "id": 1, 8704 "method": "nvmf_subsystem_get_qpairs", 8705 "params": { 8706 "nqn": "nqn.2016-06.io.spdk:cnode1" 8707 } 8708} 8709~~~ 8710 8711Example response: 8712 8713~~~json 8714{ 8715 "jsonrpc": "2.0", 8716 "id": 1, 8717 "result": [ 8718 { 8719 "cntlid": 1, 8720 "qid": 0, 8721 "state": "active", 8722 "listen_address": { 8723 "trtype": "RDMA", 8724 "adrfam": "IPv4", 8725 "traddr": "192.168.0.123", 8726 "trsvcid": "4420" 8727 } 8728 }, 8729 { 8730 "cntlid": 1, 8731 "qid": 1, 8732 "state": "active", 8733 "listen_address": { 8734 "trtype": "RDMA", 8735 "adrfam": "IPv4", 8736 "traddr": "192.168.0.123", 8737 "trsvcid": "4420" 8738 } 8739 } 8740 ] 8741} 8742~~~ 8743 8744### nvmf_subsystem_get_listeners {#rpc_nvmf_subsystem_get_listeners} 8745 8746#### Parameters 8747 8748Name | Optional | Type | Description 8749----------------------- | -------- | ----------- | ----------- 8750nqn | Required | string | Subsystem NQN 8751tgt_name | Optional | string | Parent NVMe-oF target name. 8752 8753#### Example 8754 8755Example request: 8756 8757~~~json 8758{ 8759 "jsonrpc": "2.0", 8760 "id": 1, 8761 "method": "nvmf_subsystem_get_listeners", 8762 "params": { 8763 "nqn": "nqn.2016-06.io.spdk:cnode1" 8764 } 8765} 8766~~~ 8767 8768Example response: 8769 8770~~~json 8771{ 8772 "jsonrpc": "2.0", 8773 "id": 1, 8774 "result": [ 8775 { 8776 "address": { 8777 "trtype": "RDMA", 8778 "adrfam": "IPv4", 8779 "traddr": "192.168.0.123", 8780 "trsvcid": "4420" 8781 }, 8782 "ana_state": "optimized" 8783 } 8784 ] 8785} 8786~~~ 8787 8788### nvmf_ns_add_host {#rpc_nvmf_ns_add_host} 8789 8790Make the specified namespace of the specified subnqn visible to any existing 8791or future controllers with the specified hostnqn. 8792 8793Note: the namespace must have been added with no_auto_visible = false 8794(see @ref rpc_nvmf_subsystem_add_ns). 8795 8796#### Parameters 8797 8798Name | Optional | Type | Description 8799----------------------- | -------- | ----------- | ----------- 8800nqn | Required | string | Subsystem NQN 8801nsid | Required | number | Namespace ID 8802host | Required | string | Host NQN 8803 8804#### Example 8805 8806Example request: 8807 8808~~~json 8809{ 8810 "jsonrpc": "2.0", 8811 "id": 1, 8812 "method": "nvmf_ns_add_host", 8813 "params": { 8814 "nqn": "nqn.2016-06.io.spdk:cnode1", 8815 "nsid": 1, 8816 "host": "nqn.2024-01.io.spdk:host0" 8817 } 8818} 8819~~~ 8820 8821Example response: 8822 8823~~~json 8824{ 8825 "jsonrpc": "2.0", 8826 "id": 1, 8827 "result": true 8828} 8829~~~ 8830 8831### nvmf_ns_remove_host {#rpc_nvmf_ns_remove_host} 8832 8833Make the specified namespace of the specified subnqn not visible to any existing 8834or future controllers with the specified hostnqn. 8835 8836Note: the namespace must have been added to the subsystem with 8837no_auto_visible = false (see @ref rpc_nvmf_subsystem_add_ns). 8838 8839#### Parameters 8840 8841Name | Optional | Type | Description 8842----------------------- | -------- | ----------- | ----------- 8843nqn | Required | string | Subsystem NQN 8844nsid | Required | number | Namespace ID 8845host | Required | string | Host NQN 8846 8847#### Example 8848 8849Example request: 8850 8851~~~json 8852{ 8853 "jsonrpc": "2.0", 8854 "id": 1, 8855 "method": "nvmf_ns_remove_host", 8856 "params": { 8857 "nqn": "nqn.2016-06.io.spdk:cnode1", 8858 "nsid": 1, 8859 "host": "nqn.2024-01.io.spdk:host0" 8860 } 8861} 8862~~~ 8863 8864Example response: 8865 8866~~~json 8867{ 8868 "jsonrpc": "2.0", 8869 "id": 1, 8870 "result": true 8871} 8872~~~ 8873 8874### nvmf_set_max_subsystems {#rpc_nvmf_set_max_subsystems} 8875 8876Set the maximum allowed subsystems for the NVMe-oF target. This RPC may only be called 8877before SPDK subsystems have been initialized. 8878 8879#### Parameters 8880 8881Name | Optional | Type | Description 8882----------------------- | -------- | ----------- | ----------- 8883max_subsystems | Required | number | Maximum number of NVMe-oF subsystems 8884 8885#### Example 8886 8887Example request: 8888 8889~~~json 8890{ 8891 "jsonrpc": "2.0", 8892 "id": 1, 8893 "method": "nvmf_set_max_subsystems", 8894 "params": { 8895 "max_subsystems": 1024 8896 } 8897} 8898~~~ 8899 8900Example response: 8901 8902~~~json 8903{ 8904 "jsonrpc": "2.0", 8905 "id": 1, 8906 "result": true 8907} 8908~~~ 8909 8910### nvmf_discovery_add_referral method {#rpc_nvmf_discovery_add_referral} 8911 8912Add a discovery service referral to an NVMe-oF target. If a referral with the given 8913parameters already exists, no action will be taken. 8914 8915#### Parameters 8916 8917Name | Optional | Type | Description 8918----------------------- | -------- | ----------- | ----------- 8919tgt_name | Optional | string | Parent NVMe-oF target name. 8920address | Required | object | @ref rpc_nvmf_listen_address object 8921secure_channel | Optional | bool | The connection to that discovery subsystem requires a secure channel 8922 8923#### Example 8924 8925Example request: 8926 8927~~~json 8928{ 8929 "jsonrpc": "2.0", 8930 "id": 1, 8931 "method": "nvmf_discovery_add_referral", 8932 "params": { 8933 "address": { 8934 "trtype": "RDMA", 8935 "adrfam": "IPv4", 8936 "traddr": "192.168.0.123", 8937 "trsvcid": "4420" 8938 } 8939 } 8940} 8941~~~ 8942 8943Example response: 8944 8945~~~json 8946{ 8947 "jsonrpc": "2.0", 8948 "id": 1, 8949 "result": true 8950} 8951~~~ 8952 8953### nvmf_discovery_remove_referral method {#rpc_nvmf_discovery_remove_referral} 8954 8955Remove a discovery service referral from an NVMe-oF target. 8956 8957#### Parameters 8958 8959Name | Optional | Type | Description 8960----------------------- | -------- | ----------- | ----------- 8961tgt_name | Optional | string | Parent NVMe-oF target name. 8962address | Required | object | @ref rpc_nvmf_listen_address object 8963 8964#### Example 8965 8966Example request: 8967 8968~~~json 8969{ 8970 "jsonrpc": "2.0", 8971 "id": 1, 8972 "method": "nvmf_discovery_remove_referral", 8973 "params": { 8974 "address": { 8975 "trtype": "RDMA", 8976 "adrfam": "IPv4", 8977 "traddr": "192.168.0.123", 8978 "trsvcid": "4420" 8979 } 8980 } 8981} 8982~~~ 8983 8984Example response: 8985 8986~~~json 8987{ 8988 "jsonrpc": "2.0", 8989 "id": 1, 8990 "result": true 8991} 8992~~~ 8993 8994### nvmf_discovery_get_referrals {#rpc_nvmf_discovery_get_referrals} 8995 8996#### Parameters 8997 8998Name | Optional | Type | Description 8999----------------------- | -------- | ----------- | ----------- 9000tgt_name | Optional | string | Parent NVMe-oF target name. 9001 9002#### Example 9003 9004Example request: 9005 9006~~~json 9007{ 9008 "jsonrpc": "2.0", 9009 "id": 1, 9010 "method": "nvmf_discovery_get_referrals" 9011} 9012~~~ 9013 9014Example response: 9015 9016~~~json 9017{ 9018 "jsonrpc": "2.0", 9019 "id": 1, 9020 "result": [ 9021 { 9022 "address": { 9023 "trtype": "RDMA", 9024 "adrfam": "IPv4", 9025 "traddr": "192.168.0.123", 9026 "trsvcid": "4420" 9027 } 9028 } 9029 ] 9030} 9031~~~ 9032 9033### nvmf_set_config {#rpc_nvmf_set_config} 9034 9035Set global configuration of NVMe-oF target. This RPC may only be called before SPDK subsystems 9036have been initialized. 9037 9038#### Parameters 9039 9040Name | Optional | Type | Description 9041----------------------- | -------- | ----------- | ----------- 9042acceptor_poll_rate | Optional | number | Polling interval of the acceptor for incoming connections (microseconds) 9043admin_cmd_passthru | Optional | object | Admin command passthru configuration 9044poll_groups_mask | Optional | string | Set cpumask for NVMf poll groups 9045discovery_filter | Optional | string | Set discovery filter, possible values are: `match_any` (default) or comma separated values: `transport`, `address`, `svcid` 9046dhchap_digests | Optional | list | List of allowed DH-HMAC-CHAP digests. 9047dhchap_dhgroups | Optional | list | List of allowed DH-HMAC-CHAP DH groups. 9048 9049#### admin_cmd_passthru {#spdk_nvmf_admin_passthru_conf} 9050 9051Name | Optional | Type | Description 9052----------------------- | -------- | ----------- | ----------- 9053identify_ctrlr | Required | bool | If true, enables custom identify handler that reports some identify attributes from the underlying NVMe drive 9054 9055#### Example 9056 9057Example request: 9058 9059~~~json 9060{ 9061 "jsonrpc": "2.0", 9062 "id": 1, 9063 "method": "nvmf_set_config", 9064 "params": { 9065 "acceptor_poll_rate": 10000 9066 } 9067} 9068~~~ 9069 9070Example response: 9071 9072~~~json 9073{ 9074 "jsonrpc": "2.0", 9075 "id": 1, 9076 "result": true 9077} 9078~~~ 9079 9080### nvmf_get_transports method {#rpc_nvmf_get_transports} 9081 9082#### Parameters 9083 9084The user may specify no parameters in order to list all transports, or a transport may be 9085specified by type. 9086 9087Name | Optional | Type | Description 9088--------------------------- | -------- | ------------| ----------- 9089tgt_name | Optional | string | Parent NVMe-oF target name. 9090trtype | Optional | string | Transport type. 9091 9092#### Example 9093 9094Example request: 9095 9096~~~json 9097{ 9098 "jsonrpc": "2.0", 9099 "id": 1, 9100 "method": "nvmf_get_transports" 9101} 9102~~~ 9103 9104Example response: 9105 9106~~~json 9107{ 9108 "jsonrpc": "2.0", 9109 "id": 1, 9110 "result": [ 9111 { 9112 "type": "RDMA". 9113 "max_queue_depth": 128, 9114 "max_io_qpairs_per_ctrlr": 64, 9115 "in_capsule_data_size": 4096, 9116 "max_io_size": 131072, 9117 "io_unit_size": 131072, 9118 "abort_timeout_sec": 1 9119 } 9120 ] 9121} 9122~~~ 9123 9124### nvmf_get_stats method {#rpc_nvmf_get_stats} 9125 9126Retrieve current statistics of the NVMf subsystem. 9127 9128#### Parameters 9129 9130Name | Optional | Type | Description 9131--------------------------- | -------- | ------------| ----------- 9132tgt_name | Optional | string | Parent NVMe-oF target name. 9133 9134#### Response 9135 9136The response is an object containing NVMf subsystem statistics. 9137In the response, `admin_qpairs` and `io_qpairs` are reflecting cumulative queue pair counts while 9138`current_admin_qpairs` and `current_io_qpairs` are showing the current number. 9139 9140#### Example 9141 9142Example request: 9143 9144~~~json 9145{ 9146 "jsonrpc": "2.0", 9147 "method": "nvmf_get_stats", 9148 "id": 1 9149} 9150~~~ 9151 9152Example response: 9153 9154~~~json 9155{ 9156 "jsonrpc": "2.0", 9157 "id": 1, 9158 "result": { 9159 "tick_rate": 2400000000, 9160 "poll_groups": [ 9161 { 9162 "name": "app_thread", 9163 "admin_qpairs": 1, 9164 "io_qpairs": 4, 9165 "current_admin_qpairs": 1, 9166 "current_io_qpairs": 2, 9167 "pending_bdev_io": 1721, 9168 "transports": [ 9169 { 9170 "trtype": "RDMA", 9171 "pending_data_buffer": 12131888, 9172 "devices": [ 9173 { 9174 "name": "mlx5_1", 9175 "polls": 72284105, 9176 "completions": 0, 9177 "requests": 0, 9178 "request_latency": 0, 9179 "pending_free_request": 0, 9180 "pending_rdma_read": 0, 9181 "pending_rdma_write": 0, 9182 "total_send_wrs": 0, 9183 "send_doorbell_updates": 0, 9184 "total_recv_wrs": 0, 9185 "recv_doorbell_updates": 1 9186 }, 9187 { 9188 "name": "mlx5_0", 9189 "polls": 72284105, 9190 "completions": 15165875, 9191 "requests": 7582935, 9192 "request_latency": 1249323766184, 9193 "pending_free_request": 0, 9194 "pending_rdma_read": 337602, 9195 "pending_rdma_write": 0, 9196 "total_send_wrs": 15165875, 9197 "send_doorbell_updates": 1516587, 9198 "total_recv_wrs": 15165875, 9199 "recv_doorbell_updates": 1516587 9200 } 9201 ] 9202 } 9203 ] 9204 } 9205 ] 9206 } 9207} 9208~~~ 9209 9210### nvmf_set_crdt {#rpc_nvmf_set_crdt} 9211 9212Set the 3 CRDT (Command Retry Delay Time) values. For details about 9213CRDT, please refer to the NVMe specification. Currently all the 9214SPDK nvmf subsystems share the same CRDT values. The default values 9215are 0. This rpc can only be invoked in STARTUP stage. All values are 9216in units of 100 milliseconds (same as the NVMe specification). 9217 9218#### Parameters 9219 9220Name | Optional | Type | Description 9221----------------------- | -------- | ----------- | ----------- 9222crdt1 | Optional | number | Command Retry Delay Time 1 9223crdt2 | Optional | number | Command Retry Delay Time 2 9224crdt3 | Optional | number | Command Retry Delay Time 3 9225 9226## Vfio-user Target 9227 9228### vfu_tgt_set_base_path {#rpc_vfu_tgt_set_base_path} 9229 9230Set base path of Unix Domain socket file. 9231 9232#### Parameters 9233 9234Name | Optional | Type | Description 9235----------------------- | -------- | ----------- | ----------- 9236path | Required | string | Base path 9237 9238#### Example 9239 9240Example request: 9241 9242~~~json 9243{ 9244 "params": { 9245 "path": "/var/run/vfu_tgt" 9246 }, 9247 "jsonrpc": "2.0", 9248 "method": "vfu_tgt_set_base_path", 9249 "id": 1 9250} 9251~~~ 9252 9253Example response: 9254 9255~~~json 9256{ 9257 "jsonrpc": "2.0", 9258 "id": 1, 9259 "result": true 9260} 9261~~~ 9262 9263### vfu_virtio_delete_endpoint {#rpc_vfu_virtio_delete_endpoint} 9264 9265Delete PCI device via endpoint name. 9266 9267#### Parameters 9268 9269Name | Optional | Type | Description 9270----------------------- | -------- | ----------- | ----------- 9271name | Required | string | Endpoint name 9272 9273#### Example 9274 9275Example request: 9276 9277~~~json 9278{ 9279 "params": { 9280 "name": "vfu.0" 9281 }, 9282 "jsonrpc": "2.0", 9283 "method": "vfu_virtio_delete_endpoint", 9284 "id": 1 9285} 9286~~~ 9287 9288Example response: 9289 9290~~~json 9291{ 9292 "jsonrpc": "2.0", 9293 "id": 1, 9294 "result": true 9295} 9296~~~ 9297 9298### vfu_virtio_create_blk_endpoint {#rpc_vfu_virtio_create_blk_endpoint} 9299 9300Create vfio-user virtio-blk PCI endpoint. 9301 9302#### Parameters 9303 9304Name | Optional | Type | Description 9305----------------------- | -------- | ----------- | ----------- 9306name | Required | string | Endpoint name 9307bdev_name | Required | string | Block device name 9308cpumask | Optional | string | CPU masks 9309num_queues | Optional | number | Number of queues 9310qsize | Optional | number | Queue size 9311packed_ring | Optional | boolean | Enable packed ring 9312 9313#### Example 9314 9315Example request: 9316 9317~~~json 9318{ 9319 "params": { 9320 "name": "vfu.0", 9321 "bdev_name": "Malloc0", 9322 "cpumask": "0x2", 9323 "num_queues": 4, 9324 "qsize": 256 9325 }, 9326 "jsonrpc": "2.0", 9327 "method": "vfu_virtio_create_blk_endpoint", 9328 "id": 1 9329} 9330~~~ 9331 9332Example response: 9333 9334~~~json 9335{ 9336 "jsonrpc": "2.0", 9337 "id": 1, 9338 "result": true 9339} 9340~~~ 9341 9342### vfu_virtio_scsi_add_target {#rpc_vfu_virtio_scsi_add_target} 9343 9344Add block device to specified SCSI target of vfio-user virtio-scsi PCI endpoint. 9345 9346#### Parameters 9347 9348Name | Optional | Type | Description 9349----------------------- | -------- | ----------- | ----------- 9350name | Required | string | Endpoint name 9351scsi_target_num | Required | number | SCSI target number 9352bdev_name | Required | string | Block device name 9353 9354#### Example 9355 9356Example request: 9357 9358~~~json 9359{ 9360 "params": { 9361 "name": "vfu.0", 9362 "scsi_target_num": 0, 9363 "bdev_name": "Malloc0" 9364 }, 9365 "jsonrpc": "2.0", 9366 "method": "vfu_virtio_scsi_add_target", 9367 "id": 1 9368} 9369~~~ 9370 9371Example response: 9372 9373~~~json 9374{ 9375 "jsonrpc": "2.0", 9376 "id": 1, 9377 "result": true 9378} 9379~~~ 9380 9381### vfu_virtio_scsi_remove_target {#rpc_vfu_virtio_scsi_remove_target} 9382 9383Remove a SCSI target of vfio-user virtio-scsi PCI endpoint. 9384 9385#### Parameters 9386 9387Name | Optional | Type | Description 9388----------------------- | -------- | ----------- | ----------- 9389name | Required | string | Endpoint name 9390scsi_target_num | Required | number | SCSI target number 9391 9392#### Example 9393 9394Example request: 9395 9396~~~json 9397{ 9398 "params": { 9399 "name": "vfu.0", 9400 "scsi_target_num": 0 9401 }, 9402 "jsonrpc": "2.0", 9403 "method": "vfu_virtio_scsi_remove_target", 9404 "id": 1 9405} 9406~~~ 9407 9408Example response: 9409 9410~~~json 9411{ 9412 "jsonrpc": "2.0", 9413 "id": 1, 9414 "result": true 9415} 9416~~~ 9417 9418### vfu_virtio_create_scsi_endpoint {#rpc_vfu_virtio_create_scsi_endpoint} 9419 9420Create vfio-user virtio-scsi PCI endpoint. 9421 9422#### Parameters 9423 9424Name | Optional | Type | Description 9425----------------------- | -------- | ----------- | ----------- 9426name | Required | string | Endpoint name 9427cpumask | Optional | string | CPU masks 9428num_io_queues | Optional | number | Number of IO queues 9429qsize | Optional | number | Queue size 9430packed_ring | Optional | boolean | Enable packed ring 9431 9432#### Example 9433 9434Example request: 9435 9436~~~json 9437{ 9438 "params": { 9439 "name": "vfu.0", 9440 "cpumask": "0x2", 9441 "num_io_queues": 4, 9442 "qsize": 256 9443 }, 9444 "jsonrpc": "2.0", 9445 "method": "vfu_virtio_create_scsi_endpoint", 9446 "id": 1 9447} 9448~~~ 9449 9450Example response: 9451 9452~~~json 9453{ 9454 "jsonrpc": "2.0", 9455 "id": 1, 9456 "result": true 9457} 9458~~~ 9459 9460## Vhost Target {#jsonrpc_components_vhost_tgt} 9461 9462The following common preconditions need to be met in all target types. 9463 9464Controller name will be used to create UNIX domain socket. This implies that name concatenated with vhost socket 9465directory path needs to be valid UNIX socket name. 9466 9467@ref cpu_mask parameter is used to choose CPU on which pollers will be launched when new initiator is connecting. 9468It must be a subset of application CPU mask. Default value is CPU mask of the application. 9469 9470### vhost_controller_set_coalescing {#rpc_vhost_controller_set_coalescing} 9471 9472Controls interrupt coalescing for specific target. Because `delay_base_us` is used to calculate delay in CPU ticks 9473there is no hardcoded limit for this parameter. Only limitation is that final delay in CPU ticks might not overflow 947432 bit unsigned integer (which is more than 1s @ 4GHz CPU). In real scenarios `delay_base_us` should be much lower 9475than 150us. To disable coalescing set `delay_base_us` to 0. 9476 9477#### Parameters 9478 9479Name | Optional | Type | Description 9480----------------------- | -------- | ----------- | ----------- 9481ctrlr | Required | string | Controller name 9482delay_base_us | Required | number | Base (minimum) coalescing time in microseconds 9483iops_threshold | Required | number | Coalescing activation level greater than 0 in IO per second 9484 9485#### Example 9486 9487Example request: 9488 9489~~~json 9490{ 9491 "params": { 9492 "iops_threshold": 100000, 9493 "ctrlr": "VhostScsi0", 9494 "delay_base_us": 80 9495 }, 9496 "jsonrpc": "2.0", 9497 "method": "vhost_controller_set_coalescing", 9498 "id": 1 9499} 9500~~~ 9501 9502Example response: 9503 9504~~~json 9505{ 9506 "jsonrpc": "2.0", 9507 "id": 1, 9508 "result": true 9509} 9510~~~ 9511 9512### vhost_create_scsi_controller {#rpc_vhost_create_scsi_controller} 9513 9514Construct vhost SCSI target. 9515 9516#### Parameters 9517 9518Name | Optional | Type | Description 9519----------------------- | -------- | ----------- | ----------- 9520ctrlr | Required | string | Controller name 9521cpumask | Optional | string | @ref cpu_mask for this controller 9522delay | Optional | boolean | If true, delay the controller startup. 9523 9524#### Example 9525 9526Example request: 9527 9528~~~json 9529{ 9530 "params": { 9531 "cpumask": "0x2", 9532 "ctrlr": "VhostScsi0", 9533 "delay": true 9534 }, 9535 "jsonrpc": "2.0", 9536 "method": "vhost_create_scsi_controller", 9537 "id": 1 9538} 9539~~~ 9540 9541Example response: 9542 9543~~~json 9544{ 9545 "jsonrpc": "2.0", 9546 "id": 1, 9547 "result": true 9548} 9549~~~ 9550 9551### vhost_start_scsi_controller {#rpc_vhost_start_scsi_controller} 9552 9553Start vhost SCSI controller, if controller is already started, do nothing. 9554 9555#### Parameters 9556 9557Name | Optional | Type | Description 9558----------------------- | -------- | ----------- | ----------- 9559ctrlr | Required | string | Controller name 9560 9561#### Example 9562 9563Example request: 9564 9565~~~json 9566{ 9567 "params": { 9568 "ctrlr": "VhostScsi0", 9569 }, 9570 "jsonrpc": "2.0", 9571 "method": "vhost_start_scsi_controller", 9572 "id": 1 9573} 9574~~~ 9575 9576Example response: 9577 9578~~~json 9579response: 9580{ 9581 "jsonrpc": "2.0", 9582 "id": 1, 9583 "result": true 9584} 9585~~~ 9586 9587### vhost_scsi_controller_add_target {#rpc_vhost_scsi_controller_add_target} 9588 9589In vhost target `ctrlr` create SCSI target with ID `scsi_target_num` and add `bdev_name` as LUN 0. 9590 9591#### Parameters 9592 9593Name | Optional | Type | Description 9594----------------------- | -------- | ----------- | ----------- 9595ctrlr | Required | string | Controller name 9596scsi_target_num | Required | number | SCSI target ID between 0 and 7 or -1 to use first free ID. 9597bdev_name | Required | string | Name of bdev to expose as a LUN 0 9598 9599#### Response 9600 9601SCSI target ID. 9602 9603#### Example 9604 9605Example request: 9606 9607~~~json 9608{ 9609 "params": { 9610 "scsi_target_num": 1, 9611 "bdev_name": "Malloc0", 9612 "ctrlr": "VhostScsi0" 9613 }, 9614 "jsonrpc": "2.0", 9615 "method": "vhost_scsi_controller_add_target", 9616 "id": 1 9617} 9618~~~ 9619 9620Example response: 9621 9622~~~json 9623response: 9624{ 9625 "jsonrpc": "2.0", 9626 "id": 1, 9627 "result": 1 9628} 9629~~~ 9630 9631### vhost_scsi_controller_remove_target {#rpc_vhost_scsi_controller_remove_target} 9632 9633Remove SCSI target ID `scsi_target_num` from vhost target `scsi_target_num`. 9634 9635This method will fail if initiator is connected, but doesn't support hot-remove (the `VIRTIO_SCSI_F_HOTPLUG` is not negotiated). 9636 9637#### Parameters 9638 9639Name | Optional | Type | Description 9640----------------------- | -------- | ----------- | ----------- 9641ctrlr | Required | string | Controller name 9642scsi_target_num | Required | number | SCSI target ID between 0 and 7 9643 9644#### Example 9645 9646Example request: 9647 9648~~~json 9649request: 9650{ 9651 "params": { 9652 "scsi_target_num": 1, 9653 "ctrlr": "VhostScsi0" 9654 }, 9655 "jsonrpc": "2.0", 9656 "method": "vhost_scsi_controller_remove_target", 9657 "id": 1 9658} 9659~~~ 9660 9661Example response: 9662 9663~~~json 9664{ 9665 "jsonrpc": "2.0", 9666 "id": 1, 9667 "result": true 9668} 9669~~~ 9670 9671### virtio_blk_create_transport {#rpc_virtio_blk_create_transport} 9672 9673Create virtio blk transport. 9674 9675#### Parameters 9676 9677Name | Optional | Type | Description 9678----------------------- | -------- | ----------- | ----------- 9679name | Required | string | Transport name 9680 9681#### Example 9682 9683Example request: 9684 9685~~~json 9686{ 9687 "params": { 9688 "name": "vhost_user_blk" 9689 }, 9690 "jsonrpc": "2.0", 9691 "method": "virtio_blk_create_transport", 9692 "id": 1 9693} 9694~~~ 9695 9696Example response: 9697 9698~~~json 9699{ 9700 "jsonrpc": "2.0", 9701 "id": 1, 9702 "result": true 9703} 9704~~~ 9705 9706### virtio_blk_get_transports {#rpc_virtio_blk_get_transports} 9707 9708#### Parameters 9709 9710The user may specify no parameters in order to list all transports, 9711or a transport name may be specified. 9712 9713Name | Optional | Type | Description 9714--------------------------- | -------- | ------------| ----------- 9715name | Optional | string | Transport name. 9716 9717#### Example 9718 9719Example request: 9720 9721~~~json 9722{ 9723 "jsonrpc": "2.0", 9724 "method": "virtio_blk_get_transports", 9725 "id": 1 9726} 9727~~~ 9728 9729Example response: 9730 9731~~~json 9732{ 9733 "jsonrpc": "2.0", 9734 "id": 1, 9735 "result": [ 9736 { 9737 "name": "vhost_user_blk" 9738 } 9739 ] 9740} 9741~~~ 9742 9743### vhost_create_blk_controller {#rpc_vhost_create_blk_controller} 9744 9745Create vhost block controller 9746 9747If `readonly` is `true` then vhost block target will be created as read only and fail any write requests. 9748The `VIRTIO_BLK_F_RO` feature flag will be offered to the initiator. 9749 9750#### Parameters 9751 9752Name | Optional | Type | Description 9753----------------------- | -------- | ----------- | ----------- 9754ctrlr | Required | string | Controller name 9755bdev_name | Required | string | Name of bdev to expose block device 9756readonly | Optional | boolean | If true, this target will be read only (default: false) 9757cpumask | Optional | string | @ref cpu_mask for this controller 9758transport | Optional | string | virtio blk transport name (default: vhost_user_blk) 9759 9760#### Example 9761 9762Example request: 9763 9764~~~json 9765{ 9766 "params": { 9767 "dev_name": "Malloc0", 9768 "ctrlr": "VhostBlk0" 9769 }, 9770 "jsonrpc": "2.0", 9771 "method": "vhost_create_blk_controller", 9772 "id": 1 9773} 9774~~~ 9775 9776Example response: 9777 9778~~~json 9779{ 9780 "jsonrpc": "2.0", 9781 "id": 1, 9782 "result": true 9783} 9784~~~ 9785 9786### vhost_get_controllers {#rpc_vhost_get_controllers} 9787 9788Display information about all or specific vhost controller(s). 9789 9790#### Parameters 9791 9792The user may specify no parameters in order to list all controllers, or a controller may be 9793specified by name. 9794 9795Name | Optional | Type | Description 9796----------------------- | -------- | ----------- | ----------- 9797name | Optional | string | Vhost controller name 9798 9799#### Response {#rpc_vhost_get_controllers_response} 9800 9801Response is an array of objects describing requested controller(s). Common fields are: 9802 9803Name | Type | Description 9804----------------------- | ----------- | ----------- 9805ctrlr | string | Controller name 9806cpumask | string | @ref cpu_mask of this controller 9807delay_base_us | number | Base (minimum) coalescing time in microseconds (0 if disabled) 9808iops_threshold | number | Coalescing activation level 9809backend_specific | object | Backend specific information 9810 9811### Vhost block {#rpc_vhost_get_controllers_blk} 9812 9813`backend_specific` contains one `block` object of type: 9814 9815Name | Type | Description 9816----------------------- | ----------- | ----------- 9817bdev | string | Backing bdev name or Null if bdev is hot-removed 9818readonly | boolean | True if controllers is readonly, false otherwise 9819 9820### Vhost SCSI {#rpc_vhost_get_controllers_scsi} 9821 9822`backend_specific` contains `scsi` array of following objects: 9823 9824Name | Type | Description 9825----------------------- | ----------- | ----------- 9826target_name | string | Name of this SCSI target 9827id | number | Unique SPDK global SCSI target ID 9828scsi_dev_num | number | SCSI target ID initiator will see when scanning this controller 9829luns | array | array of objects describing @ref rpc_vhost_get_controllers_scsi_luns 9830 9831### Vhost SCSI LUN {#rpc_vhost_get_controllers_scsi_luns} 9832 9833Object of type: 9834 9835Name | Type | Description 9836----------------------- | ----------- | ----------- 9837id | number | SCSI LUN ID 9838bdev_name | string | Backing bdev name 9839 9840### Vhost NVMe {#rpc_vhost_get_controllers_nvme} 9841 9842`backend_specific` contains `namespaces` array of following objects: 9843 9844Name | Type | Description 9845----------------------- | ----------- | ----------- 9846nsid | number | Namespace ID 9847bdev | string | Backing bdev name 9848 9849#### Example 9850 9851Example request: 9852 9853~~~json 9854{ 9855 "jsonrpc": "2.0", 9856 "method": "vhost_get_controllers", 9857 "id": 1 9858} 9859~~~ 9860 9861Example response: 9862 9863~~~json 9864{ 9865 "jsonrpc": "2.0", 9866 "id": 1, 9867 "result": [ 9868 { 9869 "cpumask": "0x2", 9870 "backend_specific": { 9871 "block": { 9872 "readonly": false, 9873 "bdev": "Malloc0" 9874 } 9875 }, 9876 "iops_threshold": 60000, 9877 "ctrlr": "VhostBlk0", 9878 "delay_base_us": 100 9879 }, 9880 { 9881 "cpumask": "0x2", 9882 "backend_specific": { 9883 "scsi": [ 9884 { 9885 "target_name": "Target 2", 9886 "luns": [ 9887 { 9888 "id": 0, 9889 "bdev_name": "Malloc1" 9890 } 9891 ], 9892 "id": 0, 9893 "scsi_dev_num": 2 9894 }, 9895 { 9896 "target_name": "Target 5", 9897 "luns": [ 9898 { 9899 "id": 0, 9900 "bdev_name": "Malloc2" 9901 } 9902 ], 9903 "id": 1, 9904 "scsi_dev_num": 5 9905 } 9906 ] 9907 }, 9908 "iops_threshold": 60000, 9909 "ctrlr": "VhostScsi0", 9910 "delay_base_us": 0 9911 }, 9912 { 9913 "cpumask": "0x2", 9914 "backend_specific": { 9915 "namespaces": [ 9916 { 9917 "bdev": "Malloc3", 9918 "nsid": 1 9919 }, 9920 { 9921 "bdev": "Malloc4", 9922 "nsid": 2 9923 } 9924 ] 9925 }, 9926 "iops_threshold": 60000, 9927 "ctrlr": "VhostNvme0", 9928 "delay_base_us": 0 9929 } 9930 ] 9931} 9932~~~ 9933 9934### vhost_delete_controller {#rpc_vhost_delete_controller} 9935 9936Remove vhost target. 9937 9938This call will fail if there is an initiator connected or there is at least one SCSI target configured in case of 9939vhost SCSI target. In the later case please remove all SCSI targets first using @ref rpc_vhost_scsi_controller_remove_target. 9940 9941#### Parameters 9942 9943Name | Optional | Type | Description 9944----------------------- | -------- | ----------- | ----------- 9945ctrlr | Required | string | Controller name 9946 9947#### Example 9948 9949Example request: 9950 9951~~~json 9952{ 9953 "params": { 9954 "ctrlr": "VhostNvme0" 9955 }, 9956 "jsonrpc": "2.0", 9957 "method": "vhost_delete_controller", 9958 "id": 1 9959} 9960~~~ 9961 9962Example response: 9963 9964~~~json 9965{ 9966 "jsonrpc": "2.0", 9967 "id": 1, 9968 "result": true 9969} 9970~~~ 9971 9972## Logical Volume {#jsonrpc_components_lvol} 9973 9974Identification of logical volume store and logical volume is explained first. 9975 9976A logical volume store has a UUID and a name for its identification. 9977The UUID is generated on creation and it can be used as a unique identifier. 9978The name is specified on creation and can be renamed. 9979Either UUID or name is used to access logical volume store in RPCs. 9980 9981A logical volume has a UUID and a name for its identification. 9982The UUID of the logical volume is generated on creation and it can be unique identifier. 9983The alias of the logical volume takes the format _lvs_name/lvol_name_ where: 9984 9985* _lvs_name_ is the name of the logical volume store. 9986* _lvol_name_ is specified on creation and can be renamed. 9987 9988### bdev_lvol_create_lvstore {#rpc_bdev_lvol_create_lvstore} 9989 9990Construct a logical volume store. 9991 9992#### Parameters 9993 9994Name | Optional | Type | Description 9995----------------------------- | -------- | ----------- | ----------- 9996bdev_name | Required | string | Bdev on which to construct logical volume store 9997lvs_name | Required | string | Name of the logical volume store to create 9998cluster_sz | Optional | number | Cluster size of the logical volume store in bytes (Default: 4MiB) 9999clear_method | Optional | string | Change clear method for data region. Available: none, unmap (default), write_zeroes 10000num_md_pages_per_cluster_ratio| Optional | number | Reserved metadata pages per cluster (Default: 100) 10001 10002The num_md_pages_per_cluster_ratio defines the amount of metadata to 10003allocate when the logical volume store is created. The default value 10004is '100', which translates to 1 4KiB per cluster. For the default 4MiB 10005cluster size, this equates to about 0.1% of the underlying block 10006device allocated for metadata. Logical volume stores can be grown, if 10007the size of the underlying block device grows in the future, but only 10008if enough metadata pages were allocated to support the growth. So 10009num_md_pages_per_cluster_ratio should be set to a higher value if 10010wanting to support future growth. For example, 10011num_md_pages_per_cluster_ratio = 200 would support future 2x growth of 10012the logical volume store, and would result in 0.2% of the underlying 10013block device allocated for metadata (with a default 4MiB cluster 10014size). 10015 10016#### Response 10017 10018UUID of the created logical volume store is returned. 10019 10020#### Example 10021 10022Example request: 10023 10024~~~json 10025{ 10026 "jsonrpc": "2.0", 10027 "id": 1, 10028 "method": "bdev_lvol_create_lvstore", 10029 "params": { 10030 "lvs_name": "LVS0", 10031 "bdev_name": "Malloc0" 10032 "clear_method": "write_zeroes" 10033 } 10034} 10035~~~ 10036 10037Example response: 10038 10039~~~json 10040{ 10041 "jsonrpc": "2.0", 10042 "id": 1, 10043 "result": "a9959197-b5e2-4f2d-8095-251ffb6985a5" 10044} 10045~~~ 10046 10047### bdev_lvol_delete_lvstore {#rpc_bdev_lvol_delete_lvstore} 10048 10049Destroy a logical volume store. 10050 10051#### Parameters 10052 10053Name | Optional | Type | Description 10054----------------------- | -------- | ----------- | ----------- 10055uuid | Optional | string | UUID of the logical volume store to destroy 10056lvs_name | Optional | string | Name of the logical volume store to destroy 10057 10058Either uuid or lvs_name must be specified, but not both. 10059 10060#### Example 10061 10062Example request: 10063 10064~~~json 10065{ 10066 "jsonrpc": "2.0", 10067 "method": "bdev_lvol_delete_lvstore", 10068 "id": 1 10069 "params": { 10070 "uuid": "a9959197-b5e2-4f2d-8095-251ffb6985a5" 10071 } 10072} 10073~~~ 10074 10075Example response: 10076 10077~~~json 10078{ 10079 "jsonrpc": "2.0", 10080 "id": 1, 10081 "result": true 10082} 10083~~~ 10084 10085### bdev_lvol_get_lvstores {#rpc_bdev_lvol_get_lvstores} 10086 10087Get a list of logical volume stores. 10088 10089#### Parameters 10090 10091Name | Optional | Type | Description 10092----------------------- | -------- | ----------- | ----------- 10093uuid | Optional | string | UUID of the logical volume store to retrieve information about 10094lvs_name | Optional | string | Name of the logical volume store to retrieve information about 10095 10096Either uuid or lvs_name may be specified, but not both. 10097If both uuid and lvs_name are omitted, information about all logical volume stores is returned. 10098 10099#### Example 10100 10101Example request: 10102 10103~~~json 10104{ 10105 "jsonrpc": "2.0", 10106 "method": "bdev_lvol_get_lvstores", 10107 "id": 1, 10108 "params": { 10109 "lvs_name": "LVS0" 10110 } 10111} 10112~~~ 10113 10114Example response: 10115 10116~~~json 10117{ 10118 "jsonrpc": "2.0", 10119 "id": 1, 10120 "result": [ 10121 { 10122 "uuid": "a9959197-b5e2-4f2d-8095-251ffb6985a5", 10123 "base_bdev": "Malloc0", 10124 "free_clusters": 31, 10125 "cluster_size": 4194304, 10126 "total_data_clusters": 31, 10127 "block_size": 4096, 10128 "name": "LVS0" 10129 } 10130 ] 10131} 10132~~~ 10133 10134### bdev_lvol_rename_lvstore {#rpc_bdev_lvol_rename_lvstore} 10135 10136Rename a logical volume store. 10137 10138#### Parameters 10139 10140Name | Optional | Type | Description 10141----------------------- | -------- | ----------- | ----------- 10142old_name | Required | string | Existing logical volume store name 10143new_name | Required | string | New logical volume store name 10144 10145#### Example 10146 10147Example request: 10148 10149~~~json 10150{ 10151 "jsonrpc": "2.0", 10152 "method": "bdev_lvol_rename_lvstore", 10153 "id": 1, 10154 "params": { 10155 "old_name": "LVS0", 10156 "new_name": "LVS2" 10157 } 10158} 10159~~~ 10160 10161Example response: 10162 10163~~~json 10164{ 10165 "jsonrpc": "2.0", 10166 "id": 1, 10167 "result": true 10168} 10169~~~ 10170 10171### bdev_lvol_grow_lvstore {#rpc_bdev_lvol_grow_lvstore} 10172 10173Grow the logical volume store to fill the underlying bdev 10174 10175#### Parameters 10176 10177Name | Optional | Type | Description 10178----------------------- | -------- | ----------- | ----------- 10179uuid | Optional | string | UUID of the logical volume store to grow 10180lvs_name | Optional | string | Name of the logical volume store to grow 10181 10182Either uuid or lvs_name must be specified, but not both. 10183 10184#### Example 10185 10186Example request: 10187 10188~~~json 10189{ 10190 "jsonrpc": "2.0", 10191 "method": "bdev_lvol_grow_lvstore", 10192 "id": 1 10193 "params": { 10194 "uuid": "a9959197-b5e2-4f2d-8095-251ffb6985a5" 10195 } 10196} 10197~~~ 10198 10199Example response: 10200 10201~~~json 10202{ 10203 "jsonrpc": "2.0", 10204 "id": 1, 10205 "result": true 10206} 10207~~~ 10208 10209### bdev_lvol_create {#rpc_bdev_lvol_create} 10210 10211Create a logical volume on a logical volume store. 10212 10213#### Parameters 10214 10215Name | Optional | Type | Description 10216----------------------- | -------- | ----------- | ----------- 10217lvol_name | Required | string | Name of logical volume to create 10218size_in_mib | Required | number | Desired size of logical volume in MiB 10219thin_provision | Optional | boolean | True to enable thin provisioning 10220uuid | Optional | string | UUID of logical volume store to create logical volume on 10221lvs_name | Optional | string | Name of logical volume store to create logical volume on 10222clear_method | Optional | string | Change default data clusters clear method. Available: none, unmap, write_zeroes 10223 10224Size will be rounded up to a multiple of cluster size. Either uuid or lvs_name must be specified, but not both. 10225lvol_name will be used in the alias of the created logical volume. 10226 10227#### Response 10228 10229UUID of the created logical volume is returned. 10230 10231#### Example 10232 10233Example request: 10234 10235~~~json 10236{ 10237 "jsonrpc": "2.0", 10238 "method": "bdev_lvol_create", 10239 "id": 1, 10240 "params": { 10241 "lvol_name": "LVOL0", 10242 "size_in_mib": 1, 10243 "lvs_name": "LVS0", 10244 "clear_method": "unmap", 10245 "thin_provision": true 10246 } 10247} 10248~~~ 10249 10250Example response: 10251 10252~~~json 10253{ 10254 "jsonrpc": "2.0", 10255 "id": 1, 10256 "result": "1b38702c-7f0c-411e-a962-92c6a5a8a602" 10257} 10258~~~ 10259 10260### bdev_lvol_snapshot {#rpc_bdev_lvol_snapshot} 10261 10262Capture a snapshot of the current state of a logical volume. 10263 10264#### Parameters 10265 10266Name | Optional | Type | Description 10267----------------------- | -------- | ----------- | ----------- 10268lvol_name | Required | string | UUID or alias of the logical volume to create a snapshot from 10269snapshot_name | Required | string | Name for the newly created snapshot 10270 10271#### Response 10272 10273UUID of the created logical volume snapshot is returned. 10274 10275#### Example 10276 10277Example request: 10278 10279~~~json 10280{ 10281 "jsonrpc": "2.0", 10282 "method": "bdev_lvol_snapshot", 10283 "id": 1, 10284 "params": { 10285 "lvol_name": "1b38702c-7f0c-411e-a962-92c6a5a8a602", 10286 "snapshot_name": "SNAP1" 10287 } 10288} 10289~~~ 10290 10291Example response: 10292 10293~~~json 10294{ 10295 "jsonrpc": "2.0", 10296 "id": 1, 10297 "result": "cc8d7fdf-7865-4d1f-9fc6-35da8e368670" 10298} 10299~~~ 10300 10301### bdev_lvol_clone {#rpc_bdev_lvol_clone} 10302 10303Create a logical volume based on a snapshot. 10304 10305#### Parameters 10306 10307Name | Optional | Type | Description 10308----------------------- | -------- | ----------- | ----------- 10309snapshot_name | Required | string | UUID or alias of the snapshot to clone 10310clone_name | Required | string | Name for the logical volume to create 10311 10312#### Response 10313 10314UUID of the created logical volume clone is returned. 10315 10316#### Example 10317 10318Example request: 10319 10320~~~json 10321{ 10322 "jsonrpc": "2.0" 10323 "method": "bdev_lvol_clone", 10324 "id": 1, 10325 "params": { 10326 "snapshot_name": "cc8d7fdf-7865-4d1f-9fc6-35da8e368670", 10327 "clone_name": "CLONE1" 10328 } 10329} 10330~~~ 10331 10332Example response: 10333 10334~~~json 10335{ 10336 "jsonrpc": "2.0", 10337 "id": 1, 10338 "result": "8d87fccc-c278-49f0-9d4c-6237951aca09" 10339} 10340~~~ 10341 10342### bdev_lvol_clone_bdev {#rpc_bdev_lvol_clone_bdev} 10343 10344Create a logical volume based on an external snapshot bdev. The external snapshot bdev 10345is a bdev that will not be written to by any consumer and must not be an lvol in the 10346lvstore as the clone. 10347 10348Regardless of whether the bdev is specified by name or UUID, the bdev UUID will be stored 10349in the logical volume's metadata for use while the lvolstore is loading. For this reason, 10350it is important that the bdev chosen has a static UUID. 10351 10352#### Parameters 10353 10354Name | Optional | Type | Description 10355----------------------- | -------- | ----------- | ----------- 10356bdev | Required | string | Name or UUID for bdev that acts as the external snapshot 10357lvs_name | Required | string | logical volume store name 10358clone_name | Required | string | Name for the logical volume to create 10359 10360#### Response 10361 10362UUID of the created logical volume clone is returned. 10363 10364#### Example 10365 10366Example request: 10367 10368~~~json 10369{ 10370 "jsonrpc": "2.0", 10371 "method": "bdev_lvol_clone_bdev", 10372 "id": 1, 10373 "params": { 10374 "bdev_uuid": "e4b40d8b-f623-416d-8234-baf5a4c83cbd", 10375 "lvs_name": "lvs1", 10376 "clone_name": "clone2" 10377 } 10378} 10379~~~ 10380 10381Example response: 10382 10383~~~json 10384{ 10385 "jsonrpc": "2.0", 10386 "id": 1, 10387 "result": "336f662b-08e5-4006-8e06-e2023f7f9886" 10388} 10389~~~ 10390 10391### bdev_lvol_rename {#rpc_bdev_lvol_rename} 10392 10393Rename a logical volume. New name will rename only the alias of the logical volume. 10394 10395#### Parameters 10396 10397Name | Optional | Type | Description 10398----------------------- | -------- | ----------- | ----------- 10399old_name | Required | string | UUID or alias of the existing logical volume 10400new_name | Required | string | New logical volume name 10401 10402#### Example 10403 10404Example request: 10405 10406~~~json 10407{ 10408 "jsonrpc": "2.0", 10409 "method": "bdev_lvol_rename", 10410 "id": 1, 10411 "params": { 10412 "old_name": "067df606-6dbc-4143-a499-0d05855cb3b8", 10413 "new_name": "LVOL2" 10414 } 10415} 10416~~~ 10417 10418Example response: 10419 10420~~~json 10421{ 10422 "jsonrpc": "2.0", 10423 "id": 1, 10424 "result": true 10425} 10426~~~ 10427 10428### bdev_lvol_resize {#rpc_bdev_lvol_resize} 10429 10430Resize a logical volume. 10431 10432#### Parameters 10433 10434Name | Optional | Type | Description 10435----------------------- | -------- | ----------- | ----------- 10436name | Required | string | UUID or alias of the logical volume to resize 10437size_in_mib | Required | number | Desired size of the logical volume in MiB 10438 10439#### Example 10440 10441Example request: 10442 10443~~~json 10444{ 10445 "jsonrpc": "2.0", 10446 "method": "bdev_lvol_resize", 10447 "id": 1, 10448 "params": { 10449 "name": "51638754-ca16-43a7-9f8f-294a0805ab0a", 10450 "size_in_mib": 2 10451 } 10452} 10453~~~ 10454 10455Example response: 10456 10457~~~json 10458{ 10459 "jsonrpc": "2.0", 10460 "id": 1, 10461 "result": true 10462} 10463~~~ 10464 10465### bdev_lvol_set_read_only{#rpc_bdev_lvol_set_read_only} 10466 10467Mark logical volume as read only. 10468 10469#### Parameters 10470 10471Name | Optional | Type | Description 10472----------------------- | -------- | ----------- | ----------- 10473name | Required | string | UUID or alias of the logical volume to set as read only 10474 10475#### Example 10476 10477Example request: 10478 10479~~~json 10480{ 10481 "jsonrpc": "2.0", 10482 "method": "bdev_lvol_set_read_only", 10483 "id": 1, 10484 "params": { 10485 "name": "51638754-ca16-43a7-9f8f-294a0805ab0a", 10486 } 10487} 10488~~~ 10489 10490Example response: 10491 10492~~~json 10493{ 10494 "jsonrpc": "2.0", 10495 "id": 1, 10496 "result": true 10497} 10498~~~ 10499 10500### bdev_lvol_delete {#rpc_bdev_lvol_delete} 10501 10502Destroy a logical volume. 10503 10504#### Parameters 10505 10506Name | Optional | Type | Description 10507----------------------- | -------- | ----------- | ----------- 10508name | Required | string | UUID or alias of the logical volume to destroy 10509 10510#### Example 10511 10512Example request: 10513 10514~~~json 10515{ 10516 "jsonrpc": "2.0", 10517 "method": "bdev_lvol_delete", 10518 "id": 1, 10519 "params": { 10520 "name": "51638754-ca16-43a7-9f8f-294a0805ab0a" 10521 } 10522} 10523~~~ 10524 10525Example response: 10526 10527~~~json 10528{ 10529 "jsonrpc": "2.0", 10530 "id": 1, 10531 "result": true 10532} 10533~~~ 10534 10535### bdev_lvol_inflate {#rpc_bdev_lvol_inflate} 10536 10537Inflate a logical volume. All unallocated clusters are allocated and copied from the parent or zero filled 10538if not allocated in the parent. Then all dependencies on the parent are removed. 10539 10540### Parameters 10541 10542Name | Optional | Type | Description 10543----------------------- | -------- | ----------- | ----------- 10544name | Required | string | UUID or alias of the logical volume to inflate 10545 10546#### Example 10547 10548Example request: 10549 10550~~~json 10551{ 10552 "jsonrpc": "2.0", 10553 "method": "bdev_lvol_inflate", 10554 "id": 1, 10555 "params": { 10556 "name": "8d87fccc-c278-49f0-9d4c-6237951aca09" 10557 } 10558} 10559~~~ 10560 10561Example response: 10562 10563~~~json 10564{ 10565 "jsonrpc": "2.0", 10566 "id": 1, 10567 "result": true 10568} 10569~~~ 10570 10571### bdev_lvol_decouple_parent {#rpc_bdev_lvol_decouple_parent} 10572 10573Decouple the parent of a logical volume. For unallocated clusters which is allocated in the parent, they are 10574allocated and copied from the parent, but for unallocated clusters which is thin provisioned in the parent, 10575they are kept thin provisioned. Then all dependencies on the parent are removed. 10576 10577#### Parameters 10578 10579Name | Optional | Type | Description 10580----------------------- | -------- | ----------- | ----------- 10581name | Required | string | UUID or alias of the logical volume to decouple the parent of it 10582 10583#### Example 10584 10585Example request: 10586 10587~~~json 10588{ 10589 "jsonrpc": "2.0", 10590 "method": "bdev_lvol_decouple_parent", 10591 "id": 1. 10592 "params": { 10593 "name": "8d87fccc-c278-49f0-9d4c-6237951aca09" 10594 } 10595} 10596~~~ 10597 10598Example response: 10599 10600~~~json 10601{ 10602 "jsonrpc": "2.0", 10603 "id": 1, 10604 "result": true 10605} 10606~~~ 10607 10608### bdev_lvol_get_lvols {#rpc_bdev_lvol_get_lvols} 10609 10610Get a list of logical volumes. This list can be limited by lvol store and will display volumes even if 10611they are degraded. Degraded lvols do not have an associated bdev, thus this RPC call may return lvols 10612not returned by `bdev_get_bdevs`. 10613 10614#### Parameters 10615 10616Name | Optional | Type | Description 10617----------------------- | -------- | ----------- | ----------- 10618lvs_uuid | Optional | string | Only show volumes in the logical volume store with this UUID 10619lvs_name | Optional | string | Only show volumes in the logical volume store with this name 10620 10621Either lvs_uuid or lvs_name may be specified, but not both. 10622If both lvs_uuid and lvs_name are omitted, information about lvols in all logical volume stores is returned. 10623 10624#### Example 10625 10626Example request: 10627 10628~~~json 10629{ 10630 "jsonrpc": "2.0", 10631 "method": "bdev_lvol_get_lvols", 10632 "id": 1, 10633 "params": { 10634 "lvs_name": "lvs_test" 10635 } 10636} 10637~~~ 10638 10639Example response: 10640 10641~~~json 10642[ 10643 { 10644 "alias": "lvs_test/lvol1", 10645 "uuid": "b335c368-851d-4099-81e0-018cc494fdf6", 10646 "name": "lvol1", 10647 "is_thin_provisioned": false, 10648 "is_snapshot": false, 10649 "is_clone": false, 10650 "is_esnap_clone": false, 10651 "is_degraded": false, 10652 "lvs": { 10653 "name": "lvs_test", 10654 "uuid": "a1c8d950-5715-4558-936d-ab9e6eca0794" 10655 } 10656 } 10657] 10658~~~ 10659 10660### bdev_lvol_set_parent {#rpc_bdev_lvol_set_parent} 10661 10662Set a snapshot as the parent of a lvol, making the lvol a clone of this snapshot. 10663The previous parent of the lvol, if any, can be another snapshot or an external snapshot; if the 10664lvol is not a clone, it must be thin-provisioned. 10665Lvol and parent snapshot must have the same size and must belong to the same lvol store. 10666 10667#### Parameters 10668 10669Name | Optional | Type | Description 10670----------------------- | -------- | ----------- | ----------- 10671lvol_name | Required | string | UUID or alias of the lvol to set parent of 10672snapshot_name | Required | string | UUID or alias of the snapshot to become parent of lvol 10673 10674#### Example 10675 10676Example request: 10677 10678~~~json 10679{ 10680 "jsonrpc": "2.0", 10681 "method": "bdev_lvol_set_parent", 10682 "id": 1, 10683 "params": { 10684 "lvol_name": "LVS1/LVOL0", 10685 "snapshot_name": "LVS1/SNAP0" 10686 } 10687} 10688~~~ 10689 10690Example response: 10691 10692~~~json 10693{ 10694 "jsonrpc": "2.0", 10695 "id": 1, 10696 "result": true 10697} 10698~~~ 10699 10700### bdev_lvol_set_parent_bdev {#rpc_bdev_lvol_set_parent_bdev} 10701 10702Set an external snapshot as the parent of a lvol, making the lvol a clone of this external 10703snapshot (see @ref rpc_bdev_lvol_clone_bdev). 10704The previous parent of the lvol, if any, can be another external snapshot or a snapshot; if the 10705lvol is not a clone, it must be thin-provisioned. 10706The size of the external snapshot device must be an integer multiple of cluster size of lvol's lvolstore. 10707 10708#### Parameters 10709 10710Name | Optional | Type | Description 10711----------------------- | -------- | ----------- | ----------- 10712lvol_name | Required | string | UUID or alias of the lvol to set external parent of 10713esnap_name | Required | string | UUID or name of the external snapshot to become parent of lvol 10714 10715#### Example 10716 10717Example request: 10718 10719~~~json 10720{ 10721 "jsonrpc": "2.0", 10722 "method": "bdev_lvol_set_parent_bdev", 10723 "id": 1, 10724 "params": { 10725 "lvol_name": "LVS1/LVOL0", 10726 "esnap_name": "e465527b-f412-4f70-a03e-c4a5d608f65e" 10727 } 10728} 10729~~~ 10730 10731Example response: 10732 10733~~~json 10734{ 10735 "jsonrpc": "2.0", 10736 "id": 1, 10737 "result": true 10738} 10739~~~ 10740 10741### bdev_lvol_start_shallow_copy {#rpc_bdev_lvol_start_shallow_copy} 10742 10743Start a shallow copy of an lvol over a given bdev. Only clusters allocated to the lvol will be written on the bdev. 10744Must have: 10745 10746* lvol read only 10747* lvol size less or equal than bdev size 10748* lvstore block size an even multiple of bdev block size 10749 10750#### Result 10751 10752This RPC starts the operation and return an identifier that can be used to query the status of the operation 10753with the RPC @ref rpc_bdev_lvol_check_shallow_copy. 10754 10755#### Parameters 10756 10757Name | Optional | Type | Description 10758----------------------- | -------- | ----------- | ----------- 10759src_lvol_name | Required | string | UUID or alias of lvol to create a copy from 10760dst_bdev_name | Required | string | Name of the bdev that acts as destination for the copy 10761 10762#### Example 10763 10764Example request: 10765 10766~~~json 10767{ 10768 "jsonrpc": "2.0", 10769 "method": "bdev_lvol_start_shallow_copy", 10770 "id": 1, 10771 "params": { 10772 "src_lvol_name": "8a47421a-20cf-444f-845c-d97ad0b0bd8e", 10773 "dst_bdev_name": "Nvme1n1" 10774 } 10775} 10776~~~ 10777 10778Example response: 10779 10780~~~json 10781{ 10782 "jsonrpc": "2.0", 10783 "id": 1, 10784 "result": { 10785 "operation_id": 7 10786 } 10787} 10788~~~ 10789 10790### bdev_lvol_check_shallow_copy {#rpc_bdev_lvol_check_shallow_copy} 10791 10792Get shallow copy status. 10793 10794#### Result 10795 10796Get info about the shallow copy operation identified by operation id. 10797It reports operation's status, which can be `in progress`, `complete` or `error`, 10798the actual number of copied clusters, the total number of clusters to copy and, 10799in case of error, a description. 10800Once the operation is ended and the result has been retrieved, the 10801operation is removed from the internal list of ended operation, so its 10802result cannot be accessed anymore. 10803 10804#### Parameters 10805 10806Name | Optional | Type | Description 10807----------------------- | -------- | ----------- | ----------- 10808operation_id | Required | number | operation identifier 10809 10810#### Example 10811 10812Example request: 10813 10814~~~json 10815{ 10816 "jsonrpc": "2.0", 10817 "method": "bdev_lvol_check_shallow_copy", 10818 "id": 1, 10819 "params": { 10820 "operation_id": 7 10821 } 10822} 10823~~~ 10824 10825Example response: 10826 10827~~~json 10828{ 10829 "jsonrpc": "2.0", 10830 "id": 1, 10831 "result": { 10832 "state": "in progress", 10833 "copied_clusters": 2, 10834 "total_clusters": 4 10835 } 10836} 10837~~~ 10838 10839## RAID 10840 10841### bdev_raid_set_options {#rpc_bdev_raid_set_options} 10842 10843Set options for bdev raid. 10844 10845This RPC can be called at any time, but the new value will only take effect for new raid bdevs. 10846 10847The `process_window_size_kb` parameter defines the size of the "window" (LBA range of the raid bdev) 10848in which a background process like rebuild performs its work. Any positive value is valid, but the value 10849actually used by a raid bdev can be adjusted to the size of the raid bdev or the write unit size. 10850 10851#### Parameters 10852 10853Name | Optional | Type | Description 10854-------------------------- | -------- | ----------- | ----------- 10855process_window_size_kb | Optional | number | Background process (e.g. rebuild) window size in KiB 10856 10857#### Example 10858 10859Example request: 10860 10861~~~json 10862request: 10863{ 10864 "jsonrpc": "2.0", 10865 "method": "bdev_raid_set_options", 10866 "id": 1, 10867 "params": { 10868 "process_window_size_kb": 512 10869 } 10870} 10871~~~ 10872 10873Example response: 10874 10875~~~json 10876{ 10877 "jsonrpc": "2.0", 10878 "id": 1, 10879 "result": true 10880} 10881~~~ 10882 10883### bdev_raid_get_bdevs {#rpc_bdev_raid_get_bdevs} 10884 10885This is used to list all the raid bdev details based on the input category requested. Category should be one 10886of 'all', 'online', 'configuring' or 'offline'. 'all' means all the raid bdevs whether they are online or 10887configuring or offline. 'online' is the raid bdev which is registered with bdev layer. 'configuring' is 10888the raid bdev which does not have full configuration discovered yet. 'offline' is the raid bdev which is 10889not registered with bdev as of now and it has encountered any error or user has requested to offline 10890the raid bdev. 10891 10892#### Parameters 10893 10894Name | Optional | Type | Description 10895----------------------- | -------- | ----------- | ----------- 10896category | Required | string | all or online or configuring or offline 10897 10898#### Example 10899 10900Example request: 10901 10902~~~json 10903{ 10904 "jsonrpc": "2.0", 10905 "method": "bdev_raid_get_bdevs", 10906 "id": 1, 10907 "params": { 10908 "category": "all" 10909 } 10910} 10911~~~ 10912 10913Example response: 10914 10915~~~json 10916{ 10917 "jsonrpc": "2.0", 10918 "id": 1, 10919 "result": [ 10920 { 10921 "name": "RaidBdev0", 10922 "uuid": "7d352e83-fe27-40f2-8fef-64563355e076", 10923 "strip_size_kb": 128, 10924 "state": "online", 10925 "raid_level": "raid0", 10926 "num_base_bdevs": 2, 10927 "num_base_bdevs_discovered": 2, 10928 "num_base_bdevs_operational": 2, 10929 "base_bdevs_list": [ 10930 { 10931 "name": "malloc0", 10932 "uuid": "d2788884-5b3e-4fd7-87ff-6c78177e14ab", 10933 "is_configured": true, 10934 "data_offset": 256, 10935 "data_size": 261888 10936 }, 10937 { 10938 "name": "malloc1", 10939 "uuid": "a81bb1f8-5865-488a-8758-10152017e7d1", 10940 "is_configured": true, 10941 "data_offset": 256, 10942 "data_size": 261888 10943 } 10944 ] 10945 }, 10946 { 10947 "name": "RaidBdev1", 10948 "uuid": "f7cb71ed-2d0e-4240-979e-27b0b7735f36", 10949 "strip_size_kb": 128, 10950 "state": "configuring", 10951 "raid_level": "raid0", 10952 "num_base_bdevs": 2, 10953 "num_base_bdevs_discovered": 1, 10954 "num_base_bdevs_operational": 2, 10955 "base_bdevs_list": [ 10956 { 10957 "name": "malloc2", 10958 "uuid": "f60c20e1-3439-4f89-ae55-965a70333f86", 10959 "is_configured": true, 10960 "data_offset": 256, 10961 "data_size": 261888 10962 } 10963 { 10964 "name": "malloc3", 10965 "uuid": "00000000-0000-0000-0000-000000000000", 10966 "is_configured": false, 10967 "data_offset": 0, 10968 "data_size": 0 10969 } 10970 ] 10971 } 10972 ] 10973} 10974~~~ 10975 10976### bdev_raid_create {#rpc_bdev_raid_create} 10977 10978Constructs new RAID bdev. 10979 10980#### Parameters 10981 10982Name | Optional | Type | Description 10983----------------------- | -------- | ----------- | ----------- 10984name | Required | string | RAID bdev name 10985strip_size_kb | Required | number | Strip size in KB 10986raid_level | Required | string | RAID level 10987base_bdevs | Required | string | Base bdevs name, whitespace separated list in quotes 10988uuid | Optional | string | UUID for this RAID bdev 10989superblock | Optional | boolean | If set, information about raid bdev will be stored in superblock on each base bdev (default: `false`) 10990 10991#### Example 10992 10993Example request: 10994 10995~~~json 10996{ 10997 "jsonrpc": "2.0", 10998 "method": "bdev_raid_create", 10999 "id": 1, 11000 "params": { 11001 "name": "Raid0", 11002 "raid_level": "0", 11003 "base_bdevs": [ 11004 "Malloc0", 11005 "Malloc1", 11006 "Malloc2", 11007 "Malloc3" 11008 ], 11009 "strip_size_kb": 4 11010 } 11011} 11012~~~ 11013 11014Example response: 11015 11016~~~json 11017{ 11018 "jsonrpc": "2.0", 11019 "id": 1, 11020 "result": true 11021} 11022~~~ 11023 11024### bdev_raid_delete {#rpc_bdev_raid_delete} 11025 11026Removes RAID bdev. 11027 11028#### Parameters 11029 11030Name | Optional | Type | Description 11031----------------------- | -------- | ----------- | ----------- 11032name | Required | string | RAID bdev name 11033 11034#### Example 11035 11036Example request: 11037 11038~~~json 11039{ 11040 "jsonrpc": "2.0", 11041 "method": "bdev_raid_delete", 11042 "id": 1, 11043 "params": { 11044 "name": "Raid0" 11045 } 11046} 11047~~~ 11048 11049Example response: 11050 11051~~~json 11052{ 11053 "jsonrpc": "2.0", 11054 "id": 1, 11055 "result": true 11056} 11057~~~ 11058 11059### bdev_raid_add_base_bdev {#rpc_bdev_raid_add_base_bdev} 11060 11061Add base bdev to existing raid bdev. The raid bdev must have an empty base bdev slot. 11062The bdev must be large enough and have the same block size and metadata format as the other base bdevs. 11063 11064#### Parameters 11065 11066Name | Optional | Type | Description 11067----------------------- | -------- | ----------- | ----------- 11068raid_bdev | Required | string | Raid bdev name 11069base_bdev | Required | string | Base bdev name 11070 11071#### Example 11072 11073Example request: 11074 11075~~~json 11076{ 11077 "jsonrpc": "2.0", 11078 "method": "bdev_raid_add_base_bdev", 11079 "id": 1, 11080 "params": { 11081 "raid_bdev": "RaidBdev0", 11082 "base_bdev": "Nvme0n1" 11083 } 11084} 11085~~~ 11086 11087Example response: 11088 11089~~~json 11090{ 11091 "jsonrpc": "2.0", 11092 "id": 1, 11093 "result": true 11094} 11095~~~ 11096### bdev_raid_remove_base_bdev {#rpc_bdev_raid_remove_base_bdev} 11097 11098Remove base bdev from existing raid bdev. 11099 11100#### Parameters 11101 11102Name | Optional | Type | Description 11103----------------------- | -------- | ----------- | ----------- 11104name | Required | string | Base bdev name in RAID 11105 11106#### Example 11107 11108Example request: 11109 11110~~~json 11111{ 11112 "jsonrpc": "2.0", 11113 "method": "bdev_raid_remove_base_bdev", 11114 "id": 1, 11115 "params": { 11116 "name": "Raid0" 11117 } 11118} 11119~~~ 11120 11121Example response: 11122 11123~~~json 11124{ 11125 "jsonrpc": "2.0", 11126 "id": 1, 11127 "result": true 11128} 11129~~~ 11130 11131## SPLIT 11132 11133### bdev_split_create {#rpc_bdev_split_create} 11134 11135This is used to split an underlying block device and create several smaller equal-sized vbdevs. 11136 11137#### Parameters 11138 11139Name | Optional | Type | Description 11140----------------------- | -------- | ----------- | ----------- 11141base_bdev | Required | string | base bdev name 11142split_count | Required | number | number of splits 11143split_size_mb | Optional | number | size in MB to restrict the size 11144 11145#### Example 11146 11147Example request: 11148 11149~~~json 11150{ 11151 "jsonrpc": "2.0", 11152 "method": "bdev_split_create", 11153 "id": 1, 11154 "params": { 11155 "base_bdev": "Malloc0", 11156 "split_count": 4 11157 } 11158} 11159~~~ 11160 11161Example response: 11162 11163~~~json 11164{ 11165 "jsonrpc": "2.0", 11166 "id": 1, 11167 "result": [ 11168 "Malloc0p0", 11169 "Malloc0p1", 11170 "Malloc0p2", 11171 "Malloc0p3" 11172 ] 11173} 11174~~~ 11175 11176### bdev_split_delete {#rpc_bdev_split_delete} 11177 11178This is used to remove the split vbdevs. 11179 11180#### Parameters 11181 11182Name | Optional | Type | Description 11183----------------------- | -------- | ----------- | ----------- 11184base_bdev | Required | string | base bdev name 11185 11186#### Example 11187 11188Example request: 11189 11190~~~json 11191{ 11192 "jsonrpc": "2.0", 11193 "method": "bdev_split_delete", 11194 "id": 1, 11195 "params": { 11196 "base_bdev": "Malloc0" 11197 } 11198} 11199~~~ 11200 11201Example response: 11202 11203~~~json 11204{ 11205 "jsonrpc": "2.0", 11206 "id": 1, 11207 "result": true 11208} 11209~~~ 11210 11211## Uring 11212 11213### bdev_uring_create {#rpc_bdev_uring_create} 11214 11215Create a bdev with io_uring backend. 11216 11217#### Parameters 11218 11219Name | Optional | Type | Description 11220----------------------- | -------- | ----------- | ----------- 11221filename | Required | string | path to device or file (ex: /dev/nvme0n1) 11222name | Required | string | name of bdev 11223block_size | Optional | number | block size of device (If omitted, get the block size from the file) 11224uuid | Optional | string | UUID of new bdev 11225 11226#### Example 11227 11228Example request: 11229 11230~~~json 11231{ 11232 "jsonrpc": "2.0", 11233 "method": "bdev_uring_create", 11234 "id": 1, 11235 "params": { 11236 "name": "bdev_u0", 11237 "filename": "/dev/nvme0n1", 11238 "block_size": 512 11239 } 11240} 11241~~~ 11242 11243Example response: 11244 11245~~~json 11246{ 11247 "jsonrpc": "2.0", 11248 "id": 1, 11249 "result": "bdev_u0" 11250} 11251~~~ 11252 11253### bdev_uring_rescan {#rpc_bdev_uring_rescan} 11254 11255Rescan the size of a uring bdev. 11256 11257#### Parameters 11258 11259Name | Optional | Type | Description 11260---- | -------- | ------ | ----------- 11261name | Required | string | name of uring bdev to rescan 11262 11263#### Example 11264 11265Example request: 11266 11267~~~json 11268{ 11269 "jsonrpc": "2.0", 11270 "method": "bdev_uring_rescan", 11271 "id": 1, 11272 "params": { 11273 "name": "bdev_u0" 11274 } 11275} 11276~~~ 11277 11278Example response: 11279 11280~~~json 11281{ 11282 "jsonrpc": "2.0", 11283 "id": 1, 11284 "result": true 11285} 11286~~~ 11287 11288### bdev_uring_delete {#rpc_bdev_uring_delete} 11289 11290Remove a uring bdev. 11291 11292#### Parameters 11293 11294Name | Optional | Type | Description 11295----------------------- | -------- | ----------- | ----------- 11296name | Required | string | name of uring bdev to delete 11297 11298#### Example 11299 11300Example request: 11301 11302~~~json 11303{ 11304 "jsonrpc": "2.0", 11305 "method": "bdev_uring_delete", 11306 "id": 1, 11307 "params": { 11308 "name": "bdev_u0" 11309 } 11310} 11311~~~ 11312 11313Example response: 11314 11315~~~json 11316{ 11317 "jsonrpc": "2.0", 11318 "id": 1, 11319 "result": true 11320} 11321~~~ 11322 11323## OPAL 11324 11325### bdev_nvme_opal_init {#rpc_bdev_nvme_opal_init} 11326 11327This is used to initialize OPAL of a given NVMe ctrlr, including taking ownership and activating. 11328 11329#### Parameters 11330 11331Name | Optional | Type | Description 11332----------------------- | -------- | ----------- | ----------- 11333nvme_ctrlr_name | Required | string | name of nvme ctrlr 11334password | Required | string | admin password of OPAL 11335 11336#### Example 11337 11338Example request: 11339 11340~~~json 11341{ 11342 "jsonrpc": "2.0", 11343 "method": "bdev_nvme_opal_init", 11344 "id": 1, 11345 "params": { 11346 "nvme_ctrlr_name": "nvme0", 11347 "password": "*****" 11348 } 11349} 11350~~~ 11351 11352Example response: 11353 11354~~~json 11355{ 11356 "jsonrpc": "2.0", 11357 "id": 1, 11358 "result": true 11359} 11360~~~ 11361 11362### bdev_nvme_opal_revert {#rpc_bdev_nvme_opal_revert} 11363 11364This is used to revert OPAL to its factory settings. Erase all user configuration and data. 11365 11366#### Parameters 11367 11368Name | Optional | Type | Description 11369----------------------- | -------- | ----------- | ----------- 11370nvme_ctrlr_name | Required | string | name of nvme ctrlr 11371password | Required | string | admin password of OPAL 11372 11373#### Example 11374 11375Example request: 11376 11377~~~json 11378{ 11379 "jsonrpc": "2.0", 11380 "method": "bdev_nvme_opal_revert", 11381 "id": 1, 11382 "params": { 11383 "nvme_ctrlr_name": "nvme0", 11384 "password": "*****" 11385 } 11386} 11387~~~ 11388 11389Example response: 11390 11391~~~json 11392{ 11393 "jsonrpc": "2.0", 11394 "id": 1, 11395 "result": true 11396} 11397~~~ 11398 11399### bdev_opal_create {#rpc_bdev_opal_create} 11400 11401This is used to create an OPAL virtual bdev. 11402 11403#### Parameters 11404 11405Name | Optional | Type | Description 11406----------------------- | -------- | ----------- | ----------- 11407nvme_ctrlr_name | Required | string | name of nvme ctrlr that supports OPAL 11408nsid | Required | number | namespace ID 11409locking_range_id | Required | number | OPAL locking range ID 11410range_start | Required | number | locking range start LBA 11411range_length | Required | number | locking range length 11412password | Required | string | admin password of OPAL 11413 11414#### Response 11415 11416The response is the name of created OPAL virtual bdev. 11417 11418#### Example 11419 11420Example request: 11421 11422~~~json 11423{ 11424 "jsonrpc": "2.0", 11425 "method": "bdev_opal_create", 11426 "id": 1, 11427 "params": { 11428 "nvme_ctrlr_name": "nvme0", 11429 "nsid": 1, 11430 "locking_range_id": 1, 11431 "range_start": 0, 11432 "range_length": 4096, 11433 "password": "*****" 11434 } 11435} 11436~~~ 11437 11438Example response: 11439 11440~~~json 11441{ 11442 "jsonrpc": "2.0", 11443 "id": 1, 11444 "result": "nvme0n1r1" 11445} 11446~~~ 11447 11448### bdev_opal_get_info {#rpc_bdev_opal_get_info} 11449 11450This is used to get information of a given OPAL bdev. 11451 11452#### Parameters 11453 11454Name | Optional | Type | Description 11455----------------------- | -------- | ----------- | ----------- 11456bdev_name | Required | string | name of OPAL vbdev 11457password | Required | string | admin password 11458 11459#### Response 11460 11461The response is the locking info of OPAL virtual bdev. 11462 11463#### Example 11464 11465Example request: 11466 11467~~~json 11468{ 11469 "jsonrpc": "2.0", 11470 "method": "bdev_opal_get_info", 11471 "id": 1, 11472 "params": { 11473 "bdev_name": "nvme0n1r1", 11474 "password": "*****" 11475 } 11476} 11477~~~ 11478 11479Example response: 11480 11481~~~json 11482{ 11483 "jsonrpc": "2.0", 11484 "id": 1, 11485 "result": { 11486 "name": "nvme0n1r1", 11487 "range_start": 0, 11488 "range_length": 4096, 11489 "read_lock_enabled": true, 11490 "write_lock_enabled": true, 11491 "read_locked": false, 11492 "write_locked": false 11493 } 11494} 11495~~~ 11496 11497### bdev_opal_delete {#rpc_bdev_opal_delete} 11498 11499This is used to delete OPAL vbdev. 11500 11501#### Parameters 11502 11503Name | Optional | Type | Description 11504----------------------- | -------- | ----------- | ----------- 11505bdev_name | Required | string | name of OPAL vbdev 11506password | Required | string | admin password 11507 11508#### Example 11509 11510Example request: 11511 11512~~~json 11513{ 11514 "jsonrpc": "2.0", 11515 "method": "bdev_opal_delete", 11516 "id": 1, 11517 "params": { 11518 "bdev_name": "nvme0n1r1", 11519 "password": "*****" 11520 } 11521} 11522~~~ 11523 11524Example response: 11525 11526~~~json 11527{ 11528 "jsonrpc": "2.0", 11529 "id": 1, 11530 "result": true 11531} 11532~~~ 11533 11534### bdev_opal_new_user {#rpc_bdev_opal_new_user} 11535 11536This enables a new user to the specified opal bdev so that the user can lock/unlock the bdev. 11537Recalling this for the same opal bdev, only the newest user will have the privilege. 11538 11539#### Parameters 11540 11541Name | Optional | Type | Description 11542----------------------- | -------- | ----------- | ----------- 11543bdev_name | Required | string | name of OPAL vbdev 11544admin_password | Required | string | admin password 11545user_id | Required | number | user ID 11546user_password | Required | string | user password 11547 11548#### Example 11549 11550Example request: 11551 11552~~~json 11553{ 11554 "jsonrpc": "2.0", 11555 "method": "bdev_opal_new_user", 11556 "id": 1, 11557 "params": { 11558 "bdev_name": "nvme0n1r1", 11559 "admin_password": "*****", 11560 "user_id": "1", 11561 "user_password": "********" 11562 } 11563} 11564~~~ 11565 11566Example response: 11567 11568~~~json 11569{ 11570 "jsonrpc": "2.0", 11571 "id": 1, 11572 "result": true 11573} 11574~~~ 11575 11576### bdev_opal_set_lock_state {#rpc_bdev_opal_set_lock_state} 11577 11578This is used to lock/unlock specific opal bdev providing user ID and password. 11579 11580#### Parameters 11581 11582Name | Optional | Type | Description 11583----------------------- | -------- | ----------- | ----------- 11584bdev_name | Required | string | name of OPAL vbdev 11585user_id | Required | number | user ID 11586password | Required | string | user password 11587lock_state | Required | string | lock state 11588 11589#### Example 11590 11591Example request: 11592 11593~~~json 11594{ 11595 "jsonrpc": "2.0", 11596 "method": "bdev_opal_set_lock_state", 11597 "id": 1, 11598 "params": { 11599 "bdev_name": "nvme0n1r1", 11600 "user_id": "1", 11601 "user_password": "********", 11602 "lock_state": "rwlock" 11603 } 11604} 11605~~~ 11606 11607Example response: 11608 11609~~~json 11610{ 11611 "jsonrpc": "2.0", 11612 "id": 1, 11613 "result": true 11614} 11615~~~ 11616 11617## Notifications 11618 11619### notify_get_types {#rpc_notify_get_types} 11620 11621Return list of all supported notification types. 11622 11623#### Parameters 11624 11625None 11626 11627#### Response 11628 11629The response is an array of strings - supported RPC notification types. 11630 11631#### Example 11632 11633Example request: 11634 11635~~~json 11636{ 11637 "jsonrpc": "2.0", 11638 "method": "notify_get_types", 11639 "id": 1 11640} 11641~~~ 11642 11643Example response: 11644 11645~~~json 11646{ 11647 "id": 1, 11648 "result": [ 11649 "bdev_register", 11650 "bdev_unregister" 11651 ], 11652 "jsonrpc": "2.0" 11653} 11654~~~ 11655 11656### notify_get_notifications {#notify_get_notifications} 11657 11658Request notifications. Returns array of notifications that happened since the specified id (or first that is available). 11659 11660Notice: Notifications are kept in circular buffer with limited size. Older notifications might be inaccessible 11661due to being overwritten by new ones. 11662 11663#### Parameters 11664 11665Name | Optional | Type | Description 11666----------------------- | -------- | ----------- | ----------- 11667id | Optional | number | First Event ID to fetch (default: first available). 11668max | Optional | number | Maximum number of event to return (default: no limit). 11669 11670#### Response 11671 11672Response is an array of event objects. 11673 11674Name | Optional | Type | Description 11675----------------------- | -------- | ----------- | ----------- 11676id | Optional | number | Event ID. 11677type | Optional | number | Type of the event. 11678ctx | Optional | string | Event context. 11679 11680#### Example 11681 11682Example request: 11683 11684~~~json 11685{ 11686 "id": 1, 11687 "jsonrpc": "2.0", 11688 "method": "notify_get_notifications", 11689 "params": { 11690 "id": 1, 11691 "max": 10 11692 } 11693} 11694 11695~~~ 11696 11697Example response: 11698 11699~~~json 11700{ 11701 "jsonrpc": "2.0", 11702 "id": 1, 11703 "result": [ 11704 { 11705 "ctx": "Malloc0", 11706 "type": "bdev_register", 11707 "id": 1 11708 }, 11709 { 11710 "ctx": "Malloc2", 11711 "type": "bdev_register", 11712 "id": 2 11713 } 11714 ] 11715} 11716~~~ 11717 11718## Linux Userspace Block Device (UBLK) {#jsonrpc_components_ublk} 11719 11720SPDK supports exporting bdevs though Linux ublk. The motivation behind it is to back a Linux kernel block device 11721with an SPDK user space bdev. 11722 11723To export a device over ublk, first make sure the Linux kernel ublk driver is loaded by running 'modprobe ublk_drv'. 11724 11725### ublk_create_target {#rpc_ublk_create_target} 11726 11727Start to create ublk threads and initialize ublk target. It will return an error if user calls this RPC twice without 11728ublk_destroy_target in between. It will use current cpumask in SPDK when user does not specify cpumask option. 11729 11730#### Parameters 11731 11732Name | Optional | Type | Description 11733----------------------- | -------- | ----------- | ----------- 11734cpumask | Optional | string | Cpumask for ublk target 11735disable-user-copy | Optional | boolean | Disable user copy feature 11736 11737#### Response 11738 11739True if ublk target initialization is successful; False if failed. 11740 11741#### Example 11742 11743Example request: 11744 11745~~~json 11746{ 11747 "params": { 11748 "cpumask": "0x2" 11749 }, 11750 "jsonrpc": "2.0", 11751 "method": "ublk_create_target", 11752 "id": 1 11753} 11754~~~ 11755 11756Example response: 11757 11758~~~json 11759{ 11760 "jsonrpc": "2.0", 11761 "id": 1, 11762 "result": true 11763} 11764~~~ 11765 11766### ublk_destroy_target {#rpc_ublk_destroy_target} 11767 11768Release all UBLK devices and destroy ublk target. 11769 11770#### Response 11771 11772True if ublk target destruction is successful; False if failed. 11773 11774#### Example 11775 11776Example request: 11777 11778~~~json 11779{ 11780 "jsonrpc": "2.0", 11781 "method": "ublk_destroy_target", 11782 "id": 1 11783} 11784~~~ 11785 11786Example response: 11787 11788~~~json 11789{ 11790 "jsonrpc": "2.0", 11791 "id": 1, 11792 "result": true 11793} 11794~~~ 11795 11796### ublk_start_disk {#rpc_ublk_start_disk} 11797 11798Start to export one SPDK bdev as a UBLK device 11799 11800#### Parameters 11801 11802Name | Optional | Type | Description 11803----------------------- | -------- | ----------- | ----------- 11804bdev_name | Required | string | Bdev name to export 11805ublk_id | Required | int | Device id 11806queue_depth | Optional | int | Device queue depth 11807num_queues | Optional | int | Total number of device queues 11808 11809#### Response 11810 11811UBLK device ID 11812 11813#### Example 11814 11815Example request: 11816 11817~~~json 11818{ 11819 "params": { 11820 "ublk_id": "1", 11821 "bdev_name": "Malloc1" 11822 }, 11823 "jsonrpc": "2.0", 11824 "method": "ublk_start_disk", 11825 "id": 1 11826} 11827~~~ 11828 11829Example response: 11830 11831~~~json 11832{ 11833 "jsonrpc": "2.0", 11834 "id": 1, 11835 "result": 1 11836} 11837~~~ 11838 11839### ublk_recover_disk {#rpc_ublk_recover_disk} 11840 11841Recover original UBLK device with ID and block device 11842 11843#### Parameters 11844 11845Name | Optional | Type | Description 11846----------------------- | -------- | ----------- | ----------- 11847bdev_name | Required | string | Bdev name to export 11848ublk_id | Required | int | Device id 11849 11850#### Response 11851 11852UBLK device ID 11853 11854#### Example 11855 11856Example request: 11857 11858~~~json 11859{ 11860 "params": { 11861 "ublk_id": "1", 11862 "bdev_name": "Malloc1" 11863 }, 11864 "jsonrpc": "2.0", 11865 "method": "ublk_recover_disk", 11866 "id": 1 11867} 11868~~~ 11869 11870Example response: 11871 11872~~~json 11873{ 11874 "jsonrpc": "2.0", 11875 "id": 1, 11876 "result": 1 11877} 11878 11879### ublk_stop_disk {#rpc_ublk_stop_disk} 11880 11881Delete a UBLK device 11882 11883#### Parameters 11884 11885Name | Optional | Type | Description 11886----------------------- | -------- | ----------- | ----------- 11887ublk_id | Required | int | Device id to delete 11888 11889#### Response 11890 11891True if UBLK device is deleted successfully; False if failed. 11892 11893#### Example 11894 11895Example request: 11896 11897~~~json 11898{ 11899 "params": { 11900 "ublk_id": "1", 11901 }, 11902 "jsonrpc": "2.0", 11903 "method": "ublk_stop_disk", 11904 "id": 1 11905} 11906~~~ 11907 11908Example response: 11909 11910~~~json 11911{ 11912 "jsonrpc": "2.0", 11913 "id": 1, 11914 "result": true 11915} 11916~~~ 11917 11918### ublk_get_disks {#rpc_ublk_get_disks} 11919 11920Display full or specified ublk device list 11921 11922#### Parameters 11923 11924Name | Optional | Type | Description 11925----------------------- | -------- | ----------- | ----------- 11926ublk_id | Optional | int | ublk device id to display 11927 11928#### Response 11929 11930Display ublk device list 11931 11932#### Example 11933 11934Example request: 11935 11936~~~json 11937{ 11938 "jsonrpc": "2.0", 11939 "method": "ublk_get_disks", 11940 "id": 1 11941} 11942~~~ 11943 11944Example response: 11945 11946~~~json 11947{ 11948 "jsonrpc": "2.0", 11949 "id": 1, 11950 "result": [ 11951 { 11952 "ublk_device": "/dev/ublkb1", 11953 "id": 1, 11954 "queue_depth": 512, 11955 "num_queues": 1, 11956 "bdev_name": "Malloc1" 11957 } 11958 ] 11959} 11960~~~ 11961 11962## Linux Network Block Device (NBD) {#jsonrpc_components_nbd} 11963 11964SPDK supports exporting bdevs through Linux nbd. These devices then appear as standard Linux kernel block devices 11965and can be accessed using standard utilities like fdisk. 11966 11967In order to export a device over nbd, first make sure the Linux kernel nbd driver is loaded by running 'modprobe nbd'. 11968 11969### nbd_start_disk {#rpc_nbd_start_disk} 11970 11971Start to export one SPDK bdev as NBD disk 11972 11973#### Parameters 11974 11975Name | Optional | Type | Description 11976----------------------- | -------- | ----------- | ----------- 11977bdev_name | Required | string | Bdev name to export 11978nbd_device | Optional | string | NBD device name to assign 11979 11980#### Response 11981 11982Path of exported NBD disk 11983 11984#### Example 11985 11986Example request: 11987 11988~~~json 11989{ 11990 "params": { 11991 "nbd_device": "/dev/nbd1", 11992 "bdev_name": "Malloc1" 11993 }, 11994 "jsonrpc": "2.0", 11995 "method": "nbd_start_disk", 11996 "id": 1 11997} 11998~~~ 11999 12000Example response: 12001 12002~~~json 12003{ 12004 "jsonrpc": "2.0", 12005 "id": 1, 12006 "result": "/dev/nbd1" 12007} 12008~~~ 12009 12010### nbd_stop_disk {#rpc_nbd_stop_disk} 12011 12012Stop one NBD disk which is based on SPDK bdev. 12013 12014#### Parameters 12015 12016Name | Optional | Type | Description 12017----------------------- | -------- | ----------- | ----------- 12018nbd_device | Required | string | NBD device name to stop 12019 12020#### Example 12021 12022Example request: 12023 12024~~~json 12025{ 12026 "params": { 12027 "nbd_device": "/dev/nbd1", 12028 }, 12029 "jsonrpc": "2.0", 12030 "method": "nbd_stop_disk", 12031 "id": 1 12032} 12033~~~ 12034 12035Example response: 12036 12037~~~json 12038{ 12039 "jsonrpc": "2.0", 12040 "id": 1, 12041 "result": "true" 12042} 12043~~~ 12044 12045### nbd_get_disks {#rpc_nbd_get_disks} 12046 12047Display all or specified NBD device list 12048 12049#### Parameters 12050 12051Name | Optional | Type | Description 12052----------------------- | -------- | ----------- | ----------- 12053nbd_device | Optional | string | NBD device name to display 12054 12055#### Response 12056 12057The response is an array of exported NBD devices and their corresponding SPDK bdev. 12058 12059#### Example 12060 12061Example request: 12062 12063~~~json 12064{ 12065 "jsonrpc": "2.0", 12066 "method": "nbd_get_disks", 12067 "id": 1 12068} 12069~~~ 12070 12071Example response: 12072 12073~~~json 12074{ 12075 "jsonrpc": "2.0", 12076 "id": 1, 12077 "result": [ 12078 { 12079 "bdev_name": "Malloc0", 12080 "nbd_device": "/dev/nbd0" 12081 }, 12082 { 12083 "bdev_name": "Malloc1", 12084 "nbd_device": "/dev/nbd1" 12085 } 12086 ] 12087} 12088~~~ 12089 12090## Blobfs {#jsonrpc_components_blobfs} 12091 12092### blobfs_detect {#rpc_blobfs_detect} 12093 12094Detect whether a blobfs exists on bdev. 12095 12096#### Parameters 12097 12098Name | Optional | Type | Description 12099----------------------- | -------- | ----------- | ----------- 12100bdev_name | Required | string | Block device name to detect blobfs 12101 12102#### Response 12103 12104True if a blobfs exists on the bdev; False otherwise. 12105 12106#### Example 12107 12108Example request: 12109 12110~~~json 12111{ 12112 "jsonrpc": "2.0", 12113 "id": 1, 12114 "method": "blobfs_detect", 12115 "params": { 12116 "bdev_name": "Malloc0" 12117 } 12118} 12119~~~ 12120 12121Example response: 12122 12123~~~json 12124{ 12125 "jsonrpc": "2.0", 12126 "id": 1, 12127 "result": "true" 12128} 12129~~~ 12130 12131### blobfs_create {#rpc_blobfs_create} 12132 12133Build blobfs on bdev. 12134 12135#### Parameters 12136 12137Name | Optional | Type | Description 12138----------------------- | -------- | ----------- | ----------- 12139bdev_name | Required | string | Block device name to create blobfs 12140cluster_sz | Optional | number | Size of cluster in bytes. Must be multiple of 4KiB page size, default and minimal value is 1M. 12141 12142#### Example 12143 12144Example request: 12145 12146~~~json 12147{ 12148 "jsonrpc": "2.0", 12149 "id": 1, 12150 "method": "blobfs_create", 12151 "params": { 12152 "bdev_name": "Malloc0", 12153 "cluster_sz": 1M 12154 } 12155} 12156~~~ 12157 12158Example response: 12159 12160~~~json 12161{ 12162 "jsonrpc": "2.0", 12163 "id": 1, 12164 "result": "true" 12165} 12166~~~ 12167 12168### blobfs_mount {#rpc_blobfs_mount} 12169 12170Mount a blobfs on bdev to one host path through FUSE 12171 12172#### Parameters 12173 12174Name | Optional | Type | Description 12175----------------------- | -------- | ----------- | ----------- 12176bdev_name | Required | string | Block device name where the blobfs is 12177mountpoint | Required | string | Mountpoint path in host to mount blobfs 12178 12179#### Example 12180 12181Example request: 12182 12183~~~json 12184{ 12185 "jsonrpc": "2.0", 12186 "id": 1, 12187 "method": ""blobfs_mount"", 12188 "params": { 12189 "bdev_name": "Malloc0", 12190 "mountpoint": "/mnt/" 12191 } 12192} 12193~~~ 12194 12195Example response: 12196 12197~~~json 12198{ 12199 "jsonrpc": "2.0", 12200 "id": 1, 12201 "result": "true" 12202} 12203~~~ 12204 12205### blobfs_set_cache_size {#rpc_blobfs_set_cache_size} 12206 12207Set cache pool size for blobfs filesystems. This RPC is only permitted when the cache pool is not already initialized. 12208 12209The cache pool is initialized when the first blobfs filesystem is initialized or loaded. It is freed when the all 12210initialized or loaded filesystems are unloaded. 12211 12212#### Parameters 12213 12214Name | Optional | Type | Description 12215----------------------- | -------- | ----------- | ----------- 12216size_in_mb | Required | number | Cache size in megabytes 12217 12218#### Response 12219 12220True if cache size is set successfully; False if failed to set. 12221 12222#### Example 12223 12224Example request: 12225 12226~~~json 12227{ 12228 "jsonrpc": "2.0", 12229 "id": 1, 12230 "method": "blobfs_set_cache_size", 12231 "params": { 12232 "size_in_mb": 512, 12233 } 12234} 12235~~~ 12236 12237Example response: 12238 12239~~~json 12240{ 12241 "jsonrpc": "2.0", 12242 "id": 1, 12243 "result": true 12244} 12245~~~ 12246 12247## Socket layer {#jsonrpc_components_sock} 12248 12249### sock_impl_get_options {#rpc_sock_impl_get_options} 12250 12251Get parameters for the socket layer implementation. 12252 12253#### Parameters 12254 12255Name | Optional | Type | Description 12256----------------------- | -------- | ----------- | ----------- 12257impl_name | Required | string | Name of socket implementation, e.g. posix 12258 12259#### Response 12260 12261Response is an object with current socket layer options for requested implementation. 12262 12263#### Example 12264 12265Example request: 12266 12267~~~json 12268{ 12269 "jsonrpc": "2.0", 12270 "method": "sock_impl_get_options", 12271 "id": 1, 12272 "params": { 12273 "impl_name": "posix" 12274 } 12275} 12276~~~ 12277 12278Example response: 12279 12280~~~json 12281{ 12282 "jsonrpc": "2.0", 12283 "id": 1, 12284 "result": { 12285 "recv_buf_size": 2097152, 12286 "send_buf_size": 2097152, 12287 "enable_recv_pipe": true, 12288 "enable_quickack": true, 12289 "enable_placement_id": 0, 12290 "enable_zerocopy_send_server": true, 12291 "enable_zerocopy_send_client": false, 12292 "zerocopy_threshold": 0, 12293 "tls_version": 13, 12294 "enable_ktls": false 12295 } 12296} 12297~~~ 12298 12299### sock_impl_set_options {#rpc_sock_impl_set_options} 12300 12301Set parameters for the socket layer implementation. 12302 12303#### Parameters 12304 12305Name | Optional | Type | Description 12306--------------------------- | -------- | ----------- | ----------- 12307impl_name | Required | string | Name of socket implementation, e.g. posix 12308recv_buf_size | Optional | number | Size of socket receive buffer in bytes 12309send_buf_size | Optional | number | Size of socket send buffer in bytes 12310enable_recv_pipe | Optional | boolean | Enable or disable receive pipe 12311enable_quick_ack | Optional | boolean | Enable or disable quick ACK 12312enable_placement_id | Optional | number | Enable or disable placement_id. 0:disable,1:incoming_napi,2:incoming_cpu 12313enable_zerocopy_send_server | Optional | boolean | Enable or disable zero copy on send for server sockets 12314enable_zerocopy_send_client | Optional | boolean | Enable or disable zero copy on send for client sockets 12315zerocopy_threshold | Optional | number | Set zerocopy_threshold in bytes. A consecutive sequence of requests' iovecs 12316-- | -- | -- | that fall below this threshold may be sent without zerocopy flag set 12317tls_version | Optional | number | TLS protocol version, e.g. 13 for v1.3 (only applies when impl_name == ssl) 12318enable_ktls | Optional | boolean | Enable or disable Kernel TLS (only applies when impl_name == ssl) 12319 12320#### Response 12321 12322True if socket layer options were set successfully. 12323 12324#### Example 12325 12326Example request: 12327 12328~~~json 12329{ 12330 "jsonrpc": "2.0", 12331 "method": "sock_impl_set_options", 12332 "id": 1, 12333 "params": { 12334 "impl_name": "posix", 12335 "recv_buf_size": 2097152, 12336 "send_buf_size": 2097152, 12337 "enable_recv_pipe": false, 12338 "enable_quick_ack": false, 12339 "enable_placement_id": 0, 12340 "enable_zerocopy_send_server": true, 12341 "enable_zerocopy_send_client": false, 12342 "zerocopy_threshold": 10240, 12343 "tls_version": 13, 12344 "enable_ktls": false 12345 } 12346} 12347~~~ 12348 12349Example response: 12350 12351~~~json 12352{ 12353 "jsonrpc": "2.0", 12354 "id": 1, 12355 "result": true 12356} 12357~~~ 12358 12359### sock_set_default_impl {#rpc_sock_set_default_impl} 12360 12361Set the default sock implementation. 12362 12363#### Parameters 12364 12365Name | Optional | Type | Description 12366----------------------- | -------- | ----------- | ----------- 12367impl_name | Required | string | Name of socket implementation, e.g. posix 12368 12369#### Response 12370 12371True if the default socket layer configuration was set successfully. 12372 12373#### Example 12374 12375Example request: 12376 12377~~~json 12378{ 12379 "jsonrpc": "2.0", 12380 "method": "sock_set_default_impl", 12381 "id": 1, 12382 "params": { 12383 "impl_name": "posix" 12384 } 12385} 12386~~~ 12387 12388Example response: 12389 12390~~~json 12391{ 12392 "jsonrpc": "2.0", 12393 "id": 1, 12394 "result": true 12395} 12396~~~ 12397 12398### sock_get_default_impl {#rpc_sock_get_default_impl} 12399 12400Get the name of the default sock implementation. 12401 12402#### Parameters 12403 12404This function has no parameters. 12405 12406#### Response 12407 12408The name of the current default socket implementation. 12409 12410#### Example 12411 12412Example request: 12413 12414~~~json 12415{ 12416 "jsonrpc": "2.0", 12417 "method": "sock_get_default_impl", 12418 "id": 1 12419} 12420~~~ 12421 12422Example response: 12423 12424~~~json 12425{ 12426 "jsonrpc": "2.0", 12427 "id": 1, 12428 "result": { 12429 "impl_name": "posix" 12430 } 12431} 12432~~~ 12433 12434## Miscellaneous RPC commands 12435 12436### bdev_nvme_send_cmd {#rpc_bdev_nvme_send_cmd} 12437 12438Send NVMe command directly to NVMe controller or namespace. Parameters and responses encoded by base64 urlsafe need further processing. 12439 12440Notice: bdev_nvme_send_cmd requires user to guarantee the correctness of NVMe command itself, and also optional parameters. 12441Illegal command contents or mismatching buffer size may result in unpredictable behavior. 12442 12443#### Parameters 12444 12445Name | Optional | Type | Description 12446----------------------- | -------- | ----------- | ----------- 12447name | Required | string | Name of the operating NVMe controller 12448cmd_type | Required | string | Type of nvme cmd. Valid values are: admin, io 12449data_direction | Required | string | Direction of data transfer. Valid values are: c2h, h2c 12450cmdbuf | Required | string | NVMe command encoded by base64 urlsafe 12451data | Optional | string | Data transferring to controller from host, encoded by base64 urlsafe 12452metadata | Optional | string | Metadata transferring to controller from host, encoded by base64 urlsafe 12453data_len | Optional | number | Data length required to transfer from controller to host 12454metadata_len | Optional | number | Metadata length required to transfer from controller to host 12455timeout_ms | Optional | number | Command execution timeout value, in milliseconds 12456 12457#### Response 12458 12459Name | Type | Description 12460----------------------- | ----------- | ----------- 12461cpl | string | NVMe completion queue entry, encoded by base64 urlsafe 12462data | string | Data transferred from controller to host, encoded by base64 urlsafe 12463metadata | string | Metadata transferred from controller to host, encoded by base64 urlsafe 12464 12465#### Example 12466 12467Example request: 12468 12469~~~json 12470{ 12471 "jsonrpc": "2.0", 12472 "method": "bdev_nvme_send_cmd", 12473 "id": 1, 12474 "params": { 12475 "name": "Nvme0", 12476 "cmd_type": "admin" 12477 "data_direction": "c2h", 12478 "cmdbuf": "BgAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAsGUs9P5_AAAAAAAAABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==", 12479 "data_len": 60, 12480 } 12481} 12482~~~ 12483 12484Example response: 12485 12486~~~json 12487{ 12488 "jsonrpc": "2.0", 12489 "id": 1, 12490 "result": { 12491 "cpl": "AAAAAAAAAAARAAAAWrmwABAA==", 12492 "data": "sIjg6AAAAACwiODoAAAAALCI4OgAAAAAAAYAAREAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" 12493 } 12494 12495} 12496~~~ 12497 12498### vmd_enable {#rpc_enable_vmd} 12499 12500Enable VMD enumeration. 12501 12502#### Parameters 12503 12504This method has no parameters. 12505 12506#### Response 12507 12508Completion status of enumeration is returned as a boolean. 12509 12510### Example 12511 12512Example request: 12513 12514~~~json 12515{ 12516 "jsonrpc": "2.0", 12517 "method": "vmd_enable", 12518 "id": 1 12519} 12520~~~ 12521 12522Example response: 12523 12524~~~json 12525{ 12526 "jsonrpc": "2.0", 12527 "id": 1, 12528 "result": true 12529} 12530~~~ 12531 12532### vmd_remove_device {#rpc_vmd_remove_device} 12533 12534Remove a device behind a VMD. 12535 12536### Parameters 12537 12538Name | Optional | Type | Description 12539----------------------- | -------- | ----------- | ----------- 12540addr | Required | string | Address of the device to remove. 12541 12542### Example 12543 12544~~~json 12545{ 12546 "jsonrpc": "2.0", 12547 "method": "vmd_remove_device", 12548 "params": { 12549 "addr": "5d0505:01:00.0" 12550 } 12551 "id": 1 12552} 12553~~~ 12554 12555Example response: 12556 12557~~~json 12558{ 12559 "jsonrpc": "2.0", 12560 "id": 1, 12561 "result": true 12562} 12563~~~ 12564 12565### vmd_rescan {#rpc_vmd_rescan} 12566 12567Force a rescan of the devices behind VMD. 12568 12569### Parameters 12570 12571This method has no parameters. 12572 12573#### Response 12574 12575The response is the number of new devices found. 12576 12577### Example 12578 12579~~~json 12580{ 12581 "jsonrpc": "2.0", 12582 "method": "vmd_rescan", 12583 "id": 1 12584} 12585~~~ 12586 12587Example response: 12588 12589~~~json 12590{ 12591 "jsonrpc": "2.0", 12592 "id": 1, 12593 "result": { 12594 "count": 1 12595 } 12596} 12597~~~ 12598 12599### spdk_get_version {#rpc_spdk_get_version} 12600 12601Get the version info of the running SPDK application. 12602 12603#### Parameters 12604 12605This method has no parameters. 12606 12607#### Response 12608 12609The response is the version number including major version number, minor version number, patch level number and suffix string. 12610 12611#### Example 12612 12613Example request: 12614 12615~~~json 12616{ 12617 "jsonrpc": "2.0", 12618 "id": 1, 12619 "method": "spdk_get_version" 12620} 12621~~~ 12622 12623Example response: 12624 12625~~~json 12626{ 12627 "jsonrpc": "2.0", 12628 "id": 1, 12629 "result": { 12630 "version": "19.04-pre", 12631 "fields" : { 12632 "major": 19, 12633 "minor": 4, 12634 "patch": 0, 12635 "suffix": "-pre" 12636 } 12637 } 12638} 12639~~~ 12640 12641### framework_get_pci_devices 12642 12643List PCIe devices attached to an SPDK application and the contents of their config space. 12644 12645#### Parameters 12646 12647This method has no parameters. 12648 12649#### Response 12650 12651The response is an array of attached PCIe devices. 12652 12653#### Example 12654 12655Example request: 12656 12657~~~json 12658{ 12659 "jsonrpc": "2.0", 12660 "id": 1, 12661 "method": "framework_get_pci_devices" 12662} 12663~~~ 12664 12665Example response: 12666Note that the config space buffer was trimmed. 12667 12668~~~json 12669{ 12670 "jsonrpc": "2.0", 12671 "id": 1, 12672 "result": { 12673 [ 12674 { 12675 "address": "0000:00:04.0", 12676 "config_space": "8680455807051000...0000000000000000" 12677 }, 12678 { 12679 "address": "0000:00:03.0", 12680 "config_space": "8680455807051000...0000000000000000" 12681 } 12682 ] 12683 } 12684} 12685~~~ 12686 12687### bdev_nvme_add_error_injection {#rpc_bdev_nvme_add_error_injection} 12688 12689Add a NVMe command error injection for a bdev nvme controller. 12690 12691#### Parameters 12692 12693Name | Optional | Type | Description 12694----------------------- | -------- | ----------- | ----------- 12695name | Required | string | Name of the operating NVMe controller 12696cmd_type | Required | string | Type of NVMe command. Valid values are: admin, io 12697opc | Required | number | Opcode for which the error injection is applied 12698do_not_submit | Optional | boolean | Set to true if request should not be submitted to the controller (default false) 12699timeout_in_us | Optional | number | Wait specified microseconds when do_not_submit is true 12700err_count | Optional | number | Number of matching NVMe commands to inject errors 12701sct | Optional | number | Status code type (default 0) 12702sc | Optional | number | Status code (default 0) 12703 12704#### Response 12705 12706true on success 12707 12708#### Example 12709 12710Example request: 12711 12712~~~json 12713{ 12714 "jsonrpc": "2.0", 12715 "method": "bdev_nvme_add_error_injection", 12716 "id": 1, 12717 "params": { 12718 "name": "HotInNvme0", 12719 "opc": 2, 12720 "cmd_type": "io", 12721 "err_count": 1111111, 12722 "sct": 11, 12723 "sc": 33 12724 } 12725} 12726 12727~~~ 12728 12729Example response: 12730 12731~~~json 12732{ 12733 "jsonrpc": "2.0", 12734 "id": 1, 12735 "result": true 12736} 12737 12738~~~ 12739 12740### bdev_nvme_remove_error_injection {#rpc_bdev_nvme_remove_error_injection} 12741 12742Remove a NVMe command error injection. 12743 12744#### Parameters 12745 12746Name | Optional | Type | Description 12747----------------------- | -------- | ----------- | ----------- 12748name | Required | string | Name of the operating NVMe controller 12749cmd_type | Required | string | Type of NVMe command. Valid values are: admin, io 12750opc | Required | number | Opcode for which the error injection is applied 12751 12752#### Response 12753 12754true on success 12755 12756#### Example 12757 12758Example request: 12759 12760~~~json 12761{ 12762 "jsonrpc": "2.0", 12763 "method": "bdev_nvme_remove_error_injection", 12764 "id": 1, 12765 "params": { 12766 "name": "HotInNvme0", 12767 "opc": 2, 12768 "cmd_type": "io" 12769 } 12770} 12771 12772 12773~~~ 12774 12775Example response: 12776 12777~~~json 12778{ 12779 "jsonrpc": "2.0", 12780 "id": 1, 12781 "result": true 12782} 12783 12784~~~ 12785 12786### bdev_daos_create {#rpc_bdev_daos_create} 12787 12788Construct @ref bdev_config_daos 12789 12790#### Parameters 12791 12792Name | Optional | Type | Description 12793----------------------- | -------- | ----------- | ----------- 12794name | Required | string | Bdev name to use 12795pool | Required | string | DAOS pool label or its uuid 12796cont | Required | string | DAOS cont label or its uuid 12797block_size | Required | number | Block size in bytes -must be multiple of 512 12798num_blocks | Required | number | Number of blocks 12799uuid | Optional | string | UUID of new bdev 12800oclass | Optional | string | DAOS object class (default SX) 12801 12802To find more about various object classes please visit [DAOS documentation](https://github.com/daos-stack/daos/blob/master/src/object/README.md). 12803Please note, that DAOS bdev module uses the same CLI flag notation as `dmg` and `daos` commands, 12804for instance, `SX` or `EC_4P2G2` rather than in DAOS header file `OC_SX` or `OC_EC_4P2G2`. 12805 12806#### Result 12807 12808Name of newly created bdev. 12809 12810#### Example 12811 12812Example request: 12813 12814~~~json 12815{ 12816 "params": { 12817 "block_size": 4096, 12818 "num_blocks": 16384, 12819 "name": "daosdev0", 12820 "pool": "test-pool", 12821 "cont": "test-cont", 12822 "oclass": "EC_4P2G2" 12823 }, 12824 "jsonrpc": "2.0", 12825 "method": "bdev_daos_create", 12826 "id": 1 12827} 12828~~~ 12829 12830Example response: 12831 12832~~~json 12833{ 12834 "jsonrpc": "2.0", 12835 "id": 1, 12836 "result": "daosdev0" 12837} 12838~~~ 12839 12840### bdev_daos_delete {#rpc_bdev_daos_delete} 12841 12842Delete @ref bdev_config_daos 12843 12844#### Parameters 12845 12846Name | Optional | Type | Description 12847----------------------- | -------- | ----------- | ----------- 12848name | Required | string | Bdev name 12849 12850#### Example 12851 12852Example request: 12853 12854~~~json 12855{ 12856 "params": { 12857 "name": "daosdev0" 12858 }, 12859 "jsonrpc": "2.0", 12860 "method": "bdev_daos_delete", 12861 "id": 1 12862} 12863~~~ 12864 12865Example response: 12866 12867~~~json 12868{ 12869 "jsonrpc": "2.0", 12870 "id": 1, 12871 "result": true 12872} 12873~~~ 12874 12875### bdev_daos_resize {#rpc_bdev_daos_resize} 12876 12877Resize @ref bdev_config_daos. 12878 12879#### Parameters 12880 12881Name | Optional | Type | Description 12882----------------------- | -------- | ----------- | ----------- 12883name | Required | string | Bdev name 12884new_size | Required | number | Bdev new capacity in MiB 12885 12886#### Example 12887 12888Example request: 12889 12890~~~json 12891{ 12892 "params": { 12893 "name": "daosdev0", 12894 "new_size": 8192 12895 }, 12896 "jsonrpc": "2.0", 12897 "method": "bdev_daos_resize", 12898 "id": 1 12899} 12900~~~ 12901 12902Example response: 12903 12904~~~json 12905{ 12906 "jsonrpc": "2.0", 12907 "id": 1, 12908 "result": true 12909} 12910~~~ 12911 12912### iobuf_set_options {#rpc_iobuf_set_options} 12913 12914Set iobuf buffer pool options. 12915 12916#### Parameters 12917 12918Name | Optional | Type | Description 12919----------------------- | -------- | ----------- | ----------- 12920small_pool_count | Optional | number | Number of small buffers in the global pool 12921large_pool_count | Optional | number | Number of large buffers in the global pool 12922small_bufsize | Optional | number | Size of a small buffer 12923large_bufsize | Optional | number | Size of a small buffer 12924 12925#### Example 12926 12927Example request: 12928 12929~~~json 12930{ 12931 "jsonrpc": "2.0", 12932 "id": 1, 12933 "method": "iobuf_set_options", 12934 "params": { 12935 "small_pool_count": 16383, 12936 "large_pool_count": 2047 12937 } 12938} 12939~~~ 12940 12941Example response: 12942 12943~~~json 12944{ 12945 "jsonrpc": "2.0", 12946 "id": 1, 12947 "result": true 12948} 12949~~~ 12950 12951### iobuf_get_stats {#rpc_iobuf_get_stats} 12952 12953Retrieve iobuf's statistics. 12954 12955#### Parameters 12956 12957None. 12958 12959#### Example 12960 12961Example request: 12962 12963~~~json 12964{ 12965 "jsonrpc": "2.0", 12966 "method": "iobuf_get_stats", 12967 "id": 1 12968} 12969~~~ 12970 12971Example response: 12972 12973~~~json 12974{ 12975 "jsonrpc": "2.0", 12976 "id": 1, 12977 "result": [ 12978 { 12979 "module": "accel", 12980 "small_pool": { 12981 "cache": 0, 12982 "main": 0, 12983 "retry": 0 12984 }, 12985 "large_pool": { 12986 "cache": 0, 12987 "main": 0, 12988 "retry": 0 12989 } 12990 }, 12991 { 12992 "module": "bdev", 12993 "small_pool": { 12994 "cache": 421965, 12995 "main": 1218, 12996 "retry": 0 12997 }, 12998 "large_pool": { 12999 "cache": 0, 13000 "main": 0, 13001 "retry": 0 13002 } 13003 }, 13004 { 13005 "module": "nvmf_TCP", 13006 "small_pool": { 13007 "cache": 7, 13008 "main": 0, 13009 "retry": 0 13010 }, 13011 "large_pool": { 13012 "cache": 0, 13013 "main": 0, 13014 "retry": 0 13015 } 13016 } 13017 ] 13018} 13019~~~ 13020 13021### bdev_nvme_start_mdns_discovery {#rpc_bdev_nvme_start_mdns_discovery} 13022 13023Starts an mDNS based discovery service for the specified service type for the 13024auto-discovery of discovery controllers (NVMe TP-8009). 13025 13026The discovery service will listen for the mDNS discovery events from the 13027Avahi-daemon and will connect to the newly learnt discovery controllers. 13028Then the discovery service will automatically attach to any subsystem found in the 13029discovery log page from the discovery controllers learnt using mDNS. 13030When determining a controller name to use when attaching, it will use 13031the 'name' parameter as a prefix, followed by a unique integer assigned for each of the 13032discovery controllers learnt through mDNS, followed by a unique integer for that discovery 13033service. If the discovery service identifies a subsystem that has been previously 13034attached but is listed with a different path, it will use the same controller name 13035as the previous entry, and connect as a multipath. 13036 13037When the discovery service sees that a subsystem entry has been removed 13038from the log page, it will automatically detach from that controller as well. 13039 13040The 'name' is also used to later stop the discovery service. 13041 13042#### Parameters 13043 13044Name | Optional | Type | Description 13045-------------------------- | -------- | ----------- | ----------- 13046name | Required | string | Prefix for NVMe discovery services found 13047svcname | Required | string | Service to discover: e.g. _nvme-disc._tcp 13048hostnqn | Optional | string | NVMe-oF hostnqn 13049 13050#### Example 13051 13052Example request: 13053 13054~~~json 13055{ 13056 "jsonrpc": "2.0", 13057 "method": "bdev_nvme_start_mdns_discovery", 13058 "id": 1, 13059 "params": { 13060 "name": "cdc_auto", 13061 "svcname": "_nvme-disc._tcp", 13062 "hostnqn": "nqn.2021-12.io.spdk:host1", 13063 } 13064} 13065~~~ 13066 13067Example response: 13068 13069~~~json 13070{ 13071 "jsonrpc": "2.0", 13072 "id": 1, 13073 "result": true 13074} 13075~~~ 13076 13077### bdev_nvme_stop_mdns_discovery {#rpc_bdev_nvme_stop_mdns_discovery} 13078 13079Stops a mDNS discovery service. This includes detaching any controllers that were 13080discovered via the service that is being stopped. 13081 13082#### Parameters 13083 13084Name | Optional | Type | Description 13085-------------------------- | -------- | ----------- | ----------- 13086name | Required | string | Name of mDNS discovery instance to stop 13087 13088#### Example 13089 13090Example request: 13091 13092~~~json 13093{ 13094 "jsonrpc": "2.0", 13095 "method": "bdev_nvme_stop_mdns_discovery", 13096 "id": 1, 13097 "params": { 13098 "name": "cdc_auto" 13099 } 13100} 13101~~~ 13102 13103Example response: 13104 13105~~~json 13106{ 13107 "jsonrpc": "2.0", 13108 "id": 1, 13109 "result": true 13110} 13111~~~ 13112 13113### bdev_nvme_get_mdns_discovery_info {#rpc_bdev_nvme_get_mdns_discovery_info} 13114 13115Get the information about the mDNS discovery service instances. 13116 13117#### Example 13118 13119Example request: 13120~~~json 13121{ 13122 "jsonrpc": "2.0", 13123 "method": "bdev_nvme_get_mdns_discovery_info", 13124 "id": 1 13125} 13126~~~ 13127 13128Example response: 13129 13130~~~json 13131[ 13132 { 13133 "name": "cdc_auto", 13134 "svcname": "_nvme-disc._tcp", 13135 "referrals": [ 13136 { 13137 "name": "cdc_auto0", 13138 "trid": { 13139 "trtype": "TCP", 13140 "adrfam": "IPv4", 13141 "traddr": "66.1.2.21", 13142 "trsvcid": "8009", 13143 "subnqn": "nqn.2014-08.org.nvmexpress.discovery" 13144 } 13145 }, 13146 { 13147 "name": "cdc_auto1", 13148 "trid": { 13149 "trtype": "TCP", 13150 "adrfam": "IPv4", 13151 "traddr": "66.1.1.21", 13152 "trsvcid": "8009", 13153 "subnqn": "nqn.2014-08.org.nvmexpress.discovery" 13154 } 13155 } 13156 ] 13157 } 13158] 13159~~~ 13160 13161### keyring_file_add_key {#rpc_keyring_file_add_key} 13162 13163Add a file-based key to a keyring. 13164 13165#### Parameters 13166 13167Name | Optional | Type | Description 13168-------------------------- | -------- | ----------- | ----------- 13169name | Required | string | Name of the key to add. 13170path | Required | string | Path to a file containing the key. 13171 13172#### Example 13173 13174Example request: 13175 13176~~~json 13177{ 13178 "jsonrpc": "2.0", 13179 "method": "keyring_file_add_key", 13180 "id": 1 13181 "params": { 13182 "name": "key0", 13183 "path": "/path/to/key0" 13184 } 13185} 13186~~~ 13187 13188Example response: 13189 13190~~~json 13191{ 13192 "jsonrpc": "2.0", 13193 "id": 1, 13194 "result": true 13195} 13196~~~ 13197 13198### keyring_file_remove_key {#rpc_keyring_file_remove_key} 13199 13200Remove a file-based key from a keyring. 13201 13202#### Parameters 13203 13204Name | Optional | Type | Description 13205-------------------------- | -------- | ----------- | ----------- 13206name | Required | string | Name of the key to remove. 13207 13208#### Example 13209 13210Example request: 13211 13212~~~json 13213{ 13214 "jsonrpc": "2.0", 13215 "method": "keyring_file_remove_key", 13216 "id": 1 13217 "params": { 13218 "name": "key0" 13219 } 13220} 13221~~~ 13222 13223Example response: 13224 13225~~~json 13226{ 13227 "jsonrpc": "2.0", 13228 "id": 1, 13229 "result": true 13230} 13231~~~ 13232 13233### keyring_get_keys {#rpc_keyring_get_keys} 13234 13235Get a list of available keys. This RPC will only list keys that are currently attached to a 13236keyring. Dynamically loaded keys (via the `probe_key()` callback) will only be included if they're 13237currently in-use (i.e. with active references obtained via `spdk_keyring_get_key()`). 13238 13239#### Example 13240 13241Example request: 13242~~~json 13243{ 13244 "jsonrpc": "2.0", 13245 "method": "keyring_get_keys", 13246 "id": 1 13247} 13248~~~ 13249 13250Example response: 13251 13252~~~json 13253{ 13254 "jsonrpc": "2.0", 13255 "id": 1, 13256 "result": [ 13257 { 13258 "name": "key0", 13259 "module": "keyring_file", 13260 "removed": false, 13261 "probed": false, 13262 "refcnt": 1, 13263 "path": "/path/to/key0" 13264 }, 13265 { 13266 "name": "key1", 13267 "module": "keyring_file", 13268 "removed": false, 13269 "probed": false, 13270 "refcnt": 1, 13271 "path": "/path/to/key1" 13272 } 13273 ] 13274} 13275~~~ 13276 13277### keyring_linux_set_options {#keyring_linux_set_options} 13278 13279Set options of the keyring_linux module. 13280 13281#### Parameters 13282 13283Name | Optional | Type | Description 13284----------------------- | -------- | ----------- | ----------- 13285enable | Optional | boolean | Enable the module. 13286 13287#### Example 13288 13289Example request: 13290~~~json 13291{ 13292 "jsonrpc": "2.0", 13293 "method": "keyring_linux_set_options", 13294 "id": 1 13295 "params": { 13296 "enable": true 13297 } 13298} 13299~~~ 13300 13301Example response: 13302 13303~~~json 13304{ 13305 "jsonrpc": "2.0", 13306 "id": 1, 13307 "result": true 13308} 13309~~~ 13310 13311### nvmf_publish_mdns_prr {#rpc_nvmf_publish_mdns_prr} 13312 13313This interface is used to publish an NVMf target's service location using mDNS 13314(Multicast DNS) protocol. It allows clients to discover the NVMf target using 13315the published service location. 13316 13317#### Parameters 13318 13319Name | Optional | Type | Description 13320-------------------------- | -------- | ----------- | ----------- 13321tgt_name | Optional | string | Parent NVMe-oF target name. 13322 13323#### Example 13324 13325Example request: 13326 13327~~~json 13328{ 13329 "jsonrpc": "2.0", 13330 "method": "nvmf_publish_mdns_prr", 13331 "id": 1, 13332} 13333~~~ 13334 13335Example response: 13336 13337~~~json 13338{ 13339 "jsonrpc": "2.0", 13340 "id": 1, 13341 "result": true 13342} 13343~~~ 13344 13345### nvmf_stop_mdns_prr {#rpc_nvmf_stop_mdns_prr} 13346 13347This interface is used to stop publishing the NVMf target's service location 13348using mDNS (Multicast DNS) protocol. It removes the published service location, 13349preventing clients from discovering the NVMf target. 13350 13351#### Parameters 13352 13353Name | Optional | Type | Description 13354-------------------------- | -------- | ----------- | ----------- 13355tgt_name | Optional | string | Parent NVMe-oF target name. 13356 13357#### Example 13358 13359Example request: 13360 13361~~~json 13362{ 13363 "jsonrpc": "2.0", 13364 "method": "nvmf_stop_mdns_prr", 13365 "id": 1 13366} 13367~~~ 13368 13369Example response: 13370 13371~~~json 13372{ 13373 "jsonrpc": "2.0", 13374 "id": 1, 13375 "result": true 13376} 13377~~~ 13378