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