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