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