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