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