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. 4671 4672#### Parameters 4673 4674Name | Optional | Type | Description 4675----------------------- | -------- | ----------- | ----------- 4676name | Required | string | Name of the NVMe controller 4677 4678#### Example 4679 4680Example request: 4681 4682~~~json 4683{ 4684 "jsonrpc": "2.0", 4685 "method": "bdev_nvme_cuse_register", 4686 "id": 1, 4687 "params": { 4688 "name": "Nvme0" 4689 } 4690} 4691~~~ 4692 4693Example response: 4694 4695~~~json 4696{ 4697 "jsonrpc": "2.0", 4698 "id": 1, 4699 "result": true 4700} 4701~~~ 4702 4703### bdev_nvme_cuse_unregister {#rpc_bdev_nvme_cuse_unregister} 4704 4705Unregister CUSE device on NVMe controller. 4706 4707#### Parameters 4708 4709Name | Optional | Type | Description 4710----------------------- | -------- | ----------- | ----------- 4711name | Required | string | Name of the NVMe controller 4712 4713#### Example 4714 4715Example request: 4716 4717~~~json 4718{ 4719 "params": { 4720 "name": "Nvme0" 4721 }, 4722 "jsonrpc": "2.0", 4723 "method": "bdev_nvme_cuse_unregister", 4724 "id": 1 4725} 4726~~~ 4727 4728Example response: 4729 4730~~~json 4731{ 4732 "jsonrpc": "2.0", 4733 "id": 1, 4734 "result": true 4735} 4736~~~ 4737 4738### bdev_zone_block_create {#rpc_bdev_zone_block_create} 4739 4740Creates a virtual zone device on top of existing non-zoned bdev. 4741 4742#### Parameters 4743 4744Name | Optional | Type | Description 4745----------------------- | -------- | ----------- | ----------- 4746name | Required | string | Name of the Zone device 4747base_bdev | Required | string | Name of the Base bdev 4748zone_capacity | Required | number | Zone capacity in blocks 4749optimal_open_zones | Required | number | Number of zones required to reach optimal write speed 4750 4751#### Example 4752 4753Example request: 4754 4755~~~json 4756{ 4757 "jsonrpc": "2.0", 4758 "method": "bdev_zone_block_create", 4759 "id": 1, 4760 "params": { 4761 "name": "zone1", 4762 "base_bdev": "NVMe0n1", 4763 "zone_capacity": 4096, 4764 "optimal_open_zones": 32 4765 } 4766} 4767~~~ 4768 4769Example response: 4770 4771~~~json 4772{ 4773 "jsonrpc": "2.0", 4774 "id": 1, 4775 "result": "zone1" 4776} 4777~~~ 4778 4779### bdev_zone_block_delete {#rpc_bdev_zone_block_delete} 4780 4781Deletes a virtual zone device. 4782 4783#### Parameters 4784 4785Name | Optional | Type | Description 4786----------------------- | -------- | ----------- | ----------- 4787name | Required | string | Name of the Zone device 4788 4789#### Example 4790 4791Example request: 4792 4793~~~json 4794{ 4795 "jsonrpc": "2.0", 4796 "method": "bdev_zone_block_delete", 4797 "id": 1, 4798 "params": { 4799 "name": "zone1" 4800 } 4801} 4802~~~ 4803 4804Example response: 4805 4806~~~json 4807{ 4808 "jsonrpc": "2.0", 4809 "id": 1, 4810 "result": true 4811} 4812~~~ 4813 4814### bdev_nvme_apply_firmware {#rpc_bdev_nvme_apply_firmware} 4815 4816Download and commit firmware to NVMe device. 4817 4818#### Parameters 4819 4820Name | Optional | Type | Description 4821----------------------- | -------- | ----------- | ----------- 4822filename | Required | string | filename of the firmware to download 4823bdev_name | Required | string | Name of the NVMe block device 4824 4825#### Example 4826 4827Example request: 4828 4829~~~json 4830{ 4831 "jsonrpc": "2.0", 4832 "method": "bdev_nvme_apply_firmware", 4833 "id": 1, 4834 "params": { 4835 "filename": "firmware_file", 4836 "bdev_name": "NVMe0n1" 4837 } 4838} 4839~~~ 4840 4841### bdev_nvme_get_transport_statistics {#rpc_bdev_nvme_get_transport_statistics} 4842 4843Get bdev_nvme poll group transport statistics. 4844 4845#### Parameters 4846 4847This RPC method accepts no parameters 4848 4849#### Response 4850 4851The response is an array of objects containing information about transport statistics per NVME poll group. 4852 4853#### Example 4854 4855Example request: 4856 4857~~~json 4858{ 4859 "jsonrpc": "2.0", 4860 "id": 1, 4861 "method": "bdev_nvme_get_transport_statistics", 4862} 4863~~~ 4864 4865Example response: 4866 4867~~~json 4868{ 4869 "jsonrpc": "2.0", 4870 "id": 1, 4871 "result": { 4872 "poll_groups": [ 4873 { 4874 "thread": "nvmf_tgt_poll_group_0", 4875 "transports": [ 4876 { 4877 "trname": "RDMA", 4878 "devices": [ 4879 { 4880 "dev_name": "mlx5_1", 4881 "polls": 137492169, 4882 "idle_polls": 137492169, 4883 "completions": 0, 4884 "queued_requests": 0, 4885 "total_send_wrs": 0, 4886 "send_sq_doorbell_updates": 0, 4887 "total_recv_wrs": 0, 4888 "recv_sq_doorbell_updates": 0 4889 }, 4890 { 4891 "dev_name": "mlx5_0", 4892 "polls": 137985185, 4893 "idle_polls": 137492169, 4894 "completions": 1474593, 4895 "queued_requests": 0, 4896 "total_send_wrs": 1474593, 4897 "send_sq_doorbell_updates": 426147, 4898 "total_recv_wrs": 1474721, 4899 "recv_sq_doorbell_updates": 348445 4900 } 4901 ] 4902 }, 4903 { 4904 "trname": "PCIE", 4905 "polls": 435419831, 4906 "idle_polls": 434901004, 4907 "completions": 1485543, 4908 "cq_doorbell_updates": 518827, 4909 "queued_requests": 0, 4910 "submitted_requests": 1485543, 4911 "sq_doorbell_updates": 516081 4912 } 4913 ] 4914 }, 4915 { 4916 "thread": "nvmf_tgt_poll_group_1", 4917 "transports": [ 4918 { 4919 "trname": "RDMA", 4920 "devices": [ 4921 { 4922 "dev_name": "mlx5_1", 4923 "polls": 140245630, 4924 "idle_polls": 140245630, 4925 "completions": 0, 4926 "queued_requests": 0, 4927 "total_send_wrs": 0, 4928 "send_sq_doorbell_updates": 0, 4929 "total_recv_wrs": 0, 4930 "recv_sq_doorbell_updates": 0 4931 }, 4932 { 4933 "dev_name": "mlx5_0", 4934 "polls": 140751844, 4935 "idle_polls": 140245630, 4936 "completions": 1489298, 4937 "queued_requests": 0, 4938 "total_send_wrs": 1489298, 4939 "send_sq_doorbell_updates": 433510, 4940 "total_recv_wrs": 1489426, 4941 "recv_sq_doorbell_updates": 357956 4942 } 4943 ] 4944 }, 4945 { 4946 "trname": "PCIE", 4947 "polls": 429044294, 4948 "idle_polls": 428525658, 4949 "completions": 1478730, 4950 "cq_doorbell_updates": 518636, 4951 "queued_requests": 0, 4952 "submitted_requests": 1478730, 4953 "sq_doorbell_updates": 511658 4954 } 4955 ] 4956 } 4957 ] 4958 } 4959} 4960~~~ 4961 4962### bdev_nvme_get_controller_health_info {#rpc_bdev_nvme_get_controller_health_info} 4963 4964Display health log of the required NVMe bdev device. 4965 4966#### Parameters 4967 4968Name | Optional | Type | Description 4969----------------------- | -------- | ----------- | ----------- 4970name | Required | string | Name of the NVMe bdev controller 4971 4972#### Response 4973 4974The response is the object containing information about health log of the NVMe controller. 4975 4976#### Example 4977 4978Example request: 4979 4980~~~json 4981{ 4982 "jsonrpc": "2.0", 4983 "method": "bdev_nvme_get_controller_health_info", 4984 "id": 1, 4985 "params": { 4986 "name": "Nvme0" 4987 } 4988} 4989~~~ 4990 4991Example response: 4992 4993~~~json 4994{ 4995 "model_number": "INTEL SSDPE2KX020T8", 4996 "serial_number": "BTLJ72430ARH2P0BGN", 4997 "firmware_revision": "VDV10110", 4998 "traddr": "0000:08:00.0", 4999 "temperature_celsius": 32, 5000 "available_spare_percentage": 99, 5001 "available_spare_threshold_percentage": 10, 5002 "percentage_used": 2, 5003 "data_units_read": 1013408619, 5004 "data_units_written": 346792685, 5005 "host_read_commands": 30457773282, 5006 "host_write_commands": 18949677715, 5007 "controller_busy_time": 4979, 5008 "power_cycles": 49, 5009 "power_on_hours": 31118, 5010 "unsafe_shutdowns": 18, 5011 "media_errors": 17, 5012 "num_err_log_entries": 19, 5013 "warning_temperature_time_minutes": 0, 5014 "critical_composite_temperature_time_minutes": 0 5015} 5016~~~ 5017 5018### bdev_rbd_register_cluster {#rpc_bdev_rbd_register_cluster} 5019 5020This method is available only if SPDK was build with Ceph RBD support. 5021 5022#### Parameters 5023 5024Name | Optional | Type | Description 5025----------------------- | -------- | ----------- | ----------- 5026name | Required | string | Registered Rados cluster object name 5027user_id | Optional | string | Ceph ID (i.e. admin, not client.admin) 5028config_param | Optional | string map | Explicit librados configuration 5029config_file | Optional | string | File path of libraodos configuration file 5030key_file | Optional | string | File path of libraodos key file 5031 5032This RPC registers a Rados Cluster object handle which is only known 5033to rbd module, it uses user_id + config_param or user_id + config_file + 5034key_file or user_id + config_param + config_file + key_file to identify 5035a Rados cluster object. 5036 5037When accessing the Ceph cluster as some user other than "admin" (the 5038default), the "user_id" has to be set. 5039 5040The configuration items and secret key can be specified by setting config_param, 5041config_file and key_file, all of them, or none of them. If only config_param is 5042passed, all key/value pairs are passed to rados_conf_set to configure cluster access. 5043In practice, "mon_host" (= list of monitor address+port) and "key" (= the secret key 5044stored in Ceph keyrings) are enough. If config_file and key_file are specified, they must 5045exist with all relevant settings for accessing the Ceph cluster. If config_param, config_file 5046and key_file are specified, get the key/value pairs from config_file first and set to 5047rados_conf_set function, then set pairs in config_param and keyring in key_file. If nothing 5048is specified, it will get configuration file and key file from the default location 5049/etc/ceph/ceph.conf and /etc/ceph/ceph.client.user_id.keyring. 5050 5051#### Result 5052 5053Name of newly created Rados cluster object. 5054 5055#### Example 5056 5057Example request: 5058 5059~~ 5060{ 5061 "params": { 5062 "name": "rbd_cluster", 5063 "user_id": cinder, 5064 "config_file": "/root/ceph_conf/ceph.conf", 5065 "key_file": "/root/ceph_conf/ceph.client.cinder.keyring" 5066 }, 5067 "jsonrpc": "2.0", 5068 "method": "bdev_rbd_register_cluster", 5069 "id": 1 5070} 5071~~ 5072 5073Example response: 5074 5075~~ 5076response: 5077{ 5078 "jsonrpc": "2.0", 5079 "id": 1, 5080 "result": "rbd_cluster" 5081} 5082~~ 5083 5084### bdev_rbd_unregister_cluster {#rpc_bdev_rbd_unregister_cluster} 5085 5086This method is available only if SPDK was build with Ceph RBD support. 5087If there is still rbd bdev using this cluster, the unregisteration operation 5088will fail. 5089 5090#### Result 5091 5092`true` if Rados cluster object with provided name was deleted or `false` otherwise. 5093 5094#### Parameters 5095 5096Name | Optional | Type | Description 5097----------------------- | -------- | ----------- | ------------------------- 5098name | Required | string | Rados cluster object name 5099 5100#### Example 5101 5102Example request: 5103 5104~~ 5105{ 5106 "params": { 5107 "name": "rbd_cluster" 5108 }, 5109 "jsonrpc": "2.0", 5110 "method": "bdev_rbd_unregister_cluster", 5111 "id": 1 5112} 5113~~ 5114 5115Example response: 5116 5117~~ 5118{ 5119 "jsonrpc": "2.0", 5120 "id": 1, 5121 "result": true 5122} 5123~~ 5124 5125### bdev_rbd_get_clusters_info {#rpc_bdev_rbd_get_clusters_info} 5126 5127This method is available only if SPDK was build with Ceph RBD support. 5128 5129#### Result 5130 5131Returns the cluster info of the Rados Cluster name if provided. Otherwise, it 5132returns the cluster info of every registered Raods Cluster name. 5133 5134#### Parameters 5135 5136Name | Optional | Type | Description 5137----------------------- | -------- | ----------- | ------------------------- 5138name | Optional | string | Rados cluster object name 5139 5140#### Example 5141 5142Example request: 5143 5144~~ 5145{ 5146 "params": { 5147 "name": "rbd_cluster" 5148 }, 5149 "jsonrpc": "2.0", 5150 "method": "bdev_rbd_get_clusters_info", 5151 "id": 1 5152} 5153~~ 5154 5155Example response: 5156 5157~~ 5158{ 5159 "jsonrpc": "2.0", 5160 "cluster_name": "rbd_cluster" 5161} 5162~~ 5163 5164### bdev_rbd_create {#rpc_bdev_rbd_create} 5165 5166Create @ref bdev_config_rbd bdev 5167 5168This method is available only if SPDK was build with Ceph RBD support. 5169 5170#### Parameters 5171 5172Name | Optional | Type | Description 5173----------------------- | -------- | ----------- | ----------- 5174name | Optional | string | Bdev name 5175user_id | Optional | string | Ceph ID (i.e. admin, not client.admin) 5176pool_name | Required | string | Pool name 5177rbd_name | Required | string | Image name 5178block_size | Required | number | Block size 5179config | Optional | string map | Explicit librados configuration 5180cluster_name | Optional | string | Rados cluster object name created in this module. 5181uuid | Optional | string | UUID of new bdev 5182 5183If no config is specified, Ceph configuration files must exist with 5184all relevant settings for accessing the pool. If a config map is 5185passed, the configuration files are ignored and instead all key/value 5186pairs are passed to rados_conf_set to configure cluster access. In 5187practice, "mon_host" (= list of monitor address+port) and "key" (= the 5188secret key stored in Ceph keyrings) are enough. 5189 5190When accessing the image as some user other than "admin" (the 5191default), the "user_id" has to be set. 5192 5193If provided with cluster_name option, it will use the Rados cluster object 5194referenced by the name (created by bdev_rbd_register_cluster RPC) and ignores 5195"user_id + config" combination to create its own Rados cluster. In this scenario, 5196all the bdevs will share the same cluster with one connection of Ceph in librbd module. 5197Performance tuning on the I/O workload could be done by estimating how many io_contxt 5198threads and messager threads in Ceph side and how many cores would be reasonable to provide 5199for SPDK to get up to your projections. 5200 5201#### Result 5202 5203Name of newly created bdev. 5204 5205#### Example 5206 5207Example request with `key` from `/etc/ceph/ceph.client.admin.keyring`: 5208 5209~~~json 5210{ 5211 "params": { 5212 "pool_name": "rbd", 5213 "rbd_name": "foo", 5214 "config": { 5215 "mon_host": "192.168.7.1:6789,192.168.7.2:6789", 5216 "key": "AQDwf8db7zR1GRAA5k7NKXjS5S5V4mntwUDnGQ==", 5217 } 5218 "block_size": 4096, 5219 "uuid": "76210ea4-7920-40a0-a07b-8992a7443c76" 5220 }, 5221 "jsonrpc": "2.0", 5222 "method": "bdev_rbd_create", 5223 "id": 1 5224} 5225~~~ 5226 5227Example response: 5228 5229~~~json 5230response: 5231{ 5232 "jsonrpc": "2.0", 5233 "id": 1, 5234 "result": "Ceph0" 5235} 5236~~~ 5237 5238Example request with `cluster_name`: 5239 5240~~ 5241{ 5242 "params": { 5243 "pool_name": "rbd", 5244 "rbd_name": "foo", 5245 "block_size": 4096, 5246 "cluster_name": "rbd_cluster" 5247 }, 5248 "jsonrpc": "2.0", 5249 "method": "bdev_rbd_create", 5250 "id": 1 5251} 5252~~ 5253 5254Example response: 5255 5256~~ 5257response: 5258{ 5259 "jsonrpc": "2.0", 5260 "id": 1, 5261 "result": "Ceph0" 5262} 5263~~ 5264 5265### bdev_rbd_delete {#rpc_bdev_rbd_delete} 5266 5267Delete @ref bdev_config_rbd bdev 5268 5269This method is available only if SPDK was build with Ceph RBD support. 5270 5271#### Result 5272 5273`true` if bdev with provided name was deleted or `false` otherwise. 5274 5275#### Parameters 5276 5277Name | Optional | Type | Description 5278----------------------- | -------- | ----------- | ----------- 5279name | Required | string | Bdev name 5280 5281#### Example 5282 5283Example request: 5284 5285~~~json 5286{ 5287 "params": { 5288 "name": "Rbd0" 5289 }, 5290 "jsonrpc": "2.0", 5291 "method": "bdev_rbd_delete", 5292 "id": 1 5293} 5294~~~ 5295 5296Example response: 5297 5298~~~json 5299{ 5300 "jsonrpc": "2.0", 5301 "id": 1, 5302 "result": true 5303} 5304~~~ 5305 5306### bdev_rbd_resize {#rpc_bdev_rbd_resize} 5307 5308Resize @ref bdev_config_rbd bdev 5309 5310This method is available only if SPDK was build with Ceph RBD support. 5311 5312#### Result 5313 5314`true` if bdev with provided name was resized or `false` otherwise. 5315 5316#### Parameters 5317 5318Name | Optional | Type | Description 5319----------------------- | -------- | ----------- | ----------- 5320name | Required | string | Bdev name 5321new_size | Required | int | New bdev size for resize operation in MiB 5322 5323#### Example 5324 5325Example request: 5326 5327~~~json 5328{ 5329 "params": { 5330 "name": "Rbd0" 5331 "new_size": "4096" 5332 }, 5333 "jsonrpc": "2.0", 5334 "method": "bdev_rbd_resize", 5335 "id": 1 5336} 5337~~~ 5338 5339Example response: 5340 5341~~~json 5342{ 5343 "jsonrpc": "2.0", 5344 "id": 1, 5345 "result": true 5346} 5347~~~ 5348 5349### bdev_delay_create {#rpc_bdev_delay_create} 5350 5351Create delay bdev. This bdev type redirects all IO to it's base bdev and inserts a delay on the completion 5352path to create an artificial drive latency. All latency values supplied to this bdev should be in microseconds. 5353 5354#### Parameters 5355 5356Name | Optional | Type | Description 5357----------------------- | -------- | ----------- | ----------- 5358name | Required | string | Bdev name 5359base_bdev_name | Required | string | Base bdev name 5360avg_read_latency | Required | number | average read latency (us) 5361p99_read_latency | Required | number | p99 read latency (us) 5362avg_write_latency | Required | number | average write latency (us) 5363p99_write_latency | Required | number | p99 write latency (us) 5364 5365#### Result 5366 5367Name of newly created bdev. 5368 5369#### Example 5370 5371Example request: 5372 5373~~~json 5374{ 5375 "params": { 5376 "base_bdev_name": "Null0", 5377 "name": "Delay0", 5378 "avg_read_latency": "15", 5379 "p99_read_latency": "50", 5380 "avg_write_latency": "40", 5381 "p99_write_latency": "110", 5382 }, 5383 "jsonrpc": "2.0", 5384 "method": "bdev_delay_create", 5385 "id": 1 5386} 5387~~~ 5388 5389Example response: 5390 5391~~~json 5392{ 5393 "jsonrpc": "2.0", 5394 "id": 1, 5395 "result": "Delay0" 5396} 5397~~~ 5398 5399### bdev_delay_delete {#rpc_bdev_delay_delete} 5400 5401Delete delay bdev. 5402 5403#### Parameters 5404 5405Name | Optional | Type | Description 5406----------------------- | -------- | ----------- | ----------- 5407name | Required | string | Bdev name 5408 5409#### Example 5410 5411Example request: 5412 5413~~~json 5414{ 5415 "params": { 5416 "name": "Delay0" 5417 }, 5418 "jsonrpc": "2.0", 5419 "method": "bdev_delay_delete", 5420 "id": 1 5421} 5422 5423~~~ 5424 5425Example response: 5426 5427~~~json 5428{ 5429 "jsonrpc": "2.0", 5430 "id": 1, 5431 "result": true 5432} 5433~~~ 5434 5435### bdev_delay_update_latency {#rpc_bdev_delay_update_latency} 5436 5437Update a target latency value associated with a given delay bdev. Any currently 5438outstanding I/O will be completed with the old latency. 5439 5440#### Parameters 5441 5442Name | Optional | Type | Description 5443----------------------- | -------- | ----------- | ----------- 5444delay_bdev_name | Required | string | Name of the delay bdev 5445latency_type | Required | string | One of: avg_read, avg_write, p99_read, p99_write 5446latency_us | Required | number | The new latency value in microseconds 5447 5448#### Result 5449 5450Name of newly created bdev. 5451 5452#### Example 5453 5454Example request: 5455 5456~~~json 5457{ 5458 "params": { 5459 "delay_bdev_name": "Delay0", 5460 "latency_type": "avg_read", 5461 "latency_us": "100", 5462 }, 5463 "jsonrpc": "2.0", 5464 "method": "bdev_delay_update_latency", 5465 "id": 1 5466} 5467~~~ 5468 5469Example response: 5470 5471~~~json 5472{ 5473 "result": "true" 5474} 5475~~~ 5476 5477### bdev_error_create {#rpc_bdev_error_create} 5478 5479Construct error bdev. 5480 5481#### Parameters 5482 5483Name | Optional | Type | Description 5484----------------------- | -------- | ----------- | ----------- 5485base_name | Required | string | Base bdev name 5486uuid | Optional | string | UUID for this bdev 5487 5488#### Example 5489 5490Example request: 5491 5492~~~json 5493{ 5494 "params": { 5495 "base_name": "Malloc0" 5496 }, 5497 "jsonrpc": "2.0", 5498 "method": "bdev_error_create", 5499 "id": 1 5500} 5501~~~ 5502 5503Example response: 5504 5505~~~json 5506{ 5507 "jsonrpc": "2.0", 5508 "id": 1, 5509 "result": true 5510} 5511~~~ 5512 5513### bdev_error_delete {#rpc_bdev_error_delete} 5514 5515Delete error bdev 5516 5517#### Result 5518 5519`true` if bdev with provided name was deleted or `false` otherwise. 5520 5521#### Parameters 5522 5523Name | Optional | Type | Description 5524----------------------- | -------- | ----------- | ----------- 5525name | Required | string | Error bdev name 5526 5527#### Example 5528 5529Example request: 5530 5531~~~json 5532{ 5533 "params": { 5534 "name": "EE_Malloc0" 5535 }, 5536 "jsonrpc": "2.0", 5537 "method": "bdev_error_delete", 5538 "id": 1 5539} 5540~~~ 5541 5542Example response: 5543 5544~~~json 5545{ 5546 "jsonrpc": "2.0", 5547 "id": 1, 5548 "result": true 5549} 5550~~~ 5551 5552### bdev_error_inject_error {#rpc_bdev_error_inject_error} 5553 5554Inject an error via an error bdev. Create an error bdev on base bdev first. Default 'num' 5555value is 1 and if 'num' is set to zero, the specified injection is disabled. 5556 5557#### Parameters 5558 5559Name | Optional | Type | Description 5560----------------------- | -------- | ----------- | ----------- 5561name | Required | string | Name of the error injection bdev 5562io_type | Required | string | io type 'clear' 'read' 'write' 'unmap' 'flush' 'all' 5563error_type | Required | string | error type 'failure' 'pending' 'corrupt_data' 'nomem' 5564num | Optional | int | the number of commands you want to fail.(default:1) 5565queue_depth | Optional | int | the queue depth at which to trigger the error 5566corrupt_offset | Optional | int | the offset in bytes to xor with corrupt_value 5567corrupt_value | Optional | int | the value for xor (1-255, 0 is invalid) 5568 5569#### Example 5570 5571Example request: 5572 5573~~~json 5574{ 5575 "jsonrpc": "2.0", 5576 "method": "bdev_error_inject_error", 5577 "id": 1, 5578 "params": { 5579 "name": "EE_Malloc0", 5580 "io_type": "write", 5581 "error_type": "pending", 5582 "num": 1 5583 } 5584} 5585~~~ 5586 5587Example response: 5588 5589~~~json 5590{ 5591 "jsonrpc": "2.0", 5592 "id": 1, 5593 "result": true 5594} 5595~~~ 5596 5597### bdev_iscsi_set_options {#rpc_bdev_iscsi_set_options} 5598 5599This RPC can be called at any time, but the new value will only take effect for new iSCSI bdevs. 5600 5601#### Parameters 5602 5603Name | Optional | Type | Description 5604-------------------------- | -------- | ----------- | ----------- 5605timeout_sec | Optional | number | Timeout for command, in seconds, if 0, don't track timeout 5606 5607#### Example 5608 5609Example request: 5610 5611~~~json 5612request: 5613{ 5614 "params": { 5615 "timeout_sec": 30 5616 }, 5617 "jsonrpc": "2.0", 5618 "method": "bdev_iscsi_set_options", 5619 "id": 1 5620} 5621~~~ 5622 5623Example response: 5624 5625~~~json 5626{ 5627 "jsonrpc": "2.0", 5628 "id": 1, 5629 "result": true 5630} 5631~~~ 5632 5633### bdev_iscsi_create {#rpc_bdev_iscsi_create} 5634 5635Connect to iSCSI target and create bdev backed by this connection. 5636 5637This method is available only if SPDK was build with iSCSI initiator support. 5638 5639#### Parameters 5640 5641Name | Optional | Type | Description 5642----------------------- | -------- | ----------- | ----------- 5643name | Required | string | Bdev name 5644initiator_iqn | Required | string | IQN name used during connection 5645url | Required | string | iSCSI resource URI 5646 5647#### Result 5648 5649Name of newly created bdev. 5650 5651#### Example 5652 5653Example request: 5654 5655~~~json 5656{ 5657 "params": { 5658 "url": "iscsi://127.0.0.1/iqn.2016-06.io.spdk:disk1/0", 5659 "initiator_iqn": "iqn.2016-06.io.spdk:init", 5660 "name": "iSCSI0" 5661 }, 5662 "jsonrpc": "2.0", 5663 "method": "bdev_iscsi_create", 5664 "id": 1 5665} 5666~~~ 5667 5668Example response: 5669 5670~~~json 5671{ 5672 "jsonrpc": "2.0", 5673 "id": 1, 5674 "result": "iSCSI0" 5675} 5676~~~ 5677 5678### bdev_iscsi_delete {#rpc_bdev_iscsi_delete} 5679 5680Delete iSCSI bdev and terminate connection to target. 5681 5682This method is available only if SPDK was built with iSCSI initiator support. 5683 5684#### Parameters 5685 5686Name | Optional | Type | Description 5687----------------------- | -------- | ----------- | ----------- 5688name | Required | string | Bdev name 5689 5690#### Example 5691 5692Example request: 5693 5694~~~json 5695{ 5696 "params": { 5697 "name": "iSCSI0" 5698 }, 5699 "jsonrpc": "2.0", 5700 "method": "bdev_iscsi_delete", 5701 "id": 1 5702} 5703~~~ 5704 5705Example response: 5706 5707~~~json 5708{ 5709 "jsonrpc": "2.0", 5710 "id": 1, 5711 "result": true 5712} 5713~~~ 5714 5715### bdev_ftl_create {#rpc_bdev_ftl_create} 5716 5717Create FTL bdev. 5718 5719This RPC is subject to change. 5720 5721#### Parameters 5722 5723Name | Optional | Type | Description 5724----------------------- | -------- | ----------- | ----------- 5725name | Required | string | Bdev name 5726base_bdev | Required | string | Name of the base device 5727cache | Required | string | Name of the cache device 5728uuid | Optional | string | UUID of restored bdev (not applicable when creating new instance) 5729core_mask | Optional | string | CPU core(s) possible for placement of the ftl core thread, application main thread by default 5730overprovisioning | Optional | int | Percentage of base device used for relocation, 20% by default 5731fast_shutdown | Optional | bool | When set FTL will minimize persisted data on target application shutdown and rely on shared memory during next load 5732 5733#### Result 5734 5735Name of newly created bdev. 5736 5737#### Example 5738 5739Example request: 5740 5741~~~json 5742{ 5743 "params": { 5744 "name": "ftl0", 5745 "base_bdev": "nvme0n1", 5746 "cache": "nvme1n1", 5747 "uuid": "4a7481ce-786f-41a0-9b86-8f7465c8f4d3", 5748 "core_mask": "[0]", 5749 "overprovisioning": 10 5750 }, 5751 "jsonrpc": "2.0", 5752 "method": "bdev_ftl_create", 5753 "id": 1 5754} 5755~~~ 5756 5757Example response: 5758 5759~~~json 5760{ 5761 "jsonrpc": "2.0", 5762 "id": 1, 5763 "result": { 5764 "name" : "ftl0" 5765 "uuid" : "4a7481ce-786f-41a0-9b86-8f7465c8f4d3" 5766 } 5767} 5768~~~ 5769 5770### bdev_ftl_load {#rpc_bdev_ftl_load} 5771 5772Loads FTL bdev. 5773 5774This RPC is subject to change. 5775 5776#### Parameters 5777 5778Name | Optional | Type | Description 5779----------------------- | -------- | ----------- | ----------- 5780name | Required | string | Bdev name 5781base_bdev | Required | string | Name of the base device 5782cache | Required | string | Name of the cache device 5783uuid | Required | string | UUID of restored bdev 5784core_mask | Optional | string | CPU core(s) possible for placement of the ftl core thread, application main thread by default 5785overprovisioning | Optional | int | Percentage of base device used for relocation, 20% by default 5786fast_shutdown | Optional | bool | When set FTL will minimize persisted data on target application shutdown and rely on shared memory during next load 5787 5788#### Result 5789 5790Name of loaded bdev. 5791 5792#### Example 5793 5794Example request: 5795 5796~~~json 5797{ 5798 "params": { 5799 "name": "ftl0", 5800 "base_bdev": "nvme0n1", 5801 "cache": "nvme1n1", 5802 "uuid": "4a7481ce-786f-41a0-9b86-8f7465c8f4d3", 5803 "core_mask": "[0]", 5804 "overprovisioning": 10 5805 }, 5806 "jsonrpc": "2.0", 5807 "method": "bdev_ftl_load", 5808 "id": 1 5809} 5810~~~ 5811 5812Example response: 5813 5814~~~json 5815{ 5816 "jsonrpc": "2.0", 5817 "id": 1, 5818 "result": { 5819 "name" : "ftl0" 5820 "uuid" : "4a7481ce-786f-41a0-9b86-8f7465c8f4d3" 5821 } 5822} 5823~~~ 5824 5825### bdev_ftl_delete {#rpc_bdev_ftl_delete} 5826 5827Delete FTL bdev. 5828 5829This RPC is subject to change. 5830 5831#### Parameters 5832 5833Name | Optional | Type | Description 5834----------------------- | -------- | ----------- | ----------- 5835name | Required | string | Bdev name 5836fast_shutdown | Optional | bool | When set FTL will minimize persisted data during deletion and rely on shared memory during next load 5837 5838#### Example 5839 5840Example request: 5841 5842~~~json 5843{ 5844 "params": { 5845 "name": "ftl0" 5846 }, 5847 "jsonrpc": "2.0", 5848 "method": "bdev_ftl_delete", 5849 "id": 1 5850} 5851~~~ 5852 5853Example response: 5854 5855~~~json 5856{ 5857 "jsonrpc": "2.0", 5858 "id": 1, 5859 "result": true 5860} 5861~~~ 5862 5863### bdev_ftl_unload {#rpc_bdev_ftl_unload} 5864 5865Unloads FTL bdev. 5866 5867This RPC is subject to change. 5868 5869#### Parameters 5870 5871Name | Optional | Type | Description 5872----------------------- | -------- | ----------- | ----------- 5873name | Required | string | Bdev name 5874fast_shutdown | Optional | bool | When set FTL will minimize persisted data during deletion and rely on shared memory during next load 5875 5876#### Example 5877 5878Example request: 5879 5880~~~json 5881{ 5882 "params": { 5883 "name": "ftl0" 5884 }, 5885 "jsonrpc": "2.0", 5886 "method": "bdev_ftl_unload", 5887 "id": 1 5888} 5889~~~ 5890 5891Example response: 5892 5893~~~json 5894{ 5895 "jsonrpc": "2.0", 5896 "id": 1, 5897 "result": true 5898} 5899~~~ 5900 5901### bdev_ftl_unmap {#rpc_bdev_ftl_unmap} 5902 5903Unmap range of LBAs. 5904 5905This RPC is subject to change. 5906 5907#### Parameters 5908 5909Name | Optional | Type | Description 5910----------------------- | -------- | ----------- | ----------- 5911name | Required | string | Bdev name 5912lba | Required | number | start lba, aligned to 1024 5913num_blocks | Required | number | number of blocks, aligned to 1024 5914 5915#### Example 5916 5917Example request: 5918 5919~~~json 5920{ 5921 "params": { 5922 "name": "ftl0" 5923 "lba": "0" 5924 "num_blocks": "1024" 5925 }, 5926 "jsonrpc": "2.0", 5927 "method": "bdev_ftl_unmap", 5928 "id": 1 5929} 5930~~~ 5931 5932Example response: 5933 5934~~~json 5935{ 5936 "jsonrpc": "2.0", 5937 "id": 1, 5938 "result": true 5939} 5940~~~ 5941 5942### bdev_ftl_get_stats {#rpc_bdev_ftl_get_stats} 5943 5944Get IO statistics for FTL bdev 5945 5946This RPC is subject to change. 5947 5948#### Parameters 5949 5950Name | Optional | Type | Description 5951----------------------- | -------- | ----------- | ----------- 5952name | Required | string | Bdev name 5953 5954#### Response 5955 5956The response is an object containing IO statistics for an FTL instance, split into multiple subobjects: 5957 5958- `user` - contains information about number of IOs, and errors for any incoming requests, 5959- `cmp` - information about IO for the compaction process, 5960- `gc` - information about IO for the garbage collection process, 5961- `md_base` - internal metadata requests to the base FTL device, 5962- `md_nv_cache` - internal metadata requests to the cache device, 5963- `l2p` - requests done on the L2P cache region. 5964 5965Each subobject contains the following information: 5966 5967- `ios` - describes the total number of IOs requested, 5968- `blocks` - the total number of requested blocks, 5969- `errors` - describes the number of detected errors for a given operation, with the following distinctions: 5970 - `media` - media errors, 5971 - `crc` - mismatch in calculated CRC versus saved checksum in the metadata, 5972 - `other` - any other errors. 5973 5974#### Example 5975 5976Example request: 5977 5978~~~json 5979{ 5980 "params": { 5981 "name": "ftl0" 5982 }, 5983 "jsonrpc": "2.0", 5984 "method": "bdev_ftl_get_stats", 5985 "id": 1 5986} 5987~~~ 5988 5989Example response: 5990 5991~~~json 5992{ 5993 "jsonrpc": "2.0", 5994 "id": 1, 5995 "result": { 5996 "name": "ftl0", 5997 "user": { 5998 "read": { 5999 "ios": 0, 6000 "blocks": 0, 6001 "errors": { 6002 "media": 0, 6003 "crc": 0, 6004 "other": 0 6005 } 6006 }, 6007 "write": { 6008 "ios": 318707, 6009 "blocks": 318707, 6010 "errors": { 6011 "media": 0, 6012 "other": 0 6013 } 6014 } 6015 }, 6016 "cmp": { 6017 "read": { 6018 "ios": 0, 6019 "blocks": 0, 6020 "errors": { 6021 "media": 0, 6022 "crc": 0, 6023 "other": 0 6024 } 6025 }, 6026 "write": { 6027 "ios": 0, 6028 "blocks": 0, 6029 "errors": { 6030 "media": 0, 6031 "other": 0 6032 } 6033 } 6034 }, 6035 "gc": { 6036 "read": { 6037 "ios": 0, 6038 "blocks": 0, 6039 "errors": { 6040 "media": 0, 6041 "crc": 0, 6042 "other": 0 6043 } 6044 }, 6045 "write": { 6046 "ios": 0, 6047 "blocks": 0, 6048 "errors": { 6049 "media": 0, 6050 "other": 0 6051 } 6052 } 6053 }, 6054 "md_base": { 6055 "read": { 6056 "ios": 0, 6057 "blocks": 0, 6058 "errors": { 6059 "media": 0, 6060 "crc": 0, 6061 "other": 0 6062 } 6063 }, 6064 "write": { 6065 "ios": 1, 6066 "blocks": 32, 6067 "errors": { 6068 "media": 0, 6069 "other": 0 6070 } 6071 } 6072 }, 6073 "md_nv_cache": { 6074 "read": { 6075 "ios": 0, 6076 "blocks": 0, 6077 "errors": { 6078 "media": 0, 6079 "crc": 0, 6080 "other": 0 6081 } 6082 }, 6083 "write": { 6084 "ios": 1064, 6085 "blocks": 1073896, 6086 "errors": { 6087 "media": 0, 6088 "other": 0 6089 } 6090 } 6091 }, 6092 "l2p": { 6093 "read": { 6094 "ios": 240659, 6095 "blocks": 240659, 6096 "errors": { 6097 "media": 0, 6098 "crc": 0, 6099 "other": 0 6100 } 6101 }, 6102 "write": { 6103 "ios": 235745, 6104 "blocks": 235745, 6105 "errors": { 6106 "media": 0, 6107 "other": 0 6108 } 6109 } 6110 } 6111 } 6112} 6113~~~ 6114 6115### bdev_ftl_get_properties {#rpc_bdev_ftl_get_properties} 6116 6117Get FTL properties 6118 6119#### Parameters 6120 6121Name | Optional | Type | Description 6122----------------------- | -------- | ----------- | ----------- 6123name | Required | string | Bdev name 6124 6125#### Response 6126 6127The response contains FTL bdev properties. Some of them can be modified, other 6128reported as read only. 6129 6130#### Example 6131 6132Example request: 6133 6134~~~json 6135{ 6136 "params": { 6137 "name": "ftl0" 6138 }, 6139 "jsonrpc": "2.0", 6140 "method": "bdev_ftl_get_properties", 6141 "id": 1 6142} 6143~~~ 6144 6145Example response: 6146 6147~~~json 6148{ 6149 "jsonrpc": "2.0", 6150 "id": 1, 6151 "result": { 6152 "name": "ftl0", 6153 "properties": [ 6154 { 6155 "name": "property1", 6156 "value": "Property Value 1", 6157 "unit": "MiB/s", 6158 "desc": "This is an example of read-only property", 6159 "read-only": true 6160 }, 6161 { 6162 "name": "property2", 6163 "value": 17, 6164 "unit": "s", 6165 "desc": "This is an example of FTL modifiable property", 6166 "read-only": false 6167 } 6168 ] 6169 } 6170} 6171~~~ 6172 6173### bdev_ftl_set_property {#rpc_bdev_ftl_set_property} 6174 6175Set FTL property. Trying to set a read-only property will result in an error. 6176 6177#### Parameters 6178 6179Name | Optional | Type | Description 6180----------------------- | -------- | ----------- | ----------- 6181name | Required | string | Bdev name 6182property | Required | string | Name of the property to modify 6183value | Required | string | New value of the property to be set 6184 6185#### Example 6186 6187Example request: 6188 6189~~~json 6190{ 6191 "params": { 6192 "name": "ftl0" 6193 "property": "nv_cache.flush" 6194 "value": "true" 6195 }, 6196 "jsonrpc": "2.0", 6197 "method": "bdev_ftl_set_property", 6198 "id": 1 6199} 6200~~~ 6201 6202Example response: 6203 6204~~~json 6205{ 6206 "jsonrpc": "2.0", 6207 "id": 1, 6208 "result": true 6209} 6210~~~ 6211 6212### bdev_passthru_create {#rpc_bdev_passthru_create} 6213 6214Create passthru bdev. This bdev type redirects all IO to it's base bdev. It has no other purpose than being an example 6215and a starting point in development of new bdev type. 6216 6217#### Parameters 6218 6219Name | Optional | Type | Description 6220----------------------- | -------- | ----------- | ----------- 6221name | Required | string | Bdev name 6222base_bdev_name | Required | string | Base bdev name 6223uuid | Optional | string | UUID of new bdev 6224 6225#### Result 6226 6227Name of newly created bdev. 6228 6229#### Example 6230 6231Example request: 6232 6233~~~json 6234{ 6235 "params": { 6236 "base_bdev_name": "Malloc0", 6237 "name": "Passsthru0" 6238 }, 6239 "jsonrpc": "2.0", 6240 "method": "bdev_passthru_create", 6241 "id": 1 6242} 6243~~~ 6244 6245Example response: 6246 6247~~~json 6248{ 6249 "jsonrpc": "2.0", 6250 "id": 1, 6251 "result": "Passsthru0" 6252} 6253~~~ 6254 6255### bdev_passthru_delete {#rpc_bdev_passthru_delete} 6256 6257Delete passthru bdev. 6258 6259#### Parameters 6260 6261Name | Optional | Type | Description 6262----------------------- | -------- | ----------- | ----------- 6263name | Required | string | Bdev name 6264 6265#### Example 6266 6267Example request: 6268 6269~~~json 6270{ 6271 "params": { 6272 "name": "Passsthru0" 6273 }, 6274 "jsonrpc": "2.0", 6275 "method": "bdev_passthru_delete", 6276 "id": 1 6277} 6278 6279~~~ 6280 6281Example response: 6282 6283~~~json 6284{ 6285 "jsonrpc": "2.0", 6286 "id": 1, 6287 "result": true 6288} 6289~~~ 6290 6291### bdev_xnvme_create {#rpc_bdev_xnvme_create} 6292 6293Create xnvme bdev. This bdev type redirects all IO to its underlying backend. 6294 6295#### Parameters 6296 6297Name | Optional | Type | Description 6298----------------------- | -------- | ----------- | ----------- 6299name | Required | string | name of xNVMe bdev to create 6300filename | Required | string | path to device or file (ex: /dev/nvme0n1) 6301io_mechanism | Required | string | IO mechanism to use (ex: libaio, io_uring, io_uring_cmd, etc.) 6302conserve_cpu | Optional | boolean | Whether or not to conserve CPU when polling (default: false) 6303 6304#### Result 6305 6306Name of newly created bdev. 6307 6308#### Example 6309 6310Example request: 6311 6312~~~json 6313{ 6314 "jsonrpc": "2.0", 6315 "method": "bdev_xnvme_create", 6316 "id": 1, 6317 "params": { 6318 "name": "bdev_ng0n1", 6319 "filename": "/dev/ng0n1", 6320 "io_mechanism": "io_uring_cmd", 6321 "conserve_cpu": false, 6322 } 6323} 6324~~~ 6325 6326Example response: 6327 6328~~~json 6329{ 6330 "jsonrpc": "2.0", 6331 "id": 1, 6332 "result": "bdev_ng0n1" 6333} 6334~~~ 6335 6336### bdev_xnvme_delete {#rpc_bdev_xnvme_delete} 6337 6338Delete xnvme bdev. 6339 6340#### Parameters 6341 6342Name | Optional | Type | Description 6343----------------------- | -------- | ----------- | ----------- 6344name | Required | string | name of xnvme bdev to delete 6345 6346#### Example 6347 6348Example request: 6349 6350~~~json 6351{ 6352 "params": { 6353 "name": "bdev_ng0n1" 6354 }, 6355 "jsonrpc": "2.0", 6356 "method": "bdev_xnvme_delete", 6357 "id": 1 6358} 6359 6360~~~ 6361 6362Example response: 6363 6364~~~json 6365{ 6366 "jsonrpc": "2.0", 6367 "id": 1, 6368 "result": true 6369} 6370~~~ 6371 6372### bdev_virtio_attach_controller {#rpc_bdev_virtio_attach_controller} 6373 6374Create new initiator @ref bdev_config_virtio_scsi or @ref bdev_config_virtio_blk and expose all found bdevs. 6375 6376#### Parameters 6377 6378Name | Optional | Type | Description 6379----------------------- | -------- | ----------- | ----------- 6380name | Required | string | Virtio SCSI base bdev name or Virtio Blk bdev name 6381trtype | Required | string | Virtio target trtype: pci or user 6382traddr | Required | string | target address: BDF or UNIX socket file path 6383dev_type | Required | string | Virtio device type: blk or scsi 6384vq_count | Optional | number | Number of queues this controller will utilize (default: 1) 6385vq_size | Optional | number | Size of each queue. Must be power of 2. (default: 512) 6386 6387In case of Virtio SCSI the `name` parameter will be base name for new created bdevs. For Virtio Blk `name` will be the 6388name of created bdev. 6389 6390`vq_count` and `vq_size` parameters are valid only if `trtype` is `user`. 6391 6392#### Result 6393 6394Array of names of newly created bdevs. 6395 6396#### Example 6397 6398Example request: 6399 6400~~~json 6401{ 6402 "params": { 6403 "name": "VirtioScsi0", 6404 "trtype": "user", 6405 "vq_size": 128, 6406 "dev_type": "scsi", 6407 "traddr": "/tmp/VhostScsi0", 6408 "vq_count": 4 6409 }, 6410 "jsonrpc": "2.0", 6411 "method": "bdev_virtio_attach_controller", 6412 "id": 1 6413} 6414~~~ 6415 6416Example response: 6417 6418~~~json 6419{ 6420 "jsonrpc": "2.0", 6421 "id": 1, 6422 "result": ["VirtioScsi0t2", "VirtioScsi0t4"] 6423} 6424~~~ 6425 6426### bdev_virtio_scsi_get_devices {#rpc_bdev_virtio_scsi_get_devices} 6427 6428Show information about all available Virtio SCSI devices. 6429 6430#### Parameters 6431 6432This method has no parameters. 6433 6434#### Result 6435 6436Array of Virtio SCSI information objects. 6437 6438#### Example 6439 6440Example request: 6441 6442~~~json 6443{ 6444 "jsonrpc": "2.0", 6445 "method": "bdev_virtio_scsi_get_devices", 6446 "id": 1 6447} 6448~~~ 6449 6450Example response: 6451 6452~~~json 6453{ 6454 "jsonrpc": "2.0", 6455 "id": 1, 6456 "result": [ 6457 { 6458 "name": "VirtioScsi0", 6459 "virtio": { 6460 "vq_size": 128, 6461 "vq_count": 4, 6462 "type": "user", 6463 "socket": "/tmp/VhostScsi0" 6464 } 6465 } 6466 ] 6467} 6468~~~ 6469 6470### bdev_virtio_detach_controller {#rpc_bdev_virtio_detach_controller} 6471 6472Remove a Virtio device. This command can be used to remove any type of virtio device. 6473 6474#### Parameters 6475 6476Name | Optional | Type | Description 6477----------------------- | -------- | ----------- | ----------- 6478name | Required | string | Virtio name 6479 6480#### Example 6481 6482Example request: 6483 6484~~~json 6485{ 6486 "params": { 6487 "name": "VirtioUser0" 6488 }, 6489 "jsonrpc": "2.0", 6490 "method": "bdev_virtio_detach_controller", 6491 "id": 1 6492} 6493 6494~~~ 6495 6496Example response: 6497 6498~~~json 6499{ 6500 "jsonrpc": "2.0", 6501 "id": 1, 6502 "result": true 6503} 6504~~~ 6505 6506### bdev_virtio_blk_set_hotplug {#rpc_bdev_virtio_blk_set_hotplug} 6507 6508Enable/Disable the virtio blk hotplug monitor or change the monitor period time 6509 6510#### Parameters 6511 6512Name | Optional | Type | Description 6513----------------------- | -------- | ----------- | ----------- 6514enable | Required | bool | Enable or disable the virtio blk hotplug monitor 6515period-us | Optional | number | The period time of the monitor 6516 6517When the enable is true then the period-us is optional. If user don't set the period time then use the default 6518value. When the enable is false then the period-us is not required. 6519 6520#### Result 6521 6522True the rpc is successful otherwise false 6523 6524#### Example 6525 6526Example request: 6527 6528~~~json 6529{ 6530 "params": { 6531 "enable": "true", 6532 "period-us": "1000000" 6533 }, 6534 "jsonrpc": "2.0", 6535 "method": "bdev_virtio_blk_set_hotplug", 6536 "id": 1 6537} 6538~~~ 6539 6540Example response: 6541 6542~~~json 6543{ 6544 "jsonrpc": "2.0", 6545 "id": 1, 6546 "result": true 6547} 6548~~~ 6549 6550## iSCSI Target {#jsonrpc_components_iscsi_tgt} 6551 6552### iscsi_set_options method {#rpc_iscsi_set_options} 6553 6554Set global parameters for iSCSI targets. 6555 6556This RPC may only be called before SPDK subsystems have been initialized. This RPC can be called only once. 6557 6558#### Parameters 6559 6560Name | Optional | Type | Description 6561------------------------------- | -------- | ------- | ----------- 6562auth_file | Optional | string | Path to CHAP shared secret file (default: "") 6563node_base | Optional | string | Prefix of the name of iSCSI target node (default: "iqn.2016-06.io.spdk") 6564nop_timeout | Optional | number | Timeout in seconds to nop-in request to the initiator (default: 60) 6565nop_in_interval | Optional | number | Time interval in secs between nop-in requests by the target (default: 30) 6566disable_chap | Optional | boolean | CHAP for discovery session should be disabled (default: `false`) 6567require_chap | Optional | boolean | CHAP for discovery session should be required (default: `false`) 6568mutual_chap | Optional | boolean | CHAP for discovery session should be unidirectional (`false`) or bidirectional (`true`) (default: `false`) 6569chap_group | Optional | number | CHAP group ID for discovery session (default: 0) 6570max_sessions | Optional | number | Maximum number of sessions in the host (default: 128) 6571max_queue_depth | Optional | number | Maximum number of outstanding I/Os per queue (default: 64) 6572max_connections_per_session | Optional | number | Session specific parameter, MaxConnections (default: 2) 6573default_time2wait | Optional | number | Session specific parameter, DefaultTime2Wait (default: 2) 6574default_time2retain | Optional | number | Session specific parameter, DefaultTime2Retain (default: 20) 6575first_burst_length | Optional | number | Session specific parameter, FirstBurstLength (default: 8192) 6576immediate_data | Optional | boolean | Session specific parameter, ImmediateData (default: `true`) 6577error_recovery_level | Optional | number | Session specific parameter, ErrorRecoveryLevel (default: 0) 6578allow_duplicated_isid | Optional | boolean | Allow duplicated initiator session ID (default: `false`) 6579max_large_datain_per_connection | Optional | number | Max number of outstanding split read I/Os per connection (default: 64) 6580max_r2t_per_connection | Optional | number | Max number of outstanding R2Ts per connection (default: 4) 6581pdu_pool_size | Optional | number | Number of PDUs in the pool (default: approximately 2 * max_sessions * (max_queue_depth + max_connections_per_session)) 6582immediate_data_pool_size | Optional | number | Number of immediate data buffers in the pool (default: 128 * max_sessions) 6583data_out_pool_size | Optional | number | Number of data out buffers in the pool (default: 16 * max_sessions) 6584 6585To load CHAP shared secret file, its path is required to specify explicitly in the parameter `auth_file`. 6586 6587Parameters `disable_chap` and `require_chap` are mutually exclusive. Parameters `no_discovery_auth`, `req_discovery_auth`, 6588`req_discovery_auth_mutual`, and `discovery_auth_group` are still available instead of `disable_chap`, `require_chap`, 6589`mutual_chap`, and `chap_group`, respectivey but will be removed in future releases. 6590 6591#### Example 6592 6593Example request: 6594 6595~~~json 6596{ 6597 "params": { 6598 "allow_duplicated_isid": true, 6599 "default_time2retain": 60, 6600 "first_burst_length": 8192, 6601 "immediate_data": true, 6602 "node_base": "iqn.2016-06.io.spdk", 6603 "max_sessions": 128, 6604 "nop_timeout": 30, 6605 "nop_in_interval": 30, 6606 "auth_file": "/usr/local/etc/spdk/auth.conf", 6607 "disable_chap": true, 6608 "default_time2wait": 2 6609 }, 6610 "jsonrpc": "2.0", 6611 "method": "iscsi_set_options", 6612 "id": 1 6613} 6614~~~ 6615 6616Example response: 6617 6618~~~json 6619{ 6620 "jsonrpc": "2.0", 6621 "id": 1, 6622 "result": true 6623} 6624~~~ 6625 6626### iscsi_get_options method {#rpc_iscsi_get_options} 6627 6628Show global parameters of iSCSI targets. 6629 6630#### Parameters 6631 6632This method has no parameters. 6633 6634#### Example 6635 6636Example request: 6637 6638~~~json 6639request: 6640{ 6641 "jsonrpc": "2.0", 6642 "method": "iscsi_get_options", 6643 "id": 1 6644} 6645~~~ 6646 6647Example response: 6648 6649~~~json 6650{ 6651 "jsonrpc": "2.0", 6652 "id": 1, 6653 "result": { 6654 "allow_duplicated_isid": true, 6655 "default_time2retain": 60, 6656 "first_burst_length": 8192, 6657 "immediate_data": true, 6658 "node_base": "iqn.2016-06.io.spdk", 6659 "mutual_chap": false, 6660 "nop_in_interval": 30, 6661 "chap_group": 0, 6662 "max_connections_per_session": 2, 6663 "max_queue_depth": 64, 6664 "nop_timeout": 30, 6665 "max_sessions": 128, 6666 "error_recovery_level": 0, 6667 "auth_file": "/usr/local/etc/spdk/auth.conf", 6668 "disable_chap": true, 6669 "default_time2wait": 2, 6670 "require_chap": false, 6671 "max_large_datain_per_connection": 64, 6672 "max_r2t_per_connection": 4 6673 } 6674} 6675~~~ 6676 6677### scsi_get_devices {#rpc_scsi_get_devices} 6678 6679Display SCSI devices 6680 6681#### Parameters 6682 6683This method has no parameters. 6684 6685#### Example 6686 6687Example request: 6688 6689~~~json 6690{ 6691 "jsonrpc": "2.0", 6692 "method": "scsi_get_devices", 6693 "id": 1 6694} 6695~~~ 6696 6697Example response: 6698 6699~~~json 6700{ 6701 "jsonrpc": "2.0", 6702 "id": 1, 6703 "result": [ 6704 { 6705 "id": 0, 6706 "device_name": "iqn.2016-06.io.spdk:Target3" 6707 } 6708 ] 6709} 6710~~~ 6711 6712### iscsi_set_discovery_auth method {#rpc_iscsi_set_discovery_auth} 6713 6714Set CHAP authentication for sessions dynamically. 6715 6716#### Parameters 6717 6718Name | Optional | Type | Description 6719--------------------------- | -------- | --------| ----------- 6720disable_chap | Optional | boolean | CHAP for discovery session should be disabled (default: `false`) 6721require_chap | Optional | boolean | CHAP for discovery session should be required (default: `false`) 6722mutual_chap | Optional | boolean | CHAP for discovery session should be unidirectional (`false`) or bidirectional (`true`) (default: `false`) 6723chap_group | Optional | number | CHAP group ID for discovery session (default: 0) 6724 6725Parameters `disable_chap` and `require_chap` are mutually exclusive. 6726 6727#### Example 6728 6729Example request: 6730 6731~~~json 6732request: 6733{ 6734 "params": { 6735 "chap_group": 1, 6736 "require_chap": true, 6737 "mutual_chap": true 6738 }, 6739 "jsonrpc": "2.0", 6740 "method": "iscsi_set_discovery_auth", 6741 "id": 1 6742} 6743~~~ 6744 6745Example response: 6746 6747~~~json 6748{ 6749 "jsonrpc": "2.0", 6750 "id": 1, 6751 "result": true 6752} 6753~~~ 6754 6755### iscsi_create_auth_group method {#rpc_iscsi_create_auth_group} 6756 6757Create an authentication group for CHAP authentication. 6758 6759#### Parameters 6760 6761Name | Optional | Type | Description 6762--------------------------- | -------- | --------| ----------- 6763tag | Required | number | Authentication group tag (unique, integer > 0) 6764secrets | Optional | array | Array of @ref rpc_iscsi_create_auth_group_secret objects 6765 6766#### secret {#rpc_iscsi_create_auth_group_secret} 6767 6768Name | Optional | Type | Description 6769--------------------------- | ---------| --------| ----------- 6770user | Required | string | Unidirectional CHAP name 6771secret | Required | string | Unidirectional CHAP secret 6772muser | Optional | string | Bidirectional CHAP name 6773msecret | Optional | string | Bidirectional CHAP secret 6774 6775#### Example 6776 6777Example request: 6778 6779~~~json 6780{ 6781 "params": { 6782 "secrets": [ 6783 { 6784 "muser": "mu1", 6785 "secret": "s1", 6786 "user": "u1", 6787 "msecret": "ms1" 6788 } 6789 ], 6790 "tag": 2 6791 }, 6792 "jsonrpc": "2.0", 6793 "method": "iscsi_create_auth_group", 6794 "id": 1 6795} 6796~~~ 6797 6798Example response: 6799 6800~~~json 6801{ 6802 "jsonrpc": "2.0", 6803 "id": 1, 6804 "result": true 6805} 6806~~~ 6807 6808### iscsi_delete_auth_group method {#rpc_iscsi_delete_auth_group} 6809 6810Delete an existing authentication group for CHAP authentication. 6811 6812#### Parameters 6813 6814Name | Optional | Type | Description 6815--------------------------- | -------- | --------| ----------- 6816tag | Required | number | Authentication group tag (unique, integer > 0) 6817 6818#### Example 6819 6820Example request: 6821 6822~~~json 6823{ 6824 "params": { 6825 "tag": 2 6826 }, 6827 "jsonrpc": "2.0", 6828 "method": "iscsi_delete_auth_group", 6829 "id": 1 6830} 6831~~~ 6832 6833Example response: 6834 6835~~~json 6836{ 6837 "jsonrpc": "2.0", 6838 "id": 1, 6839 "result": true 6840} 6841~~~ 6842 6843### iscsi_get_auth_groups {#rpc_iscsi_get_auth_groups} 6844 6845Show information about all existing authentication group for CHAP authentication. 6846 6847#### Parameters 6848 6849This method has no parameters. 6850 6851#### Result 6852 6853Array of objects describing authentication group. 6854 6855Name | Type | Description 6856--------------------------- | --------| ----------- 6857tag | number | Authentication group tag 6858secrets | array | Array of @ref rpc_iscsi_create_auth_group_secret objects 6859 6860#### Example 6861 6862Example request: 6863 6864~~~json 6865{ 6866 "jsonrpc": "2.0", 6867 "method": "iscsi_get_auth_groups", 6868 "id": 1 6869} 6870~~~ 6871 6872Example response: 6873 6874~~~json 6875{ 6876 "jsonrpc": "2.0", 6877 "id": 1, 6878 "result": [ 6879 { 6880 "secrets": [ 6881 { 6882 "muser": "mu1", 6883 "secret": "s1", 6884 "user": "u1", 6885 "msecret": "ms1" 6886 } 6887 ], 6888 "tag": 1 6889 }, 6890 { 6891 "secrets": [ 6892 { 6893 "secret": "s2", 6894 "user": "u2" 6895 } 6896 ], 6897 "tag": 2 6898 } 6899 ] 6900} 6901~~~ 6902 6903### iscsi_auth_group_add_secret {#rpc_iscsi_auth_group_add_secret} 6904 6905Add a secret to an existing authentication group for CHAP authentication. 6906 6907#### Parameters 6908 6909Name | Optional | Type | Description 6910--------------------------- | -------- | --------| ----------- 6911tag | Required | number | Authentication group tag (unique, integer > 0) 6912user | Required | string | Unidirectional CHAP name 6913secret | Required | string | Unidirectional CHAP secret 6914muser | Optional | string | Bidirectional CHAP name 6915msecret | Optional | string | Bidirectional CHAP secret 6916 6917#### Example 6918 6919Example request: 6920 6921~~~json 6922{ 6923 "params": { 6924 "muser": "mu3", 6925 "secret": "s3", 6926 "tag": 2, 6927 "user": "u3", 6928 "msecret": "ms3" 6929 }, 6930 "jsonrpc": "2.0", 6931 "method": "iscsi_auth_group_add_secret", 6932 "id": 1 6933} 6934~~~json 6935 6936Example response: 6937 6938~~~json 6939{ 6940 "jsonrpc": "2.0", 6941 "id": 1, 6942 "result": true 6943} 6944~~~ 6945 6946### iscsi_auth_group_remove_secret {#rpc_iscsi_auth_group_remove_secret} 6947 6948Remove a secret from an existing authentication group for CHAP authentication. 6949 6950#### Parameters 6951 6952Name | Optional | Type | Description 6953--------------------------- | -------- | --------| ----------- 6954tag | Required | number | Authentication group tag (unique, integer > 0) 6955user | Required | string | Unidirectional CHAP name 6956 6957#### Example 6958 6959Example request: 6960 6961~~~json 6962{ 6963 "params": { 6964 "tag": 2, 6965 "user": "u3" 6966 }, 6967 "jsonrpc": "2.0", 6968 "method": "iscsi_auth_group_remove_secret", 6969 "id": 1 6970} 6971~~~ 6972 6973Example response: 6974 6975~~~json 6976{ 6977 "jsonrpc": "2.0", 6978 "id": 1, 6979 "result": true 6980} 6981~~~ 6982 6983### iscsi_get_initiator_groups method {#rpc_iscsi_get_initiator_groups} 6984 6985Show information about all available initiator groups. 6986 6987#### Parameters 6988 6989This method has no parameters. 6990 6991#### Result 6992 6993Array of objects describing initiator groups. 6994 6995Name | Type | Description 6996--------------------------- | --------| ----------- 6997tag | number | Initiator group tag 6998initiators | array | Array of initiator hostnames or IP addresses 6999netmasks | array | Array of initiator netmasks 7000 7001#### Example 7002 7003Example request: 7004 7005~~~json 7006{ 7007 "jsonrpc": "2.0", 7008 "method": "iscsi_get_initiator_groups", 7009 "id": 1 7010} 7011~~~ 7012 7013Example response: 7014 7015~~~json 7016{ 7017 "jsonrpc": "2.0", 7018 "id": 1, 7019 "result": [ 7020 { 7021 "initiators": [ 7022 "iqn.2016-06.io.spdk:host1", 7023 "iqn.2016-06.io.spdk:host2" 7024 ], 7025 "tag": 1, 7026 "netmasks": [ 7027 "192.168.1.0/24" 7028 ] 7029 } 7030 ] 7031} 7032~~~ 7033 7034### iscsi_create_initiator_group method {#rpc_iscsi_create_initiator_group} 7035 7036Add an initiator group. 7037 7038#### Parameters 7039 7040Name | Optional | Type | Description 7041--------------------------- | -------- | --------| ----------- 7042tag | Required | number | Initiator group tag (unique, integer > 0) 7043initiators | Required | array | Not empty array of initiator hostnames or IP addresses 7044netmasks | Required | array | Not empty array of initiator netmasks 7045 7046#### Example 7047 7048Example request: 7049 7050~~~json 7051{ 7052 "params": { 7053 "initiators": [ 7054 "iqn.2016-06.io.spdk:host1", 7055 "iqn.2016-06.io.spdk:host2" 7056 ], 7057 "tag": 1, 7058 "netmasks": [ 7059 "192.168.1.0/24" 7060 ] 7061 }, 7062 "jsonrpc": "2.0", 7063 "method": "iscsi_create_initiator_group", 7064 "id": 1 7065} 7066~~~ 7067 7068Example response: 7069 7070~~~json 7071response: 7072{ 7073 "jsonrpc": "2.0", 7074 "id": 1, 7075 "result": true 7076} 7077~~~ 7078 7079### iscsi_delete_initiator_group method {#rpc_iscsi_delete_initiator_group} 7080 7081Delete an existing initiator group. 7082 7083#### Parameters 7084 7085Name | Optional | Type | Description 7086--------------------------- | -------- | --------| ----------- 7087tag | Required | number | Initiator group tag (unique, integer > 0) 7088 7089#### Example 7090 7091Example request: 7092 7093~~~json 7094{ 7095 "params": { 7096 "tag": 1 7097 }, 7098 "jsonrpc": "2.0", 7099 "method": "iscsi_delete_initiator_group", 7100 "id": 1 7101} 7102~~~ 7103 7104Example response: 7105 7106~~~json 7107{ 7108 "jsonrpc": "2.0", 7109 "id": 1, 7110 "result": true 7111} 7112~~~ 7113 7114### iscsi_initiator_group_add_initiators method {#rpc_iscsi_initiator_group_add_initiators} 7115 7116Add initiators to an existing initiator group. 7117 7118#### Parameters 7119 7120Name | Optional | Type | Description 7121--------------------------- | -------- | --------| ----------- 7122tag | Required | number | Existing initiator group tag. 7123initiators | Optional | array | Array of initiator hostnames or IP addresses 7124netmasks | Optional | array | Array of initiator netmasks 7125 7126#### Example 7127 7128Example request: 7129 7130~~~json 7131request: 7132{ 7133 "params": { 7134 "initiators": [ 7135 "iqn.2016-06.io.spdk:host3" 7136 ], 7137 "tag": 1, 7138 "netmasks": [ 7139 "255.255.255.1" 7140 ] 7141 }, 7142 "jsonrpc": "2.0", 7143 "method": "iscsi_initiator_group_add_initiators", 7144 "id": 1 7145} 7146~~~ 7147 7148Example response: 7149 7150~~~json 7151response: 7152{ 7153 "jsonrpc": "2.0", 7154 "id": 1, 7155 "result": true 7156} 7157~~~ 7158 7159### iscsi_initiator_group_remove_initiators method {#rpc_iscsi_initiator_group_remove_initiators} 7160 7161Remove initiators from an initiator group. 7162 7163#### Parameters 7164 7165Name | Optional | Type | Description 7166--------------------------- | -------- | --------| ----------- 7167tag | Required | number | Existing initiator group tag. 7168initiators | Optional | array | Array of initiator hostnames or IP addresses 7169netmasks | Optional | array | Array of initiator netmasks 7170 7171#### Example 7172 7173Example request: 7174 7175~~~json 7176request: 7177{ 7178 "params": { 7179 "initiators": [ 7180 "iqn.2016-06.io.spdk:host3" 7181 ], 7182 "tag": 1, 7183 "netmasks": [ 7184 "255.255.255.1" 7185 ] 7186 }, 7187 "jsonrpc": "2.0", 7188 "method": "iscsi_initiator_group_remove_initiators", 7189 "id": 1 7190} 7191~~~ 7192 7193Example response: 7194 7195~~~json 7196response: 7197{ 7198 "jsonrpc": "2.0", 7199 "id": 1, 7200 "result": true 7201} 7202~~~ 7203 7204### iscsi_get_target_nodes method {#rpc_iscsi_get_target_nodes} 7205 7206Show information about all available iSCSI target nodes. 7207 7208#### Parameters 7209 7210This method has no parameters. 7211 7212#### Result 7213 7214Array of objects describing target node. 7215 7216Name | Type | Description 7217--------------------------- | --------| ----------- 7218name | string | Target node name (ASCII) 7219alias_name | string | Target node alias name (ASCII) 7220pg_ig_maps | array | Array of Portal_Group_Tag:Initiator_Group_Tag mappings 7221luns | array | Array of Bdev names to LUN ID mappings 7222queue_depth | number | Target queue depth 7223disable_chap | boolean | CHAP authentication should be disabled for this target 7224require_chap | boolean | CHAP authentication should be required for this target 7225mutual_chap | boolean | CHAP authentication should be bidirectional (`true`) or unidirectional (`false`) 7226chap_group | number | Authentication group ID for this target node 7227header_digest | boolean | Header Digest should be required for this target node 7228data_digest | boolean | Data Digest should be required for this target node 7229 7230#### Example 7231 7232Example request: 7233 7234~~~json 7235{ 7236 "jsonrpc": "2.0", 7237 "method": "iscsi_get_target_nodes", 7238 "id": 1 7239} 7240~~~ 7241 7242Example response: 7243 7244~~~json 7245{ 7246 "jsonrpc": "2.0", 7247 "id": 1, 7248 "result": [ 7249 { 7250 "luns": [ 7251 { 7252 "lun_id": 0, 7253 "bdev_name": "Nvme0n1" 7254 } 7255 ], 7256 "mutual_chap": false, 7257 "name": "iqn.2016-06.io.spdk:target1", 7258 "alias_name": "iscsi-target1-alias", 7259 "require_chap": false, 7260 "chap_group": 0, 7261 "pg_ig_maps": [ 7262 { 7263 "ig_tag": 1, 7264 "pg_tag": 1 7265 } 7266 ], 7267 "data_digest": false, 7268 "disable_chap": false, 7269 "header_digest": false, 7270 "queue_depth": 64 7271 } 7272 ] 7273} 7274~~~ 7275 7276### iscsi_create_target_node method {#rpc_iscsi_create_target_node} 7277 7278Add an iSCSI target node. 7279 7280#### Parameters 7281 7282Name | Optional | Type | Description 7283--------------------------- | -------- | --------| ----------- 7284name | Required | string | Target node name (ASCII) 7285alias_name | Required | string | Target node alias name (ASCII) 7286pg_ig_maps | Required | array | Array of (Portal_Group_Tag:Initiator_Group_Tag) mappings 7287luns | Required | array | Array of Bdev names to LUN ID mappings 7288queue_depth | Required | number | Target queue depth 7289disable_chap | Optional | boolean | CHAP authentication should be disabled for this target 7290require_chap | Optional | boolean | CHAP authentication should be required for this target 7291mutual_chap | Optional | boolean | CHAP authentication should be bidirectional (`true`) or unidirectional (`false`) 7292chap_group | Optional | number | Authentication group ID for this target node 7293header_digest | Optional | boolean | Header Digest should be required for this target node 7294data_digest | Optional | boolean | Data Digest should be required for this target node 7295 7296Parameters `disable_chap` and `require_chap` are mutually exclusive. 7297 7298#### Example 7299 7300Example request: 7301 7302~~~json 7303{ 7304 "params": { 7305 "luns": [ 7306 { 7307 "lun_id": 0, 7308 "bdev_name": "Nvme0n1" 7309 } 7310 ], 7311 "mutual_chap": true, 7312 "name": "target2", 7313 "alias_name": "iscsi-target2-alias", 7314 "pg_ig_maps": [ 7315 { 7316 "ig_tag": 1, 7317 "pg_tag": 1 7318 }, 7319 { 7320 "ig_tag": 2, 7321 "pg_tag": 2 7322 } 7323 ], 7324 "data_digest": true, 7325 "disable_chap": true, 7326 "header_digest": true, 7327 "queue_depth": 24 7328 }, 7329 "jsonrpc": "2.0", 7330 "method": "iscsi_create_target_node", 7331 "id": 1 7332} 7333~~~ 7334 7335Example response: 7336 7337~~~json 7338{ 7339 "jsonrpc": "2.0", 7340 "id": 1, 7341 "result": true 7342} 7343~~~ 7344 7345### iscsi_target_node_set_auth method {#rpc_iscsi_target_node_set_auth} 7346 7347Set CHAP authentication to an existing iSCSI target node. 7348 7349#### Parameters 7350 7351Name | Optional | Type | Description 7352--------------------------- | -------- | --------| ----------- 7353name | Required | string | Target node name (ASCII) 7354disable_chap | Optional | boolean | CHAP authentication should be disabled for this target 7355require_chap | Optional | boolean | CHAP authentication should be required for this target 7356mutual_chap | Optional | boolean | CHAP authentication should be bidirectional (`true`) or unidirectional (`false`) 7357chap_group | Optional | number | Authentication group ID for this target node 7358 7359Parameters `disable_chap` and `require_chap` are mutually exclusive. 7360 7361#### Example 7362 7363Example request: 7364 7365~~~json 7366{ 7367 "params": { 7368 "chap_group": 1, 7369 "require_chap": true, 7370 "name": "iqn.2016-06.io.spdk:target1", 7371 "mutual_chap": true 7372 }, 7373 "jsonrpc": "2.0", 7374 "method": "iscsi_target_node_set_auth", 7375 "id": 1 7376} 7377~~~ 7378 7379Example response: 7380 7381~~~json 7382{ 7383 "jsonrpc": "2.0", 7384 "id": 1, 7385 "result": true 7386} 7387~~~ 7388 7389### iscsi_target_node_add_pg_ig_maps method {#rpc_iscsi_target_node_add_pg_ig_maps} 7390 7391Add initiator group to portal group mappings to an existing iSCSI target node. 7392 7393#### Parameters 7394 7395Name | Optional | Type | Description 7396--------------------------- | -------- | --------| ----------- 7397name | Required | string | Target node name (ASCII) 7398pg_ig_maps | Required | array | Not empty array of initiator to portal group mappings objects 7399 7400Portal to Initiator group mappings object: 7401 7402Name | Optional | Type | Description 7403--------------------------- | -------- | --------| ----------- 7404ig_tag | Required | number | Existing initiator group tag 7405pg_tag | Required | number | Existing portal group tag 7406 7407#### Example 7408 7409Example request: 7410 7411~~~json 7412{ 7413 "params": { 7414 "pg_ig_maps": [ 7415 { 7416 "ig_tag": 1, 7417 "pg_tag": 1 7418 }, 7419 { 7420 "ig_tag": 2, 7421 "pg_tag": 2 7422 }, 7423 { 7424 "ig_tag": 3, 7425 "pg_tag": 3 7426 } 7427 ], 7428 "name": "iqn.2016-06.io.spdk:target3" 7429 }, 7430 "jsonrpc": "2.0", 7431 "method": "iscsi_target_node_add_pg_ig_maps", 7432 "id": 1 7433} 7434~~~ 7435 7436Example response: 7437 7438~~~json 7439{ 7440 "jsonrpc": "2.0", 7441 "id": 1, 7442 "result": true 7443} 7444~~~ 7445 7446### iscsi_target_node_remove_pg_ig_maps method {#rpc_iscsi_target_node_remove_pg_ig_maps} 7447 7448Delete initiator group to portal group mappings from an existing iSCSI target node. 7449 7450#### Parameters 7451 7452Name | Optional | Type | Description 7453--------------------------- | -------- | --------| ----------- 7454name | Required | string | Target node name (ASCII) 7455pg_ig_maps | Required | array | Not empty array of Portal to Initiator group mappings objects 7456 7457Portal to Initiator group mappings object: 7458 7459Name | Optional | Type | Description 7460--------------------------- | -------- | --------| ----------- 7461ig_tag | Required | number | Existing initiator group tag 7462pg_tag | Required | number | Existing portal group tag 7463 7464#### Example 7465 7466Example request: 7467 7468~~~json 7469{ 7470 "params": { 7471 "pg_ig_maps": [ 7472 { 7473 "ig_tag": 1, 7474 "pg_tag": 1 7475 }, 7476 { 7477 "ig_tag": 2, 7478 "pg_tag": 2 7479 }, 7480 { 7481 "ig_tag": 3, 7482 "pg_tag": 3 7483 } 7484 ], 7485 "name": "iqn.2016-06.io.spdk:target3" 7486 }, 7487 "jsonrpc": "2.0", 7488 "method": "iscsi_target_node_remove_pg_ig_maps", 7489 "id": 1 7490} 7491~~~ 7492 7493Example response: 7494 7495~~~json 7496{ 7497 "jsonrpc": "2.0", 7498 "id": 1, 7499 "result": true 7500} 7501~~~ 7502 7503### iscsi_delete_target_node method {#rpc_iscsi_delete_target_node} 7504 7505Delete an iSCSI target node. 7506 7507#### Parameters 7508 7509Name | Optional | Type | Description 7510--------------------------- | -------- | --------| ----------- 7511name | Required | string | Target node name (ASCII) 7512 7513#### Example 7514 7515Example request: 7516 7517~~~json 7518{ 7519 "params": { 7520 "name": "iqn.2016-06.io.spdk:target1" 7521 }, 7522 "jsonrpc": "2.0", 7523 "method": "iscsi_delete_target_node", 7524 "id": 1 7525} 7526~~~ 7527 7528Example response: 7529 7530~~~json 7531{ 7532 "jsonrpc": "2.0", 7533 "id": 1, 7534 "result": true 7535} 7536~~~ 7537 7538### iscsi_get_portal_groups method {#rpc_iscsi_get_portal_groups} 7539 7540Show information about all available portal groups. 7541 7542#### Parameters 7543 7544This method has no parameters. 7545 7546#### Example 7547 7548Example request: 7549 7550~~~json 7551request: 7552{ 7553 "jsonrpc": "2.0", 7554 "method": "iscsi_get_portal_groups", 7555 "id": 1 7556} 7557~~~ 7558 7559Example response: 7560 7561~~~json 7562{ 7563 "jsonrpc": "2.0", 7564 "id": 1, 7565 "result": [ 7566 { 7567 "portals": [ 7568 { 7569 "host": "127.0.0.1", 7570 "port": "3260" 7571 } 7572 ], 7573 "tag": 1, 7574 "private": false 7575 } 7576 ] 7577} 7578~~~ 7579 7580### iscsi_create_portal_group method {#rpc_iscsi_create_portal_group} 7581 7582Add a portal group. 7583 7584#### Parameters 7585 7586Name | Optional | Type | Description 7587--------------------------- | -------- | --------| ----------- 7588tag | Required | number | Portal group tag 7589portals | Required | array | Not empty array of portals 7590private | Optional | boolean | When true, portals in this group are not returned by a discovery session. Used for login redirection. (default: `false`) 7591wait | Optional | boolean | When true, do not listen on portals until it is started explicitly. (default: `false`) 7592 7593Portal object 7594 7595Name | Optional | Type | Description 7596--------------------------- | -------- | --------| ----------- 7597host | Required | string | Hostname or IP address 7598port | Required | string | Port number 7599 7600#### Example 7601 7602Example request: 7603 7604~~~json 7605{ 7606 "params": { 7607 "portals": [ 7608 { 7609 "host": "127.0.0.1", 7610 "port": "3260" 7611 } 7612 ], 7613 "tag": 1 7614 }, 7615 "jsonrpc": "2.0", 7616 "method": "iscsi_create_portal_group", 7617 "id": 1 7618} 7619~~~ 7620 7621Example response: 7622 7623~~~json 7624{ 7625 "jsonrpc": "2.0", 7626 "id": 1, 7627 "result": true 7628} 7629~~~ 7630 7631### iscsi_start_portal_group method {#rpc_iscsi_start_portal_group} 7632 7633Start listening on portals if the portal group is not started yet, or do nothing 7634if the portal group already started. Return a success response for both cases. 7635 7636#### Parameters 7637 7638Name | Optional | Type | Description 7639--------------------------- | -------- | --------| ----------- 7640tag | Required | number | Existing portal group tag 7641 7642#### Example 7643 7644Example request: 7645 7646~~~json 7647{ 7648 "params": { 7649 "tag": 1 7650 }, 7651 "jsonrpc": "2.0", 7652 "method": "iscsi_start_portal_group", 7653 "id": 1 7654} 7655~~~ 7656 7657Example response: 7658 7659~~~json 7660{ 7661 "jsonrpc": "2.0", 7662 "id": 1, 7663 "result": true 7664} 7665~~~ 7666 7667### iscsi_delete_portal_group method {#rpc_iscsi_delete_portal_group} 7668 7669Delete an existing portal group. 7670 7671#### Parameters 7672 7673Name | Optional | Type | Description 7674--------------------------- | -------- | --------| ----------- 7675tag | Required | number | Existing portal group tag 7676 7677#### Example 7678 7679Example request: 7680 7681~~~json 7682{ 7683 "params": { 7684 "tag": 1 7685 }, 7686 "jsonrpc": "2.0", 7687 "method": "iscsi_delete_portal_group", 7688 "id": 1 7689} 7690~~~ 7691 7692Example response: 7693 7694~~~json 7695{ 7696 "jsonrpc": "2.0", 7697 "id": 1, 7698 "result": true 7699} 7700~~~ 7701 7702### iscsi_portal_group_set_auth method {#rpc_iscsi_portal_group_set_auth} 7703 7704Set CHAP authentication for discovery sessions specific for the existing iSCSI portal group. 7705This RPC overwrites the setting by the global parameters for the iSCSI portal group. 7706 7707#### Parameters 7708 7709Name | Optional | Type | Description 7710--------------------------- | -------- | --------| ----------- 7711disable_chap | Optional | boolean | CHAP for discovery session should be disabled (default: `false`) 7712require_chap | Optional | boolean | CHAP for discovery session should be required (default: `false`) 7713mutual_chap | Optional | boolean | CHAP for discovery session should be unidirectional (`false`) or bidirectional (`true`) (default: `false`) 7714chap_group | Optional | number | CHAP group ID for discovery session (default: 0) 7715 7716Parameters `disable_chap` and `require_chap` are mutually exclusive. 7717 7718#### Example 7719 7720Example request: 7721 7722~~~json 7723request: 7724{ 7725 "params": { 7726 "tag": 1, 7727 "chap_group": 1, 7728 "require_chap": true, 7729 "mutual_chap": true 7730 }, 7731 "jsonrpc": "2.0", 7732 "method": "iscsi_portal_group_set_auth", 7733 "id": 1 7734} 7735~~~ 7736 7737Example response: 7738 7739~~~json 7740{ 7741 "jsonrpc": "2.0", 7742 "id": 1, 7743 "result": true 7744} 7745~~~ 7746 7747### iscsi_get_connections method {#rpc_iscsi_get_connections} 7748 7749Show information about all active connections. 7750 7751#### Parameters 7752 7753This method has no parameters. 7754 7755#### Results 7756 7757Array of objects describing iSCSI connection. 7758 7759Name | Type | Description 7760--------------------------- | --------| ----------- 7761id | number | Index (used for TTT - Target Transfer Tag) 7762cid | number | CID (Connection ID) 7763tsih | number | TSIH (Target Session Identifying Handle) 7764lcore_id | number | Core number on which the iSCSI connection runs 7765initiator_addr | string | Initiator address 7766target_addr | string | Target address 7767target_node_name | string | Target node name (ASCII) without prefix 7768 7769#### Example 7770 7771Example request: 7772 7773~~~json 7774{ 7775 "jsonrpc": "2.0", 7776 "method": "iscsi_get_connections", 7777 "id": 1 7778} 7779~~~ 7780 7781Example response: 7782 7783~~~json 7784{ 7785 "jsonrpc": "2.0", 7786 "id": 1, 7787 "result": [ 7788 { 7789 "tsih": 4, 7790 "cid": 0, 7791 "target_node_name": "target1", 7792 "lcore_id": 0, 7793 "initiator_addr": "10.0.0.2", 7794 "target_addr": "10.0.0.1", 7795 "id": 0 7796 } 7797 ] 7798} 7799~~~ 7800 7801### iscsi_get_stats method {#iscsi_get_stats} 7802 7803Show stat information of iSCSI connections. 7804 7805#### Parameters 7806 7807This method has no parameters. 7808 7809#### Results 7810 7811Stat information of iSCSI connections. 7812 7813Name | Type | Description 7814--------------------------- | --------| ----------- 7815invalid | number | The number of invalid connections 7816running | number | The number of running connections 7817exiting | number | The number of exiting connections 7818exited | number | The number of exited connections 7819 7820#### Example 7821 7822Example request: 7823 7824~~~json 7825{ 7826 "jsonrpc": "2.0", 7827 "method": "iscsi_get_stats", 7828 "id": 1 7829} 7830~~~ 7831 7832Example response: 7833 7834~~~json 7835{ 7836 "jsonrpc": "2.0", 7837 "id": 1, 7838 "result": 7839 { 7840 "invalid": 0, 7841 "running": 5, 7842 "exiting": 0, 7843 "exited": 0 7844 } 7845 7846} 7847~~~ 7848 7849### iscsi_target_node_add_lun method {#rpc_iscsi_target_node_add_lun} 7850 7851Add an LUN to an existing iSCSI target node. 7852 7853#### Parameters 7854 7855Name | Optional | Type | Description 7856--------------------------- | -------- | --------| ----------- 7857name | Required | string | Target node name (ASCII) 7858bdev_name | Required | string | bdev name to be added as a LUN 7859lun_id | Optional | number | LUN ID (default: first free ID) 7860 7861#### Example 7862 7863Example request: 7864 7865~~~json 7866{ 7867 "params": { 7868 "lun_id": 2, 7869 "name": "iqn.2016-06.io.spdk:target1", 7870 "bdev_name": "Malloc0" 7871 }, 7872 "jsonrpc": "2.0", 7873 "method": "iscsi_target_node_add_lun", 7874 "id": 1 7875} 7876~~~ 7877 7878Example response: 7879 7880~~~json 7881{ 7882 "jsonrpc": "2.0", 7883 "id": 1, 7884 "result": true 7885} 7886~~~ 7887 7888### iscsi_target_node_set_redirect method {#rpc_iscsi_target_node_set_redirect} 7889 7890Update redirect portal of the primary portal group for the target node, 7891 7892#### Parameters 7893 7894Name | Optional | Type | Description 7895--------------------------- | -------- | --------| ----------- 7896name | Required | string | Target node name (ASCII) 7897pg_tag | Required | number | Existing portal group tag 7898redirect_host | Optional | string | Numeric IP address to which the target node is redirected 7899redirect_port | Optional | string | Numeric TCP port to which the target node is redirected 7900 7901If both redirect_host and redirect_port are omitted, clear the redirect portal. 7902 7903#### Example 7904 7905Example request: 7906 7907~~~json 7908{ 7909 "params": { 7910 "name": "iqn.2016-06.io.spdk:target1", 7911 "pg_tag": 1, 7912 "redirect_host": "10.0.0.3", 7913 "redirect_port": "3260" 7914 }, 7915 "jsonrpc": "2.0", 7916 "method": "iscsi_target_node_set_redirect", 7917 "id": 1 7918} 7919~~~ 7920 7921Example response: 7922 7923~~~json 7924{ 7925 "jsonrpc": "2.0", 7926 "id": 1, 7927 "result": true 7928} 7929~~~ 7930 7931### iscsi_target_node_request_logout method {#rpc_iscsi_target_node_request_logout} 7932 7933For the target node, request connections whose portal group tag match to logout, 7934or request all connections to logout if portal group tag is omitted. 7935 7936#### Parameters 7937 7938Name | Optional | Type | Description 7939--------------------------- | -------- | --------| ----------- 7940name | Required | string | Target node name (ASCII) 7941pg_tag | Optional | number | Existing portal group tag 7942 7943#### Example 7944 7945Example request: 7946 7947~~~json 7948{ 7949 "params": { 7950 "name": "iqn.2016-06.io.spdk:target1", 7951 "pg_tag": 1 7952 }, 7953 "jsonrpc": "2.0", 7954 "method": "iscsi_target_node_request_logout", 7955 "id": 1 7956} 7957~~~ 7958 7959Example response: 7960 7961~~~json 7962{ 7963 "jsonrpc": "2.0", 7964 "id": 1, 7965 "result": true 7966} 7967~~~ 7968 7969## NVMe-oF Target {#jsonrpc_components_nvmf_tgt} 7970 7971### nvmf_create_transport method {#rpc_nvmf_create_transport} 7972 7973Initialize an NVMe-oF transport with the given options. 7974 7975#### Parameters 7976 7977Name | Optional | Type | Description 7978--------------------------- | -------- | --------| ----------- 7979trtype | Required | string | Transport type (ex. RDMA) 7980tgt_name | Optional | string | Parent NVMe-oF target name. 7981max_queue_depth | Optional | number | Max number of outstanding I/O per queue 7982max_io_qpairs_per_ctrlr | Optional | number | Max number of IO qpairs per controller 7983in_capsule_data_size | Optional | number | Max number of in-capsule data size 7984max_io_size | Optional | number | Max I/O size (bytes) 7985io_unit_size | Optional | number | I/O unit size (bytes) 7986max_aq_depth | Optional | number | Max number of admin cmds per AQ 7987num_shared_buffers | Optional | number | The number of pooled data buffers available to the transport 7988buf_cache_size | Optional | number | The number of shared buffers to reserve for each poll group 7989num_cqe | Optional | number | The number of CQ entries. Only used when no_srq=true (RDMA only) 7990max_srq_depth | Optional | number | The number of elements in a per-thread shared receive queue (RDMA only) 7991no_srq | Optional | boolean | Disable shared receive queue even for devices that support it. (RDMA only) 7992c2h_success | Optional | boolean | Disable C2H success optimization (TCP only) 7993dif_insert_or_strip | Optional | boolean | Enable DIF insert for write I/O and DIF strip for read I/O DIF 7994sock_priority | Optional | number | The socket priority of the connection owned by this transport (TCP only) 7995acceptor_backlog | Optional | number | The number of pending connections allowed in backlog before failing new connection attempts (RDMA only) 7996abort_timeout_sec | Optional | number | Abort execution timeout value, in seconds 7997no_wr_batching | Optional | boolean | Disable work requests batching (RDMA only) 7998control_msg_num | Optional | number | The number of control messages per poll group (TCP only) 7999disable_mappable_bar0 | Optional | boolean | disable client mmap() of BAR0 (VFIO-USER only) 8000disable_adaptive_irq | Optional | boolean | Disable adaptive interrupt feature (VFIO-USER only) 8001disable_shadow_doorbells | Optional | boolean | disable shadow doorbell support (VFIO-USER only) 8002zcopy | Optional | boolean | Use zero-copy operations if the underlying bdev supports them 8003 8004#### Example 8005 8006Example request: 8007 8008~~~json 8009{ 8010 "jsonrpc": "2.0", 8011 "method": "nvmf_create_transport", 8012 "id": 1, 8013 "params": { 8014 "trtype": "RDMA", 8015 "max_queue_depth": 32 8016 } 8017} 8018~~~ 8019 8020Example response: 8021 8022~~~json 8023{ 8024 "jsonrpc": "2.0", 8025 "id": 1, 8026 "result": true 8027} 8028~~~ 8029 8030### nvmf_get_subsystems method {#rpc_nvmf_get_subsystems} 8031 8032#### Parameters 8033 8034Name | Optional | Type | Description 8035--------------------------- | -------- | ------------| ----------- 8036tgt_name | Optional | string | Parent NVMe-oF target name. 8037 8038#### Example 8039 8040Example request: 8041 8042~~~json 8043{ 8044 "jsonrpc": "2.0", 8045 "id": 1, 8046 "method": "nvmf_get_subsystems" 8047} 8048~~~ 8049 8050Example response: 8051 8052~~~json 8053{ 8054 "jsonrpc": "2.0", 8055 "id": 1, 8056 "result": [ 8057 { 8058 "nqn": "nqn.2014-08.org.nvmexpress.discovery", 8059 "subtype": "Discovery" 8060 "listen_addresses": [], 8061 "hosts": [], 8062 "allow_any_host": true 8063 }, 8064 { 8065 "nqn": "nqn.2016-06.io.spdk:cnode1", 8066 "subtype": "NVMe", 8067 "listen_addresses": [ 8068 { 8069 "trtype": "RDMA", 8070 "adrfam": "IPv4", 8071 "traddr": "192.168.0.123", 8072 "trsvcid": "4420" 8073 } 8074 ], 8075 "hosts": [ 8076 {"nqn": "nqn.2016-06.io.spdk:host1"} 8077 ], 8078 "allow_any_host": false, 8079 "serial_number": "abcdef", 8080 "model_number": "ghijklmnop", 8081 "namespaces": [ 8082 {"nsid": 1, "name": "Malloc2"}, 8083 {"nsid": 2, "name": "Nvme0n1"} 8084 ] 8085 } 8086 ] 8087} 8088~~~ 8089 8090### nvmf_create_subsystem method {#rpc_nvmf_create_subsystem} 8091 8092Construct an NVMe over Fabrics target subsystem. 8093 8094#### Parameters 8095 8096Name | Optional | Type | Description 8097-------------------------- | -------- | ----------- | ----------- 8098nqn | Required | string | Subsystem NQN 8099tgt_name | Optional | string | Parent NVMe-oF target name. 8100serial_number | Optional | string | Serial number of virtual controller 8101model_number | Optional | string | Model number of virtual controller 8102max_namespaces | Optional | number | Maximum number of namespaces that can be attached to the subsystem. Default: 32 (also used if user specifies 0) 8103allow_any_host | Optional | boolean | Allow any host (`true`) or enforce allowed host list (`false`). Default: `false`. 8104ana_reporting | Optional | boolean | Enable ANA reporting feature (default: `false`). 8105min_cntlid | Optional | number | Minimum controller ID. Default: 1 8106max_cntlid | Optional | number | Maximum controller ID. Default: 0xffef 8107max_discard_size_kib | Optional | number | Maximum discard size (Kib). Default: 0 8108max_write_zeroes_size_kib | Optional | number | Maximum write_zeroes size (Kib). Default: 0 8109 8110#### Example 8111 8112Example request: 8113 8114~~~json 8115{ 8116 "jsonrpc": "2.0", 8117 "id": 1, 8118 "method": "nvmf_create_subsystem", 8119 "params": { 8120 "nqn": "nqn.2016-06.io.spdk:cnode1", 8121 "allow_any_host": false, 8122 "serial_number": "abcdef", 8123 "model_number": "ghijklmnop" 8124 } 8125} 8126~~~ 8127 8128Example response: 8129 8130~~~json 8131{ 8132 "jsonrpc": "2.0", 8133 "id": 1, 8134 "result": true 8135} 8136~~~ 8137 8138### nvmf_delete_subsystem method {#rpc_nvmf_delete_subsystem} 8139 8140Delete an existing NVMe-oF subsystem. 8141 8142#### Parameters 8143 8144Parameter | Optional | Type | Description 8145---------------------- | -------- | ----------- | ----------- 8146nqn | Required | string | Subsystem NQN to delete. 8147tgt_name | Optional | string | Parent NVMe-oF target name. 8148 8149#### Example 8150 8151Example request: 8152 8153~~~json 8154{ 8155 "jsonrpc": "2.0", 8156 "id": 1, 8157 "method": "nvmf_delete_subsystem", 8158 "params": { 8159 "nqn": "nqn.2016-06.io.spdk:cnode1" 8160 } 8161} 8162~~~ 8163 8164Example response: 8165 8166~~~json 8167{ 8168 "jsonrpc": "2.0", 8169 "id": 1, 8170 "result": true 8171} 8172~~~ 8173 8174### nvmf_subsystem_add_listener method {#rpc_nvmf_subsystem_add_listener} 8175 8176Add a new listen address to an NVMe-oF subsystem. 8177 8178#### Parameters 8179 8180Name | Optional | Type | Description 8181----------------------- | -------- | ----------- | ----------- 8182nqn | Required | string | Subsystem NQN 8183tgt_name | Optional | string | Parent NVMe-oF target name. 8184listen_address | Required | object | @ref rpc_nvmf_listen_address object 8185secure_channel | Optional | bool | Whether all connections immediately attempt to establish a secure channel 8186 8187#### listen_address {#rpc_nvmf_listen_address} 8188 8189The listen_address is used for adding the listeners to the NVMe-oF target 8190and for referring to discovery services on other targets. 8191 8192Name | Optional | Type | Description 8193----------------------- | -------- | ----------- | ----------- 8194trtype | Required | string | Transport type ("RDMA") 8195adrfam | Required | string | Address family ("IPv4", "IPv6", "IB", or "FC") 8196traddr | Required | string | Transport address 8197trsvcid | Optional | string | Transport service ID (required for RDMA or TCP) 8198 8199#### Example 8200 8201Example request: 8202 8203~~~json 8204{ 8205 "jsonrpc": "2.0", 8206 "id": 1, 8207 "method": "nvmf_subsystem_add_listener", 8208 "params": { 8209 "nqn": "nqn.2016-06.io.spdk:cnode1", 8210 "listen_address": { 8211 "trtype": "RDMA", 8212 "adrfam": "IPv4", 8213 "traddr": "192.168.0.123", 8214 "trsvcid": "4420" 8215 } 8216 } 8217} 8218~~~ 8219 8220Example response: 8221 8222~~~json 8223{ 8224 "jsonrpc": "2.0", 8225 "id": 1, 8226 "result": true 8227} 8228~~~ 8229 8230### nvmf_subsystem_remove_listener method {#rpc_nvmf_subsystem_remove_listener} 8231 8232Remove a listen address from an NVMe-oF subsystem. 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 8241 8242#### Example 8243 8244Example request: 8245 8246~~~json 8247{ 8248 "jsonrpc": "2.0", 8249 "id": 1, 8250 "method": "nvmf_subsystem_remove_listener", 8251 "params": { 8252 "nqn": "nqn.2016-06.io.spdk:cnode1", 8253 "listen_address": { 8254 "trtype": "RDMA", 8255 "adrfam": "IPv4", 8256 "traddr": "192.168.0.123", 8257 "trsvcid": "4420" 8258 } 8259 } 8260} 8261~~~ 8262 8263Example response: 8264 8265~~~json 8266{ 8267 "jsonrpc": "2.0", 8268 "id": 1, 8269 "result": true 8270} 8271~~~ 8272 8273### nvmf_subsystem_listener_set_ana_state method {#rpc_nvmf_subsystem_listener_set_ana_state} 8274 8275Set ANA state of a listener for an NVMe-oF subsystem. Only the ANA state of the specified ANA 8276group is updated, or ANA states of all ANA groups if ANA group is not specified. 8277 8278#### Parameters 8279 8280Name | Optional | Type | Description 8281----------------------- | -------- | ----------- | ----------- 8282nqn | Required | string | Subsystem NQN 8283tgt_name | Optional | string | Parent NVMe-oF target name. 8284listen_address | Required | object | @ref rpc_nvmf_listen_address object 8285ana_state | Required | string | ANA state to set ("optimized", "non_optimized", or "inaccessible") 8286anagrpid | Optional | number | ANA group ID 8287 8288#### Example 8289 8290Example request: 8291 8292~~~json 8293{ 8294 "jsonrpc": "2.0", 8295 "id": 1, 8296 "method": "nvmf_subsystem_listener_set_ana_state", 8297 "params": { 8298 "nqn": "nqn.2016-06.io.spdk:cnode1", 8299 "listen_address": { 8300 "trtype": "RDMA", 8301 "adrfam": "IPv4", 8302 "traddr": "192.168.0.123", 8303 "trsvcid": "4420" 8304 }, 8305 "ana_state", "inaccessible" 8306 } 8307} 8308~~~ 8309 8310Example response: 8311 8312~~~json 8313{ 8314 "jsonrpc": "2.0", 8315 "id": 1, 8316 "result": true 8317} 8318~~~ 8319 8320### nvmf_subsystem_add_ns method {#rpc_nvmf_subsystem_add_ns} 8321 8322Add a namespace to a subsystem. The namespace ID is returned as the result. 8323 8324### Parameters 8325 8326Name | Optional | Type | Description 8327----------------------- | -------- | ----------- | ----------- 8328nqn | Required | string | Subsystem NQN 8329namespace | Required | object | @ref rpc_nvmf_namespace object 8330tgt_name | Optional | string | Parent NVMe-oF target name. 8331 8332#### namespace {#rpc_nvmf_namespace} 8333 8334Name | Optional | Type | Description 8335----------------------- | -------- | ----------- | ----------- 8336nsid | Optional | number | Namespace ID between 1 and 4294967294, inclusive. Default: Automatically assign NSID. 8337bdev_name | Required | string | Name of bdev to expose as a namespace. 8338nguid | Optional | string | 16-byte namespace globally unique identifier in hexadecimal (e.g. "ABCDEF0123456789ABCDEF0123456789") 8339eui64 | Optional | string | 8-byte namespace EUI-64 in hexadecimal (e.g. "ABCDEF0123456789") 8340uuid | Optional | string | RFC 4122 UUID (e.g. "ceccf520-691e-4b46-9546-34af789907c5") 8341ptpl_file | Optional | string | File path to save/restore persistent reservation information 8342anagrpid | Optional | number | ANA group ID. Default: Namespace ID. 8343 8344#### Example 8345 8346Example request: 8347 8348~~~json 8349{ 8350 "jsonrpc": "2.0", 8351 "id": 1, 8352 "method": "nvmf_subsystem_add_ns", 8353 "params": { 8354 "nqn": "nqn.2016-06.io.spdk:cnode1", 8355 "namespace": { 8356 "nsid": 3, 8357 "bdev_name": "Nvme0n1", 8358 "ptpl_file": "/opt/Nvme0n1PR.json" 8359 } 8360 } 8361} 8362~~~ 8363 8364Example response: 8365 8366~~~json 8367{ 8368 "jsonrpc": "2.0", 8369 "id": 1, 8370 "result": 3 8371} 8372~~~ 8373 8374### nvmf_subsystem_remove_ns method {#rpc_nvmf_subsystem_remove_ns} 8375 8376Remove a namespace from a subsystem. 8377 8378#### Parameters 8379 8380Name | Optional | Type | Description 8381----------------------- | -------- | ----------- | ----------- 8382nqn | Required | string | Subsystem NQN 8383nsid | Required | number | Namespace ID 8384tgt_name | Optional | string | Parent NVMe-oF target name. 8385 8386#### Example 8387 8388Example request: 8389 8390~~~json 8391{ 8392 "jsonrpc": "2.0", 8393 "id": 1, 8394 "method": "nvmf_subsystem_remove_ns", 8395 "params": { 8396 "nqn": "nqn.2016-06.io.spdk:cnode1", 8397 "nsid": 1 8398 } 8399} 8400~~~ 8401 8402Example response: 8403 8404~~~json 8405{ 8406 "jsonrpc": "2.0", 8407 "id": 1, 8408 "result": true 8409} 8410~~~ 8411 8412### nvmf_subsystem_add_host method {#rpc_nvmf_subsystem_add_host} 8413 8414Add a host NQN to the list of allowed hosts. 8415 8416#### Parameters 8417 8418Name | Optional | Type | Description 8419----------------------- | -------- | ----------- | ----------- 8420nqn | Required | string | Subsystem NQN 8421host | Required | string | Host NQN to add to the list of allowed host NQNs 8422tgt_name | Optional | string | Parent NVMe-oF target name. 8423psk | Optional | string | Path to a file containing PSK for TLS connection 8424 8425#### Example 8426 8427Example request: 8428 8429~~~json 8430{ 8431 "jsonrpc": "2.0", 8432 "id": 1, 8433 "method": "nvmf_subsystem_add_host", 8434 "params": { 8435 "nqn": "nqn.2016-06.io.spdk:cnode1", 8436 "host": "nqn.2016-06.io.spdk:host1" 8437 } 8438} 8439~~~ 8440 8441Example response: 8442 8443~~~json 8444{ 8445 "jsonrpc": "2.0", 8446 "id": 1, 8447 "result": true 8448} 8449~~~ 8450 8451### nvmf_subsystem_remove_host method {#rpc_nvmf_subsystem_remove_host} 8452 8453Remove a host NQN from the list of allowed hosts. 8454 8455#### Parameters 8456 8457Name | Optional | Type | Description 8458----------------------- | -------- | ----------- | ----------- 8459nqn | Required | string | Subsystem NQN 8460host | Required | string | Host NQN to remove from the list of allowed host NQNs 8461tgt_name | Optional | string | Parent NVMe-oF target name. 8462 8463#### Example 8464 8465Example request: 8466 8467~~~json 8468{ 8469 "jsonrpc": "2.0", 8470 "id": 1, 8471 "method": "nvmf_subsystem_remove_host", 8472 "params": { 8473 "nqn": "nqn.2016-06.io.spdk:cnode1", 8474 "host": "nqn.2016-06.io.spdk:host1" 8475 } 8476} 8477~~~ 8478 8479Example response: 8480 8481~~~json 8482{ 8483 "jsonrpc": "2.0", 8484 "id": 1, 8485 "result": true 8486} 8487~~~ 8488 8489### nvmf_subsystem_allow_any_host method {#rpc_nvmf_subsystem_allow_any_host} 8490 8491Configure a subsystem to allow any host to connect or to enforce the host NQN list. 8492 8493#### Parameters 8494 8495Name | Optional | Type | Description 8496----------------------- | -------- | ----------- | ----------- 8497nqn | Required | string | Subsystem NQN 8498allow_any_host | Required | boolean | Allow any host (`true`) or enforce allowed host list (`false`). 8499tgt_name | Optional | string | Parent NVMe-oF target name. 8500 8501#### Example 8502 8503Example request: 8504 8505~~~json 8506{ 8507 "jsonrpc": "2.0", 8508 "id": 1, 8509 "method": "nvmf_subsystem_allow_any_host", 8510 "params": { 8511 "nqn": "nqn.2016-06.io.spdk:cnode1", 8512 "allow_any_host": true 8513 } 8514} 8515~~~ 8516 8517Example response: 8518 8519~~~json 8520{ 8521 "jsonrpc": "2.0", 8522 "id": 1, 8523 "result": true 8524} 8525~~~ 8526 8527### nvmf_subsystem_get_controllers {#rpc_nvmf_subsystem_get_controllers} 8528 8529#### Parameters 8530 8531Name | Optional | Type | Description 8532----------------------- | -------- | ----------- | ----------- 8533nqn | Required | string | Subsystem NQN 8534tgt_name | Optional | string | Parent NVMe-oF target name. 8535 8536#### Example 8537 8538Example request: 8539 8540~~~json 8541{ 8542 "jsonrpc": "2.0", 8543 "id": 1, 8544 "method": "nvmf_subsystem_get_controllers", 8545 "params": { 8546 "nqn": "nqn.2016-06.io.spdk:cnode1" 8547 } 8548} 8549~~~ 8550 8551Example response: 8552 8553~~~json 8554{ 8555 "jsonrpc": "2.0", 8556 "id": 1, 8557 "result": [ 8558 { 8559 "cntlid": 1, 8560 "hostnqn": "nqn.2016-06.io.spdk:host1", 8561 "hostid": "27dad528-6368-41c3-82d3-0b956b49025d", 8562 "num_io_qpairs": 5 8563 } 8564 ] 8565} 8566~~~ 8567 8568### nvmf_subsystem_get_qpairs {#rpc_nvmf_subsystem_get_qpairs} 8569 8570#### Parameters 8571 8572Name | Optional | Type | Description 8573----------------------- | -------- | ----------- | ----------- 8574nqn | Required | string | Subsystem NQN 8575tgt_name | Optional | string | Parent NVMe-oF target name. 8576 8577#### Example 8578 8579Example request: 8580 8581~~~json 8582{ 8583 "jsonrpc": "2.0", 8584 "id": 1, 8585 "method": "nvmf_subsystem_get_qpairs", 8586 "params": { 8587 "nqn": "nqn.2016-06.io.spdk:cnode1" 8588 } 8589} 8590~~~ 8591 8592Example response: 8593 8594~~~json 8595{ 8596 "jsonrpc": "2.0", 8597 "id": 1, 8598 "result": [ 8599 { 8600 "cntlid": 1, 8601 "qid": 0, 8602 "state": "active", 8603 "listen_address": { 8604 "trtype": "RDMA", 8605 "adrfam": "IPv4", 8606 "traddr": "192.168.0.123", 8607 "trsvcid": "4420" 8608 } 8609 }, 8610 { 8611 "cntlid": 1, 8612 "qid": 1, 8613 "state": "active", 8614 "listen_address": { 8615 "trtype": "RDMA", 8616 "adrfam": "IPv4", 8617 "traddr": "192.168.0.123", 8618 "trsvcid": "4420" 8619 } 8620 } 8621 ] 8622} 8623~~~ 8624 8625### nvmf_subsystem_get_listeners {#rpc_nvmf_subsystem_get_listeners} 8626 8627#### Parameters 8628 8629Name | Optional | Type | Description 8630----------------------- | -------- | ----------- | ----------- 8631nqn | Required | string | Subsystem NQN 8632tgt_name | Optional | string | Parent NVMe-oF target name. 8633 8634#### Example 8635 8636Example request: 8637 8638~~~json 8639{ 8640 "jsonrpc": "2.0", 8641 "id": 1, 8642 "method": "nvmf_subsystem_get_listeners", 8643 "params": { 8644 "nqn": "nqn.2016-06.io.spdk:cnode1" 8645 } 8646} 8647~~~ 8648 8649Example response: 8650 8651~~~json 8652{ 8653 "jsonrpc": "2.0", 8654 "id": 1, 8655 "result": [ 8656 { 8657 "address": { 8658 "trtype": "RDMA", 8659 "adrfam": "IPv4", 8660 "traddr": "192.168.0.123", 8661 "trsvcid": "4420" 8662 }, 8663 "ana_state": "optimized" 8664 } 8665 ] 8666} 8667~~~ 8668 8669### nvmf_set_max_subsystems {#rpc_nvmf_set_max_subsystems} 8670 8671Set the maximum allowed subsystems for the NVMe-oF target. This RPC may only be called 8672before SPDK subsystems have been initialized. 8673 8674#### Parameters 8675 8676Name | Optional | Type | Description 8677----------------------- | -------- | ----------- | ----------- 8678max_subsystems | Required | number | Maximum number of NVMe-oF subsystems 8679 8680#### Example 8681 8682Example request: 8683 8684~~~json 8685{ 8686 "jsonrpc": "2.0", 8687 "id": 1, 8688 "method": "nvmf_set_max_subsystems", 8689 "params": { 8690 "max_subsystems": 1024 8691 } 8692} 8693~~~ 8694 8695Example response: 8696 8697~~~json 8698{ 8699 "jsonrpc": "2.0", 8700 "id": 1, 8701 "result": true 8702} 8703~~~ 8704 8705### nvmf_discovery_add_referral method {#rpc_nvmf_discovery_add_referral} 8706 8707Add a discovery service referral to an NVMe-oF target. If a referral with the given 8708parameters already exists, no action will be taken. 8709 8710#### Parameters 8711 8712Name | Optional | Type | Description 8713----------------------- | -------- | ----------- | ----------- 8714tgt_name | Optional | string | Parent NVMe-oF target name. 8715address | Required | object | @ref rpc_nvmf_listen_address object 8716secure_channel | Optional | bool | The connection to that discovery subsystem requires a secure channel 8717 8718#### Example 8719 8720Example request: 8721 8722~~~json 8723{ 8724 "jsonrpc": "2.0", 8725 "id": 1, 8726 "method": "nvmf_discovery_add_referral", 8727 "params": { 8728 "address": { 8729 "trtype": "RDMA", 8730 "adrfam": "IPv4", 8731 "traddr": "192.168.0.123", 8732 "trsvcid": "4420" 8733 } 8734 } 8735} 8736~~~ 8737 8738Example response: 8739 8740~~~json 8741{ 8742 "jsonrpc": "2.0", 8743 "id": 1, 8744 "result": true 8745} 8746~~~ 8747 8748### nvmf_discovery_remove_referral method {#rpc_nvmf_discovery_remove_referral} 8749 8750Remove a discovery service referral from an NVMe-oF target. 8751 8752#### Parameters 8753 8754Name | Optional | Type | Description 8755----------------------- | -------- | ----------- | ----------- 8756tgt_name | Optional | string | Parent NVMe-oF target name. 8757address | Required | object | @ref rpc_nvmf_listen_address object 8758 8759#### Example 8760 8761Example request: 8762 8763~~~json 8764{ 8765 "jsonrpc": "2.0", 8766 "id": 1, 8767 "method": "nvmf_discovery_remove_referral", 8768 "params": { 8769 "address": { 8770 "trtype": "RDMA", 8771 "adrfam": "IPv4", 8772 "traddr": "192.168.0.123", 8773 "trsvcid": "4420" 8774 } 8775 } 8776} 8777~~~ 8778 8779Example response: 8780 8781~~~json 8782{ 8783 "jsonrpc": "2.0", 8784 "id": 1, 8785 "result": true 8786} 8787~~~ 8788 8789### nvmf_discovery_get_referrals {#rpc_nvmf_discovery_get_referrals} 8790 8791#### Parameters 8792 8793Name | Optional | Type | Description 8794----------------------- | -------- | ----------- | ----------- 8795tgt_name | Optional | string | Parent NVMe-oF target name. 8796 8797#### Example 8798 8799Example request: 8800 8801~~~json 8802{ 8803 "jsonrpc": "2.0", 8804 "id": 1, 8805 "method": "nvmf_discovery_get_referrals" 8806} 8807~~~ 8808 8809Example response: 8810 8811~~~json 8812{ 8813 "jsonrpc": "2.0", 8814 "id": 1, 8815 "result": [ 8816 { 8817 "address": { 8818 "trtype": "RDMA", 8819 "adrfam": "IPv4", 8820 "traddr": "192.168.0.123", 8821 "trsvcid": "4420" 8822 } 8823 } 8824 ] 8825} 8826~~~ 8827 8828### nvmf_set_config {#rpc_nvmf_set_config} 8829 8830Set global configuration of NVMe-oF target. This RPC may only be called before SPDK subsystems 8831have been initialized. 8832 8833#### Parameters 8834 8835Name | Optional | Type | Description 8836----------------------- | -------- | ----------- | ----------- 8837acceptor_poll_rate | Optional | number | Polling interval of the acceptor for incoming connections (microseconds) 8838admin_cmd_passthru | Optional | object | Admin command passthru configuration 8839poll_groups_mask | Optional | string | Set cpumask for NVMf poll groups 8840discovery_filter | Optional | string | Set discovery filter, possible values are: `match_any` (default) or comma separated values: `transport`, `address`, `svcid` 8841 8842#### admin_cmd_passthru {#spdk_nvmf_admin_passthru_conf} 8843 8844Name | Optional | Type | Description 8845----------------------- | -------- | ----------- | ----------- 8846identify_ctrlr | Required | bool | If true, enables custom identify handler that reports some identify attributes from the underlying NVMe drive 8847 8848#### Example 8849 8850Example request: 8851 8852~~~json 8853{ 8854 "jsonrpc": "2.0", 8855 "id": 1, 8856 "method": "nvmf_set_config", 8857 "params": { 8858 "acceptor_poll_rate": 10000 8859 } 8860} 8861~~~ 8862 8863Example response: 8864 8865~~~json 8866{ 8867 "jsonrpc": "2.0", 8868 "id": 1, 8869 "result": true 8870} 8871~~~ 8872 8873### nvmf_get_transports method {#rpc_nvmf_get_transports} 8874 8875#### Parameters 8876 8877The user may specify no parameters in order to list all transports, or a transport may be 8878specified by type. 8879 8880Name | Optional | Type | Description 8881--------------------------- | -------- | ------------| ----------- 8882tgt_name | Optional | string | Parent NVMe-oF target name. 8883trtype | Optional | string | Transport type. 8884 8885#### Example 8886 8887Example request: 8888 8889~~~json 8890{ 8891 "jsonrpc": "2.0", 8892 "id": 1, 8893 "method": "nvmf_get_transports" 8894} 8895~~~ 8896 8897Example response: 8898 8899~~~json 8900{ 8901 "jsonrpc": "2.0", 8902 "id": 1, 8903 "result": [ 8904 { 8905 "type": "RDMA". 8906 "max_queue_depth": 128, 8907 "max_io_qpairs_per_ctrlr": 64, 8908 "in_capsule_data_size": 4096, 8909 "max_io_size": 131072, 8910 "io_unit_size": 131072, 8911 "abort_timeout_sec": 1 8912 } 8913 ] 8914} 8915~~~ 8916 8917### nvmf_get_stats method {#rpc_nvmf_get_stats} 8918 8919Retrieve current statistics of the NVMf subsystem. 8920 8921#### Parameters 8922 8923Name | Optional | Type | Description 8924--------------------------- | -------- | ------------| ----------- 8925tgt_name | Optional | string | Parent NVMe-oF target name. 8926 8927#### Response 8928 8929The response is an object containing NVMf subsystem statistics. 8930In the response, `admin_qpairs` and `io_qpairs` are reflecting cumulative queue pair counts while 8931`current_admin_qpairs` and `current_io_qpairs` are showing the current number. 8932 8933#### Example 8934 8935Example request: 8936 8937~~~json 8938{ 8939 "jsonrpc": "2.0", 8940 "method": "nvmf_get_stats", 8941 "id": 1 8942} 8943~~~ 8944 8945Example response: 8946 8947~~~json 8948{ 8949 "jsonrpc": "2.0", 8950 "id": 1, 8951 "result": { 8952 "tick_rate": 2400000000, 8953 "poll_groups": [ 8954 { 8955 "name": "app_thread", 8956 "admin_qpairs": 1, 8957 "io_qpairs": 4, 8958 "current_admin_qpairs": 1, 8959 "current_io_qpairs": 2, 8960 "pending_bdev_io": 1721, 8961 "transports": [ 8962 { 8963 "trtype": "RDMA", 8964 "pending_data_buffer": 12131888, 8965 "devices": [ 8966 { 8967 "name": "mlx5_1", 8968 "polls": 72284105, 8969 "completions": 0, 8970 "requests": 0, 8971 "request_latency": 0, 8972 "pending_free_request": 0, 8973 "pending_rdma_read": 0, 8974 "pending_rdma_write": 0, 8975 "total_send_wrs": 0, 8976 "send_doorbell_updates": 0, 8977 "total_recv_wrs": 0, 8978 "recv_doorbell_updates": 1 8979 }, 8980 { 8981 "name": "mlx5_0", 8982 "polls": 72284105, 8983 "completions": 15165875, 8984 "requests": 7582935, 8985 "request_latency": 1249323766184, 8986 "pending_free_request": 0, 8987 "pending_rdma_read": 337602, 8988 "pending_rdma_write": 0, 8989 "total_send_wrs": 15165875, 8990 "send_doorbell_updates": 1516587, 8991 "total_recv_wrs": 15165875, 8992 "recv_doorbell_updates": 1516587 8993 } 8994 ] 8995 } 8996 ] 8997 } 8998 ] 8999 } 9000} 9001~~~ 9002 9003### nvmf_set_crdt {#rpc_nvmf_set_crdt} 9004 9005Set the 3 CRDT (Command Retry Delay Time) values. For details about 9006CRDT, please refer to the NVMe specification. Currently all the 9007SPDK nvmf subsystems share the same CRDT values. The default values 9008are 0. This rpc can only be invoked in STARTUP stage. All values are 9009in units of 100 milliseconds (same as the NVMe specification). 9010 9011#### Parameters 9012 9013Name | Optional | Type | Description 9014----------------------- | -------- | ----------- | ----------- 9015crdt1 | Optional | number | Command Retry Delay Time 1 9016crdt2 | Optional | number | Command Retry Delay Time 2 9017crdt3 | Optional | number | Command Retry Delay Time 3 9018 9019## Vfio-user Target 9020 9021### vfu_tgt_set_base_path {#rpc_vfu_tgt_set_base_path} 9022 9023Set base path of Unix Domain socket file. 9024 9025#### Parameters 9026 9027Name | Optional | Type | Description 9028----------------------- | -------- | ----------- | ----------- 9029path | Required | string | Base path 9030 9031#### Example 9032 9033Example request: 9034 9035~~~json 9036{ 9037 "params": { 9038 "path": "/var/run/vfu_tgt" 9039 }, 9040 "jsonrpc": "2.0", 9041 "method": "vfu_tgt_set_base_path", 9042 "id": 1 9043} 9044~~~ 9045 9046Example response: 9047 9048~~~json 9049{ 9050 "jsonrpc": "2.0", 9051 "id": 1, 9052 "result": true 9053} 9054~~~ 9055 9056### vfu_virtio_delete_endpoint {#rpc_vfu_virtio_delete_endpoint} 9057 9058Delete PCI device via endpoint name. 9059 9060#### Parameters 9061 9062Name | Optional | Type | Description 9063----------------------- | -------- | ----------- | ----------- 9064name | Required | string | Endpoint name 9065 9066#### Example 9067 9068Example request: 9069 9070~~~json 9071{ 9072 "params": { 9073 "name": "vfu.0" 9074 }, 9075 "jsonrpc": "2.0", 9076 "method": "vfu_virtio_delete_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_create_blk_endpoint {#rpc_vfu_virtio_create_blk_endpoint} 9092 9093Create vfio-user virtio-blk PCI endpoint. 9094 9095#### Parameters 9096 9097Name | Optional | Type | Description 9098----------------------- | -------- | ----------- | ----------- 9099name | Required | string | Endpoint name 9100bdev_name | Required | string | Block device name 9101cpumask | Optional | string | CPU masks 9102num_queues | Optional | number | Number of queues 9103qsize | Optional | number | Queue size 9104packed_ring | Optional | boolean | Enable packed ring 9105 9106#### Example 9107 9108Example request: 9109 9110~~~json 9111{ 9112 "params": { 9113 "name": "vfu.0", 9114 "bdev_name": "Malloc0", 9115 "cpumask": "0x2", 9116 "num_queues": 4, 9117 "qsize": 256 9118 }, 9119 "jsonrpc": "2.0", 9120 "method": "vfu_virtio_create_blk_endpoint", 9121 "id": 1 9122} 9123~~~ 9124 9125Example response: 9126 9127~~~json 9128{ 9129 "jsonrpc": "2.0", 9130 "id": 1, 9131 "result": true 9132} 9133~~~ 9134 9135### vfu_virtio_scsi_add_target {#rpc_vfu_virtio_scsi_add_target} 9136 9137Add block device to specified SCSI target of vfio-user virtio-scsi PCI endpoint. 9138 9139#### Parameters 9140 9141Name | Optional | Type | Description 9142----------------------- | -------- | ----------- | ----------- 9143name | Required | string | Endpoint name 9144scsi_target_num | Required | number | SCSI target number 9145bdev_name | Required | string | Block device name 9146 9147#### Example 9148 9149Example request: 9150 9151~~~json 9152{ 9153 "params": { 9154 "name": "vfu.0", 9155 "scsi_target_num": 0, 9156 "bdev_name": "Malloc0" 9157 }, 9158 "jsonrpc": "2.0", 9159 "method": "vfu_virtio_scsi_add_target", 9160 "id": 1 9161} 9162~~~ 9163 9164Example response: 9165 9166~~~json 9167{ 9168 "jsonrpc": "2.0", 9169 "id": 1, 9170 "result": true 9171} 9172~~~ 9173 9174### vfu_virtio_scsi_remove_target {#rpc_vfu_virtio_scsi_remove_target} 9175 9176Remove a SCSI target of vfio-user virtio-scsi PCI endpoint. 9177 9178#### Parameters 9179 9180Name | Optional | Type | Description 9181----------------------- | -------- | ----------- | ----------- 9182name | Required | string | Endpoint name 9183scsi_target_num | Required | number | SCSI target number 9184 9185#### Example 9186 9187Example request: 9188 9189~~~json 9190{ 9191 "params": { 9192 "name": "vfu.0", 9193 "scsi_target_num": 0 9194 }, 9195 "jsonrpc": "2.0", 9196 "method": "vfu_virtio_scsi_remove_target", 9197 "id": 1 9198} 9199~~~ 9200 9201Example response: 9202 9203~~~json 9204{ 9205 "jsonrpc": "2.0", 9206 "id": 1, 9207 "result": true 9208} 9209~~~ 9210 9211### vfu_virtio_create_scsi_endpoint {#rpc_vfu_virtio_create_scsi_endpoint} 9212 9213Create vfio-user virtio-scsi PCI endpoint. 9214 9215#### Parameters 9216 9217Name | Optional | Type | Description 9218----------------------- | -------- | ----------- | ----------- 9219name | Required | string | Endpoint name 9220cpumask | Optional | string | CPU masks 9221num_io_queues | Optional | number | Number of IO queues 9222qsize | Optional | number | Queue size 9223packed_ring | Optional | boolean | Enable packed ring 9224 9225#### Example 9226 9227Example request: 9228 9229~~~json 9230{ 9231 "params": { 9232 "name": "vfu.0", 9233 "cpumask": "0x2", 9234 "num_io_queues": 4, 9235 "qsize": 256 9236 }, 9237 "jsonrpc": "2.0", 9238 "method": "vfu_virtio_create_scsi_endpoint", 9239 "id": 1 9240} 9241~~~ 9242 9243Example response: 9244 9245~~~json 9246{ 9247 "jsonrpc": "2.0", 9248 "id": 1, 9249 "result": true 9250} 9251~~~ 9252 9253## Vhost Target {#jsonrpc_components_vhost_tgt} 9254 9255The following common preconditions need to be met in all target types. 9256 9257Controller name will be used to create UNIX domain socket. This implies that name concatenated with vhost socket 9258directory path needs to be valid UNIX socket name. 9259 9260@ref cpu_mask parameter is used to choose CPU on which pollers will be launched when new initiator is connecting. 9261It must be a subset of application CPU mask. Default value is CPU mask of the application. 9262 9263### vhost_controller_set_coalescing {#rpc_vhost_controller_set_coalescing} 9264 9265Controls interrupt coalescing for specific target. Because `delay_base_us` is used to calculate delay in CPU ticks 9266there is no hardcoded limit for this parameter. Only limitation is that final delay in CPU ticks might not overflow 926732 bit unsigned integer (which is more than 1s @ 4GHz CPU). In real scenarios `delay_base_us` should be much lower 9268than 150us. To disable coalescing set `delay_base_us` to 0. 9269 9270#### Parameters 9271 9272Name | Optional | Type | Description 9273----------------------- | -------- | ----------- | ----------- 9274ctrlr | Required | string | Controller name 9275delay_base_us | Required | number | Base (minimum) coalescing time in microseconds 9276iops_threshold | Required | number | Coalescing activation level greater than 0 in IO per second 9277 9278#### Example 9279 9280Example request: 9281 9282~~~json 9283{ 9284 "params": { 9285 "iops_threshold": 100000, 9286 "ctrlr": "VhostScsi0", 9287 "delay_base_us": 80 9288 }, 9289 "jsonrpc": "2.0", 9290 "method": "vhost_controller_set_coalescing", 9291 "id": 1 9292} 9293~~~ 9294 9295Example response: 9296 9297~~~json 9298{ 9299 "jsonrpc": "2.0", 9300 "id": 1, 9301 "result": true 9302} 9303~~~ 9304 9305### vhost_create_scsi_controller {#rpc_vhost_create_scsi_controller} 9306 9307Construct vhost SCSI target. 9308 9309#### Parameters 9310 9311Name | Optional | Type | Description 9312----------------------- | -------- | ----------- | ----------- 9313ctrlr | Required | string | Controller name 9314cpumask | Optional | string | @ref cpu_mask for this controller 9315delay | Optional | boolean | If true, delay the controller startup. 9316 9317#### Example 9318 9319Example request: 9320 9321~~~json 9322{ 9323 "params": { 9324 "cpumask": "0x2", 9325 "ctrlr": "VhostScsi0", 9326 "delay": true 9327 }, 9328 "jsonrpc": "2.0", 9329 "method": "vhost_create_scsi_controller", 9330 "id": 1 9331} 9332~~~ 9333 9334Example response: 9335 9336~~~json 9337{ 9338 "jsonrpc": "2.0", 9339 "id": 1, 9340 "result": true 9341} 9342~~~ 9343 9344### vhost_start_scsi_controller {#rpc_vhost_start_scsi_controller} 9345 9346Start vhost SCSI controller, if controller is already started, do nothing. 9347 9348#### Parameters 9349 9350Name | Optional | Type | Description 9351----------------------- | -------- | ----------- | ----------- 9352ctrlr | Required | string | Controller name 9353 9354#### Example 9355 9356Example request: 9357 9358~~~json 9359{ 9360 "params": { 9361 "ctrlr": "VhostScsi0", 9362 }, 9363 "jsonrpc": "2.0", 9364 "method": "vhost_start_scsi_controller", 9365 "id": 1 9366} 9367~~~ 9368 9369Example response: 9370 9371~~~json 9372response: 9373{ 9374 "jsonrpc": "2.0", 9375 "id": 1, 9376 "result": true 9377} 9378~~~ 9379 9380### vhost_scsi_controller_add_target {#rpc_vhost_scsi_controller_add_target} 9381 9382In vhost target `ctrlr` create SCSI target with ID `scsi_target_num` and add `bdev_name` as LUN 0. 9383 9384#### Parameters 9385 9386Name | Optional | Type | Description 9387----------------------- | -------- | ----------- | ----------- 9388ctrlr | Required | string | Controller name 9389scsi_target_num | Required | number | SCSI target ID between 0 and 7 or -1 to use first free ID. 9390bdev_name | Required | string | Name of bdev to expose as a LUN 0 9391 9392#### Response 9393 9394SCSI target ID. 9395 9396#### Example 9397 9398Example request: 9399 9400~~~json 9401{ 9402 "params": { 9403 "scsi_target_num": 1, 9404 "bdev_name": "Malloc0", 9405 "ctrlr": "VhostScsi0" 9406 }, 9407 "jsonrpc": "2.0", 9408 "method": "vhost_scsi_controller_add_target", 9409 "id": 1 9410} 9411~~~ 9412 9413Example response: 9414 9415~~~json 9416response: 9417{ 9418 "jsonrpc": "2.0", 9419 "id": 1, 9420 "result": 1 9421} 9422~~~ 9423 9424### vhost_scsi_controller_remove_target {#rpc_vhost_scsi_controller_remove_target} 9425 9426Remove SCSI target ID `scsi_target_num` from vhost target `scsi_target_num`. 9427 9428This method will fail if initiator is connected, but doesn't support hot-remove (the `VIRTIO_SCSI_F_HOTPLUG` is not negotiated). 9429 9430#### Parameters 9431 9432Name | Optional | Type | Description 9433----------------------- | -------- | ----------- | ----------- 9434ctrlr | Required | string | Controller name 9435scsi_target_num | Required | number | SCSI target ID between 0 and 7 9436 9437#### Example 9438 9439Example request: 9440 9441~~~json 9442request: 9443{ 9444 "params": { 9445 "scsi_target_num": 1, 9446 "ctrlr": "VhostScsi0" 9447 }, 9448 "jsonrpc": "2.0", 9449 "method": "vhost_scsi_controller_remove_target", 9450 "id": 1 9451} 9452~~~ 9453 9454Example response: 9455 9456~~~json 9457{ 9458 "jsonrpc": "2.0", 9459 "id": 1, 9460 "result": true 9461} 9462~~~ 9463 9464### virtio_blk_create_transport {#rpc_virtio_blk_create_transport} 9465 9466Create virtio blk transport. 9467 9468#### Parameters 9469 9470Name | Optional | Type | Description 9471----------------------- | -------- | ----------- | ----------- 9472name | Required | string | Transport name 9473 9474#### Example 9475 9476Example request: 9477 9478~~~json 9479{ 9480 "params": { 9481 "name": "vhost_user_blk" 9482 }, 9483 "jsonrpc": "2.0", 9484 "method": "virtio_blk_create_transport", 9485 "id": 1 9486} 9487~~~ 9488 9489Example response: 9490 9491~~~json 9492{ 9493 "jsonrpc": "2.0", 9494 "id": 1, 9495 "result": true 9496} 9497~~~ 9498 9499### virtio_blk_get_transports {#rpc_virtio_blk_get_transports} 9500 9501#### Parameters 9502 9503The user may specify no parameters in order to list all transports, 9504or a transport name may be specified. 9505 9506Name | Optional | Type | Description 9507--------------------------- | -------- | ------------| ----------- 9508name | Optional | string | Transport name. 9509 9510#### Example 9511 9512Example request: 9513 9514~~~json 9515{ 9516 "jsonrpc": "2.0", 9517 "method": "virtio_blk_get_transports", 9518 "id": 1 9519} 9520~~~ 9521 9522Example response: 9523 9524~~~json 9525{ 9526 "jsonrpc": "2.0", 9527 "id": 1, 9528 "result": [ 9529 { 9530 "name": "vhost_user_blk" 9531 } 9532 ] 9533} 9534~~~ 9535 9536### vhost_create_blk_controller {#rpc_vhost_create_blk_controller} 9537 9538Create vhost block controller 9539 9540If `readonly` is `true` then vhost block target will be created as read only and fail any write requests. 9541The `VIRTIO_BLK_F_RO` feature flag will be offered to the initiator. 9542 9543#### Parameters 9544 9545Name | Optional | Type | Description 9546----------------------- | -------- | ----------- | ----------- 9547ctrlr | Required | string | Controller name 9548bdev_name | Required | string | Name of bdev to expose block device 9549readonly | Optional | boolean | If true, this target will be read only (default: false) 9550cpumask | Optional | string | @ref cpu_mask for this controller 9551transport | Optional | string | virtio blk transport name (default: vhost_user_blk) 9552 9553#### Example 9554 9555Example request: 9556 9557~~~json 9558{ 9559 "params": { 9560 "dev_name": "Malloc0", 9561 "ctrlr": "VhostBlk0" 9562 }, 9563 "jsonrpc": "2.0", 9564 "method": "vhost_create_blk_controller", 9565 "id": 1 9566} 9567~~~ 9568 9569Example response: 9570 9571~~~json 9572{ 9573 "jsonrpc": "2.0", 9574 "id": 1, 9575 "result": true 9576} 9577~~~ 9578 9579### vhost_get_controllers {#rpc_vhost_get_controllers} 9580 9581Display information about all or specific vhost controller(s). 9582 9583#### Parameters 9584 9585The user may specify no parameters in order to list all controllers, or a controller may be 9586specified by name. 9587 9588Name | Optional | Type | Description 9589----------------------- | -------- | ----------- | ----------- 9590name | Optional | string | Vhost controller name 9591 9592#### Response {#rpc_vhost_get_controllers_response} 9593 9594Response is an array of objects describing requested controller(s). Common fields are: 9595 9596Name | Type | Description 9597----------------------- | ----------- | ----------- 9598ctrlr | string | Controller name 9599cpumask | string | @ref cpu_mask of this controller 9600delay_base_us | number | Base (minimum) coalescing time in microseconds (0 if disabled) 9601iops_threshold | number | Coalescing activation level 9602backend_specific | object | Backend specific information 9603 9604### Vhost block {#rpc_vhost_get_controllers_blk} 9605 9606`backend_specific` contains one `block` object of type: 9607 9608Name | Type | Description 9609----------------------- | ----------- | ----------- 9610bdev | string | Backing bdev name or Null if bdev is hot-removed 9611readonly | boolean | True if controllers is readonly, false otherwise 9612 9613### Vhost SCSI {#rpc_vhost_get_controllers_scsi} 9614 9615`backend_specific` contains `scsi` array of following objects: 9616 9617Name | Type | Description 9618----------------------- | ----------- | ----------- 9619target_name | string | Name of this SCSI target 9620id | number | Unique SPDK global SCSI target ID 9621scsi_dev_num | number | SCSI target ID initiator will see when scanning this controller 9622luns | array | array of objects describing @ref rpc_vhost_get_controllers_scsi_luns 9623 9624### Vhost SCSI LUN {#rpc_vhost_get_controllers_scsi_luns} 9625 9626Object of type: 9627 9628Name | Type | Description 9629----------------------- | ----------- | ----------- 9630id | number | SCSI LUN ID 9631bdev_name | string | Backing bdev name 9632 9633### Vhost NVMe {#rpc_vhost_get_controllers_nvme} 9634 9635`backend_specific` contains `namespaces` array of following objects: 9636 9637Name | Type | Description 9638----------------------- | ----------- | ----------- 9639nsid | number | Namespace ID 9640bdev | string | Backing bdev name 9641 9642#### Example 9643 9644Example request: 9645 9646~~~json 9647{ 9648 "jsonrpc": "2.0", 9649 "method": "vhost_get_controllers", 9650 "id": 1 9651} 9652~~~ 9653 9654Example response: 9655 9656~~~json 9657{ 9658 "jsonrpc": "2.0", 9659 "id": 1, 9660 "result": [ 9661 { 9662 "cpumask": "0x2", 9663 "backend_specific": { 9664 "block": { 9665 "readonly": false, 9666 "bdev": "Malloc0" 9667 } 9668 }, 9669 "iops_threshold": 60000, 9670 "ctrlr": "VhostBlk0", 9671 "delay_base_us": 100 9672 }, 9673 { 9674 "cpumask": "0x2", 9675 "backend_specific": { 9676 "scsi": [ 9677 { 9678 "target_name": "Target 2", 9679 "luns": [ 9680 { 9681 "id": 0, 9682 "bdev_name": "Malloc1" 9683 } 9684 ], 9685 "id": 0, 9686 "scsi_dev_num": 2 9687 }, 9688 { 9689 "target_name": "Target 5", 9690 "luns": [ 9691 { 9692 "id": 0, 9693 "bdev_name": "Malloc2" 9694 } 9695 ], 9696 "id": 1, 9697 "scsi_dev_num": 5 9698 } 9699 ] 9700 }, 9701 "iops_threshold": 60000, 9702 "ctrlr": "VhostScsi0", 9703 "delay_base_us": 0 9704 }, 9705 { 9706 "cpumask": "0x2", 9707 "backend_specific": { 9708 "namespaces": [ 9709 { 9710 "bdev": "Malloc3", 9711 "nsid": 1 9712 }, 9713 { 9714 "bdev": "Malloc4", 9715 "nsid": 2 9716 } 9717 ] 9718 }, 9719 "iops_threshold": 60000, 9720 "ctrlr": "VhostNvme0", 9721 "delay_base_us": 0 9722 } 9723 ] 9724} 9725~~~ 9726 9727### vhost_delete_controller {#rpc_vhost_delete_controller} 9728 9729Remove vhost target. 9730 9731This call will fail if there is an initiator connected or there is at least one SCSI target configured in case of 9732vhost SCSI target. In the later case please remove all SCSI targets first using @ref rpc_vhost_scsi_controller_remove_target. 9733 9734#### Parameters 9735 9736Name | Optional | Type | Description 9737----------------------- | -------- | ----------- | ----------- 9738ctrlr | Required | string | Controller name 9739 9740#### Example 9741 9742Example request: 9743 9744~~~json 9745{ 9746 "params": { 9747 "ctrlr": "VhostNvme0" 9748 }, 9749 "jsonrpc": "2.0", 9750 "method": "vhost_delete_controller", 9751 "id": 1 9752} 9753~~~ 9754 9755Example response: 9756 9757~~~json 9758{ 9759 "jsonrpc": "2.0", 9760 "id": 1, 9761 "result": true 9762} 9763~~~ 9764 9765## Logical Volume {#jsonrpc_components_lvol} 9766 9767Identification of logical volume store and logical volume is explained first. 9768 9769A logical volume store has a UUID and a name for its identification. 9770The UUID is generated on creation and it can be used as a unique identifier. 9771The name is specified on creation and can be renamed. 9772Either UUID or name is used to access logical volume store in RPCs. 9773 9774A logical volume has a UUID and a name for its identification. 9775The UUID of the logical volume is generated on creation and it can be unique identifier. 9776The alias of the logical volume takes the format _lvs_name/lvol_name_ where: 9777 9778* _lvs_name_ is the name of the logical volume store. 9779* _lvol_name_ is specified on creation and can be renamed. 9780 9781### bdev_lvol_create_lvstore {#rpc_bdev_lvol_create_lvstore} 9782 9783Construct a logical volume store. 9784 9785#### Parameters 9786 9787Name | Optional | Type | Description 9788----------------------------- | -------- | ----------- | ----------- 9789bdev_name | Required | string | Bdev on which to construct logical volume store 9790lvs_name | Required | string | Name of the logical volume store to create 9791cluster_sz | Optional | number | Cluster size of the logical volume store in bytes (Default: 4MiB) 9792clear_method | Optional | string | Change clear method for data region. Available: none, unmap (default), write_zeroes 9793num_md_pages_per_cluster_ratio| Optional | number | Reserved metadata pages per cluster (Default: 100) 9794 9795The num_md_pages_per_cluster_ratio defines the amount of metadata to 9796allocate when the logical volume store is created. The default value 9797is '100', which translates to 1 4KiB per cluster. For the default 4MiB 9798cluster size, this equates to about 0.1% of the underlying block 9799device allocated for metadata. Logical volume stores can be grown, if 9800the size of the underlying block device grows in the future, but only 9801if enough metadata pages were allocated to support the growth. So 9802num_md_pages_per_cluster_ratio should be set to a higher value if 9803wanting to support future growth. For example, 9804num_md_pages_per_cluster_ratio = 200 would support future 2x growth of 9805the logical volume store, and would result in 0.2% of the underlying 9806block device allocated for metadata (with a default 4MiB cluster 9807size). 9808 9809#### Response 9810 9811UUID of the created logical volume store is returned. 9812 9813#### Example 9814 9815Example request: 9816 9817~~~json 9818{ 9819 "jsonrpc": "2.0", 9820 "id": 1, 9821 "method": "bdev_lvol_create_lvstore", 9822 "params": { 9823 "lvs_name": "LVS0", 9824 "bdev_name": "Malloc0" 9825 "clear_method": "write_zeroes" 9826 } 9827} 9828~~~ 9829 9830Example response: 9831 9832~~~json 9833{ 9834 "jsonrpc": "2.0", 9835 "id": 1, 9836 "result": "a9959197-b5e2-4f2d-8095-251ffb6985a5" 9837} 9838~~~ 9839 9840### bdev_lvol_delete_lvstore {#rpc_bdev_lvol_delete_lvstore} 9841 9842Destroy a logical volume store. 9843 9844#### Parameters 9845 9846Name | Optional | Type | Description 9847----------------------- | -------- | ----------- | ----------- 9848uuid | Optional | string | UUID of the logical volume store to destroy 9849lvs_name | Optional | string | Name of the logical volume store to destroy 9850 9851Either uuid or lvs_name must be specified, but not both. 9852 9853#### Example 9854 9855Example request: 9856 9857~~~json 9858{ 9859 "jsonrpc": "2.0", 9860 "method": "bdev_lvol_delete_lvstore", 9861 "id": 1 9862 "params": { 9863 "uuid": "a9959197-b5e2-4f2d-8095-251ffb6985a5" 9864 } 9865} 9866~~~ 9867 9868Example response: 9869 9870~~~json 9871{ 9872 "jsonrpc": "2.0", 9873 "id": 1, 9874 "result": true 9875} 9876~~~ 9877 9878### bdev_lvol_get_lvstores {#rpc_bdev_lvol_get_lvstores} 9879 9880Get a list of logical volume stores. 9881 9882#### Parameters 9883 9884Name | Optional | Type | Description 9885----------------------- | -------- | ----------- | ----------- 9886uuid | Optional | string | UUID of the logical volume store to retrieve information about 9887lvs_name | Optional | string | Name of the logical volume store to retrieve information about 9888 9889Either uuid or lvs_name may be specified, but not both. 9890If both uuid and lvs_name are omitted, information about all logical volume stores is returned. 9891 9892#### Example 9893 9894Example request: 9895 9896~~~json 9897{ 9898 "jsonrpc": "2.0", 9899 "method": "bdev_lvol_get_lvstores", 9900 "id": 1, 9901 "params": { 9902 "lvs_name": "LVS0" 9903 } 9904} 9905~~~ 9906 9907Example response: 9908 9909~~~json 9910{ 9911 "jsonrpc": "2.0", 9912 "id": 1, 9913 "result": [ 9914 { 9915 "uuid": "a9959197-b5e2-4f2d-8095-251ffb6985a5", 9916 "base_bdev": "Malloc0", 9917 "free_clusters": 31, 9918 "cluster_size": 4194304, 9919 "total_data_clusters": 31, 9920 "block_size": 4096, 9921 "name": "LVS0" 9922 } 9923 ] 9924} 9925~~~ 9926 9927### bdev_lvol_rename_lvstore {#rpc_bdev_lvol_rename_lvstore} 9928 9929Rename a logical volume store. 9930 9931#### Parameters 9932 9933Name | Optional | Type | Description 9934----------------------- | -------- | ----------- | ----------- 9935old_name | Required | string | Existing logical volume store name 9936new_name | Required | string | New logical volume store name 9937 9938#### Example 9939 9940Example request: 9941 9942~~~json 9943{ 9944 "jsonrpc": "2.0", 9945 "method": "bdev_lvol_rename_lvstore", 9946 "id": 1, 9947 "params": { 9948 "old_name": "LVS0", 9949 "new_name": "LVS2" 9950 } 9951} 9952~~~ 9953 9954Example response: 9955 9956~~~json 9957{ 9958 "jsonrpc": "2.0", 9959 "id": 1, 9960 "result": true 9961} 9962~~~ 9963 9964### bdev_lvol_grow_lvstore {#rpc_bdev_lvol_grow_lvstore} 9965 9966Grow the logical volume store to fill the underlying bdev 9967 9968#### Parameters 9969 9970Name | Optional | Type | Description 9971----------------------- | -------- | ----------- | ----------- 9972uuid | Optional | string | UUID of the logical volume store to grow 9973lvs_name | Optional | string | Name of the logical volume store to grow 9974 9975Either uuid or lvs_name must be specified, but not both. 9976 9977#### Example 9978 9979Example request: 9980 9981~~~json 9982{ 9983 "jsonrpc": "2.0", 9984 "method": "bdev_lvol_grow_lvstore", 9985 "id": 1 9986 "params": { 9987 "uuid": "a9959197-b5e2-4f2d-8095-251ffb6985a5" 9988 } 9989} 9990~~~ 9991 9992Example response: 9993 9994~~~json 9995{ 9996 "jsonrpc": "2.0", 9997 "id": 1, 9998 "result": true 9999} 10000~~~ 10001 10002### bdev_lvol_create {#rpc_bdev_lvol_create} 10003 10004Create a logical volume on a logical volume store. 10005 10006#### Parameters 10007 10008Name | Optional | Type | Description 10009----------------------- | -------- | ----------- | ----------- 10010lvol_name | Required | string | Name of logical volume to create 10011size | Optional | number | Desired size of logical volume in bytes (Deprecated. Please use size_in_mib instead.) 10012size_in_mib | Optional | number | Desired size of logical volume in MiB 10013thin_provision | Optional | boolean | True to enable thin provisioning 10014uuid | Optional | string | UUID of logical volume store to create logical volume on 10015lvs_name | Optional | string | Name of logical volume store to create logical volume on 10016clear_method | Optional | string | Change default data clusters clear method. Available: none, unmap, write_zeroes 10017 10018Size will be rounded up to a multiple of cluster size. Either uuid or lvs_name must be specified, but not both. 10019lvol_name will be used in the alias of the created logical volume. 10020 10021#### Response 10022 10023UUID of the created logical volume is returned. 10024 10025#### Example 10026 10027Example request: 10028 10029~~~json 10030{ 10031 "jsonrpc": "2.0", 10032 "method": "bdev_lvol_create", 10033 "id": 1, 10034 "params": { 10035 "lvol_name": "LVOL0", 10036 "size_in_mib": 1, 10037 "lvs_name": "LVS0", 10038 "clear_method": "unmap", 10039 "thin_provision": true 10040 } 10041} 10042~~~ 10043 10044Example response: 10045 10046~~~json 10047{ 10048 "jsonrpc": "2.0", 10049 "id": 1, 10050 "result": "1b38702c-7f0c-411e-a962-92c6a5a8a602" 10051} 10052~~~ 10053 10054### bdev_lvol_snapshot {#rpc_bdev_lvol_snapshot} 10055 10056Capture a snapshot of the current state of a logical volume. 10057 10058#### Parameters 10059 10060Name | Optional | Type | Description 10061----------------------- | -------- | ----------- | ----------- 10062lvol_name | Required | string | UUID or alias of the logical volume to create a snapshot from 10063snapshot_name | Required | string | Name for the newly created snapshot 10064 10065#### Response 10066 10067UUID of the created logical volume snapshot is returned. 10068 10069#### Example 10070 10071Example request: 10072 10073~~~json 10074{ 10075 "jsonrpc": "2.0", 10076 "method": "bdev_lvol_snapshot", 10077 "id": 1, 10078 "params": { 10079 "lvol_name": "1b38702c-7f0c-411e-a962-92c6a5a8a602", 10080 "snapshot_name": "SNAP1" 10081 } 10082} 10083~~~ 10084 10085Example response: 10086 10087~~~json 10088{ 10089 "jsonrpc": "2.0", 10090 "id": 1, 10091 "result": "cc8d7fdf-7865-4d1f-9fc6-35da8e368670" 10092} 10093~~~ 10094 10095### bdev_lvol_clone {#rpc_bdev_lvol_clone} 10096 10097Create a logical volume based on a snapshot. 10098 10099#### Parameters 10100 10101Name | Optional | Type | Description 10102----------------------- | -------- | ----------- | ----------- 10103snapshot_name | Required | string | UUID or alias of the snapshot to clone 10104clone_name | Required | string | Name for the logical volume to create 10105 10106#### Response 10107 10108UUID of the created logical volume clone is returned. 10109 10110#### Example 10111 10112Example request: 10113 10114~~~json 10115{ 10116 "jsonrpc": "2.0" 10117 "method": "bdev_lvol_clone", 10118 "id": 1, 10119 "params": { 10120 "snapshot_name": "cc8d7fdf-7865-4d1f-9fc6-35da8e368670", 10121 "clone_name": "CLONE1" 10122 } 10123} 10124~~~ 10125 10126Example response: 10127 10128~~~json 10129{ 10130 "jsonrpc": "2.0", 10131 "id": 1, 10132 "result": "8d87fccc-c278-49f0-9d4c-6237951aca09" 10133} 10134~~~ 10135 10136### bdev_lvol_clone_bdev {#rpc_bdev_lvol_clone_bdev} 10137 10138Create a logical volume based on an external snapshot bdev. The external snapshot bdev 10139is a bdev that will not be written to by any consumer and must not be an lvol in the 10140lvstore as the clone. 10141 10142Regardless of whether the bdev is specified by name or UUID, the bdev UUID will be stored 10143in the logical volume's metadata for use while the lvolstore is loading. For this reason, 10144it is important that the bdev chosen has a static UUID. 10145 10146#### Parameters 10147 10148Name | Optional | Type | Description 10149----------------------- | -------- | ----------- | ----------- 10150bdev | Required | string | Name or UUID for bdev that acts as the external snapshot 10151lvs_name | Required | string | logical volume store name 10152clone_name | Required | string | Name for the logical volume to create 10153 10154#### Response 10155 10156UUID of the created logical volume clone is returned. 10157 10158#### Example 10159 10160Example request: 10161 10162~~~json 10163{ 10164 "jsonrpc": "2.0", 10165 "method": "bdev_lvol_clone_bdev", 10166 "id": 1, 10167 "params": { 10168 "bdev_uuid": "e4b40d8b-f623-416d-8234-baf5a4c83cbd", 10169 "lvs_name": "lvs1", 10170 "clone_name": "clone2" 10171 } 10172} 10173~~~ 10174 10175Example response: 10176 10177~~~json 10178{ 10179 "jsonrpc": "2.0", 10180 "id": 1, 10181 "result": "336f662b-08e5-4006-8e06-e2023f7f9886" 10182} 10183~~~ 10184 10185### bdev_lvol_rename {#rpc_bdev_lvol_rename} 10186 10187Rename a logical volume. New name will rename only the alias of the logical volume. 10188 10189#### Parameters 10190 10191Name | Optional | Type | Description 10192----------------------- | -------- | ----------- | ----------- 10193old_name | Required | string | UUID or alias of the existing logical volume 10194new_name | Required | string | New logical volume name 10195 10196#### Example 10197 10198Example request: 10199 10200~~~json 10201{ 10202 "jsonrpc": "2.0", 10203 "method": "bdev_lvol_rename", 10204 "id": 1, 10205 "params": { 10206 "old_name": "067df606-6dbc-4143-a499-0d05855cb3b8", 10207 "new_name": "LVOL2" 10208 } 10209} 10210~~~ 10211 10212Example response: 10213 10214~~~json 10215{ 10216 "jsonrpc": "2.0", 10217 "id": 1, 10218 "result": true 10219} 10220~~~ 10221 10222### bdev_lvol_resize {#rpc_bdev_lvol_resize} 10223 10224Resize a logical volume. 10225 10226#### Parameters 10227 10228Name | Optional | Type | Description 10229----------------------- | -------- | ----------- | ----------- 10230name | Required | string | UUID or alias of the logical volume to resize 10231size | Optional | number | Desired size of the logical volume in bytes (Deprecated. Please use size_in_mib instead.) 10232size_in_mib | Optional | number | Desired size of the logical volume in MiB 10233 10234#### Example 10235 10236Example request: 10237 10238~~~json 10239{ 10240 "jsonrpc": "2.0", 10241 "method": "bdev_lvol_resize", 10242 "id": 1, 10243 "params": { 10244 "name": "51638754-ca16-43a7-9f8f-294a0805ab0a", 10245 "size_in_mib": 2 10246 } 10247} 10248~~~ 10249 10250Example response: 10251 10252~~~json 10253{ 10254 "jsonrpc": "2.0", 10255 "id": 1, 10256 "result": true 10257} 10258~~~ 10259 10260### bdev_lvol_set_read_only{#rpc_bdev_lvol_set_read_only} 10261 10262Mark logical volume as read only. 10263 10264#### Parameters 10265 10266Name | Optional | Type | Description 10267----------------------- | -------- | ----------- | ----------- 10268name | Required | string | UUID or alias of the logical volume to set as read only 10269 10270#### Example 10271 10272Example request: 10273 10274~~~json 10275{ 10276 "jsonrpc": "2.0", 10277 "method": "bdev_lvol_set_read_only", 10278 "id": 1, 10279 "params": { 10280 "name": "51638754-ca16-43a7-9f8f-294a0805ab0a", 10281 } 10282} 10283~~~ 10284 10285Example response: 10286 10287~~~json 10288{ 10289 "jsonrpc": "2.0", 10290 "id": 1, 10291 "result": true 10292} 10293~~~ 10294 10295### bdev_lvol_delete {#rpc_bdev_lvol_delete} 10296 10297Destroy a logical volume. 10298 10299#### Parameters 10300 10301Name | Optional | Type | Description 10302----------------------- | -------- | ----------- | ----------- 10303name | Required | string | UUID or alias of the logical volume to destroy 10304 10305#### Example 10306 10307Example request: 10308 10309~~~json 10310{ 10311 "jsonrpc": "2.0", 10312 "method": "bdev_lvol_delete", 10313 "id": 1, 10314 "params": { 10315 "name": "51638754-ca16-43a7-9f8f-294a0805ab0a" 10316 } 10317} 10318~~~ 10319 10320Example response: 10321 10322~~~json 10323{ 10324 "jsonrpc": "2.0", 10325 "id": 1, 10326 "result": true 10327} 10328~~~ 10329 10330### bdev_lvol_inflate {#rpc_bdev_lvol_inflate} 10331 10332Inflate a logical volume. All unallocated clusters are allocated and copied from the parent or zero filled 10333if not allocated in the parent. Then all dependencies on the parent are removed. 10334 10335### Parameters 10336 10337Name | Optional | Type | Description 10338----------------------- | -------- | ----------- | ----------- 10339name | Required | string | UUID or alias of the logical volume to inflate 10340 10341#### Example 10342 10343Example request: 10344 10345~~~json 10346{ 10347 "jsonrpc": "2.0", 10348 "method": "bdev_lvol_inflate", 10349 "id": 1, 10350 "params": { 10351 "name": "8d87fccc-c278-49f0-9d4c-6237951aca09" 10352 } 10353} 10354~~~ 10355 10356Example response: 10357 10358~~~json 10359{ 10360 "jsonrpc": "2.0", 10361 "id": 1, 10362 "result": true 10363} 10364~~~ 10365 10366### bdev_lvol_decouple_parent {#rpc_bdev_lvol_decouple_parent} 10367 10368Decouple the parent of a logical volume. For unallocated clusters which is allocated in the parent, they are 10369allocated and copied from the parent, but for unallocated clusters which is thin provisioned in the parent, 10370they are kept thin provisioned. Then all dependencies on the parent are removed. 10371 10372#### Parameters 10373 10374Name | Optional | Type | Description 10375----------------------- | -------- | ----------- | ----------- 10376name | Required | string | UUID or alias of the logical volume to decouple the parent of it 10377 10378#### Example 10379 10380Example request: 10381 10382~~~json 10383{ 10384 "jsonrpc": "2.0", 10385 "method": "bdev_lvol_decouple_parent", 10386 "id": 1. 10387 "params": { 10388 "name": "8d87fccc-c278-49f0-9d4c-6237951aca09" 10389 } 10390} 10391~~~ 10392 10393Example response: 10394 10395~~~json 10396{ 10397 "jsonrpc": "2.0", 10398 "id": 1, 10399 "result": true 10400} 10401~~~ 10402 10403### bdev_lvol_get_lvols {#rpc_bdev_lvol_get_lvols} 10404 10405Get a list of logical volumes. This list can be limited by lvol store and will display volumes even if 10406they are degraded. Degraded lvols do not have an associated bdev, thus this RPC call may return lvols 10407not returned by `bdev_get_bdevs`. 10408 10409#### Parameters 10410 10411Name | Optional | Type | Description 10412----------------------- | -------- | ----------- | ----------- 10413lvs_uuid | Optional | string | Only show volumes in the logical volume store with this UUID 10414lvs_name | Optional | string | Only show volumes in the logical volume store with this name 10415 10416Either lvs_uuid or lvs_name may be specified, but not both. 10417If both lvs_uuid and lvs_name are omitted, information about lvols in all logical volume stores is returned. 10418 10419#### Example 10420 10421Example request: 10422 10423~~~json 10424{ 10425 "jsonrpc": "2.0", 10426 "method": "bdev_lvol_get_lvols", 10427 "id": 1, 10428 "params": { 10429 "lvs_name": "lvs_test" 10430 } 10431} 10432~~~ 10433 10434Example response: 10435 10436~~~json 10437[ 10438 { 10439 "alias": "lvs_test/lvol1", 10440 "uuid": "b335c368-851d-4099-81e0-018cc494fdf6", 10441 "name": "lvol1", 10442 "is_thin_provisioned": false, 10443 "is_snapshot": false, 10444 "is_clone": false, 10445 "is_esnap_clone": false, 10446 "is_degraded": false, 10447 "lvs": { 10448 "name": "lvs_test", 10449 "uuid": "a1c8d950-5715-4558-936d-ab9e6eca0794" 10450 } 10451 } 10452] 10453~~~ 10454 10455## RAID 10456 10457### bdev_raid_set_options {#rpc_bdev_raid_set_options} 10458 10459Set options for bdev raid. 10460 10461This RPC can be called at any time, but the new value will only take effect for new raid bdevs. 10462 10463The `process_window_size_kb` parameter defines the size of the "window" (LBA range of the raid bdev) 10464in which a background process like rebuild performs its work. Any positive value is valid, but the value 10465actually used by a raid bdev can be adjusted to the size of the raid bdev or the write unit size. 10466 10467#### Parameters 10468 10469Name | Optional | Type | Description 10470-------------------------- | -------- | ----------- | ----------- 10471process_window_size_kb | Optional | number | Background process (e.g. rebuild) window size in KiB 10472 10473#### Example 10474 10475Example request: 10476 10477~~~json 10478request: 10479{ 10480 "jsonrpc": "2.0", 10481 "method": "bdev_raid_set_options", 10482 "id": 1, 10483 "params": { 10484 "process_window_size_kb": 512 10485 } 10486} 10487~~~ 10488 10489Example response: 10490 10491~~~json 10492{ 10493 "jsonrpc": "2.0", 10494 "id": 1, 10495 "result": true 10496} 10497~~~ 10498 10499### bdev_raid_get_bdevs {#rpc_bdev_raid_get_bdevs} 10500 10501This is used to list all the raid bdev details based on the input category requested. Category should be one 10502of 'all', 'online', 'configuring' or 'offline'. 'all' means all the raid bdevs whether they are online or 10503configuring or offline. 'online' is the raid bdev which is registered with bdev layer. 'configuring' is 10504the raid bdev which does not have full configuration discovered yet. 'offline' is the raid bdev which is 10505not registered with bdev as of now and it has encountered any error or user has requested to offline 10506the raid bdev. 10507 10508#### Parameters 10509 10510Name | Optional | Type | Description 10511----------------------- | -------- | ----------- | ----------- 10512category | Required | string | all or online or configuring or offline 10513 10514#### Example 10515 10516Example request: 10517 10518~~~json 10519{ 10520 "jsonrpc": "2.0", 10521 "method": "bdev_raid_get_bdevs", 10522 "id": 1, 10523 "params": { 10524 "category": "all" 10525 } 10526} 10527~~~ 10528 10529Example response: 10530 10531~~~json 10532{ 10533 "jsonrpc": "2.0", 10534 "id": 1, 10535 "result": [ 10536 { 10537 "name": "RaidBdev0", 10538 "uuid": "7d352e83-fe27-40f2-8fef-64563355e076", 10539 "strip_size_kb": 128, 10540 "state": "online", 10541 "raid_level": "raid0", 10542 "num_base_bdevs": 2, 10543 "num_base_bdevs_discovered": 2, 10544 "num_base_bdevs_operational": 2, 10545 "base_bdevs_list": [ 10546 { 10547 "name": "malloc0", 10548 "uuid": "d2788884-5b3e-4fd7-87ff-6c78177e14ab", 10549 "is_configured": true, 10550 "data_offset": 256, 10551 "data_size": 261888 10552 }, 10553 { 10554 "name": "malloc1", 10555 "uuid": "a81bb1f8-5865-488a-8758-10152017e7d1", 10556 "is_configured": true, 10557 "data_offset": 256, 10558 "data_size": 261888 10559 } 10560 ] 10561 }, 10562 { 10563 "name": "RaidBdev1", 10564 "uuid": "f7cb71ed-2d0e-4240-979e-27b0b7735f36", 10565 "strip_size_kb": 128, 10566 "state": "configuring", 10567 "raid_level": "raid0", 10568 "num_base_bdevs": 2, 10569 "num_base_bdevs_discovered": 1, 10570 "num_base_bdevs_operational": 2, 10571 "base_bdevs_list": [ 10572 { 10573 "name": "malloc2", 10574 "uuid": "f60c20e1-3439-4f89-ae55-965a70333f86", 10575 "is_configured": true, 10576 "data_offset": 256, 10577 "data_size": 261888 10578 } 10579 { 10580 "name": "malloc3", 10581 "uuid": "00000000-0000-0000-0000-000000000000", 10582 "is_configured": false, 10583 "data_offset": 0, 10584 "data_size": 0 10585 } 10586 ] 10587 } 10588 ] 10589} 10590~~~ 10591 10592### bdev_raid_create {#rpc_bdev_raid_create} 10593 10594Constructs new RAID bdev. 10595 10596#### Parameters 10597 10598Name | Optional | Type | Description 10599----------------------- | -------- | ----------- | ----------- 10600name | Required | string | RAID bdev name 10601strip_size_kb | Required | number | Strip size in KB 10602raid_level | Required | string | RAID level 10603base_bdevs | Required | string | Base bdevs name, whitespace separated list in quotes 10604uuid | Optional | string | UUID for this RAID bdev 10605superblock | Optional | boolean | If set, information about raid bdev will be stored in superblock on each base bdev (default: `false`) 10606 10607#### Example 10608 10609Example request: 10610 10611~~~json 10612{ 10613 "jsonrpc": "2.0", 10614 "method": "bdev_raid_create", 10615 "id": 1, 10616 "params": { 10617 "name": "Raid0", 10618 "raid_level": "0", 10619 "base_bdevs": [ 10620 "Malloc0", 10621 "Malloc1", 10622 "Malloc2", 10623 "Malloc3" 10624 ], 10625 "strip_size_kb": 4 10626 } 10627} 10628~~~ 10629 10630Example response: 10631 10632~~~json 10633{ 10634 "jsonrpc": "2.0", 10635 "id": 1, 10636 "result": true 10637} 10638~~~ 10639 10640### bdev_raid_delete {#rpc_bdev_raid_delete} 10641 10642Removes RAID bdev. 10643 10644#### Parameters 10645 10646Name | Optional | Type | Description 10647----------------------- | -------- | ----------- | ----------- 10648name | Required | string | RAID bdev name 10649 10650#### Example 10651 10652Example request: 10653 10654~~~json 10655{ 10656 "jsonrpc": "2.0", 10657 "method": "bdev_raid_delete", 10658 "id": 1, 10659 "params": { 10660 "name": "Raid0" 10661 } 10662} 10663~~~ 10664 10665Example response: 10666 10667~~~json 10668{ 10669 "jsonrpc": "2.0", 10670 "id": 1, 10671 "result": true 10672} 10673~~~ 10674 10675### bdev_raid_add_base_bdev {#rpc_bdev_raid_add_base_bdev} 10676 10677Add base bdev to existing raid bdev. The raid bdev must have an empty base bdev slot. 10678The bdev must be large enough and have the same block size and metadata format as the other base bdevs. 10679 10680#### Parameters 10681 10682Name | Optional | Type | Description 10683----------------------- | -------- | ----------- | ----------- 10684raid_bdev | Required | string | Raid bdev name 10685base_bdev | Required | string | Base bdev name 10686 10687#### Example 10688 10689Example request: 10690 10691~~~json 10692{ 10693 "jsonrpc": "2.0", 10694 "method": "bdev_raid_add_base_bdev", 10695 "id": 1, 10696 "params": { 10697 "raid_bdev": "RaidBdev0", 10698 "base_bdev": "Nvme0n1" 10699 } 10700} 10701~~~ 10702 10703Example response: 10704 10705~~~json 10706{ 10707 "jsonrpc": "2.0", 10708 "id": 1, 10709 "result": true 10710} 10711~~~ 10712### bdev_raid_remove_base_bdev {#rpc_bdev_raid_remove_base_bdev} 10713 10714Remove base bdev from existing raid bdev. 10715 10716#### Parameters 10717 10718Name | Optional | Type | Description 10719----------------------- | -------- | ----------- | ----------- 10720name | Required | string | Base bdev name in RAID 10721 10722#### Example 10723 10724Example request: 10725 10726~~~json 10727{ 10728 "jsonrpc": "2.0", 10729 "method": "bdev_raid_remove_base_bdev", 10730 "id": 1, 10731 "params": { 10732 "name": "Raid0" 10733 } 10734} 10735~~~ 10736 10737Example response: 10738 10739~~~json 10740{ 10741 "jsonrpc": "2.0", 10742 "id": 1, 10743 "result": true 10744} 10745~~~ 10746 10747## SPLIT 10748 10749### bdev_split_create {#rpc_bdev_split_create} 10750 10751This is used to split an underlying block device and create several smaller equal-sized vbdevs. 10752 10753#### Parameters 10754 10755Name | Optional | Type | Description 10756----------------------- | -------- | ----------- | ----------- 10757base_bdev | Required | string | base bdev name 10758split_count | Required | number | number of splits 10759split_size_mb | Optional | number | size in MB to restrict the size 10760 10761#### Example 10762 10763Example request: 10764 10765~~~json 10766{ 10767 "jsonrpc": "2.0", 10768 "method": "bdev_split_create", 10769 "id": 1, 10770 "params": { 10771 "base_bdev": "Malloc0", 10772 "split_count": 4 10773 } 10774} 10775~~~ 10776 10777Example response: 10778 10779~~~json 10780{ 10781 "jsonrpc": "2.0", 10782 "id": 1, 10783 "result": [ 10784 "Malloc0p0", 10785 "Malloc0p1", 10786 "Malloc0p2", 10787 "Malloc0p3" 10788 ] 10789} 10790~~~ 10791 10792### bdev_split_delete {#rpc_bdev_split_delete} 10793 10794This is used to remove the split vbdevs. 10795 10796#### Parameters 10797 10798Name | Optional | Type | Description 10799----------------------- | -------- | ----------- | ----------- 10800base_bdev | Required | string | base bdev name 10801 10802#### Example 10803 10804Example request: 10805 10806~~~json 10807{ 10808 "jsonrpc": "2.0", 10809 "method": "bdev_split_delete", 10810 "id": 1, 10811 "params": { 10812 "base_bdev": "Malloc0" 10813 } 10814} 10815~~~ 10816 10817Example response: 10818 10819~~~json 10820{ 10821 "jsonrpc": "2.0", 10822 "id": 1, 10823 "result": true 10824} 10825~~~ 10826 10827## Uring 10828 10829### bdev_uring_create {#rpc_bdev_uring_create} 10830 10831Create a bdev with io_uring backend. 10832 10833#### Parameters 10834 10835Name | Optional | Type | Description 10836----------------------- | -------- | ----------- | ----------- 10837filename | Required | string | path to device or file (ex: /dev/nvme0n1) 10838name | Required | string | name of bdev 10839block_size | Optional | number | block size of device (If omitted, get the block size from the file) 10840uuid | Optional | string | UUID of new bdev 10841 10842#### Example 10843 10844Example request: 10845 10846~~~json 10847{ 10848 "jsonrpc": "2.0", 10849 "method": "bdev_uring_create", 10850 "id": 1, 10851 "params": { 10852 "name": "bdev_u0", 10853 "filename": "/dev/nvme0n1", 10854 "block_size": 512 10855 } 10856} 10857~~~ 10858 10859Example response: 10860 10861~~~json 10862{ 10863 "jsonrpc": "2.0", 10864 "id": 1, 10865 "result": "bdev_u0" 10866} 10867~~~ 10868 10869### bdev_uring_rescan {#rpc_bdev_uring_rescan} 10870 10871Rescan the size of a uring bdev. 10872 10873#### Parameters 10874 10875Name | Optional | Type | Description 10876---- | -------- | ------ | ----------- 10877name | Required | string | name of uring bdev to rescan 10878 10879#### Example 10880 10881Example request: 10882 10883~~~json 10884{ 10885 "jsonrpc": "2.0", 10886 "method": "bdev_uring_rescan", 10887 "id": 1, 10888 "params": { 10889 "name": "bdev_u0" 10890 } 10891} 10892~~~ 10893 10894Example response: 10895 10896~~~json 10897{ 10898 "jsonrpc": "2.0", 10899 "id": 1, 10900 "result": true 10901} 10902~~~ 10903 10904### bdev_uring_delete {#rpc_bdev_uring_delete} 10905 10906Remove a uring bdev. 10907 10908#### Parameters 10909 10910Name | Optional | Type | Description 10911----------------------- | -------- | ----------- | ----------- 10912name | Required | string | name of uring bdev to delete 10913 10914#### Example 10915 10916Example request: 10917 10918~~~json 10919{ 10920 "jsonrpc": "2.0", 10921 "method": "bdev_uring_delete", 10922 "id": 1, 10923 "params": { 10924 "name": "bdev_u0" 10925 } 10926} 10927~~~ 10928 10929Example response: 10930 10931~~~json 10932{ 10933 "jsonrpc": "2.0", 10934 "id": 1, 10935 "result": true 10936} 10937~~~ 10938 10939## OPAL 10940 10941### bdev_nvme_opal_init {#rpc_bdev_nvme_opal_init} 10942 10943This is used to initialize OPAL of a given NVMe ctrlr, including taking ownership and activating. 10944 10945#### Parameters 10946 10947Name | Optional | Type | Description 10948----------------------- | -------- | ----------- | ----------- 10949nvme_ctrlr_name | Required | string | name of nvme ctrlr 10950password | Required | string | admin password of OPAL 10951 10952#### Example 10953 10954Example request: 10955 10956~~~json 10957{ 10958 "jsonrpc": "2.0", 10959 "method": "bdev_nvme_opal_init", 10960 "id": 1, 10961 "params": { 10962 "nvme_ctrlr_name": "nvme0", 10963 "password": "*****" 10964 } 10965} 10966~~~ 10967 10968Example response: 10969 10970~~~json 10971{ 10972 "jsonrpc": "2.0", 10973 "id": 1, 10974 "result": true 10975} 10976~~~ 10977 10978### bdev_nvme_opal_revert {#rpc_bdev_nvme_opal_revert} 10979 10980This is used to revert OPAL to its factory settings. Erase all user configuration and data. 10981 10982#### Parameters 10983 10984Name | Optional | Type | Description 10985----------------------- | -------- | ----------- | ----------- 10986nvme_ctrlr_name | Required | string | name of nvme ctrlr 10987password | Required | string | admin password of OPAL 10988 10989#### Example 10990 10991Example request: 10992 10993~~~json 10994{ 10995 "jsonrpc": "2.0", 10996 "method": "bdev_nvme_opal_revert", 10997 "id": 1, 10998 "params": { 10999 "nvme_ctrlr_name": "nvme0", 11000 "password": "*****" 11001 } 11002} 11003~~~ 11004 11005Example response: 11006 11007~~~json 11008{ 11009 "jsonrpc": "2.0", 11010 "id": 1, 11011 "result": true 11012} 11013~~~ 11014 11015### bdev_opal_create {#rpc_bdev_opal_create} 11016 11017This is used to create an OPAL virtual bdev. 11018 11019#### Parameters 11020 11021Name | Optional | Type | Description 11022----------------------- | -------- | ----------- | ----------- 11023nvme_ctrlr_name | Required | string | name of nvme ctrlr that supports OPAL 11024nsid | Required | number | namespace ID 11025locking_range_id | Required | number | OPAL locking range ID 11026range_start | Required | number | locking range start LBA 11027range_length | Required | number | locking range length 11028password | Required | string | admin password of OPAL 11029 11030#### Response 11031 11032The response is the name of created OPAL virtual bdev. 11033 11034#### Example 11035 11036Example request: 11037 11038~~~json 11039{ 11040 "jsonrpc": "2.0", 11041 "method": "bdev_opal_create", 11042 "id": 1, 11043 "params": { 11044 "nvme_ctrlr_name": "nvme0", 11045 "nsid": 1, 11046 "locking_range_id": 1, 11047 "range_start": 0, 11048 "range_length": 4096, 11049 "password": "*****" 11050 } 11051} 11052~~~ 11053 11054Example response: 11055 11056~~~json 11057{ 11058 "jsonrpc": "2.0", 11059 "id": 1, 11060 "result": "nvme0n1r1" 11061} 11062~~~ 11063 11064### bdev_opal_get_info {#rpc_bdev_opal_get_info} 11065 11066This is used to get information of a given OPAL bdev. 11067 11068#### Parameters 11069 11070Name | Optional | Type | Description 11071----------------------- | -------- | ----------- | ----------- 11072bdev_name | Required | string | name of OPAL vbdev 11073password | Required | string | admin password 11074 11075#### Response 11076 11077The response is the locking info of OPAL virtual bdev. 11078 11079#### Example 11080 11081Example request: 11082 11083~~~json 11084{ 11085 "jsonrpc": "2.0", 11086 "method": "bdev_opal_get_info", 11087 "id": 1, 11088 "params": { 11089 "bdev_name": "nvme0n1r1", 11090 "password": "*****" 11091 } 11092} 11093~~~ 11094 11095Example response: 11096 11097~~~json 11098{ 11099 "jsonrpc": "2.0", 11100 "id": 1, 11101 "result": { 11102 "name": "nvme0n1r1", 11103 "range_start": 0, 11104 "range_length": 4096, 11105 "read_lock_enabled": true, 11106 "write_lock_enabled": true, 11107 "read_locked": false, 11108 "write_locked": false 11109 } 11110} 11111~~~ 11112 11113### bdev_opal_delete {#rpc_bdev_opal_delete} 11114 11115This is used to delete OPAL vbdev. 11116 11117#### Parameters 11118 11119Name | Optional | Type | Description 11120----------------------- | -------- | ----------- | ----------- 11121bdev_name | Required | string | name of OPAL vbdev 11122password | Required | string | admin password 11123 11124#### Example 11125 11126Example request: 11127 11128~~~json 11129{ 11130 "jsonrpc": "2.0", 11131 "method": "bdev_opal_delete", 11132 "id": 1, 11133 "params": { 11134 "bdev_name": "nvme0n1r1", 11135 "password": "*****" 11136 } 11137} 11138~~~ 11139 11140Example response: 11141 11142~~~json 11143{ 11144 "jsonrpc": "2.0", 11145 "id": 1, 11146 "result": true 11147} 11148~~~ 11149 11150### bdev_opal_new_user {#rpc_bdev_opal_new_user} 11151 11152This enables a new user to the specified opal bdev so that the user can lock/unlock the bdev. 11153Recalling this for the same opal bdev, only the newest user will have the privilege. 11154 11155#### Parameters 11156 11157Name | Optional | Type | Description 11158----------------------- | -------- | ----------- | ----------- 11159bdev_name | Required | string | name of OPAL vbdev 11160admin_password | Required | string | admin password 11161user_id | Required | number | user ID 11162user_password | Required | string | user password 11163 11164#### Example 11165 11166Example request: 11167 11168~~~json 11169{ 11170 "jsonrpc": "2.0", 11171 "method": "bdev_opal_new_user", 11172 "id": 1, 11173 "params": { 11174 "bdev_name": "nvme0n1r1", 11175 "admin_password": "*****", 11176 "user_id": "1", 11177 "user_password": "********" 11178 } 11179} 11180~~~ 11181 11182Example response: 11183 11184~~~json 11185{ 11186 "jsonrpc": "2.0", 11187 "id": 1, 11188 "result": true 11189} 11190~~~ 11191 11192### bdev_opal_set_lock_state {#rpc_bdev_opal_set_lock_state} 11193 11194This is used to lock/unlock specific opal bdev providing user ID and password. 11195 11196#### Parameters 11197 11198Name | Optional | Type | Description 11199----------------------- | -------- | ----------- | ----------- 11200bdev_name | Required | string | name of OPAL vbdev 11201user_id | Required | number | user ID 11202password | Required | string | user password 11203lock_state | Required | string | lock state 11204 11205#### Example 11206 11207Example request: 11208 11209~~~json 11210{ 11211 "jsonrpc": "2.0", 11212 "method": "bdev_opal_set_lock_state", 11213 "id": 1, 11214 "params": { 11215 "bdev_name": "nvme0n1r1", 11216 "user_id": "1", 11217 "user_password": "********", 11218 "lock_state": "rwlock" 11219 } 11220} 11221~~~ 11222 11223Example response: 11224 11225~~~json 11226{ 11227 "jsonrpc": "2.0", 11228 "id": 1, 11229 "result": true 11230} 11231~~~ 11232 11233## Notifications 11234 11235### notify_get_types {#rpc_notify_get_types} 11236 11237Return list of all supported notification types. 11238 11239#### Parameters 11240 11241None 11242 11243#### Response 11244 11245The response is an array of strings - supported RPC notification types. 11246 11247#### Example 11248 11249Example request: 11250 11251~~~json 11252{ 11253 "jsonrpc": "2.0", 11254 "method": "notify_get_types", 11255 "id": 1 11256} 11257~~~ 11258 11259Example response: 11260 11261~~~json 11262{ 11263 "id": 1, 11264 "result": [ 11265 "bdev_register", 11266 "bdev_unregister" 11267 ], 11268 "jsonrpc": "2.0" 11269} 11270~~~ 11271 11272### notify_get_notifications {#notify_get_notifications} 11273 11274Request notifications. Returns array of notifications that happened since the specified id (or first that is available). 11275 11276Notice: Notifications are kept in circular buffer with limited size. Older notifications might be inaccessible 11277due to being overwritten by new ones. 11278 11279#### Parameters 11280 11281Name | Optional | Type | Description 11282----------------------- | -------- | ----------- | ----------- 11283id | Optional | number | First Event ID to fetch (default: first available). 11284max | Optional | number | Maximum number of event to return (default: no limit). 11285 11286#### Response 11287 11288Response is an array of event objects. 11289 11290Name | Optional | Type | Description 11291----------------------- | -------- | ----------- | ----------- 11292id | Optional | number | Event ID. 11293type | Optional | number | Type of the event. 11294ctx | Optional | string | Event context. 11295 11296#### Example 11297 11298Example request: 11299 11300~~~json 11301{ 11302 "id": 1, 11303 "jsonrpc": "2.0", 11304 "method": "notify_get_notifications", 11305 "params": { 11306 "id": 1, 11307 "max": 10 11308 } 11309} 11310 11311~~~ 11312 11313Example response: 11314 11315~~~json 11316{ 11317 "jsonrpc": "2.0", 11318 "id": 1, 11319 "result": [ 11320 { 11321 "ctx": "Malloc0", 11322 "type": "bdev_register", 11323 "id": 1 11324 }, 11325 { 11326 "ctx": "Malloc2", 11327 "type": "bdev_register", 11328 "id": 2 11329 } 11330 ] 11331} 11332~~~ 11333 11334## Linux Userspace Block Device (UBLK) {#jsonrpc_components_ublk} 11335 11336SPDK supports exporting bdevs though Linux ublk. The motivation behind it is to back a Linux kernel block device 11337with an SPDK user space bdev. 11338 11339To export a device over ublk, first make sure the Linux kernel ublk driver is loaded by running 'modprobe ublk_drv'. 11340 11341### ublk_create_target {#rpc_ublk_create_target} 11342 11343Start to create ublk threads and initialize ublk target. It will return an error if user calls this RPC twice without 11344ublk_destroy_target in between. It will use current cpumask in SPDK when user does not specify cpumask option. 11345 11346#### Parameters 11347 11348Name | Optional | Type | Description 11349----------------------- | -------- | ----------- | ----------- 11350cpumask | Optional | string | Cpumask for ublk target 11351 11352#### Response 11353 11354True if ublk target initialization is successful; False if failed. 11355 11356#### Example 11357 11358Example request: 11359 11360~~~json 11361{ 11362 "params": { 11363 "cpumask": "0x2" 11364 }, 11365 "jsonrpc": "2.0", 11366 "method": "ublk_create_target", 11367 "id": 1 11368} 11369~~~ 11370 11371Example response: 11372 11373~~~json 11374{ 11375 "jsonrpc": "2.0", 11376 "id": 1, 11377 "result": true 11378} 11379~~~ 11380 11381### ublk_destroy_target {#rpc_ublk_destroy_target} 11382 11383Release all UBLK devices and destroy ublk target. 11384 11385#### Response 11386 11387True if ublk target destruction is successful; False if failed. 11388 11389#### Example 11390 11391Example request: 11392 11393~~~json 11394{ 11395 "jsonrpc": "2.0", 11396 "method": "ublk_destroy_target", 11397 "id": 1 11398} 11399~~~ 11400 11401Example response: 11402 11403~~~json 11404{ 11405 "jsonrpc": "2.0", 11406 "id": 1, 11407 "result": true 11408} 11409~~~ 11410 11411### ublk_start_disk {#rpc_ublk_start_disk} 11412 11413Start to export one SPDK bdev as a UBLK device 11414 11415#### Parameters 11416 11417Name | Optional | Type | Description 11418----------------------- | -------- | ----------- | ----------- 11419bdev_name | Required | string | Bdev name to export 11420ublk_id | Required | int | Device id 11421queue_depth | Optional | int | Device queue depth 11422num_queues | Optional | int | Total number of device queues 11423 11424#### Response 11425 11426UBLK device ID 11427 11428#### Example 11429 11430Example request: 11431 11432~~~json 11433{ 11434 "params": { 11435 "ublk_id": "1", 11436 "bdev_name": "Malloc1" 11437 }, 11438 "jsonrpc": "2.0", 11439 "method": "ublk_start_disk", 11440 "id": 1 11441} 11442~~~ 11443 11444Example response: 11445 11446~~~json 11447{ 11448 "jsonrpc": "2.0", 11449 "id": 1, 11450 "result": 1 11451} 11452~~~ 11453 11454### ublk_recover_disk {#rpc_ublk_recover_disk} 11455 11456Recover original UBLK device with ID and block device 11457 11458#### Parameters 11459 11460Name | Optional | Type | Description 11461----------------------- | -------- | ----------- | ----------- 11462bdev_name | Required | string | Bdev name to export 11463ublk_id | Required | int | Device id 11464 11465#### Response 11466 11467UBLK device ID 11468 11469#### Example 11470 11471Example request: 11472 11473~~~json 11474{ 11475 "params": { 11476 "ublk_id": "1", 11477 "bdev_name": "Malloc1" 11478 }, 11479 "jsonrpc": "2.0", 11480 "method": "ublk_recover_disk", 11481 "id": 1 11482} 11483~~~ 11484 11485Example response: 11486 11487~~~json 11488{ 11489 "jsonrpc": "2.0", 11490 "id": 1, 11491 "result": 1 11492} 11493 11494### ublk_stop_disk {#rpc_ublk_stop_disk} 11495 11496Delete a UBLK device 11497 11498#### Parameters 11499 11500Name | Optional | Type | Description 11501----------------------- | -------- | ----------- | ----------- 11502ublk_id | Required | int | Device id to delete 11503 11504#### Response 11505 11506True if UBLK device is deleted successfully; False if failed. 11507 11508#### Example 11509 11510Example request: 11511 11512~~~json 11513{ 11514 "params": { 11515 "ublk_id": "1", 11516 }, 11517 "jsonrpc": "2.0", 11518 "method": "ublk_stop_disk", 11519 "id": 1 11520} 11521~~~ 11522 11523Example response: 11524 11525~~~json 11526{ 11527 "jsonrpc": "2.0", 11528 "id": 1, 11529 "result": true 11530} 11531~~~ 11532 11533### ublk_get_disks {#rpc_ublk_get_disks} 11534 11535Display full or specified ublk device list 11536 11537#### Parameters 11538 11539Name | Optional | Type | Description 11540----------------------- | -------- | ----------- | ----------- 11541ublk_id | Optional | int | ublk device id to display 11542 11543#### Response 11544 11545Display ublk device list 11546 11547#### Example 11548 11549Example request: 11550 11551~~~json 11552{ 11553 "jsonrpc": "2.0", 11554 "method": "ublk_get_disks", 11555 "id": 1 11556} 11557~~~ 11558 11559Example response: 11560 11561~~~json 11562{ 11563 "jsonrpc": "2.0", 11564 "id": 1, 11565 "result": [ 11566 { 11567 "ublk_device": "/dev/ublkb1", 11568 "id": 1, 11569 "queue_depth": 512, 11570 "num_queues": 1, 11571 "bdev_name": "Malloc1" 11572 } 11573 ] 11574} 11575~~~ 11576 11577## Linux Network Block Device (NBD) {#jsonrpc_components_nbd} 11578 11579SPDK supports exporting bdevs through Linux nbd. These devices then appear as standard Linux kernel block devices 11580and can be accessed using standard utilities like fdisk. 11581 11582In order to export a device over nbd, first make sure the Linux kernel nbd driver is loaded by running 'modprobe nbd'. 11583 11584### nbd_start_disk {#rpc_nbd_start_disk} 11585 11586Start to export one SPDK bdev as NBD disk 11587 11588#### Parameters 11589 11590Name | Optional | Type | Description 11591----------------------- | -------- | ----------- | ----------- 11592bdev_name | Required | string | Bdev name to export 11593nbd_device | Optional | string | NBD device name to assign 11594 11595#### Response 11596 11597Path of exported NBD disk 11598 11599#### Example 11600 11601Example request: 11602 11603~~~json 11604{ 11605 "params": { 11606 "nbd_device": "/dev/nbd1", 11607 "bdev_name": "Malloc1" 11608 }, 11609 "jsonrpc": "2.0", 11610 "method": "nbd_start_disk", 11611 "id": 1 11612} 11613~~~ 11614 11615Example response: 11616 11617~~~json 11618{ 11619 "jsonrpc": "2.0", 11620 "id": 1, 11621 "result": "/dev/nbd1" 11622} 11623~~~ 11624 11625### nbd_stop_disk {#rpc_nbd_stop_disk} 11626 11627Stop one NBD disk which is based on SPDK bdev. 11628 11629#### Parameters 11630 11631Name | Optional | Type | Description 11632----------------------- | -------- | ----------- | ----------- 11633nbd_device | Required | string | NBD device name to stop 11634 11635#### Example 11636 11637Example request: 11638 11639~~~json 11640{ 11641 "params": { 11642 "nbd_device": "/dev/nbd1", 11643 }, 11644 "jsonrpc": "2.0", 11645 "method": "nbd_stop_disk", 11646 "id": 1 11647} 11648~~~ 11649 11650Example response: 11651 11652~~~json 11653{ 11654 "jsonrpc": "2.0", 11655 "id": 1, 11656 "result": "true" 11657} 11658~~~ 11659 11660### nbd_get_disks {#rpc_nbd_get_disks} 11661 11662Display all or specified NBD device list 11663 11664#### Parameters 11665 11666Name | Optional | Type | Description 11667----------------------- | -------- | ----------- | ----------- 11668nbd_device | Optional | string | NBD device name to display 11669 11670#### Response 11671 11672The response is an array of exported NBD devices and their corresponding SPDK bdev. 11673 11674#### Example 11675 11676Example request: 11677 11678~~~json 11679{ 11680 "jsonrpc": "2.0", 11681 "method": "nbd_get_disks", 11682 "id": 1 11683} 11684~~~ 11685 11686Example response: 11687 11688~~~json 11689{ 11690 "jsonrpc": "2.0", 11691 "id": 1, 11692 "result": [ 11693 { 11694 "bdev_name": "Malloc0", 11695 "nbd_device": "/dev/nbd0" 11696 }, 11697 { 11698 "bdev_name": "Malloc1", 11699 "nbd_device": "/dev/nbd1" 11700 } 11701 ] 11702} 11703~~~ 11704 11705## Blobfs {#jsonrpc_components_blobfs} 11706 11707### blobfs_detect {#rpc_blobfs_detect} 11708 11709Detect whether a blobfs exists on bdev. 11710 11711#### Parameters 11712 11713Name | Optional | Type | Description 11714----------------------- | -------- | ----------- | ----------- 11715bdev_name | Required | string | Block device name to detect blobfs 11716 11717#### Response 11718 11719True if a blobfs exists on the bdev; False otherwise. 11720 11721#### Example 11722 11723Example request: 11724 11725~~~json 11726{ 11727 "jsonrpc": "2.0", 11728 "id": 1, 11729 "method": "blobfs_detect", 11730 "params": { 11731 "bdev_name": "Malloc0" 11732 } 11733} 11734~~~ 11735 11736Example response: 11737 11738~~~json 11739{ 11740 "jsonrpc": "2.0", 11741 "id": 1, 11742 "result": "true" 11743} 11744~~~ 11745 11746### blobfs_create {#rpc_blobfs_create} 11747 11748Build blobfs on bdev. 11749 11750#### Parameters 11751 11752Name | Optional | Type | Description 11753----------------------- | -------- | ----------- | ----------- 11754bdev_name | Required | string | Block device name to create blobfs 11755cluster_sz | Optional | number | Size of cluster in bytes. Must be multiple of 4KiB page size, default and minimal value is 1M. 11756 11757#### Example 11758 11759Example request: 11760 11761~~~json 11762{ 11763 "jsonrpc": "2.0", 11764 "id": 1, 11765 "method": "blobfs_create", 11766 "params": { 11767 "bdev_name": "Malloc0", 11768 "cluster_sz": 1M 11769 } 11770} 11771~~~ 11772 11773Example response: 11774 11775~~~json 11776{ 11777 "jsonrpc": "2.0", 11778 "id": 1, 11779 "result": "true" 11780} 11781~~~ 11782 11783### blobfs_mount {#rpc_blobfs_mount} 11784 11785Mount a blobfs on bdev to one host path through FUSE 11786 11787#### Parameters 11788 11789Name | Optional | Type | Description 11790----------------------- | -------- | ----------- | ----------- 11791bdev_name | Required | string | Block device name where the blobfs is 11792mountpoint | Required | string | Mountpoint path in host to mount blobfs 11793 11794#### Example 11795 11796Example request: 11797 11798~~~json 11799{ 11800 "jsonrpc": "2.0", 11801 "id": 1, 11802 "method": ""blobfs_mount"", 11803 "params": { 11804 "bdev_name": "Malloc0", 11805 "mountpoint": "/mnt/" 11806 } 11807} 11808~~~ 11809 11810Example response: 11811 11812~~~json 11813{ 11814 "jsonrpc": "2.0", 11815 "id": 1, 11816 "result": "true" 11817} 11818~~~ 11819 11820### blobfs_set_cache_size {#rpc_blobfs_set_cache_size} 11821 11822Set cache pool size for blobfs filesystems. This RPC is only permitted when the cache pool is not already initialized. 11823 11824The cache pool is initialized when the first blobfs filesystem is initialized or loaded. It is freed when the all 11825initialized or loaded filesystems are unloaded. 11826 11827#### Parameters 11828 11829Name | Optional | Type | Description 11830----------------------- | -------- | ----------- | ----------- 11831size_in_mb | Required | number | Cache size in megabytes 11832 11833#### Response 11834 11835True if cache size is set successfully; False if failed to set. 11836 11837#### Example 11838 11839Example request: 11840 11841~~~json 11842{ 11843 "jsonrpc": "2.0", 11844 "id": 1, 11845 "method": "blobfs_set_cache_size", 11846 "params": { 11847 "size_in_mb": 512, 11848 } 11849} 11850~~~ 11851 11852Example response: 11853 11854~~~json 11855{ 11856 "jsonrpc": "2.0", 11857 "id": 1, 11858 "result": true 11859} 11860~~~ 11861 11862## Socket layer {#jsonrpc_components_sock} 11863 11864### sock_impl_get_options {#rpc_sock_impl_get_options} 11865 11866Get parameters for the socket layer implementation. 11867 11868#### Parameters 11869 11870Name | Optional | Type | Description 11871----------------------- | -------- | ----------- | ----------- 11872impl_name | Required | string | Name of socket implementation, e.g. posix 11873 11874#### Response 11875 11876Response is an object with current socket layer options for requested implementation. 11877 11878#### Example 11879 11880Example request: 11881 11882~~~json 11883{ 11884 "jsonrpc": "2.0", 11885 "method": "sock_impl_get_options", 11886 "id": 1, 11887 "params": { 11888 "impl_name": "posix" 11889 } 11890} 11891~~~ 11892 11893Example response: 11894 11895~~~json 11896{ 11897 "jsonrpc": "2.0", 11898 "id": 1, 11899 "result": { 11900 "recv_buf_size": 2097152, 11901 "send_buf_size": 2097152, 11902 "enable_recv_pipe": true, 11903 "enable_quickack": true, 11904 "enable_placement_id": 0, 11905 "enable_zerocopy_send_server": true, 11906 "enable_zerocopy_send_client": false, 11907 "zerocopy_threshold": 0, 11908 "tls_version": 13, 11909 "enable_ktls": false 11910 } 11911} 11912~~~ 11913 11914### sock_impl_set_options {#rpc_sock_impl_set_options} 11915 11916Set parameters for the socket layer implementation. 11917 11918#### Parameters 11919 11920Name | Optional | Type | Description 11921--------------------------- | -------- | ----------- | ----------- 11922impl_name | Required | string | Name of socket implementation, e.g. posix 11923recv_buf_size | Optional | number | Size of socket receive buffer in bytes 11924send_buf_size | Optional | number | Size of socket send buffer in bytes 11925enable_recv_pipe | Optional | boolean | Enable or disable receive pipe 11926enable_quick_ack | Optional | boolean | Enable or disable quick ACK 11927enable_placement_id | Optional | number | Enable or disable placement_id. 0:disable,1:incoming_napi,2:incoming_cpu 11928enable_zerocopy_send_server | Optional | boolean | Enable or disable zero copy on send for server sockets 11929enable_zerocopy_send_client | Optional | boolean | Enable or disable zero copy on send for client sockets 11930zerocopy_threshold | Optional | number | Set zerocopy_threshold in bytes. A consecutive sequence of requests' iovecs 11931-- | -- | -- | that fall below this threshold may be sent without zerocopy flag set 11932tls_version | Optional | number | TLS protocol version, e.g. 13 for v1.3 (only applies when impl_name == ssl) 11933enable_ktls | Optional | boolean | Enable or disable Kernel TLS (only applies when impl_name == ssl) 11934 11935#### Response 11936 11937True if socket layer options were set successfully. 11938 11939#### Example 11940 11941Example request: 11942 11943~~~json 11944{ 11945 "jsonrpc": "2.0", 11946 "method": "sock_impl_set_options", 11947 "id": 1, 11948 "params": { 11949 "impl_name": "posix", 11950 "recv_buf_size": 2097152, 11951 "send_buf_size": 2097152, 11952 "enable_recv_pipe": false, 11953 "enable_quick_ack": false, 11954 "enable_placement_id": 0, 11955 "enable_zerocopy_send_server": true, 11956 "enable_zerocopy_send_client": false, 11957 "zerocopy_threshold": 10240, 11958 "tls_version": 13, 11959 "enable_ktls": false 11960 } 11961} 11962~~~ 11963 11964Example response: 11965 11966~~~json 11967{ 11968 "jsonrpc": "2.0", 11969 "id": 1, 11970 "result": true 11971} 11972~~~ 11973 11974### sock_set_default_impl {#rpc_sock_set_default_impl} 11975 11976Set the default sock implementation. 11977 11978#### Parameters 11979 11980Name | Optional | Type | Description 11981----------------------- | -------- | ----------- | ----------- 11982impl_name | Required | string | Name of socket implementation, e.g. posix 11983 11984#### Response 11985 11986True if the default socket layer configuration was set successfully. 11987 11988#### Example 11989 11990Example request: 11991 11992~~~json 11993{ 11994 "jsonrpc": "2.0", 11995 "method": "sock_set_default_impl", 11996 "id": 1, 11997 "params": { 11998 "impl_name": "posix" 11999 } 12000} 12001~~~ 12002 12003Example response: 12004 12005~~~json 12006{ 12007 "jsonrpc": "2.0", 12008 "id": 1, 12009 "result": true 12010} 12011~~~ 12012 12013## Miscellaneous RPC commands 12014 12015### bdev_nvme_send_cmd {#rpc_bdev_nvme_send_cmd} 12016 12017Send NVMe command directly to NVMe controller or namespace. Parameters and responses encoded by base64 urlsafe need further processing. 12018 12019Notice: bdev_nvme_send_cmd requires user to guarantee the correctness of NVMe command itself, and also optional parameters. 12020Illegal command contents or mismatching buffer size may result in unpredictable behavior. 12021 12022#### Parameters 12023 12024Name | Optional | Type | Description 12025----------------------- | -------- | ----------- | ----------- 12026name | Required | string | Name of the operating NVMe controller 12027cmd_type | Required | string | Type of nvme cmd. Valid values are: admin, io 12028data_direction | Required | string | Direction of data transfer. Valid values are: c2h, h2c 12029cmdbuf | Required | string | NVMe command encoded by base64 urlsafe 12030data | Optional | string | Data transferring to controller from host, encoded by base64 urlsafe 12031metadata | Optional | string | Metadata transferring to controller from host, encoded by base64 urlsafe 12032data_len | Optional | number | Data length required to transfer from controller to host 12033metadata_len | Optional | number | Metadata length required to transfer from controller to host 12034timeout_ms | Optional | number | Command execution timeout value, in milliseconds 12035 12036#### Response 12037 12038Name | Type | Description 12039----------------------- | ----------- | ----------- 12040cpl | string | NVMe completion queue entry, encoded by base64 urlsafe 12041data | string | Data transferred from controller to host, encoded by base64 urlsafe 12042metadata | string | Metadata transferred from controller to host, encoded by base64 urlsafe 12043 12044#### Example 12045 12046Example request: 12047 12048~~~json 12049{ 12050 "jsonrpc": "2.0", 12051 "method": "bdev_nvme_send_cmd", 12052 "id": 1, 12053 "params": { 12054 "name": "Nvme0", 12055 "cmd_type": "admin" 12056 "data_direction": "c2h", 12057 "cmdbuf": "BgAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAsGUs9P5_AAAAAAAAABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==", 12058 "data_len": 60, 12059 } 12060} 12061~~~ 12062 12063Example response: 12064 12065~~~json 12066{ 12067 "jsonrpc": "2.0", 12068 "id": 1, 12069 "result": { 12070 "cpl": "AAAAAAAAAAARAAAAWrmwABAA==", 12071 "data": "sIjg6AAAAACwiODoAAAAALCI4OgAAAAAAAYAAREAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" 12072 } 12073 12074} 12075~~~ 12076 12077### vmd_enable {#rpc_enable_vmd} 12078 12079Enable VMD enumeration. 12080 12081#### Parameters 12082 12083This method has no parameters. 12084 12085#### Response 12086 12087Completion status of enumeration is returned as a boolean. 12088 12089### Example 12090 12091Example request: 12092 12093~~~json 12094{ 12095 "jsonrpc": "2.0", 12096 "method": "vmd_enable", 12097 "id": 1 12098} 12099~~~ 12100 12101Example response: 12102 12103~~~json 12104{ 12105 "jsonrpc": "2.0", 12106 "id": 1, 12107 "result": true 12108} 12109~~~ 12110 12111### vmd_remove_device {#rpc_vmd_remove_device} 12112 12113Remove a device behind a VMD. 12114 12115### Parameters 12116 12117Name | Optional | Type | Description 12118----------------------- | -------- | ----------- | ----------- 12119addr | Required | string | Address of the device to remove. 12120 12121### Example 12122 12123~~~json 12124{ 12125 "jsonrpc": "2.0", 12126 "method": "vmd_remove_device", 12127 "params": { 12128 "addr": "5d0505:01:00.0" 12129 } 12130 "id": 1 12131} 12132~~~ 12133 12134Example response: 12135 12136~~~json 12137{ 12138 "jsonrpc": "2.0", 12139 "id": 1, 12140 "result": true 12141} 12142~~~ 12143 12144### vmd_rescan {#rpc_vmd_rescan} 12145 12146Force a rescan of the devices behind VMD. 12147 12148### Parameters 12149 12150This method has no parameters. 12151 12152#### Response 12153 12154The response is the number of new devices found. 12155 12156### Example 12157 12158~~~json 12159{ 12160 "jsonrpc": "2.0", 12161 "method": "vmd_rescan", 12162 "id": 1 12163} 12164~~~ 12165 12166Example response: 12167 12168~~~json 12169{ 12170 "jsonrpc": "2.0", 12171 "id": 1, 12172 "result": { 12173 "count": 1 12174 } 12175} 12176~~~ 12177 12178### spdk_get_version {#rpc_spdk_get_version} 12179 12180Get the version info of the running SPDK application. 12181 12182#### Parameters 12183 12184This method has no parameters. 12185 12186#### Response 12187 12188The response is the version number including major version number, minor version number, patch level number and suffix string. 12189 12190#### Example 12191 12192Example request: 12193 12194~~~json 12195{ 12196 "jsonrpc": "2.0", 12197 "id": 1, 12198 "method": "spdk_get_version" 12199} 12200~~~ 12201 12202Example response: 12203 12204~~~json 12205{ 12206 "jsonrpc": "2.0", 12207 "id": 1, 12208 "result": { 12209 "version": "19.04-pre", 12210 "fields" : { 12211 "major": 19, 12212 "minor": 4, 12213 "patch": 0, 12214 "suffix": "-pre" 12215 } 12216 } 12217} 12218~~~ 12219 12220### framework_get_pci_devices 12221 12222List PCIe devices attached to an SPDK application and the contents of their config space. 12223 12224#### Parameters 12225 12226This method has no parameters. 12227 12228#### Response 12229 12230The response is an array of attached PCIe devices. 12231 12232#### Example 12233 12234Example request: 12235 12236~~~json 12237{ 12238 "jsonrpc": "2.0", 12239 "id": 1, 12240 "method": "framework_get_pci_devices" 12241} 12242~~~ 12243 12244Example response: 12245Note that the config space buffer was trimmed. 12246 12247~~~json 12248{ 12249 "jsonrpc": "2.0", 12250 "id": 1, 12251 "result": { 12252 [ 12253 { 12254 "address": "0000:00:04.0", 12255 "config_space": "8680455807051000...0000000000000000" 12256 }, 12257 { 12258 "address": "0000:00:03.0", 12259 "config_space": "8680455807051000...0000000000000000" 12260 } 12261 ] 12262 } 12263} 12264~~~ 12265 12266### bdev_nvme_add_error_injection {#rpc_bdev_nvme_add_error_injection} 12267 12268Add a NVMe command error injection for a bdev nvme controller. 12269 12270#### Parameters 12271 12272Name | Optional | Type | Description 12273----------------------- | -------- | ----------- | ----------- 12274name | Required | string | Name of the operating NVMe controller 12275cmd_type | Required | string | Type of NVMe command. Valid values are: admin, io 12276opc | Required | number | Opcode for which the error injection is applied 12277do_not_submit | Optional | boolean | Set to true if request should not be submitted to the controller (default false) 12278timeout_in_us | Optional | number | Wait specified microseconds when do_not_submit is true 12279err_count | Optional | number | Number of matching NVMe commands to inject errors 12280sct | Optional | number | Status code type (default 0) 12281sc | Optional | number | Status code (default 0) 12282 12283#### Response 12284 12285true on success 12286 12287#### Example 12288 12289Example request: 12290 12291~~~json 12292{ 12293 "jsonrpc": "2.0", 12294 "method": "bdev_nvme_add_error_injection", 12295 "id": 1, 12296 "params": { 12297 "name": "HotInNvme0", 12298 "opc": 2, 12299 "cmd_type": "io", 12300 "err_count": 1111111, 12301 "sct": 11, 12302 "sc": 33 12303 } 12304} 12305 12306~~~ 12307 12308Example response: 12309 12310~~~json 12311{ 12312 "jsonrpc": "2.0", 12313 "id": 1, 12314 "result": true 12315} 12316 12317~~~ 12318 12319### bdev_nvme_remove_error_injection {#rpc_bdev_nvme_remove_error_injection} 12320 12321Remove a NVMe command error injection. 12322 12323#### Parameters 12324 12325Name | Optional | Type | Description 12326----------------------- | -------- | ----------- | ----------- 12327name | Required | string | Name of the operating NVMe controller 12328cmd_type | Required | string | Type of NVMe command. Valid values are: admin, io 12329opc | Required | number | Opcode for which the error injection is applied 12330 12331#### Response 12332 12333true on success 12334 12335#### Example 12336 12337Example request: 12338 12339~~~json 12340{ 12341 "jsonrpc": "2.0", 12342 "method": "bdev_nvme_remove_error_injection", 12343 "id": 1, 12344 "params": { 12345 "name": "HotInNvme0", 12346 "opc": 2, 12347 "cmd_type": "io" 12348 } 12349} 12350 12351 12352~~~ 12353 12354Example response: 12355 12356~~~json 12357{ 12358 "jsonrpc": "2.0", 12359 "id": 1, 12360 "result": true 12361} 12362 12363~~~ 12364 12365### bdev_daos_create {#rpc_bdev_daos_create} 12366 12367Construct @ref bdev_config_daos 12368 12369#### Parameters 12370 12371Name | Optional | Type | Description 12372----------------------- | -------- | ----------- | ----------- 12373name | Required | string | Bdev name to use 12374pool | Required | string | DAOS pool label or its uuid 12375cont | Required | string | DAOS cont label or its uuid 12376block_size | Required | number | Block size in bytes -must be multiple of 512 12377num_blocks | Required | number | Number of blocks 12378uuid | Optional | string | UUID of new bdev 12379oclass | Optional | string | DAOS object class (default SX) 12380 12381To find more about various object classes please visit [DAOS documentation](https://github.com/daos-stack/daos/blob/master/src/object/README.md). 12382Please note, that DAOS bdev module uses the same CLI flag notation as `dmg` and `daos` commands, 12383for instance, `SX` or `EC_4P2G2` rather than in DAOS header file `OC_SX` or `OC_EC_4P2G2`. 12384 12385#### Result 12386 12387Name of newly created bdev. 12388 12389#### Example 12390 12391Example request: 12392 12393~~~json 12394{ 12395 "params": { 12396 "block_size": 4096, 12397 "num_blocks": 16384, 12398 "name": "daosdev0", 12399 "pool": "test-pool", 12400 "cont": "test-cont", 12401 "oclass": "EC_4P2G2" 12402 }, 12403 "jsonrpc": "2.0", 12404 "method": "bdev_daos_create", 12405 "id": 1 12406} 12407~~~ 12408 12409Example response: 12410 12411~~~json 12412{ 12413 "jsonrpc": "2.0", 12414 "id": 1, 12415 "result": "daosdev0" 12416} 12417~~~ 12418 12419### bdev_daos_delete {#rpc_bdev_daos_delete} 12420 12421Delete @ref bdev_config_daos 12422 12423#### Parameters 12424 12425Name | Optional | Type | Description 12426----------------------- | -------- | ----------- | ----------- 12427name | Required | string | Bdev name 12428 12429#### Example 12430 12431Example request: 12432 12433~~~json 12434{ 12435 "params": { 12436 "name": "daosdev0" 12437 }, 12438 "jsonrpc": "2.0", 12439 "method": "bdev_daos_delete", 12440 "id": 1 12441} 12442~~~ 12443 12444Example response: 12445 12446~~~json 12447{ 12448 "jsonrpc": "2.0", 12449 "id": 1, 12450 "result": true 12451} 12452~~~ 12453 12454### bdev_daos_resize {#rpc_bdev_daos_resize} 12455 12456Resize @ref bdev_config_daos. 12457 12458#### Parameters 12459 12460Name | Optional | Type | Description 12461----------------------- | -------- | ----------- | ----------- 12462name | Required | string | Bdev name 12463new_size | Required | number | Bdev new capacity in MiB 12464 12465#### Example 12466 12467Example request: 12468 12469~~~json 12470{ 12471 "params": { 12472 "name": "daosdev0", 12473 "new_size": 8192 12474 }, 12475 "jsonrpc": "2.0", 12476 "method": "bdev_daos_resize", 12477 "id": 1 12478} 12479~~~ 12480 12481Example response: 12482 12483~~~json 12484{ 12485 "jsonrpc": "2.0", 12486 "id": 1, 12487 "result": true 12488} 12489~~~ 12490 12491### iobuf_set_options {#rpc_iobuf_set_options} 12492 12493Set iobuf buffer pool options. 12494 12495#### Parameters 12496 12497Name | Optional | Type | Description 12498----------------------- | -------- | ----------- | ----------- 12499small_pool_count | Optional | number | Number of small buffers in the global pool 12500large_pool_count | Optional | number | Number of large buffers in the global pool 12501small_bufsize | Optional | number | Size of a small buffer 12502large_bufsize | Optional | number | Size of a small buffer 12503 12504#### Example 12505 12506Example request: 12507 12508~~~json 12509{ 12510 "jsonrpc": "2.0", 12511 "id": 1, 12512 "method": "iobuf_set_options", 12513 "params": { 12514 "small_pool_count": 16383, 12515 "large_pool_count": 2047 12516 } 12517} 12518~~~ 12519 12520Example response: 12521 12522~~~json 12523{ 12524 "jsonrpc": "2.0", 12525 "id": 1, 12526 "result": true 12527} 12528~~~ 12529 12530### iobuf_get_stats {#rpc_iobuf_get_stats} 12531 12532Retrieve iobuf's statistics. 12533 12534#### Parameters 12535 12536None. 12537 12538#### Example 12539 12540Example request: 12541 12542~~~json 12543{ 12544 "jsonrpc": "2.0", 12545 "method": "iobuf_get_stats", 12546 "id": 1 12547} 12548~~~ 12549 12550Example response: 12551 12552~~~json 12553{ 12554 "jsonrpc": "2.0", 12555 "id": 1, 12556 "result": [ 12557 { 12558 "module": "accel", 12559 "small_pool": { 12560 "cache": 0, 12561 "main": 0, 12562 "retry": 0 12563 }, 12564 "large_pool": { 12565 "cache": 0, 12566 "main": 0, 12567 "retry": 0 12568 } 12569 }, 12570 { 12571 "module": "bdev", 12572 "small_pool": { 12573 "cache": 421965, 12574 "main": 1218, 12575 "retry": 0 12576 }, 12577 "large_pool": { 12578 "cache": 0, 12579 "main": 0, 12580 "retry": 0 12581 } 12582 }, 12583 { 12584 "module": "nvmf_TCP", 12585 "small_pool": { 12586 "cache": 7, 12587 "main": 0, 12588 "retry": 0 12589 }, 12590 "large_pool": { 12591 "cache": 0, 12592 "main": 0, 12593 "retry": 0 12594 } 12595 } 12596 ] 12597} 12598~~~ 12599 12600### bdev_nvme_start_mdns_discovery {#rpc_bdev_nvme_start_mdns_discovery} 12601 12602Starts an mDNS based discovery service for the specified service type for the 12603auto-discovery of discovery controllers (NVMe TP-8009). 12604 12605The discovery service will listen for the mDNS discovery events from the 12606Avahi-daemon and will connect to the newly learnt discovery controllers. 12607Then the discovery service will automatically attach to any subsystem found in the 12608discovery log page from the discovery controllers learnt using mDNS. 12609When determining a controller name to use when attaching, it will use 12610the 'name' parameter as a prefix, followed by a unique integer assigned for each of the 12611discovery controllers learnt through mDNS, followed by a unique integer for that discovery 12612service. If the discovery service identifies a subsystem that has been previously 12613attached but is listed with a different path, it will use the same controller name 12614as the previous entry, and connect as a multipath. 12615 12616When the discovery service sees that a subsystem entry has been removed 12617from the log page, it will automatically detach from that controller as well. 12618 12619The 'name' is also used to later stop the discovery service. 12620 12621#### Parameters 12622 12623Name | Optional | Type | Description 12624-------------------------- | -------- | ----------- | ----------- 12625name | Required | string | Prefix for NVMe discovery services found 12626svcname | Required | string | Service to discover: e.g. _nvme-disc._tcp 12627hostnqn | Optional | string | NVMe-oF hostnqn 12628 12629#### Example 12630 12631Example request: 12632 12633~~~json 12634{ 12635 "jsonrpc": "2.0", 12636 "method": "bdev_nvme_start_mdns_discovery", 12637 "id": 1, 12638 "params": { 12639 "name": "cdc_auto", 12640 "svcname": "_nvme-disc._tcp", 12641 "hostnqn": "nqn.2021-12.io.spdk:host1", 12642 } 12643} 12644~~~ 12645 12646Example response: 12647 12648~~~json 12649{ 12650 "jsonrpc": "2.0", 12651 "id": 1, 12652 "result": true 12653} 12654~~~ 12655 12656### bdev_nvme_stop_mdns_discovery {#rpc_bdev_nvme_stop_mdns_discovery} 12657 12658Stops a mDNS discovery service. This includes detaching any controllers that were 12659discovered via the service that is being stopped. 12660 12661#### Parameters 12662 12663Name | Optional | Type | Description 12664-------------------------- | -------- | ----------- | ----------- 12665name | Required | string | Name of mDNS discovery instance to stop 12666 12667#### Example 12668 12669Example request: 12670 12671~~~json 12672{ 12673 "jsonrpc": "2.0", 12674 "method": "bdev_nvme_stop_mdns_discovery", 12675 "id": 1, 12676 "params": { 12677 "name": "cdc_auto" 12678 } 12679} 12680~~~ 12681 12682Example response: 12683 12684~~~json 12685{ 12686 "jsonrpc": "2.0", 12687 "id": 1, 12688 "result": true 12689} 12690~~~ 12691 12692### bdev_nvme_get_mdns_discovery_info {#rpc_bdev_nvme_get_mdns_discovery_info} 12693 12694Get the information about the mDNS discovery service instances. 12695 12696#### Example 12697 12698Example request: 12699~~~json 12700{ 12701 "jsonrpc": "2.0", 12702 "method": "bdev_nvme_get_mdns_discovery_info", 12703 "id": 1 12704} 12705~~~ 12706 12707Example response: 12708 12709~~~json 12710[ 12711 { 12712 "name": "cdc_auto", 12713 "svcname": "_nvme-disc._tcp", 12714 "referrals": [ 12715 { 12716 "name": "cdc_auto0", 12717 "trid": { 12718 "trtype": "TCP", 12719 "adrfam": "IPv4", 12720 "traddr": "66.1.2.21", 12721 "trsvcid": "8009", 12722 "subnqn": "nqn.2014-08.org.nvmexpress.discovery" 12723 } 12724 }, 12725 { 12726 "name": "cdc_auto1", 12727 "trid": { 12728 "trtype": "TCP", 12729 "adrfam": "IPv4", 12730 "traddr": "66.1.1.21", 12731 "trsvcid": "8009", 12732 "subnqn": "nqn.2014-08.org.nvmexpress.discovery" 12733 } 12734 } 12735 ] 12736 } 12737] 12738~~~ 12739