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` 9037dhchap_digests | Optional | list | List of allowed DH-HMAC-CHAP digests. 9038dhchap_dhgroups | Optional | list | List of allowed DH-HMAC-CHAP DH groups. 9039 9040#### admin_cmd_passthru {#spdk_nvmf_admin_passthru_conf} 9041 9042Name | Optional | Type | Description 9043----------------------- | -------- | ----------- | ----------- 9044identify_ctrlr | Required | bool | If true, enables custom identify handler that reports some identify attributes from the underlying NVMe drive 9045 9046#### Example 9047 9048Example request: 9049 9050~~~json 9051{ 9052 "jsonrpc": "2.0", 9053 "id": 1, 9054 "method": "nvmf_set_config", 9055 "params": { 9056 "acceptor_poll_rate": 10000 9057 } 9058} 9059~~~ 9060 9061Example response: 9062 9063~~~json 9064{ 9065 "jsonrpc": "2.0", 9066 "id": 1, 9067 "result": true 9068} 9069~~~ 9070 9071### nvmf_get_transports method {#rpc_nvmf_get_transports} 9072 9073#### Parameters 9074 9075The user may specify no parameters in order to list all transports, or a transport may be 9076specified by type. 9077 9078Name | Optional | Type | Description 9079--------------------------- | -------- | ------------| ----------- 9080tgt_name | Optional | string | Parent NVMe-oF target name. 9081trtype | Optional | string | Transport type. 9082 9083#### Example 9084 9085Example request: 9086 9087~~~json 9088{ 9089 "jsonrpc": "2.0", 9090 "id": 1, 9091 "method": "nvmf_get_transports" 9092} 9093~~~ 9094 9095Example response: 9096 9097~~~json 9098{ 9099 "jsonrpc": "2.0", 9100 "id": 1, 9101 "result": [ 9102 { 9103 "type": "RDMA". 9104 "max_queue_depth": 128, 9105 "max_io_qpairs_per_ctrlr": 64, 9106 "in_capsule_data_size": 4096, 9107 "max_io_size": 131072, 9108 "io_unit_size": 131072, 9109 "abort_timeout_sec": 1 9110 } 9111 ] 9112} 9113~~~ 9114 9115### nvmf_get_stats method {#rpc_nvmf_get_stats} 9116 9117Retrieve current statistics of the NVMf subsystem. 9118 9119#### Parameters 9120 9121Name | Optional | Type | Description 9122--------------------------- | -------- | ------------| ----------- 9123tgt_name | Optional | string | Parent NVMe-oF target name. 9124 9125#### Response 9126 9127The response is an object containing NVMf subsystem statistics. 9128In the response, `admin_qpairs` and `io_qpairs` are reflecting cumulative queue pair counts while 9129`current_admin_qpairs` and `current_io_qpairs` are showing the current number. 9130 9131#### Example 9132 9133Example request: 9134 9135~~~json 9136{ 9137 "jsonrpc": "2.0", 9138 "method": "nvmf_get_stats", 9139 "id": 1 9140} 9141~~~ 9142 9143Example response: 9144 9145~~~json 9146{ 9147 "jsonrpc": "2.0", 9148 "id": 1, 9149 "result": { 9150 "tick_rate": 2400000000, 9151 "poll_groups": [ 9152 { 9153 "name": "app_thread", 9154 "admin_qpairs": 1, 9155 "io_qpairs": 4, 9156 "current_admin_qpairs": 1, 9157 "current_io_qpairs": 2, 9158 "pending_bdev_io": 1721, 9159 "transports": [ 9160 { 9161 "trtype": "RDMA", 9162 "pending_data_buffer": 12131888, 9163 "devices": [ 9164 { 9165 "name": "mlx5_1", 9166 "polls": 72284105, 9167 "completions": 0, 9168 "requests": 0, 9169 "request_latency": 0, 9170 "pending_free_request": 0, 9171 "pending_rdma_read": 0, 9172 "pending_rdma_write": 0, 9173 "total_send_wrs": 0, 9174 "send_doorbell_updates": 0, 9175 "total_recv_wrs": 0, 9176 "recv_doorbell_updates": 1 9177 }, 9178 { 9179 "name": "mlx5_0", 9180 "polls": 72284105, 9181 "completions": 15165875, 9182 "requests": 7582935, 9183 "request_latency": 1249323766184, 9184 "pending_free_request": 0, 9185 "pending_rdma_read": 337602, 9186 "pending_rdma_write": 0, 9187 "total_send_wrs": 15165875, 9188 "send_doorbell_updates": 1516587, 9189 "total_recv_wrs": 15165875, 9190 "recv_doorbell_updates": 1516587 9191 } 9192 ] 9193 } 9194 ] 9195 } 9196 ] 9197 } 9198} 9199~~~ 9200 9201### nvmf_set_crdt {#rpc_nvmf_set_crdt} 9202 9203Set the 3 CRDT (Command Retry Delay Time) values. For details about 9204CRDT, please refer to the NVMe specification. Currently all the 9205SPDK nvmf subsystems share the same CRDT values. The default values 9206are 0. This rpc can only be invoked in STARTUP stage. All values are 9207in units of 100 milliseconds (same as the NVMe specification). 9208 9209#### Parameters 9210 9211Name | Optional | Type | Description 9212----------------------- | -------- | ----------- | ----------- 9213crdt1 | Optional | number | Command Retry Delay Time 1 9214crdt2 | Optional | number | Command Retry Delay Time 2 9215crdt3 | Optional | number | Command Retry Delay Time 3 9216 9217## Vfio-user Target 9218 9219### vfu_tgt_set_base_path {#rpc_vfu_tgt_set_base_path} 9220 9221Set base path of Unix Domain socket file. 9222 9223#### Parameters 9224 9225Name | Optional | Type | Description 9226----------------------- | -------- | ----------- | ----------- 9227path | Required | string | Base path 9228 9229#### Example 9230 9231Example request: 9232 9233~~~json 9234{ 9235 "params": { 9236 "path": "/var/run/vfu_tgt" 9237 }, 9238 "jsonrpc": "2.0", 9239 "method": "vfu_tgt_set_base_path", 9240 "id": 1 9241} 9242~~~ 9243 9244Example response: 9245 9246~~~json 9247{ 9248 "jsonrpc": "2.0", 9249 "id": 1, 9250 "result": true 9251} 9252~~~ 9253 9254### vfu_virtio_delete_endpoint {#rpc_vfu_virtio_delete_endpoint} 9255 9256Delete PCI device via endpoint name. 9257 9258#### Parameters 9259 9260Name | Optional | Type | Description 9261----------------------- | -------- | ----------- | ----------- 9262name | Required | string | Endpoint name 9263 9264#### Example 9265 9266Example request: 9267 9268~~~json 9269{ 9270 "params": { 9271 "name": "vfu.0" 9272 }, 9273 "jsonrpc": "2.0", 9274 "method": "vfu_virtio_delete_endpoint", 9275 "id": 1 9276} 9277~~~ 9278 9279Example response: 9280 9281~~~json 9282{ 9283 "jsonrpc": "2.0", 9284 "id": 1, 9285 "result": true 9286} 9287~~~ 9288 9289### vfu_virtio_create_blk_endpoint {#rpc_vfu_virtio_create_blk_endpoint} 9290 9291Create vfio-user virtio-blk PCI endpoint. 9292 9293#### Parameters 9294 9295Name | Optional | Type | Description 9296----------------------- | -------- | ----------- | ----------- 9297name | Required | string | Endpoint name 9298bdev_name | Required | string | Block device name 9299cpumask | Optional | string | CPU masks 9300num_queues | Optional | number | Number of queues 9301qsize | Optional | number | Queue size 9302packed_ring | Optional | boolean | Enable packed ring 9303 9304#### Example 9305 9306Example request: 9307 9308~~~json 9309{ 9310 "params": { 9311 "name": "vfu.0", 9312 "bdev_name": "Malloc0", 9313 "cpumask": "0x2", 9314 "num_queues": 4, 9315 "qsize": 256 9316 }, 9317 "jsonrpc": "2.0", 9318 "method": "vfu_virtio_create_blk_endpoint", 9319 "id": 1 9320} 9321~~~ 9322 9323Example response: 9324 9325~~~json 9326{ 9327 "jsonrpc": "2.0", 9328 "id": 1, 9329 "result": true 9330} 9331~~~ 9332 9333### vfu_virtio_scsi_add_target {#rpc_vfu_virtio_scsi_add_target} 9334 9335Add block device to specified SCSI target of vfio-user virtio-scsi PCI endpoint. 9336 9337#### Parameters 9338 9339Name | Optional | Type | Description 9340----------------------- | -------- | ----------- | ----------- 9341name | Required | string | Endpoint name 9342scsi_target_num | Required | number | SCSI target number 9343bdev_name | Required | string | Block device name 9344 9345#### Example 9346 9347Example request: 9348 9349~~~json 9350{ 9351 "params": { 9352 "name": "vfu.0", 9353 "scsi_target_num": 0, 9354 "bdev_name": "Malloc0" 9355 }, 9356 "jsonrpc": "2.0", 9357 "method": "vfu_virtio_scsi_add_target", 9358 "id": 1 9359} 9360~~~ 9361 9362Example response: 9363 9364~~~json 9365{ 9366 "jsonrpc": "2.0", 9367 "id": 1, 9368 "result": true 9369} 9370~~~ 9371 9372### vfu_virtio_scsi_remove_target {#rpc_vfu_virtio_scsi_remove_target} 9373 9374Remove a SCSI target of vfio-user virtio-scsi PCI endpoint. 9375 9376#### Parameters 9377 9378Name | Optional | Type | Description 9379----------------------- | -------- | ----------- | ----------- 9380name | Required | string | Endpoint name 9381scsi_target_num | Required | number | SCSI target number 9382 9383#### Example 9384 9385Example request: 9386 9387~~~json 9388{ 9389 "params": { 9390 "name": "vfu.0", 9391 "scsi_target_num": 0 9392 }, 9393 "jsonrpc": "2.0", 9394 "method": "vfu_virtio_scsi_remove_target", 9395 "id": 1 9396} 9397~~~ 9398 9399Example response: 9400 9401~~~json 9402{ 9403 "jsonrpc": "2.0", 9404 "id": 1, 9405 "result": true 9406} 9407~~~ 9408 9409### vfu_virtio_create_scsi_endpoint {#rpc_vfu_virtio_create_scsi_endpoint} 9410 9411Create vfio-user virtio-scsi PCI endpoint. 9412 9413#### Parameters 9414 9415Name | Optional | Type | Description 9416----------------------- | -------- | ----------- | ----------- 9417name | Required | string | Endpoint name 9418cpumask | Optional | string | CPU masks 9419num_io_queues | Optional | number | Number of IO queues 9420qsize | Optional | number | Queue size 9421packed_ring | Optional | boolean | Enable packed ring 9422 9423#### Example 9424 9425Example request: 9426 9427~~~json 9428{ 9429 "params": { 9430 "name": "vfu.0", 9431 "cpumask": "0x2", 9432 "num_io_queues": 4, 9433 "qsize": 256 9434 }, 9435 "jsonrpc": "2.0", 9436 "method": "vfu_virtio_create_scsi_endpoint", 9437 "id": 1 9438} 9439~~~ 9440 9441Example response: 9442 9443~~~json 9444{ 9445 "jsonrpc": "2.0", 9446 "id": 1, 9447 "result": true 9448} 9449~~~ 9450 9451## Vhost Target {#jsonrpc_components_vhost_tgt} 9452 9453The following common preconditions need to be met in all target types. 9454 9455Controller name will be used to create UNIX domain socket. This implies that name concatenated with vhost socket 9456directory path needs to be valid UNIX socket name. 9457 9458@ref cpu_mask parameter is used to choose CPU on which pollers will be launched when new initiator is connecting. 9459It must be a subset of application CPU mask. Default value is CPU mask of the application. 9460 9461### vhost_controller_set_coalescing {#rpc_vhost_controller_set_coalescing} 9462 9463Controls interrupt coalescing for specific target. Because `delay_base_us` is used to calculate delay in CPU ticks 9464there is no hardcoded limit for this parameter. Only limitation is that final delay in CPU ticks might not overflow 946532 bit unsigned integer (which is more than 1s @ 4GHz CPU). In real scenarios `delay_base_us` should be much lower 9466than 150us. To disable coalescing set `delay_base_us` to 0. 9467 9468#### Parameters 9469 9470Name | Optional | Type | Description 9471----------------------- | -------- | ----------- | ----------- 9472ctrlr | Required | string | Controller name 9473delay_base_us | Required | number | Base (minimum) coalescing time in microseconds 9474iops_threshold | Required | number | Coalescing activation level greater than 0 in IO per second 9475 9476#### Example 9477 9478Example request: 9479 9480~~~json 9481{ 9482 "params": { 9483 "iops_threshold": 100000, 9484 "ctrlr": "VhostScsi0", 9485 "delay_base_us": 80 9486 }, 9487 "jsonrpc": "2.0", 9488 "method": "vhost_controller_set_coalescing", 9489 "id": 1 9490} 9491~~~ 9492 9493Example response: 9494 9495~~~json 9496{ 9497 "jsonrpc": "2.0", 9498 "id": 1, 9499 "result": true 9500} 9501~~~ 9502 9503### vhost_create_scsi_controller {#rpc_vhost_create_scsi_controller} 9504 9505Construct vhost SCSI target. 9506 9507#### Parameters 9508 9509Name | Optional | Type | Description 9510----------------------- | -------- | ----------- | ----------- 9511ctrlr | Required | string | Controller name 9512cpumask | Optional | string | @ref cpu_mask for this controller 9513delay | Optional | boolean | If true, delay the controller startup. 9514 9515#### Example 9516 9517Example request: 9518 9519~~~json 9520{ 9521 "params": { 9522 "cpumask": "0x2", 9523 "ctrlr": "VhostScsi0", 9524 "delay": true 9525 }, 9526 "jsonrpc": "2.0", 9527 "method": "vhost_create_scsi_controller", 9528 "id": 1 9529} 9530~~~ 9531 9532Example response: 9533 9534~~~json 9535{ 9536 "jsonrpc": "2.0", 9537 "id": 1, 9538 "result": true 9539} 9540~~~ 9541 9542### vhost_start_scsi_controller {#rpc_vhost_start_scsi_controller} 9543 9544Start vhost SCSI controller, if controller is already started, do nothing. 9545 9546#### Parameters 9547 9548Name | Optional | Type | Description 9549----------------------- | -------- | ----------- | ----------- 9550ctrlr | Required | string | Controller name 9551 9552#### Example 9553 9554Example request: 9555 9556~~~json 9557{ 9558 "params": { 9559 "ctrlr": "VhostScsi0", 9560 }, 9561 "jsonrpc": "2.0", 9562 "method": "vhost_start_scsi_controller", 9563 "id": 1 9564} 9565~~~ 9566 9567Example response: 9568 9569~~~json 9570response: 9571{ 9572 "jsonrpc": "2.0", 9573 "id": 1, 9574 "result": true 9575} 9576~~~ 9577 9578### vhost_scsi_controller_add_target {#rpc_vhost_scsi_controller_add_target} 9579 9580In vhost target `ctrlr` create SCSI target with ID `scsi_target_num` and add `bdev_name` as LUN 0. 9581 9582#### Parameters 9583 9584Name | Optional | Type | Description 9585----------------------- | -------- | ----------- | ----------- 9586ctrlr | Required | string | Controller name 9587scsi_target_num | Required | number | SCSI target ID between 0 and 7 or -1 to use first free ID. 9588bdev_name | Required | string | Name of bdev to expose as a LUN 0 9589 9590#### Response 9591 9592SCSI target ID. 9593 9594#### Example 9595 9596Example request: 9597 9598~~~json 9599{ 9600 "params": { 9601 "scsi_target_num": 1, 9602 "bdev_name": "Malloc0", 9603 "ctrlr": "VhostScsi0" 9604 }, 9605 "jsonrpc": "2.0", 9606 "method": "vhost_scsi_controller_add_target", 9607 "id": 1 9608} 9609~~~ 9610 9611Example response: 9612 9613~~~json 9614response: 9615{ 9616 "jsonrpc": "2.0", 9617 "id": 1, 9618 "result": 1 9619} 9620~~~ 9621 9622### vhost_scsi_controller_remove_target {#rpc_vhost_scsi_controller_remove_target} 9623 9624Remove SCSI target ID `scsi_target_num` from vhost target `scsi_target_num`. 9625 9626This method will fail if initiator is connected, but doesn't support hot-remove (the `VIRTIO_SCSI_F_HOTPLUG` is not negotiated). 9627 9628#### Parameters 9629 9630Name | Optional | Type | Description 9631----------------------- | -------- | ----------- | ----------- 9632ctrlr | Required | string | Controller name 9633scsi_target_num | Required | number | SCSI target ID between 0 and 7 9634 9635#### Example 9636 9637Example request: 9638 9639~~~json 9640request: 9641{ 9642 "params": { 9643 "scsi_target_num": 1, 9644 "ctrlr": "VhostScsi0" 9645 }, 9646 "jsonrpc": "2.0", 9647 "method": "vhost_scsi_controller_remove_target", 9648 "id": 1 9649} 9650~~~ 9651 9652Example response: 9653 9654~~~json 9655{ 9656 "jsonrpc": "2.0", 9657 "id": 1, 9658 "result": true 9659} 9660~~~ 9661 9662### virtio_blk_create_transport {#rpc_virtio_blk_create_transport} 9663 9664Create virtio blk transport. 9665 9666#### Parameters 9667 9668Name | Optional | Type | Description 9669----------------------- | -------- | ----------- | ----------- 9670name | Required | string | Transport name 9671 9672#### Example 9673 9674Example request: 9675 9676~~~json 9677{ 9678 "params": { 9679 "name": "vhost_user_blk" 9680 }, 9681 "jsonrpc": "2.0", 9682 "method": "virtio_blk_create_transport", 9683 "id": 1 9684} 9685~~~ 9686 9687Example response: 9688 9689~~~json 9690{ 9691 "jsonrpc": "2.0", 9692 "id": 1, 9693 "result": true 9694} 9695~~~ 9696 9697### virtio_blk_get_transports {#rpc_virtio_blk_get_transports} 9698 9699#### Parameters 9700 9701The user may specify no parameters in order to list all transports, 9702or a transport name may be specified. 9703 9704Name | Optional | Type | Description 9705--------------------------- | -------- | ------------| ----------- 9706name | Optional | string | Transport name. 9707 9708#### Example 9709 9710Example request: 9711 9712~~~json 9713{ 9714 "jsonrpc": "2.0", 9715 "method": "virtio_blk_get_transports", 9716 "id": 1 9717} 9718~~~ 9719 9720Example response: 9721 9722~~~json 9723{ 9724 "jsonrpc": "2.0", 9725 "id": 1, 9726 "result": [ 9727 { 9728 "name": "vhost_user_blk" 9729 } 9730 ] 9731} 9732~~~ 9733 9734### vhost_create_blk_controller {#rpc_vhost_create_blk_controller} 9735 9736Create vhost block controller 9737 9738If `readonly` is `true` then vhost block target will be created as read only and fail any write requests. 9739The `VIRTIO_BLK_F_RO` feature flag will be offered to the initiator. 9740 9741#### Parameters 9742 9743Name | Optional | Type | Description 9744----------------------- | -------- | ----------- | ----------- 9745ctrlr | Required | string | Controller name 9746bdev_name | Required | string | Name of bdev to expose block device 9747readonly | Optional | boolean | If true, this target will be read only (default: false) 9748cpumask | Optional | string | @ref cpu_mask for this controller 9749transport | Optional | string | virtio blk transport name (default: vhost_user_blk) 9750 9751#### Example 9752 9753Example request: 9754 9755~~~json 9756{ 9757 "params": { 9758 "dev_name": "Malloc0", 9759 "ctrlr": "VhostBlk0" 9760 }, 9761 "jsonrpc": "2.0", 9762 "method": "vhost_create_blk_controller", 9763 "id": 1 9764} 9765~~~ 9766 9767Example response: 9768 9769~~~json 9770{ 9771 "jsonrpc": "2.0", 9772 "id": 1, 9773 "result": true 9774} 9775~~~ 9776 9777### vhost_get_controllers {#rpc_vhost_get_controllers} 9778 9779Display information about all or specific vhost controller(s). 9780 9781#### Parameters 9782 9783The user may specify no parameters in order to list all controllers, or a controller may be 9784specified by name. 9785 9786Name | Optional | Type | Description 9787----------------------- | -------- | ----------- | ----------- 9788name | Optional | string | Vhost controller name 9789 9790#### Response {#rpc_vhost_get_controllers_response} 9791 9792Response is an array of objects describing requested controller(s). Common fields are: 9793 9794Name | Type | Description 9795----------------------- | ----------- | ----------- 9796ctrlr | string | Controller name 9797cpumask | string | @ref cpu_mask of this controller 9798delay_base_us | number | Base (minimum) coalescing time in microseconds (0 if disabled) 9799iops_threshold | number | Coalescing activation level 9800backend_specific | object | Backend specific information 9801 9802### Vhost block {#rpc_vhost_get_controllers_blk} 9803 9804`backend_specific` contains one `block` object of type: 9805 9806Name | Type | Description 9807----------------------- | ----------- | ----------- 9808bdev | string | Backing bdev name or Null if bdev is hot-removed 9809readonly | boolean | True if controllers is readonly, false otherwise 9810 9811### Vhost SCSI {#rpc_vhost_get_controllers_scsi} 9812 9813`backend_specific` contains `scsi` array of following objects: 9814 9815Name | Type | Description 9816----------------------- | ----------- | ----------- 9817target_name | string | Name of this SCSI target 9818id | number | Unique SPDK global SCSI target ID 9819scsi_dev_num | number | SCSI target ID initiator will see when scanning this controller 9820luns | array | array of objects describing @ref rpc_vhost_get_controllers_scsi_luns 9821 9822### Vhost SCSI LUN {#rpc_vhost_get_controllers_scsi_luns} 9823 9824Object of type: 9825 9826Name | Type | Description 9827----------------------- | ----------- | ----------- 9828id | number | SCSI LUN ID 9829bdev_name | string | Backing bdev name 9830 9831### Vhost NVMe {#rpc_vhost_get_controllers_nvme} 9832 9833`backend_specific` contains `namespaces` array of following objects: 9834 9835Name | Type | Description 9836----------------------- | ----------- | ----------- 9837nsid | number | Namespace ID 9838bdev | string | Backing bdev name 9839 9840#### Example 9841 9842Example request: 9843 9844~~~json 9845{ 9846 "jsonrpc": "2.0", 9847 "method": "vhost_get_controllers", 9848 "id": 1 9849} 9850~~~ 9851 9852Example response: 9853 9854~~~json 9855{ 9856 "jsonrpc": "2.0", 9857 "id": 1, 9858 "result": [ 9859 { 9860 "cpumask": "0x2", 9861 "backend_specific": { 9862 "block": { 9863 "readonly": false, 9864 "bdev": "Malloc0" 9865 } 9866 }, 9867 "iops_threshold": 60000, 9868 "ctrlr": "VhostBlk0", 9869 "delay_base_us": 100 9870 }, 9871 { 9872 "cpumask": "0x2", 9873 "backend_specific": { 9874 "scsi": [ 9875 { 9876 "target_name": "Target 2", 9877 "luns": [ 9878 { 9879 "id": 0, 9880 "bdev_name": "Malloc1" 9881 } 9882 ], 9883 "id": 0, 9884 "scsi_dev_num": 2 9885 }, 9886 { 9887 "target_name": "Target 5", 9888 "luns": [ 9889 { 9890 "id": 0, 9891 "bdev_name": "Malloc2" 9892 } 9893 ], 9894 "id": 1, 9895 "scsi_dev_num": 5 9896 } 9897 ] 9898 }, 9899 "iops_threshold": 60000, 9900 "ctrlr": "VhostScsi0", 9901 "delay_base_us": 0 9902 }, 9903 { 9904 "cpumask": "0x2", 9905 "backend_specific": { 9906 "namespaces": [ 9907 { 9908 "bdev": "Malloc3", 9909 "nsid": 1 9910 }, 9911 { 9912 "bdev": "Malloc4", 9913 "nsid": 2 9914 } 9915 ] 9916 }, 9917 "iops_threshold": 60000, 9918 "ctrlr": "VhostNvme0", 9919 "delay_base_us": 0 9920 } 9921 ] 9922} 9923~~~ 9924 9925### vhost_delete_controller {#rpc_vhost_delete_controller} 9926 9927Remove vhost target. 9928 9929This call will fail if there is an initiator connected or there is at least one SCSI target configured in case of 9930vhost SCSI target. In the later case please remove all SCSI targets first using @ref rpc_vhost_scsi_controller_remove_target. 9931 9932#### Parameters 9933 9934Name | Optional | Type | Description 9935----------------------- | -------- | ----------- | ----------- 9936ctrlr | Required | string | Controller name 9937 9938#### Example 9939 9940Example request: 9941 9942~~~json 9943{ 9944 "params": { 9945 "ctrlr": "VhostNvme0" 9946 }, 9947 "jsonrpc": "2.0", 9948 "method": "vhost_delete_controller", 9949 "id": 1 9950} 9951~~~ 9952 9953Example response: 9954 9955~~~json 9956{ 9957 "jsonrpc": "2.0", 9958 "id": 1, 9959 "result": true 9960} 9961~~~ 9962 9963## Logical Volume {#jsonrpc_components_lvol} 9964 9965Identification of logical volume store and logical volume is explained first. 9966 9967A logical volume store has a UUID and a name for its identification. 9968The UUID is generated on creation and it can be used as a unique identifier. 9969The name is specified on creation and can be renamed. 9970Either UUID or name is used to access logical volume store in RPCs. 9971 9972A logical volume has a UUID and a name for its identification. 9973The UUID of the logical volume is generated on creation and it can be unique identifier. 9974The alias of the logical volume takes the format _lvs_name/lvol_name_ where: 9975 9976* _lvs_name_ is the name of the logical volume store. 9977* _lvol_name_ is specified on creation and can be renamed. 9978 9979### bdev_lvol_create_lvstore {#rpc_bdev_lvol_create_lvstore} 9980 9981Construct a logical volume store. 9982 9983#### Parameters 9984 9985Name | Optional | Type | Description 9986----------------------------- | -------- | ----------- | ----------- 9987bdev_name | Required | string | Bdev on which to construct logical volume store 9988lvs_name | Required | string | Name of the logical volume store to create 9989cluster_sz | Optional | number | Cluster size of the logical volume store in bytes (Default: 4MiB) 9990clear_method | Optional | string | Change clear method for data region. Available: none, unmap (default), write_zeroes 9991num_md_pages_per_cluster_ratio| Optional | number | Reserved metadata pages per cluster (Default: 100) 9992 9993The num_md_pages_per_cluster_ratio defines the amount of metadata to 9994allocate when the logical volume store is created. The default value 9995is '100', which translates to 1 4KiB per cluster. For the default 4MiB 9996cluster size, this equates to about 0.1% of the underlying block 9997device allocated for metadata. Logical volume stores can be grown, if 9998the size of the underlying block device grows in the future, but only 9999if enough metadata pages were allocated to support the growth. So 10000num_md_pages_per_cluster_ratio should be set to a higher value if 10001wanting to support future growth. For example, 10002num_md_pages_per_cluster_ratio = 200 would support future 2x growth of 10003the logical volume store, and would result in 0.2% of the underlying 10004block device allocated for metadata (with a default 4MiB cluster 10005size). 10006 10007#### Response 10008 10009UUID of the created logical volume store is returned. 10010 10011#### Example 10012 10013Example request: 10014 10015~~~json 10016{ 10017 "jsonrpc": "2.0", 10018 "id": 1, 10019 "method": "bdev_lvol_create_lvstore", 10020 "params": { 10021 "lvs_name": "LVS0", 10022 "bdev_name": "Malloc0" 10023 "clear_method": "write_zeroes" 10024 } 10025} 10026~~~ 10027 10028Example response: 10029 10030~~~json 10031{ 10032 "jsonrpc": "2.0", 10033 "id": 1, 10034 "result": "a9959197-b5e2-4f2d-8095-251ffb6985a5" 10035} 10036~~~ 10037 10038### bdev_lvol_delete_lvstore {#rpc_bdev_lvol_delete_lvstore} 10039 10040Destroy a logical volume store. 10041 10042#### Parameters 10043 10044Name | Optional | Type | Description 10045----------------------- | -------- | ----------- | ----------- 10046uuid | Optional | string | UUID of the logical volume store to destroy 10047lvs_name | Optional | string | Name of the logical volume store to destroy 10048 10049Either uuid or lvs_name must be specified, but not both. 10050 10051#### Example 10052 10053Example request: 10054 10055~~~json 10056{ 10057 "jsonrpc": "2.0", 10058 "method": "bdev_lvol_delete_lvstore", 10059 "id": 1 10060 "params": { 10061 "uuid": "a9959197-b5e2-4f2d-8095-251ffb6985a5" 10062 } 10063} 10064~~~ 10065 10066Example response: 10067 10068~~~json 10069{ 10070 "jsonrpc": "2.0", 10071 "id": 1, 10072 "result": true 10073} 10074~~~ 10075 10076### bdev_lvol_get_lvstores {#rpc_bdev_lvol_get_lvstores} 10077 10078Get a list of logical volume stores. 10079 10080#### Parameters 10081 10082Name | Optional | Type | Description 10083----------------------- | -------- | ----------- | ----------- 10084uuid | Optional | string | UUID of the logical volume store to retrieve information about 10085lvs_name | Optional | string | Name of the logical volume store to retrieve information about 10086 10087Either uuid or lvs_name may be specified, but not both. 10088If both uuid and lvs_name are omitted, information about all logical volume stores is returned. 10089 10090#### Example 10091 10092Example request: 10093 10094~~~json 10095{ 10096 "jsonrpc": "2.0", 10097 "method": "bdev_lvol_get_lvstores", 10098 "id": 1, 10099 "params": { 10100 "lvs_name": "LVS0" 10101 } 10102} 10103~~~ 10104 10105Example response: 10106 10107~~~json 10108{ 10109 "jsonrpc": "2.0", 10110 "id": 1, 10111 "result": [ 10112 { 10113 "uuid": "a9959197-b5e2-4f2d-8095-251ffb6985a5", 10114 "base_bdev": "Malloc0", 10115 "free_clusters": 31, 10116 "cluster_size": 4194304, 10117 "total_data_clusters": 31, 10118 "block_size": 4096, 10119 "name": "LVS0" 10120 } 10121 ] 10122} 10123~~~ 10124 10125### bdev_lvol_rename_lvstore {#rpc_bdev_lvol_rename_lvstore} 10126 10127Rename a logical volume store. 10128 10129#### Parameters 10130 10131Name | Optional | Type | Description 10132----------------------- | -------- | ----------- | ----------- 10133old_name | Required | string | Existing logical volume store name 10134new_name | Required | string | New logical volume store name 10135 10136#### Example 10137 10138Example request: 10139 10140~~~json 10141{ 10142 "jsonrpc": "2.0", 10143 "method": "bdev_lvol_rename_lvstore", 10144 "id": 1, 10145 "params": { 10146 "old_name": "LVS0", 10147 "new_name": "LVS2" 10148 } 10149} 10150~~~ 10151 10152Example response: 10153 10154~~~json 10155{ 10156 "jsonrpc": "2.0", 10157 "id": 1, 10158 "result": true 10159} 10160~~~ 10161 10162### bdev_lvol_grow_lvstore {#rpc_bdev_lvol_grow_lvstore} 10163 10164Grow the logical volume store to fill the underlying bdev 10165 10166#### Parameters 10167 10168Name | Optional | Type | Description 10169----------------------- | -------- | ----------- | ----------- 10170uuid | Optional | string | UUID of the logical volume store to grow 10171lvs_name | Optional | string | Name of the logical volume store to grow 10172 10173Either uuid or lvs_name must be specified, but not both. 10174 10175#### Example 10176 10177Example request: 10178 10179~~~json 10180{ 10181 "jsonrpc": "2.0", 10182 "method": "bdev_lvol_grow_lvstore", 10183 "id": 1 10184 "params": { 10185 "uuid": "a9959197-b5e2-4f2d-8095-251ffb6985a5" 10186 } 10187} 10188~~~ 10189 10190Example response: 10191 10192~~~json 10193{ 10194 "jsonrpc": "2.0", 10195 "id": 1, 10196 "result": true 10197} 10198~~~ 10199 10200### bdev_lvol_create {#rpc_bdev_lvol_create} 10201 10202Create a logical volume on a logical volume store. 10203 10204#### Parameters 10205 10206Name | Optional | Type | Description 10207----------------------- | -------- | ----------- | ----------- 10208lvol_name | Required | string | Name of logical volume to create 10209size_in_mib | Required | number | Desired size of logical volume in MiB 10210thin_provision | Optional | boolean | True to enable thin provisioning 10211uuid | Optional | string | UUID of logical volume store to create logical volume on 10212lvs_name | Optional | string | Name of logical volume store to create logical volume on 10213clear_method | Optional | string | Change default data clusters clear method. Available: none, unmap, write_zeroes 10214 10215Size will be rounded up to a multiple of cluster size. Either uuid or lvs_name must be specified, but not both. 10216lvol_name will be used in the alias of the created logical volume. 10217 10218#### Response 10219 10220UUID of the created logical volume is returned. 10221 10222#### Example 10223 10224Example request: 10225 10226~~~json 10227{ 10228 "jsonrpc": "2.0", 10229 "method": "bdev_lvol_create", 10230 "id": 1, 10231 "params": { 10232 "lvol_name": "LVOL0", 10233 "size_in_mib": 1, 10234 "lvs_name": "LVS0", 10235 "clear_method": "unmap", 10236 "thin_provision": true 10237 } 10238} 10239~~~ 10240 10241Example response: 10242 10243~~~json 10244{ 10245 "jsonrpc": "2.0", 10246 "id": 1, 10247 "result": "1b38702c-7f0c-411e-a962-92c6a5a8a602" 10248} 10249~~~ 10250 10251### bdev_lvol_snapshot {#rpc_bdev_lvol_snapshot} 10252 10253Capture a snapshot of the current state of a logical volume. 10254 10255#### Parameters 10256 10257Name | Optional | Type | Description 10258----------------------- | -------- | ----------- | ----------- 10259lvol_name | Required | string | UUID or alias of the logical volume to create a snapshot from 10260snapshot_name | Required | string | Name for the newly created snapshot 10261 10262#### Response 10263 10264UUID of the created logical volume snapshot is returned. 10265 10266#### Example 10267 10268Example request: 10269 10270~~~json 10271{ 10272 "jsonrpc": "2.0", 10273 "method": "bdev_lvol_snapshot", 10274 "id": 1, 10275 "params": { 10276 "lvol_name": "1b38702c-7f0c-411e-a962-92c6a5a8a602", 10277 "snapshot_name": "SNAP1" 10278 } 10279} 10280~~~ 10281 10282Example response: 10283 10284~~~json 10285{ 10286 "jsonrpc": "2.0", 10287 "id": 1, 10288 "result": "cc8d7fdf-7865-4d1f-9fc6-35da8e368670" 10289} 10290~~~ 10291 10292### bdev_lvol_clone {#rpc_bdev_lvol_clone} 10293 10294Create a logical volume based on a snapshot. 10295 10296#### Parameters 10297 10298Name | Optional | Type | Description 10299----------------------- | -------- | ----------- | ----------- 10300snapshot_name | Required | string | UUID or alias of the snapshot to clone 10301clone_name | Required | string | Name for the logical volume to create 10302 10303#### Response 10304 10305UUID of the created logical volume clone is returned. 10306 10307#### Example 10308 10309Example request: 10310 10311~~~json 10312{ 10313 "jsonrpc": "2.0" 10314 "method": "bdev_lvol_clone", 10315 "id": 1, 10316 "params": { 10317 "snapshot_name": "cc8d7fdf-7865-4d1f-9fc6-35da8e368670", 10318 "clone_name": "CLONE1" 10319 } 10320} 10321~~~ 10322 10323Example response: 10324 10325~~~json 10326{ 10327 "jsonrpc": "2.0", 10328 "id": 1, 10329 "result": "8d87fccc-c278-49f0-9d4c-6237951aca09" 10330} 10331~~~ 10332 10333### bdev_lvol_clone_bdev {#rpc_bdev_lvol_clone_bdev} 10334 10335Create a logical volume based on an external snapshot bdev. The external snapshot bdev 10336is a bdev that will not be written to by any consumer and must not be an lvol in the 10337lvstore as the clone. 10338 10339Regardless of whether the bdev is specified by name or UUID, the bdev UUID will be stored 10340in the logical volume's metadata for use while the lvolstore is loading. For this reason, 10341it is important that the bdev chosen has a static UUID. 10342 10343#### Parameters 10344 10345Name | Optional | Type | Description 10346----------------------- | -------- | ----------- | ----------- 10347bdev | Required | string | Name or UUID for bdev that acts as the external snapshot 10348lvs_name | Required | string | logical volume store name 10349clone_name | Required | string | Name for the logical volume to create 10350 10351#### Response 10352 10353UUID of the created logical volume clone is returned. 10354 10355#### Example 10356 10357Example request: 10358 10359~~~json 10360{ 10361 "jsonrpc": "2.0", 10362 "method": "bdev_lvol_clone_bdev", 10363 "id": 1, 10364 "params": { 10365 "bdev_uuid": "e4b40d8b-f623-416d-8234-baf5a4c83cbd", 10366 "lvs_name": "lvs1", 10367 "clone_name": "clone2" 10368 } 10369} 10370~~~ 10371 10372Example response: 10373 10374~~~json 10375{ 10376 "jsonrpc": "2.0", 10377 "id": 1, 10378 "result": "336f662b-08e5-4006-8e06-e2023f7f9886" 10379} 10380~~~ 10381 10382### bdev_lvol_rename {#rpc_bdev_lvol_rename} 10383 10384Rename a logical volume. New name will rename only the alias of the logical volume. 10385 10386#### Parameters 10387 10388Name | Optional | Type | Description 10389----------------------- | -------- | ----------- | ----------- 10390old_name | Required | string | UUID or alias of the existing logical volume 10391new_name | Required | string | New logical volume name 10392 10393#### Example 10394 10395Example request: 10396 10397~~~json 10398{ 10399 "jsonrpc": "2.0", 10400 "method": "bdev_lvol_rename", 10401 "id": 1, 10402 "params": { 10403 "old_name": "067df606-6dbc-4143-a499-0d05855cb3b8", 10404 "new_name": "LVOL2" 10405 } 10406} 10407~~~ 10408 10409Example response: 10410 10411~~~json 10412{ 10413 "jsonrpc": "2.0", 10414 "id": 1, 10415 "result": true 10416} 10417~~~ 10418 10419### bdev_lvol_resize {#rpc_bdev_lvol_resize} 10420 10421Resize a logical volume. 10422 10423#### Parameters 10424 10425Name | Optional | Type | Description 10426----------------------- | -------- | ----------- | ----------- 10427name | Required | string | UUID or alias of the logical volume to resize 10428size_in_mib | Required | number | Desired size of the logical volume in MiB 10429 10430#### Example 10431 10432Example request: 10433 10434~~~json 10435{ 10436 "jsonrpc": "2.0", 10437 "method": "bdev_lvol_resize", 10438 "id": 1, 10439 "params": { 10440 "name": "51638754-ca16-43a7-9f8f-294a0805ab0a", 10441 "size_in_mib": 2 10442 } 10443} 10444~~~ 10445 10446Example response: 10447 10448~~~json 10449{ 10450 "jsonrpc": "2.0", 10451 "id": 1, 10452 "result": true 10453} 10454~~~ 10455 10456### bdev_lvol_set_read_only{#rpc_bdev_lvol_set_read_only} 10457 10458Mark logical volume as read only. 10459 10460#### Parameters 10461 10462Name | Optional | Type | Description 10463----------------------- | -------- | ----------- | ----------- 10464name | Required | string | UUID or alias of the logical volume to set as read only 10465 10466#### Example 10467 10468Example request: 10469 10470~~~json 10471{ 10472 "jsonrpc": "2.0", 10473 "method": "bdev_lvol_set_read_only", 10474 "id": 1, 10475 "params": { 10476 "name": "51638754-ca16-43a7-9f8f-294a0805ab0a", 10477 } 10478} 10479~~~ 10480 10481Example response: 10482 10483~~~json 10484{ 10485 "jsonrpc": "2.0", 10486 "id": 1, 10487 "result": true 10488} 10489~~~ 10490 10491### bdev_lvol_delete {#rpc_bdev_lvol_delete} 10492 10493Destroy a logical volume. 10494 10495#### Parameters 10496 10497Name | Optional | Type | Description 10498----------------------- | -------- | ----------- | ----------- 10499name | Required | string | UUID or alias of the logical volume to destroy 10500 10501#### Example 10502 10503Example request: 10504 10505~~~json 10506{ 10507 "jsonrpc": "2.0", 10508 "method": "bdev_lvol_delete", 10509 "id": 1, 10510 "params": { 10511 "name": "51638754-ca16-43a7-9f8f-294a0805ab0a" 10512 } 10513} 10514~~~ 10515 10516Example response: 10517 10518~~~json 10519{ 10520 "jsonrpc": "2.0", 10521 "id": 1, 10522 "result": true 10523} 10524~~~ 10525 10526### bdev_lvol_inflate {#rpc_bdev_lvol_inflate} 10527 10528Inflate a logical volume. All unallocated clusters are allocated and copied from the parent or zero filled 10529if not allocated in the parent. Then all dependencies on the parent are removed. 10530 10531### Parameters 10532 10533Name | Optional | Type | Description 10534----------------------- | -------- | ----------- | ----------- 10535name | Required | string | UUID or alias of the logical volume to inflate 10536 10537#### Example 10538 10539Example request: 10540 10541~~~json 10542{ 10543 "jsonrpc": "2.0", 10544 "method": "bdev_lvol_inflate", 10545 "id": 1, 10546 "params": { 10547 "name": "8d87fccc-c278-49f0-9d4c-6237951aca09" 10548 } 10549} 10550~~~ 10551 10552Example response: 10553 10554~~~json 10555{ 10556 "jsonrpc": "2.0", 10557 "id": 1, 10558 "result": true 10559} 10560~~~ 10561 10562### bdev_lvol_decouple_parent {#rpc_bdev_lvol_decouple_parent} 10563 10564Decouple the parent of a logical volume. For unallocated clusters which is allocated in the parent, they are 10565allocated and copied from the parent, but for unallocated clusters which is thin provisioned in the parent, 10566they are kept thin provisioned. Then all dependencies on the parent are removed. 10567 10568#### Parameters 10569 10570Name | Optional | Type | Description 10571----------------------- | -------- | ----------- | ----------- 10572name | Required | string | UUID or alias of the logical volume to decouple the parent of it 10573 10574#### Example 10575 10576Example request: 10577 10578~~~json 10579{ 10580 "jsonrpc": "2.0", 10581 "method": "bdev_lvol_decouple_parent", 10582 "id": 1. 10583 "params": { 10584 "name": "8d87fccc-c278-49f0-9d4c-6237951aca09" 10585 } 10586} 10587~~~ 10588 10589Example response: 10590 10591~~~json 10592{ 10593 "jsonrpc": "2.0", 10594 "id": 1, 10595 "result": true 10596} 10597~~~ 10598 10599### bdev_lvol_get_lvols {#rpc_bdev_lvol_get_lvols} 10600 10601Get a list of logical volumes. This list can be limited by lvol store and will display volumes even if 10602they are degraded. Degraded lvols do not have an associated bdev, thus this RPC call may return lvols 10603not returned by `bdev_get_bdevs`. 10604 10605#### Parameters 10606 10607Name | Optional | Type | Description 10608----------------------- | -------- | ----------- | ----------- 10609lvs_uuid | Optional | string | Only show volumes in the logical volume store with this UUID 10610lvs_name | Optional | string | Only show volumes in the logical volume store with this name 10611 10612Either lvs_uuid or lvs_name may be specified, but not both. 10613If both lvs_uuid and lvs_name are omitted, information about lvols in all logical volume stores is returned. 10614 10615#### Example 10616 10617Example request: 10618 10619~~~json 10620{ 10621 "jsonrpc": "2.0", 10622 "method": "bdev_lvol_get_lvols", 10623 "id": 1, 10624 "params": { 10625 "lvs_name": "lvs_test" 10626 } 10627} 10628~~~ 10629 10630Example response: 10631 10632~~~json 10633[ 10634 { 10635 "alias": "lvs_test/lvol1", 10636 "uuid": "b335c368-851d-4099-81e0-018cc494fdf6", 10637 "name": "lvol1", 10638 "is_thin_provisioned": false, 10639 "is_snapshot": false, 10640 "is_clone": false, 10641 "is_esnap_clone": false, 10642 "is_degraded": false, 10643 "lvs": { 10644 "name": "lvs_test", 10645 "uuid": "a1c8d950-5715-4558-936d-ab9e6eca0794" 10646 } 10647 } 10648] 10649~~~ 10650 10651### bdev_lvol_set_parent {#rpc_bdev_lvol_set_parent} 10652 10653Set a snapshot as the parent of a lvol, making the lvol a clone of this snapshot. 10654The previous parent of the lvol, if any, can be another snapshot or an external snapshot; if the 10655lvol is not a clone, it must be thin-provisioned. 10656Lvol and parent snapshot must have the same size and must belong to the same lvol store. 10657 10658#### Parameters 10659 10660Name | Optional | Type | Description 10661----------------------- | -------- | ----------- | ----------- 10662lvol_name | Required | string | UUID or alias of the lvol to set parent of 10663snapshot_name | Required | string | UUID or alias of the snapshot to become parent of lvol 10664 10665#### Example 10666 10667Example request: 10668 10669~~~json 10670{ 10671 "jsonrpc": "2.0", 10672 "method": "bdev_lvol_set_parent", 10673 "id": 1, 10674 "params": { 10675 "lvol_name": "LVS1/LVOL0", 10676 "snapshot_name": "LVS1/SNAP0" 10677 } 10678} 10679~~~ 10680 10681Example response: 10682 10683~~~json 10684{ 10685 "jsonrpc": "2.0", 10686 "id": 1, 10687 "result": true 10688} 10689~~~ 10690 10691### bdev_lvol_set_parent_bdev {#rpc_bdev_lvol_set_parent_bdev} 10692 10693Set an external snapshot as the parent of a lvol, making the lvol a clone of this external 10694snapshot (see @ref rpc_bdev_lvol_clone_bdev). 10695The previous parent of the lvol, if any, can be another external snapshot or a snapshot; if the 10696lvol is not a clone, it must be thin-provisioned. 10697The size of the external snapshot device must be an integer multiple of cluster size of lvol's lvolstore. 10698 10699#### Parameters 10700 10701Name | Optional | Type | Description 10702----------------------- | -------- | ----------- | ----------- 10703lvol_name | Required | string | UUID or alias of the lvol to set external parent of 10704esnap_name | Required | string | UUID or name of the external snapshot to become parent of lvol 10705 10706#### Example 10707 10708Example request: 10709 10710~~~json 10711{ 10712 "jsonrpc": "2.0", 10713 "method": "bdev_lvol_set_parent_bdev", 10714 "id": 1, 10715 "params": { 10716 "lvol_name": "LVS1/LVOL0", 10717 "esnap_name": "e465527b-f412-4f70-a03e-c4a5d608f65e" 10718 } 10719} 10720~~~ 10721 10722Example response: 10723 10724~~~json 10725{ 10726 "jsonrpc": "2.0", 10727 "id": 1, 10728 "result": true 10729} 10730~~~ 10731 10732### bdev_lvol_start_shallow_copy {#rpc_bdev_lvol_start_shallow_copy} 10733 10734Start a shallow copy of an lvol over a given bdev. Only clusters allocated to the lvol will be written on the bdev. 10735Must have: 10736 10737* lvol read only 10738* lvol size less or equal than bdev size 10739* lvstore block size an even multiple of bdev block size 10740 10741#### Result 10742 10743This RPC starts the operation and return an identifier that can be used to query the status of the operation 10744with the RPC @ref rpc_bdev_lvol_check_shallow_copy. 10745 10746#### Parameters 10747 10748Name | Optional | Type | Description 10749----------------------- | -------- | ----------- | ----------- 10750src_lvol_name | Required | string | UUID or alias of lvol to create a copy from 10751dst_bdev_name | Required | string | Name of the bdev that acts as destination for the copy 10752 10753#### Example 10754 10755Example request: 10756 10757~~~json 10758{ 10759 "jsonrpc": "2.0", 10760 "method": "bdev_lvol_start_shallow_copy", 10761 "id": 1, 10762 "params": { 10763 "src_lvol_name": "8a47421a-20cf-444f-845c-d97ad0b0bd8e", 10764 "dst_bdev_name": "Nvme1n1" 10765 } 10766} 10767~~~ 10768 10769Example response: 10770 10771~~~json 10772{ 10773 "jsonrpc": "2.0", 10774 "id": 1, 10775 "result": { 10776 "operation_id": 7 10777 } 10778} 10779~~~ 10780 10781### bdev_lvol_check_shallow_copy {#rpc_bdev_lvol_check_shallow_copy} 10782 10783Get shallow copy status. 10784 10785#### Result 10786 10787Get info about the shallow copy operation identified by operation id. 10788It reports operation's status, which can be `in progress`, `complete` or `error`, 10789the actual number of copied clusters, the total number of clusters to copy and, 10790in case of error, a description. 10791Once the operation is ended and the result has been retrieved, the 10792operation is removed from the internal list of ended operation, so its 10793result cannot be accessed anymore. 10794 10795#### Parameters 10796 10797Name | Optional | Type | Description 10798----------------------- | -------- | ----------- | ----------- 10799operation_id | Required | number | operation identifier 10800 10801#### Example 10802 10803Example request: 10804 10805~~~json 10806{ 10807 "jsonrpc": "2.0", 10808 "method": "bdev_lvol_check_shallow_copy", 10809 "id": 1, 10810 "params": { 10811 "operation_id": 7 10812 } 10813} 10814~~~ 10815 10816Example response: 10817 10818~~~json 10819{ 10820 "jsonrpc": "2.0", 10821 "id": 1, 10822 "result": { 10823 "state": "in progress", 10824 "copied_clusters": 2, 10825 "total_clusters": 4 10826 } 10827} 10828~~~ 10829 10830## RAID 10831 10832### bdev_raid_set_options {#rpc_bdev_raid_set_options} 10833 10834Set options for bdev raid. 10835 10836This RPC can be called at any time, but the new value will only take effect for new raid bdevs. 10837 10838The `process_window_size_kb` parameter defines the size of the "window" (LBA range of the raid bdev) 10839in which a background process like rebuild performs its work. Any positive value is valid, but the value 10840actually used by a raid bdev can be adjusted to the size of the raid bdev or the write unit size. 10841 10842#### Parameters 10843 10844Name | Optional | Type | Description 10845-------------------------- | -------- | ----------- | ----------- 10846process_window_size_kb | Optional | number | Background process (e.g. rebuild) window size in KiB 10847 10848#### Example 10849 10850Example request: 10851 10852~~~json 10853request: 10854{ 10855 "jsonrpc": "2.0", 10856 "method": "bdev_raid_set_options", 10857 "id": 1, 10858 "params": { 10859 "process_window_size_kb": 512 10860 } 10861} 10862~~~ 10863 10864Example response: 10865 10866~~~json 10867{ 10868 "jsonrpc": "2.0", 10869 "id": 1, 10870 "result": true 10871} 10872~~~ 10873 10874### bdev_raid_get_bdevs {#rpc_bdev_raid_get_bdevs} 10875 10876This is used to list all the raid bdev details based on the input category requested. Category should be one 10877of 'all', 'online', 'configuring' or 'offline'. 'all' means all the raid bdevs whether they are online or 10878configuring or offline. 'online' is the raid bdev which is registered with bdev layer. 'configuring' is 10879the raid bdev which does not have full configuration discovered yet. 'offline' is the raid bdev which is 10880not registered with bdev as of now and it has encountered any error or user has requested to offline 10881the raid bdev. 10882 10883#### Parameters 10884 10885Name | Optional | Type | Description 10886----------------------- | -------- | ----------- | ----------- 10887category | Required | string | all or online or configuring or offline 10888 10889#### Example 10890 10891Example request: 10892 10893~~~json 10894{ 10895 "jsonrpc": "2.0", 10896 "method": "bdev_raid_get_bdevs", 10897 "id": 1, 10898 "params": { 10899 "category": "all" 10900 } 10901} 10902~~~ 10903 10904Example response: 10905 10906~~~json 10907{ 10908 "jsonrpc": "2.0", 10909 "id": 1, 10910 "result": [ 10911 { 10912 "name": "RaidBdev0", 10913 "uuid": "7d352e83-fe27-40f2-8fef-64563355e076", 10914 "strip_size_kb": 128, 10915 "state": "online", 10916 "raid_level": "raid0", 10917 "num_base_bdevs": 2, 10918 "num_base_bdevs_discovered": 2, 10919 "num_base_bdevs_operational": 2, 10920 "base_bdevs_list": [ 10921 { 10922 "name": "malloc0", 10923 "uuid": "d2788884-5b3e-4fd7-87ff-6c78177e14ab", 10924 "is_configured": true, 10925 "data_offset": 256, 10926 "data_size": 261888 10927 }, 10928 { 10929 "name": "malloc1", 10930 "uuid": "a81bb1f8-5865-488a-8758-10152017e7d1", 10931 "is_configured": true, 10932 "data_offset": 256, 10933 "data_size": 261888 10934 } 10935 ] 10936 }, 10937 { 10938 "name": "RaidBdev1", 10939 "uuid": "f7cb71ed-2d0e-4240-979e-27b0b7735f36", 10940 "strip_size_kb": 128, 10941 "state": "configuring", 10942 "raid_level": "raid0", 10943 "num_base_bdevs": 2, 10944 "num_base_bdevs_discovered": 1, 10945 "num_base_bdevs_operational": 2, 10946 "base_bdevs_list": [ 10947 { 10948 "name": "malloc2", 10949 "uuid": "f60c20e1-3439-4f89-ae55-965a70333f86", 10950 "is_configured": true, 10951 "data_offset": 256, 10952 "data_size": 261888 10953 } 10954 { 10955 "name": "malloc3", 10956 "uuid": "00000000-0000-0000-0000-000000000000", 10957 "is_configured": false, 10958 "data_offset": 0, 10959 "data_size": 0 10960 } 10961 ] 10962 } 10963 ] 10964} 10965~~~ 10966 10967### bdev_raid_create {#rpc_bdev_raid_create} 10968 10969Constructs new RAID bdev. 10970 10971#### Parameters 10972 10973Name | Optional | Type | Description 10974----------------------- | -------- | ----------- | ----------- 10975name | Required | string | RAID bdev name 10976strip_size_kb | Required | number | Strip size in KB 10977raid_level | Required | string | RAID level 10978base_bdevs | Required | string | Base bdevs name, whitespace separated list in quotes 10979uuid | Optional | string | UUID for this RAID bdev 10980superblock | Optional | boolean | If set, information about raid bdev will be stored in superblock on each base bdev (default: `false`) 10981 10982#### Example 10983 10984Example request: 10985 10986~~~json 10987{ 10988 "jsonrpc": "2.0", 10989 "method": "bdev_raid_create", 10990 "id": 1, 10991 "params": { 10992 "name": "Raid0", 10993 "raid_level": "0", 10994 "base_bdevs": [ 10995 "Malloc0", 10996 "Malloc1", 10997 "Malloc2", 10998 "Malloc3" 10999 ], 11000 "strip_size_kb": 4 11001 } 11002} 11003~~~ 11004 11005Example response: 11006 11007~~~json 11008{ 11009 "jsonrpc": "2.0", 11010 "id": 1, 11011 "result": true 11012} 11013~~~ 11014 11015### bdev_raid_delete {#rpc_bdev_raid_delete} 11016 11017Removes RAID bdev. 11018 11019#### Parameters 11020 11021Name | Optional | Type | Description 11022----------------------- | -------- | ----------- | ----------- 11023name | Required | string | RAID bdev name 11024 11025#### Example 11026 11027Example request: 11028 11029~~~json 11030{ 11031 "jsonrpc": "2.0", 11032 "method": "bdev_raid_delete", 11033 "id": 1, 11034 "params": { 11035 "name": "Raid0" 11036 } 11037} 11038~~~ 11039 11040Example response: 11041 11042~~~json 11043{ 11044 "jsonrpc": "2.0", 11045 "id": 1, 11046 "result": true 11047} 11048~~~ 11049 11050### bdev_raid_add_base_bdev {#rpc_bdev_raid_add_base_bdev} 11051 11052Add base bdev to existing raid bdev. The raid bdev must have an empty base bdev slot. 11053The bdev must be large enough and have the same block size and metadata format as the other base bdevs. 11054 11055#### Parameters 11056 11057Name | Optional | Type | Description 11058----------------------- | -------- | ----------- | ----------- 11059raid_bdev | Required | string | Raid bdev name 11060base_bdev | Required | string | Base bdev name 11061 11062#### Example 11063 11064Example request: 11065 11066~~~json 11067{ 11068 "jsonrpc": "2.0", 11069 "method": "bdev_raid_add_base_bdev", 11070 "id": 1, 11071 "params": { 11072 "raid_bdev": "RaidBdev0", 11073 "base_bdev": "Nvme0n1" 11074 } 11075} 11076~~~ 11077 11078Example response: 11079 11080~~~json 11081{ 11082 "jsonrpc": "2.0", 11083 "id": 1, 11084 "result": true 11085} 11086~~~ 11087### bdev_raid_remove_base_bdev {#rpc_bdev_raid_remove_base_bdev} 11088 11089Remove base bdev from existing raid bdev. 11090 11091#### Parameters 11092 11093Name | Optional | Type | Description 11094----------------------- | -------- | ----------- | ----------- 11095name | Required | string | Base bdev name in RAID 11096 11097#### Example 11098 11099Example request: 11100 11101~~~json 11102{ 11103 "jsonrpc": "2.0", 11104 "method": "bdev_raid_remove_base_bdev", 11105 "id": 1, 11106 "params": { 11107 "name": "Raid0" 11108 } 11109} 11110~~~ 11111 11112Example response: 11113 11114~~~json 11115{ 11116 "jsonrpc": "2.0", 11117 "id": 1, 11118 "result": true 11119} 11120~~~ 11121 11122## SPLIT 11123 11124### bdev_split_create {#rpc_bdev_split_create} 11125 11126This is used to split an underlying block device and create several smaller equal-sized vbdevs. 11127 11128#### Parameters 11129 11130Name | Optional | Type | Description 11131----------------------- | -------- | ----------- | ----------- 11132base_bdev | Required | string | base bdev name 11133split_count | Required | number | number of splits 11134split_size_mb | Optional | number | size in MB to restrict the size 11135 11136#### Example 11137 11138Example request: 11139 11140~~~json 11141{ 11142 "jsonrpc": "2.0", 11143 "method": "bdev_split_create", 11144 "id": 1, 11145 "params": { 11146 "base_bdev": "Malloc0", 11147 "split_count": 4 11148 } 11149} 11150~~~ 11151 11152Example response: 11153 11154~~~json 11155{ 11156 "jsonrpc": "2.0", 11157 "id": 1, 11158 "result": [ 11159 "Malloc0p0", 11160 "Malloc0p1", 11161 "Malloc0p2", 11162 "Malloc0p3" 11163 ] 11164} 11165~~~ 11166 11167### bdev_split_delete {#rpc_bdev_split_delete} 11168 11169This is used to remove the split vbdevs. 11170 11171#### Parameters 11172 11173Name | Optional | Type | Description 11174----------------------- | -------- | ----------- | ----------- 11175base_bdev | Required | string | base bdev name 11176 11177#### Example 11178 11179Example request: 11180 11181~~~json 11182{ 11183 "jsonrpc": "2.0", 11184 "method": "bdev_split_delete", 11185 "id": 1, 11186 "params": { 11187 "base_bdev": "Malloc0" 11188 } 11189} 11190~~~ 11191 11192Example response: 11193 11194~~~json 11195{ 11196 "jsonrpc": "2.0", 11197 "id": 1, 11198 "result": true 11199} 11200~~~ 11201 11202## Uring 11203 11204### bdev_uring_create {#rpc_bdev_uring_create} 11205 11206Create a bdev with io_uring backend. 11207 11208#### Parameters 11209 11210Name | Optional | Type | Description 11211----------------------- | -------- | ----------- | ----------- 11212filename | Required | string | path to device or file (ex: /dev/nvme0n1) 11213name | Required | string | name of bdev 11214block_size | Optional | number | block size of device (If omitted, get the block size from the file) 11215uuid | Optional | string | UUID of new bdev 11216 11217#### Example 11218 11219Example request: 11220 11221~~~json 11222{ 11223 "jsonrpc": "2.0", 11224 "method": "bdev_uring_create", 11225 "id": 1, 11226 "params": { 11227 "name": "bdev_u0", 11228 "filename": "/dev/nvme0n1", 11229 "block_size": 512 11230 } 11231} 11232~~~ 11233 11234Example response: 11235 11236~~~json 11237{ 11238 "jsonrpc": "2.0", 11239 "id": 1, 11240 "result": "bdev_u0" 11241} 11242~~~ 11243 11244### bdev_uring_rescan {#rpc_bdev_uring_rescan} 11245 11246Rescan the size of a uring bdev. 11247 11248#### Parameters 11249 11250Name | Optional | Type | Description 11251---- | -------- | ------ | ----------- 11252name | Required | string | name of uring bdev to rescan 11253 11254#### Example 11255 11256Example request: 11257 11258~~~json 11259{ 11260 "jsonrpc": "2.0", 11261 "method": "bdev_uring_rescan", 11262 "id": 1, 11263 "params": { 11264 "name": "bdev_u0" 11265 } 11266} 11267~~~ 11268 11269Example response: 11270 11271~~~json 11272{ 11273 "jsonrpc": "2.0", 11274 "id": 1, 11275 "result": true 11276} 11277~~~ 11278 11279### bdev_uring_delete {#rpc_bdev_uring_delete} 11280 11281Remove a uring bdev. 11282 11283#### Parameters 11284 11285Name | Optional | Type | Description 11286----------------------- | -------- | ----------- | ----------- 11287name | Required | string | name of uring bdev to delete 11288 11289#### Example 11290 11291Example request: 11292 11293~~~json 11294{ 11295 "jsonrpc": "2.0", 11296 "method": "bdev_uring_delete", 11297 "id": 1, 11298 "params": { 11299 "name": "bdev_u0" 11300 } 11301} 11302~~~ 11303 11304Example response: 11305 11306~~~json 11307{ 11308 "jsonrpc": "2.0", 11309 "id": 1, 11310 "result": true 11311} 11312~~~ 11313 11314## OPAL 11315 11316### bdev_nvme_opal_init {#rpc_bdev_nvme_opal_init} 11317 11318This is used to initialize OPAL of a given NVMe ctrlr, including taking ownership and activating. 11319 11320#### Parameters 11321 11322Name | Optional | Type | Description 11323----------------------- | -------- | ----------- | ----------- 11324nvme_ctrlr_name | Required | string | name of nvme ctrlr 11325password | Required | string | admin password of OPAL 11326 11327#### Example 11328 11329Example request: 11330 11331~~~json 11332{ 11333 "jsonrpc": "2.0", 11334 "method": "bdev_nvme_opal_init", 11335 "id": 1, 11336 "params": { 11337 "nvme_ctrlr_name": "nvme0", 11338 "password": "*****" 11339 } 11340} 11341~~~ 11342 11343Example response: 11344 11345~~~json 11346{ 11347 "jsonrpc": "2.0", 11348 "id": 1, 11349 "result": true 11350} 11351~~~ 11352 11353### bdev_nvme_opal_revert {#rpc_bdev_nvme_opal_revert} 11354 11355This is used to revert OPAL to its factory settings. Erase all user configuration and data. 11356 11357#### Parameters 11358 11359Name | Optional | Type | Description 11360----------------------- | -------- | ----------- | ----------- 11361nvme_ctrlr_name | Required | string | name of nvme ctrlr 11362password | Required | string | admin password of OPAL 11363 11364#### Example 11365 11366Example request: 11367 11368~~~json 11369{ 11370 "jsonrpc": "2.0", 11371 "method": "bdev_nvme_opal_revert", 11372 "id": 1, 11373 "params": { 11374 "nvme_ctrlr_name": "nvme0", 11375 "password": "*****" 11376 } 11377} 11378~~~ 11379 11380Example response: 11381 11382~~~json 11383{ 11384 "jsonrpc": "2.0", 11385 "id": 1, 11386 "result": true 11387} 11388~~~ 11389 11390### bdev_opal_create {#rpc_bdev_opal_create} 11391 11392This is used to create an OPAL virtual bdev. 11393 11394#### Parameters 11395 11396Name | Optional | Type | Description 11397----------------------- | -------- | ----------- | ----------- 11398nvme_ctrlr_name | Required | string | name of nvme ctrlr that supports OPAL 11399nsid | Required | number | namespace ID 11400locking_range_id | Required | number | OPAL locking range ID 11401range_start | Required | number | locking range start LBA 11402range_length | Required | number | locking range length 11403password | Required | string | admin password of OPAL 11404 11405#### Response 11406 11407The response is the name of created OPAL virtual bdev. 11408 11409#### Example 11410 11411Example request: 11412 11413~~~json 11414{ 11415 "jsonrpc": "2.0", 11416 "method": "bdev_opal_create", 11417 "id": 1, 11418 "params": { 11419 "nvme_ctrlr_name": "nvme0", 11420 "nsid": 1, 11421 "locking_range_id": 1, 11422 "range_start": 0, 11423 "range_length": 4096, 11424 "password": "*****" 11425 } 11426} 11427~~~ 11428 11429Example response: 11430 11431~~~json 11432{ 11433 "jsonrpc": "2.0", 11434 "id": 1, 11435 "result": "nvme0n1r1" 11436} 11437~~~ 11438 11439### bdev_opal_get_info {#rpc_bdev_opal_get_info} 11440 11441This is used to get information of a given OPAL bdev. 11442 11443#### Parameters 11444 11445Name | Optional | Type | Description 11446----------------------- | -------- | ----------- | ----------- 11447bdev_name | Required | string | name of OPAL vbdev 11448password | Required | string | admin password 11449 11450#### Response 11451 11452The response is the locking info of OPAL virtual bdev. 11453 11454#### Example 11455 11456Example request: 11457 11458~~~json 11459{ 11460 "jsonrpc": "2.0", 11461 "method": "bdev_opal_get_info", 11462 "id": 1, 11463 "params": { 11464 "bdev_name": "nvme0n1r1", 11465 "password": "*****" 11466 } 11467} 11468~~~ 11469 11470Example response: 11471 11472~~~json 11473{ 11474 "jsonrpc": "2.0", 11475 "id": 1, 11476 "result": { 11477 "name": "nvme0n1r1", 11478 "range_start": 0, 11479 "range_length": 4096, 11480 "read_lock_enabled": true, 11481 "write_lock_enabled": true, 11482 "read_locked": false, 11483 "write_locked": false 11484 } 11485} 11486~~~ 11487 11488### bdev_opal_delete {#rpc_bdev_opal_delete} 11489 11490This is used to delete OPAL vbdev. 11491 11492#### Parameters 11493 11494Name | Optional | Type | Description 11495----------------------- | -------- | ----------- | ----------- 11496bdev_name | Required | string | name of OPAL vbdev 11497password | Required | string | admin password 11498 11499#### Example 11500 11501Example request: 11502 11503~~~json 11504{ 11505 "jsonrpc": "2.0", 11506 "method": "bdev_opal_delete", 11507 "id": 1, 11508 "params": { 11509 "bdev_name": "nvme0n1r1", 11510 "password": "*****" 11511 } 11512} 11513~~~ 11514 11515Example response: 11516 11517~~~json 11518{ 11519 "jsonrpc": "2.0", 11520 "id": 1, 11521 "result": true 11522} 11523~~~ 11524 11525### bdev_opal_new_user {#rpc_bdev_opal_new_user} 11526 11527This enables a new user to the specified opal bdev so that the user can lock/unlock the bdev. 11528Recalling this for the same opal bdev, only the newest user will have the privilege. 11529 11530#### Parameters 11531 11532Name | Optional | Type | Description 11533----------------------- | -------- | ----------- | ----------- 11534bdev_name | Required | string | name of OPAL vbdev 11535admin_password | Required | string | admin password 11536user_id | Required | number | user ID 11537user_password | Required | string | user password 11538 11539#### Example 11540 11541Example request: 11542 11543~~~json 11544{ 11545 "jsonrpc": "2.0", 11546 "method": "bdev_opal_new_user", 11547 "id": 1, 11548 "params": { 11549 "bdev_name": "nvme0n1r1", 11550 "admin_password": "*****", 11551 "user_id": "1", 11552 "user_password": "********" 11553 } 11554} 11555~~~ 11556 11557Example response: 11558 11559~~~json 11560{ 11561 "jsonrpc": "2.0", 11562 "id": 1, 11563 "result": true 11564} 11565~~~ 11566 11567### bdev_opal_set_lock_state {#rpc_bdev_opal_set_lock_state} 11568 11569This is used to lock/unlock specific opal bdev providing user ID and password. 11570 11571#### Parameters 11572 11573Name | Optional | Type | Description 11574----------------------- | -------- | ----------- | ----------- 11575bdev_name | Required | string | name of OPAL vbdev 11576user_id | Required | number | user ID 11577password | Required | string | user password 11578lock_state | Required | string | lock state 11579 11580#### Example 11581 11582Example request: 11583 11584~~~json 11585{ 11586 "jsonrpc": "2.0", 11587 "method": "bdev_opal_set_lock_state", 11588 "id": 1, 11589 "params": { 11590 "bdev_name": "nvme0n1r1", 11591 "user_id": "1", 11592 "user_password": "********", 11593 "lock_state": "rwlock" 11594 } 11595} 11596~~~ 11597 11598Example response: 11599 11600~~~json 11601{ 11602 "jsonrpc": "2.0", 11603 "id": 1, 11604 "result": true 11605} 11606~~~ 11607 11608## Notifications 11609 11610### notify_get_types {#rpc_notify_get_types} 11611 11612Return list of all supported notification types. 11613 11614#### Parameters 11615 11616None 11617 11618#### Response 11619 11620The response is an array of strings - supported RPC notification types. 11621 11622#### Example 11623 11624Example request: 11625 11626~~~json 11627{ 11628 "jsonrpc": "2.0", 11629 "method": "notify_get_types", 11630 "id": 1 11631} 11632~~~ 11633 11634Example response: 11635 11636~~~json 11637{ 11638 "id": 1, 11639 "result": [ 11640 "bdev_register", 11641 "bdev_unregister" 11642 ], 11643 "jsonrpc": "2.0" 11644} 11645~~~ 11646 11647### notify_get_notifications {#notify_get_notifications} 11648 11649Request notifications. Returns array of notifications that happened since the specified id (or first that is available). 11650 11651Notice: Notifications are kept in circular buffer with limited size. Older notifications might be inaccessible 11652due to being overwritten by new ones. 11653 11654#### Parameters 11655 11656Name | Optional | Type | Description 11657----------------------- | -------- | ----------- | ----------- 11658id | Optional | number | First Event ID to fetch (default: first available). 11659max | Optional | number | Maximum number of event to return (default: no limit). 11660 11661#### Response 11662 11663Response is an array of event objects. 11664 11665Name | Optional | Type | Description 11666----------------------- | -------- | ----------- | ----------- 11667id | Optional | number | Event ID. 11668type | Optional | number | Type of the event. 11669ctx | Optional | string | Event context. 11670 11671#### Example 11672 11673Example request: 11674 11675~~~json 11676{ 11677 "id": 1, 11678 "jsonrpc": "2.0", 11679 "method": "notify_get_notifications", 11680 "params": { 11681 "id": 1, 11682 "max": 10 11683 } 11684} 11685 11686~~~ 11687 11688Example response: 11689 11690~~~json 11691{ 11692 "jsonrpc": "2.0", 11693 "id": 1, 11694 "result": [ 11695 { 11696 "ctx": "Malloc0", 11697 "type": "bdev_register", 11698 "id": 1 11699 }, 11700 { 11701 "ctx": "Malloc2", 11702 "type": "bdev_register", 11703 "id": 2 11704 } 11705 ] 11706} 11707~~~ 11708 11709## Linux Userspace Block Device (UBLK) {#jsonrpc_components_ublk} 11710 11711SPDK supports exporting bdevs though Linux ublk. The motivation behind it is to back a Linux kernel block device 11712with an SPDK user space bdev. 11713 11714To export a device over ublk, first make sure the Linux kernel ublk driver is loaded by running 'modprobe ublk_drv'. 11715 11716### ublk_create_target {#rpc_ublk_create_target} 11717 11718Start to create ublk threads and initialize ublk target. It will return an error if user calls this RPC twice without 11719ublk_destroy_target in between. It will use current cpumask in SPDK when user does not specify cpumask option. 11720 11721#### Parameters 11722 11723Name | Optional | Type | Description 11724----------------------- | -------- | ----------- | ----------- 11725cpumask | Optional | string | Cpumask for ublk target 11726disable-user-copy | Optional | boolean | Disable user copy feature 11727 11728#### Response 11729 11730True if ublk target initialization is successful; False if failed. 11731 11732#### Example 11733 11734Example request: 11735 11736~~~json 11737{ 11738 "params": { 11739 "cpumask": "0x2" 11740 }, 11741 "jsonrpc": "2.0", 11742 "method": "ublk_create_target", 11743 "id": 1 11744} 11745~~~ 11746 11747Example response: 11748 11749~~~json 11750{ 11751 "jsonrpc": "2.0", 11752 "id": 1, 11753 "result": true 11754} 11755~~~ 11756 11757### ublk_destroy_target {#rpc_ublk_destroy_target} 11758 11759Release all UBLK devices and destroy ublk target. 11760 11761#### Response 11762 11763True if ublk target destruction is successful; False if failed. 11764 11765#### Example 11766 11767Example request: 11768 11769~~~json 11770{ 11771 "jsonrpc": "2.0", 11772 "method": "ublk_destroy_target", 11773 "id": 1 11774} 11775~~~ 11776 11777Example response: 11778 11779~~~json 11780{ 11781 "jsonrpc": "2.0", 11782 "id": 1, 11783 "result": true 11784} 11785~~~ 11786 11787### ublk_start_disk {#rpc_ublk_start_disk} 11788 11789Start to export one SPDK bdev as a UBLK device 11790 11791#### Parameters 11792 11793Name | Optional | Type | Description 11794----------------------- | -------- | ----------- | ----------- 11795bdev_name | Required | string | Bdev name to export 11796ublk_id | Required | int | Device id 11797queue_depth | Optional | int | Device queue depth 11798num_queues | Optional | int | Total number of device queues 11799 11800#### Response 11801 11802UBLK device ID 11803 11804#### Example 11805 11806Example request: 11807 11808~~~json 11809{ 11810 "params": { 11811 "ublk_id": "1", 11812 "bdev_name": "Malloc1" 11813 }, 11814 "jsonrpc": "2.0", 11815 "method": "ublk_start_disk", 11816 "id": 1 11817} 11818~~~ 11819 11820Example response: 11821 11822~~~json 11823{ 11824 "jsonrpc": "2.0", 11825 "id": 1, 11826 "result": 1 11827} 11828~~~ 11829 11830### ublk_recover_disk {#rpc_ublk_recover_disk} 11831 11832Recover original UBLK device with ID and block device 11833 11834#### Parameters 11835 11836Name | Optional | Type | Description 11837----------------------- | -------- | ----------- | ----------- 11838bdev_name | Required | string | Bdev name to export 11839ublk_id | Required | int | Device id 11840 11841#### Response 11842 11843UBLK device ID 11844 11845#### Example 11846 11847Example request: 11848 11849~~~json 11850{ 11851 "params": { 11852 "ublk_id": "1", 11853 "bdev_name": "Malloc1" 11854 }, 11855 "jsonrpc": "2.0", 11856 "method": "ublk_recover_disk", 11857 "id": 1 11858} 11859~~~ 11860 11861Example response: 11862 11863~~~json 11864{ 11865 "jsonrpc": "2.0", 11866 "id": 1, 11867 "result": 1 11868} 11869 11870### ublk_stop_disk {#rpc_ublk_stop_disk} 11871 11872Delete a UBLK device 11873 11874#### Parameters 11875 11876Name | Optional | Type | Description 11877----------------------- | -------- | ----------- | ----------- 11878ublk_id | Required | int | Device id to delete 11879 11880#### Response 11881 11882True if UBLK device is deleted successfully; False if failed. 11883 11884#### Example 11885 11886Example request: 11887 11888~~~json 11889{ 11890 "params": { 11891 "ublk_id": "1", 11892 }, 11893 "jsonrpc": "2.0", 11894 "method": "ublk_stop_disk", 11895 "id": 1 11896} 11897~~~ 11898 11899Example response: 11900 11901~~~json 11902{ 11903 "jsonrpc": "2.0", 11904 "id": 1, 11905 "result": true 11906} 11907~~~ 11908 11909### ublk_get_disks {#rpc_ublk_get_disks} 11910 11911Display full or specified ublk device list 11912 11913#### Parameters 11914 11915Name | Optional | Type | Description 11916----------------------- | -------- | ----------- | ----------- 11917ublk_id | Optional | int | ublk device id to display 11918 11919#### Response 11920 11921Display ublk device list 11922 11923#### Example 11924 11925Example request: 11926 11927~~~json 11928{ 11929 "jsonrpc": "2.0", 11930 "method": "ublk_get_disks", 11931 "id": 1 11932} 11933~~~ 11934 11935Example response: 11936 11937~~~json 11938{ 11939 "jsonrpc": "2.0", 11940 "id": 1, 11941 "result": [ 11942 { 11943 "ublk_device": "/dev/ublkb1", 11944 "id": 1, 11945 "queue_depth": 512, 11946 "num_queues": 1, 11947 "bdev_name": "Malloc1" 11948 } 11949 ] 11950} 11951~~~ 11952 11953## Linux Network Block Device (NBD) {#jsonrpc_components_nbd} 11954 11955SPDK supports exporting bdevs through Linux nbd. These devices then appear as standard Linux kernel block devices 11956and can be accessed using standard utilities like fdisk. 11957 11958In order to export a device over nbd, first make sure the Linux kernel nbd driver is loaded by running 'modprobe nbd'. 11959 11960### nbd_start_disk {#rpc_nbd_start_disk} 11961 11962Start to export one SPDK bdev as NBD disk 11963 11964#### Parameters 11965 11966Name | Optional | Type | Description 11967----------------------- | -------- | ----------- | ----------- 11968bdev_name | Required | string | Bdev name to export 11969nbd_device | Optional | string | NBD device name to assign 11970 11971#### Response 11972 11973Path of exported NBD disk 11974 11975#### Example 11976 11977Example request: 11978 11979~~~json 11980{ 11981 "params": { 11982 "nbd_device": "/dev/nbd1", 11983 "bdev_name": "Malloc1" 11984 }, 11985 "jsonrpc": "2.0", 11986 "method": "nbd_start_disk", 11987 "id": 1 11988} 11989~~~ 11990 11991Example response: 11992 11993~~~json 11994{ 11995 "jsonrpc": "2.0", 11996 "id": 1, 11997 "result": "/dev/nbd1" 11998} 11999~~~ 12000 12001### nbd_stop_disk {#rpc_nbd_stop_disk} 12002 12003Stop one NBD disk which is based on SPDK bdev. 12004 12005#### Parameters 12006 12007Name | Optional | Type | Description 12008----------------------- | -------- | ----------- | ----------- 12009nbd_device | Required | string | NBD device name to stop 12010 12011#### Example 12012 12013Example request: 12014 12015~~~json 12016{ 12017 "params": { 12018 "nbd_device": "/dev/nbd1", 12019 }, 12020 "jsonrpc": "2.0", 12021 "method": "nbd_stop_disk", 12022 "id": 1 12023} 12024~~~ 12025 12026Example response: 12027 12028~~~json 12029{ 12030 "jsonrpc": "2.0", 12031 "id": 1, 12032 "result": "true" 12033} 12034~~~ 12035 12036### nbd_get_disks {#rpc_nbd_get_disks} 12037 12038Display all or specified NBD device list 12039 12040#### Parameters 12041 12042Name | Optional | Type | Description 12043----------------------- | -------- | ----------- | ----------- 12044nbd_device | Optional | string | NBD device name to display 12045 12046#### Response 12047 12048The response is an array of exported NBD devices and their corresponding SPDK bdev. 12049 12050#### Example 12051 12052Example request: 12053 12054~~~json 12055{ 12056 "jsonrpc": "2.0", 12057 "method": "nbd_get_disks", 12058 "id": 1 12059} 12060~~~ 12061 12062Example response: 12063 12064~~~json 12065{ 12066 "jsonrpc": "2.0", 12067 "id": 1, 12068 "result": [ 12069 { 12070 "bdev_name": "Malloc0", 12071 "nbd_device": "/dev/nbd0" 12072 }, 12073 { 12074 "bdev_name": "Malloc1", 12075 "nbd_device": "/dev/nbd1" 12076 } 12077 ] 12078} 12079~~~ 12080 12081## Blobfs {#jsonrpc_components_blobfs} 12082 12083### blobfs_detect {#rpc_blobfs_detect} 12084 12085Detect whether a blobfs exists on bdev. 12086 12087#### Parameters 12088 12089Name | Optional | Type | Description 12090----------------------- | -------- | ----------- | ----------- 12091bdev_name | Required | string | Block device name to detect blobfs 12092 12093#### Response 12094 12095True if a blobfs exists on the bdev; False otherwise. 12096 12097#### Example 12098 12099Example request: 12100 12101~~~json 12102{ 12103 "jsonrpc": "2.0", 12104 "id": 1, 12105 "method": "blobfs_detect", 12106 "params": { 12107 "bdev_name": "Malloc0" 12108 } 12109} 12110~~~ 12111 12112Example response: 12113 12114~~~json 12115{ 12116 "jsonrpc": "2.0", 12117 "id": 1, 12118 "result": "true" 12119} 12120~~~ 12121 12122### blobfs_create {#rpc_blobfs_create} 12123 12124Build blobfs on bdev. 12125 12126#### Parameters 12127 12128Name | Optional | Type | Description 12129----------------------- | -------- | ----------- | ----------- 12130bdev_name | Required | string | Block device name to create blobfs 12131cluster_sz | Optional | number | Size of cluster in bytes. Must be multiple of 4KiB page size, default and minimal value is 1M. 12132 12133#### Example 12134 12135Example request: 12136 12137~~~json 12138{ 12139 "jsonrpc": "2.0", 12140 "id": 1, 12141 "method": "blobfs_create", 12142 "params": { 12143 "bdev_name": "Malloc0", 12144 "cluster_sz": 1M 12145 } 12146} 12147~~~ 12148 12149Example response: 12150 12151~~~json 12152{ 12153 "jsonrpc": "2.0", 12154 "id": 1, 12155 "result": "true" 12156} 12157~~~ 12158 12159### blobfs_mount {#rpc_blobfs_mount} 12160 12161Mount a blobfs on bdev to one host path through FUSE 12162 12163#### Parameters 12164 12165Name | Optional | Type | Description 12166----------------------- | -------- | ----------- | ----------- 12167bdev_name | Required | string | Block device name where the blobfs is 12168mountpoint | Required | string | Mountpoint path in host to mount blobfs 12169 12170#### Example 12171 12172Example request: 12173 12174~~~json 12175{ 12176 "jsonrpc": "2.0", 12177 "id": 1, 12178 "method": ""blobfs_mount"", 12179 "params": { 12180 "bdev_name": "Malloc0", 12181 "mountpoint": "/mnt/" 12182 } 12183} 12184~~~ 12185 12186Example response: 12187 12188~~~json 12189{ 12190 "jsonrpc": "2.0", 12191 "id": 1, 12192 "result": "true" 12193} 12194~~~ 12195 12196### blobfs_set_cache_size {#rpc_blobfs_set_cache_size} 12197 12198Set cache pool size for blobfs filesystems. This RPC is only permitted when the cache pool is not already initialized. 12199 12200The cache pool is initialized when the first blobfs filesystem is initialized or loaded. It is freed when the all 12201initialized or loaded filesystems are unloaded. 12202 12203#### Parameters 12204 12205Name | Optional | Type | Description 12206----------------------- | -------- | ----------- | ----------- 12207size_in_mb | Required | number | Cache size in megabytes 12208 12209#### Response 12210 12211True if cache size is set successfully; False if failed to set. 12212 12213#### Example 12214 12215Example request: 12216 12217~~~json 12218{ 12219 "jsonrpc": "2.0", 12220 "id": 1, 12221 "method": "blobfs_set_cache_size", 12222 "params": { 12223 "size_in_mb": 512, 12224 } 12225} 12226~~~ 12227 12228Example response: 12229 12230~~~json 12231{ 12232 "jsonrpc": "2.0", 12233 "id": 1, 12234 "result": true 12235} 12236~~~ 12237 12238## Socket layer {#jsonrpc_components_sock} 12239 12240### sock_impl_get_options {#rpc_sock_impl_get_options} 12241 12242Get parameters for the socket layer implementation. 12243 12244#### Parameters 12245 12246Name | Optional | Type | Description 12247----------------------- | -------- | ----------- | ----------- 12248impl_name | Required | string | Name of socket implementation, e.g. posix 12249 12250#### Response 12251 12252Response is an object with current socket layer options for requested implementation. 12253 12254#### Example 12255 12256Example request: 12257 12258~~~json 12259{ 12260 "jsonrpc": "2.0", 12261 "method": "sock_impl_get_options", 12262 "id": 1, 12263 "params": { 12264 "impl_name": "posix" 12265 } 12266} 12267~~~ 12268 12269Example response: 12270 12271~~~json 12272{ 12273 "jsonrpc": "2.0", 12274 "id": 1, 12275 "result": { 12276 "recv_buf_size": 2097152, 12277 "send_buf_size": 2097152, 12278 "enable_recv_pipe": true, 12279 "enable_quickack": true, 12280 "enable_placement_id": 0, 12281 "enable_zerocopy_send_server": true, 12282 "enable_zerocopy_send_client": false, 12283 "zerocopy_threshold": 0, 12284 "tls_version": 13, 12285 "enable_ktls": false 12286 } 12287} 12288~~~ 12289 12290### sock_impl_set_options {#rpc_sock_impl_set_options} 12291 12292Set parameters for the socket layer implementation. 12293 12294#### Parameters 12295 12296Name | Optional | Type | Description 12297--------------------------- | -------- | ----------- | ----------- 12298impl_name | Required | string | Name of socket implementation, e.g. posix 12299recv_buf_size | Optional | number | Size of socket receive buffer in bytes 12300send_buf_size | Optional | number | Size of socket send buffer in bytes 12301enable_recv_pipe | Optional | boolean | Enable or disable receive pipe 12302enable_quick_ack | Optional | boolean | Enable or disable quick ACK 12303enable_placement_id | Optional | number | Enable or disable placement_id. 0:disable,1:incoming_napi,2:incoming_cpu 12304enable_zerocopy_send_server | Optional | boolean | Enable or disable zero copy on send for server sockets 12305enable_zerocopy_send_client | Optional | boolean | Enable or disable zero copy on send for client sockets 12306zerocopy_threshold | Optional | number | Set zerocopy_threshold in bytes. A consecutive sequence of requests' iovecs 12307-- | -- | -- | that fall below this threshold may be sent without zerocopy flag set 12308tls_version | Optional | number | TLS protocol version, e.g. 13 for v1.3 (only applies when impl_name == ssl) 12309enable_ktls | Optional | boolean | Enable or disable Kernel TLS (only applies when impl_name == ssl) 12310 12311#### Response 12312 12313True if socket layer options were set successfully. 12314 12315#### Example 12316 12317Example request: 12318 12319~~~json 12320{ 12321 "jsonrpc": "2.0", 12322 "method": "sock_impl_set_options", 12323 "id": 1, 12324 "params": { 12325 "impl_name": "posix", 12326 "recv_buf_size": 2097152, 12327 "send_buf_size": 2097152, 12328 "enable_recv_pipe": false, 12329 "enable_quick_ack": false, 12330 "enable_placement_id": 0, 12331 "enable_zerocopy_send_server": true, 12332 "enable_zerocopy_send_client": false, 12333 "zerocopy_threshold": 10240, 12334 "tls_version": 13, 12335 "enable_ktls": false 12336 } 12337} 12338~~~ 12339 12340Example response: 12341 12342~~~json 12343{ 12344 "jsonrpc": "2.0", 12345 "id": 1, 12346 "result": true 12347} 12348~~~ 12349 12350### sock_set_default_impl {#rpc_sock_set_default_impl} 12351 12352Set the default sock implementation. 12353 12354#### Parameters 12355 12356Name | Optional | Type | Description 12357----------------------- | -------- | ----------- | ----------- 12358impl_name | Required | string | Name of socket implementation, e.g. posix 12359 12360#### Response 12361 12362True if the default socket layer configuration was set successfully. 12363 12364#### Example 12365 12366Example request: 12367 12368~~~json 12369{ 12370 "jsonrpc": "2.0", 12371 "method": "sock_set_default_impl", 12372 "id": 1, 12373 "params": { 12374 "impl_name": "posix" 12375 } 12376} 12377~~~ 12378 12379Example response: 12380 12381~~~json 12382{ 12383 "jsonrpc": "2.0", 12384 "id": 1, 12385 "result": true 12386} 12387~~~ 12388 12389### sock_get_default_impl {#rpc_sock_get_default_impl} 12390 12391Get the name of the default sock implementation. 12392 12393#### Parameters 12394 12395This function has no parameters. 12396 12397#### Response 12398 12399The name of the current default socket implementation. 12400 12401#### Example 12402 12403Example request: 12404 12405~~~json 12406{ 12407 "jsonrpc": "2.0", 12408 "method": "sock_get_default_impl", 12409 "id": 1 12410} 12411~~~ 12412 12413Example response: 12414 12415~~~json 12416{ 12417 "jsonrpc": "2.0", 12418 "id": 1, 12419 "result": { 12420 "impl_name": "posix" 12421 } 12422} 12423~~~ 12424 12425## Miscellaneous RPC commands 12426 12427### bdev_nvme_send_cmd {#rpc_bdev_nvme_send_cmd} 12428 12429Send NVMe command directly to NVMe controller or namespace. Parameters and responses encoded by base64 urlsafe need further processing. 12430 12431Notice: bdev_nvme_send_cmd requires user to guarantee the correctness of NVMe command itself, and also optional parameters. 12432Illegal command contents or mismatching buffer size may result in unpredictable behavior. 12433 12434#### Parameters 12435 12436Name | Optional | Type | Description 12437----------------------- | -------- | ----------- | ----------- 12438name | Required | string | Name of the operating NVMe controller 12439cmd_type | Required | string | Type of nvme cmd. Valid values are: admin, io 12440data_direction | Required | string | Direction of data transfer. Valid values are: c2h, h2c 12441cmdbuf | Required | string | NVMe command encoded by base64 urlsafe 12442data | Optional | string | Data transferring to controller from host, encoded by base64 urlsafe 12443metadata | Optional | string | Metadata transferring to controller from host, encoded by base64 urlsafe 12444data_len | Optional | number | Data length required to transfer from controller to host 12445metadata_len | Optional | number | Metadata length required to transfer from controller to host 12446timeout_ms | Optional | number | Command execution timeout value, in milliseconds 12447 12448#### Response 12449 12450Name | Type | Description 12451----------------------- | ----------- | ----------- 12452cpl | string | NVMe completion queue entry, encoded by base64 urlsafe 12453data | string | Data transferred from controller to host, encoded by base64 urlsafe 12454metadata | string | Metadata transferred from controller to host, encoded by base64 urlsafe 12455 12456#### Example 12457 12458Example request: 12459 12460~~~json 12461{ 12462 "jsonrpc": "2.0", 12463 "method": "bdev_nvme_send_cmd", 12464 "id": 1, 12465 "params": { 12466 "name": "Nvme0", 12467 "cmd_type": "admin" 12468 "data_direction": "c2h", 12469 "cmdbuf": "BgAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAsGUs9P5_AAAAAAAAABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==", 12470 "data_len": 60, 12471 } 12472} 12473~~~ 12474 12475Example response: 12476 12477~~~json 12478{ 12479 "jsonrpc": "2.0", 12480 "id": 1, 12481 "result": { 12482 "cpl": "AAAAAAAAAAARAAAAWrmwABAA==", 12483 "data": "sIjg6AAAAACwiODoAAAAALCI4OgAAAAAAAYAAREAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" 12484 } 12485 12486} 12487~~~ 12488 12489### vmd_enable {#rpc_enable_vmd} 12490 12491Enable VMD enumeration. 12492 12493#### Parameters 12494 12495This method has no parameters. 12496 12497#### Response 12498 12499Completion status of enumeration is returned as a boolean. 12500 12501### Example 12502 12503Example request: 12504 12505~~~json 12506{ 12507 "jsonrpc": "2.0", 12508 "method": "vmd_enable", 12509 "id": 1 12510} 12511~~~ 12512 12513Example response: 12514 12515~~~json 12516{ 12517 "jsonrpc": "2.0", 12518 "id": 1, 12519 "result": true 12520} 12521~~~ 12522 12523### vmd_remove_device {#rpc_vmd_remove_device} 12524 12525Remove a device behind a VMD. 12526 12527### Parameters 12528 12529Name | Optional | Type | Description 12530----------------------- | -------- | ----------- | ----------- 12531addr | Required | string | Address of the device to remove. 12532 12533### Example 12534 12535~~~json 12536{ 12537 "jsonrpc": "2.0", 12538 "method": "vmd_remove_device", 12539 "params": { 12540 "addr": "5d0505:01:00.0" 12541 } 12542 "id": 1 12543} 12544~~~ 12545 12546Example response: 12547 12548~~~json 12549{ 12550 "jsonrpc": "2.0", 12551 "id": 1, 12552 "result": true 12553} 12554~~~ 12555 12556### vmd_rescan {#rpc_vmd_rescan} 12557 12558Force a rescan of the devices behind VMD. 12559 12560### Parameters 12561 12562This method has no parameters. 12563 12564#### Response 12565 12566The response is the number of new devices found. 12567 12568### Example 12569 12570~~~json 12571{ 12572 "jsonrpc": "2.0", 12573 "method": "vmd_rescan", 12574 "id": 1 12575} 12576~~~ 12577 12578Example response: 12579 12580~~~json 12581{ 12582 "jsonrpc": "2.0", 12583 "id": 1, 12584 "result": { 12585 "count": 1 12586 } 12587} 12588~~~ 12589 12590### spdk_get_version {#rpc_spdk_get_version} 12591 12592Get the version info of the running SPDK application. 12593 12594#### Parameters 12595 12596This method has no parameters. 12597 12598#### Response 12599 12600The response is the version number including major version number, minor version number, patch level number and suffix string. 12601 12602#### Example 12603 12604Example request: 12605 12606~~~json 12607{ 12608 "jsonrpc": "2.0", 12609 "id": 1, 12610 "method": "spdk_get_version" 12611} 12612~~~ 12613 12614Example response: 12615 12616~~~json 12617{ 12618 "jsonrpc": "2.0", 12619 "id": 1, 12620 "result": { 12621 "version": "19.04-pre", 12622 "fields" : { 12623 "major": 19, 12624 "minor": 4, 12625 "patch": 0, 12626 "suffix": "-pre" 12627 } 12628 } 12629} 12630~~~ 12631 12632### framework_get_pci_devices 12633 12634List PCIe devices attached to an SPDK application and the contents of their config space. 12635 12636#### Parameters 12637 12638This method has no parameters. 12639 12640#### Response 12641 12642The response is an array of attached PCIe devices. 12643 12644#### Example 12645 12646Example request: 12647 12648~~~json 12649{ 12650 "jsonrpc": "2.0", 12651 "id": 1, 12652 "method": "framework_get_pci_devices" 12653} 12654~~~ 12655 12656Example response: 12657Note that the config space buffer was trimmed. 12658 12659~~~json 12660{ 12661 "jsonrpc": "2.0", 12662 "id": 1, 12663 "result": { 12664 [ 12665 { 12666 "address": "0000:00:04.0", 12667 "config_space": "8680455807051000...0000000000000000" 12668 }, 12669 { 12670 "address": "0000:00:03.0", 12671 "config_space": "8680455807051000...0000000000000000" 12672 } 12673 ] 12674 } 12675} 12676~~~ 12677 12678### bdev_nvme_add_error_injection {#rpc_bdev_nvme_add_error_injection} 12679 12680Add a NVMe command error injection for a bdev nvme controller. 12681 12682#### Parameters 12683 12684Name | Optional | Type | Description 12685----------------------- | -------- | ----------- | ----------- 12686name | Required | string | Name of the operating NVMe controller 12687cmd_type | Required | string | Type of NVMe command. Valid values are: admin, io 12688opc | Required | number | Opcode for which the error injection is applied 12689do_not_submit | Optional | boolean | Set to true if request should not be submitted to the controller (default false) 12690timeout_in_us | Optional | number | Wait specified microseconds when do_not_submit is true 12691err_count | Optional | number | Number of matching NVMe commands to inject errors 12692sct | Optional | number | Status code type (default 0) 12693sc | Optional | number | Status code (default 0) 12694 12695#### Response 12696 12697true on success 12698 12699#### Example 12700 12701Example request: 12702 12703~~~json 12704{ 12705 "jsonrpc": "2.0", 12706 "method": "bdev_nvme_add_error_injection", 12707 "id": 1, 12708 "params": { 12709 "name": "HotInNvme0", 12710 "opc": 2, 12711 "cmd_type": "io", 12712 "err_count": 1111111, 12713 "sct": 11, 12714 "sc": 33 12715 } 12716} 12717 12718~~~ 12719 12720Example response: 12721 12722~~~json 12723{ 12724 "jsonrpc": "2.0", 12725 "id": 1, 12726 "result": true 12727} 12728 12729~~~ 12730 12731### bdev_nvme_remove_error_injection {#rpc_bdev_nvme_remove_error_injection} 12732 12733Remove a NVMe command error injection. 12734 12735#### Parameters 12736 12737Name | Optional | Type | Description 12738----------------------- | -------- | ----------- | ----------- 12739name | Required | string | Name of the operating NVMe controller 12740cmd_type | Required | string | Type of NVMe command. Valid values are: admin, io 12741opc | Required | number | Opcode for which the error injection is applied 12742 12743#### Response 12744 12745true on success 12746 12747#### Example 12748 12749Example request: 12750 12751~~~json 12752{ 12753 "jsonrpc": "2.0", 12754 "method": "bdev_nvme_remove_error_injection", 12755 "id": 1, 12756 "params": { 12757 "name": "HotInNvme0", 12758 "opc": 2, 12759 "cmd_type": "io" 12760 } 12761} 12762 12763 12764~~~ 12765 12766Example response: 12767 12768~~~json 12769{ 12770 "jsonrpc": "2.0", 12771 "id": 1, 12772 "result": true 12773} 12774 12775~~~ 12776 12777### bdev_daos_create {#rpc_bdev_daos_create} 12778 12779Construct @ref bdev_config_daos 12780 12781#### Parameters 12782 12783Name | Optional | Type | Description 12784----------------------- | -------- | ----------- | ----------- 12785name | Required | string | Bdev name to use 12786pool | Required | string | DAOS pool label or its uuid 12787cont | Required | string | DAOS cont label or its uuid 12788block_size | Required | number | Block size in bytes -must be multiple of 512 12789num_blocks | Required | number | Number of blocks 12790uuid | Optional | string | UUID of new bdev 12791oclass | Optional | string | DAOS object class (default SX) 12792 12793To find more about various object classes please visit [DAOS documentation](https://github.com/daos-stack/daos/blob/master/src/object/README.md). 12794Please note, that DAOS bdev module uses the same CLI flag notation as `dmg` and `daos` commands, 12795for instance, `SX` or `EC_4P2G2` rather than in DAOS header file `OC_SX` or `OC_EC_4P2G2`. 12796 12797#### Result 12798 12799Name of newly created bdev. 12800 12801#### Example 12802 12803Example request: 12804 12805~~~json 12806{ 12807 "params": { 12808 "block_size": 4096, 12809 "num_blocks": 16384, 12810 "name": "daosdev0", 12811 "pool": "test-pool", 12812 "cont": "test-cont", 12813 "oclass": "EC_4P2G2" 12814 }, 12815 "jsonrpc": "2.0", 12816 "method": "bdev_daos_create", 12817 "id": 1 12818} 12819~~~ 12820 12821Example response: 12822 12823~~~json 12824{ 12825 "jsonrpc": "2.0", 12826 "id": 1, 12827 "result": "daosdev0" 12828} 12829~~~ 12830 12831### bdev_daos_delete {#rpc_bdev_daos_delete} 12832 12833Delete @ref bdev_config_daos 12834 12835#### Parameters 12836 12837Name | Optional | Type | Description 12838----------------------- | -------- | ----------- | ----------- 12839name | Required | string | Bdev name 12840 12841#### Example 12842 12843Example request: 12844 12845~~~json 12846{ 12847 "params": { 12848 "name": "daosdev0" 12849 }, 12850 "jsonrpc": "2.0", 12851 "method": "bdev_daos_delete", 12852 "id": 1 12853} 12854~~~ 12855 12856Example response: 12857 12858~~~json 12859{ 12860 "jsonrpc": "2.0", 12861 "id": 1, 12862 "result": true 12863} 12864~~~ 12865 12866### bdev_daos_resize {#rpc_bdev_daos_resize} 12867 12868Resize @ref bdev_config_daos. 12869 12870#### Parameters 12871 12872Name | Optional | Type | Description 12873----------------------- | -------- | ----------- | ----------- 12874name | Required | string | Bdev name 12875new_size | Required | number | Bdev new capacity in MiB 12876 12877#### Example 12878 12879Example request: 12880 12881~~~json 12882{ 12883 "params": { 12884 "name": "daosdev0", 12885 "new_size": 8192 12886 }, 12887 "jsonrpc": "2.0", 12888 "method": "bdev_daos_resize", 12889 "id": 1 12890} 12891~~~ 12892 12893Example response: 12894 12895~~~json 12896{ 12897 "jsonrpc": "2.0", 12898 "id": 1, 12899 "result": true 12900} 12901~~~ 12902 12903### iobuf_set_options {#rpc_iobuf_set_options} 12904 12905Set iobuf buffer pool options. 12906 12907#### Parameters 12908 12909Name | Optional | Type | Description 12910----------------------- | -------- | ----------- | ----------- 12911small_pool_count | Optional | number | Number of small buffers in the global pool 12912large_pool_count | Optional | number | Number of large buffers in the global pool 12913small_bufsize | Optional | number | Size of a small buffer 12914large_bufsize | Optional | number | Size of a small buffer 12915 12916#### Example 12917 12918Example request: 12919 12920~~~json 12921{ 12922 "jsonrpc": "2.0", 12923 "id": 1, 12924 "method": "iobuf_set_options", 12925 "params": { 12926 "small_pool_count": 16383, 12927 "large_pool_count": 2047 12928 } 12929} 12930~~~ 12931 12932Example response: 12933 12934~~~json 12935{ 12936 "jsonrpc": "2.0", 12937 "id": 1, 12938 "result": true 12939} 12940~~~ 12941 12942### iobuf_get_stats {#rpc_iobuf_get_stats} 12943 12944Retrieve iobuf's statistics. 12945 12946#### Parameters 12947 12948None. 12949 12950#### Example 12951 12952Example request: 12953 12954~~~json 12955{ 12956 "jsonrpc": "2.0", 12957 "method": "iobuf_get_stats", 12958 "id": 1 12959} 12960~~~ 12961 12962Example response: 12963 12964~~~json 12965{ 12966 "jsonrpc": "2.0", 12967 "id": 1, 12968 "result": [ 12969 { 12970 "module": "accel", 12971 "small_pool": { 12972 "cache": 0, 12973 "main": 0, 12974 "retry": 0 12975 }, 12976 "large_pool": { 12977 "cache": 0, 12978 "main": 0, 12979 "retry": 0 12980 } 12981 }, 12982 { 12983 "module": "bdev", 12984 "small_pool": { 12985 "cache": 421965, 12986 "main": 1218, 12987 "retry": 0 12988 }, 12989 "large_pool": { 12990 "cache": 0, 12991 "main": 0, 12992 "retry": 0 12993 } 12994 }, 12995 { 12996 "module": "nvmf_TCP", 12997 "small_pool": { 12998 "cache": 7, 12999 "main": 0, 13000 "retry": 0 13001 }, 13002 "large_pool": { 13003 "cache": 0, 13004 "main": 0, 13005 "retry": 0 13006 } 13007 } 13008 ] 13009} 13010~~~ 13011 13012### bdev_nvme_start_mdns_discovery {#rpc_bdev_nvme_start_mdns_discovery} 13013 13014Starts an mDNS based discovery service for the specified service type for the 13015auto-discovery of discovery controllers (NVMe TP-8009). 13016 13017The discovery service will listen for the mDNS discovery events from the 13018Avahi-daemon and will connect to the newly learnt discovery controllers. 13019Then the discovery service will automatically attach to any subsystem found in the 13020discovery log page from the discovery controllers learnt using mDNS. 13021When determining a controller name to use when attaching, it will use 13022the 'name' parameter as a prefix, followed by a unique integer assigned for each of the 13023discovery controllers learnt through mDNS, followed by a unique integer for that discovery 13024service. If the discovery service identifies a subsystem that has been previously 13025attached but is listed with a different path, it will use the same controller name 13026as the previous entry, and connect as a multipath. 13027 13028When the discovery service sees that a subsystem entry has been removed 13029from the log page, it will automatically detach from that controller as well. 13030 13031The 'name' is also used to later stop the discovery service. 13032 13033#### Parameters 13034 13035Name | Optional | Type | Description 13036-------------------------- | -------- | ----------- | ----------- 13037name | Required | string | Prefix for NVMe discovery services found 13038svcname | Required | string | Service to discover: e.g. _nvme-disc._tcp 13039hostnqn | Optional | string | NVMe-oF hostnqn 13040 13041#### Example 13042 13043Example request: 13044 13045~~~json 13046{ 13047 "jsonrpc": "2.0", 13048 "method": "bdev_nvme_start_mdns_discovery", 13049 "id": 1, 13050 "params": { 13051 "name": "cdc_auto", 13052 "svcname": "_nvme-disc._tcp", 13053 "hostnqn": "nqn.2021-12.io.spdk:host1", 13054 } 13055} 13056~~~ 13057 13058Example response: 13059 13060~~~json 13061{ 13062 "jsonrpc": "2.0", 13063 "id": 1, 13064 "result": true 13065} 13066~~~ 13067 13068### bdev_nvme_stop_mdns_discovery {#rpc_bdev_nvme_stop_mdns_discovery} 13069 13070Stops a mDNS discovery service. This includes detaching any controllers that were 13071discovered via the service that is being stopped. 13072 13073#### Parameters 13074 13075Name | Optional | Type | Description 13076-------------------------- | -------- | ----------- | ----------- 13077name | Required | string | Name of mDNS discovery instance to stop 13078 13079#### Example 13080 13081Example request: 13082 13083~~~json 13084{ 13085 "jsonrpc": "2.0", 13086 "method": "bdev_nvme_stop_mdns_discovery", 13087 "id": 1, 13088 "params": { 13089 "name": "cdc_auto" 13090 } 13091} 13092~~~ 13093 13094Example response: 13095 13096~~~json 13097{ 13098 "jsonrpc": "2.0", 13099 "id": 1, 13100 "result": true 13101} 13102~~~ 13103 13104### bdev_nvme_get_mdns_discovery_info {#rpc_bdev_nvme_get_mdns_discovery_info} 13105 13106Get the information about the mDNS discovery service instances. 13107 13108#### Example 13109 13110Example request: 13111~~~json 13112{ 13113 "jsonrpc": "2.0", 13114 "method": "bdev_nvme_get_mdns_discovery_info", 13115 "id": 1 13116} 13117~~~ 13118 13119Example response: 13120 13121~~~json 13122[ 13123 { 13124 "name": "cdc_auto", 13125 "svcname": "_nvme-disc._tcp", 13126 "referrals": [ 13127 { 13128 "name": "cdc_auto0", 13129 "trid": { 13130 "trtype": "TCP", 13131 "adrfam": "IPv4", 13132 "traddr": "66.1.2.21", 13133 "trsvcid": "8009", 13134 "subnqn": "nqn.2014-08.org.nvmexpress.discovery" 13135 } 13136 }, 13137 { 13138 "name": "cdc_auto1", 13139 "trid": { 13140 "trtype": "TCP", 13141 "adrfam": "IPv4", 13142 "traddr": "66.1.1.21", 13143 "trsvcid": "8009", 13144 "subnqn": "nqn.2014-08.org.nvmexpress.discovery" 13145 } 13146 } 13147 ] 13148 } 13149] 13150~~~ 13151 13152### keyring_file_add_key {#rpc_keyring_file_add_key} 13153 13154Add a file-based key to a keyring. 13155 13156#### Parameters 13157 13158Name | Optional | Type | Description 13159-------------------------- | -------- | ----------- | ----------- 13160name | Required | string | Name of the key to add. 13161path | Required | string | Path to a file containing the key. 13162 13163#### Example 13164 13165Example request: 13166 13167~~~json 13168{ 13169 "jsonrpc": "2.0", 13170 "method": "keyring_file_add_key", 13171 "id": 1 13172 "params": { 13173 "name": "key0", 13174 "path": "/path/to/key0" 13175 } 13176} 13177~~~ 13178 13179Example response: 13180 13181~~~json 13182{ 13183 "jsonrpc": "2.0", 13184 "id": 1, 13185 "result": true 13186} 13187~~~ 13188 13189### keyring_file_remove_key {#rpc_keyring_file_remove_key} 13190 13191Remove a file-based key from a keyring. 13192 13193#### Parameters 13194 13195Name | Optional | Type | Description 13196-------------------------- | -------- | ----------- | ----------- 13197name | Required | string | Name of the key to remove. 13198 13199#### Example 13200 13201Example request: 13202 13203~~~json 13204{ 13205 "jsonrpc": "2.0", 13206 "method": "keyring_file_remove_key", 13207 "id": 1 13208 "params": { 13209 "name": "key0" 13210 } 13211} 13212~~~ 13213 13214Example response: 13215 13216~~~json 13217{ 13218 "jsonrpc": "2.0", 13219 "id": 1, 13220 "result": true 13221} 13222~~~ 13223 13224### keyring_get_keys {#rpc_keyring_get_keys} 13225 13226Get a list of available keys. This RPC will only list keys that are currently attached to a 13227keyring. Dynamically loaded keys (via the `probe_key()` callback) will only be included if they're 13228currently in-use (i.e. with active references obtained via `spdk_keyring_get_key()`). 13229 13230#### Example 13231 13232Example request: 13233~~~json 13234{ 13235 "jsonrpc": "2.0", 13236 "method": "keyring_get_keys", 13237 "id": 1 13238} 13239~~~ 13240 13241Example response: 13242 13243~~~json 13244{ 13245 "jsonrpc": "2.0", 13246 "id": 1, 13247 "result": [ 13248 { 13249 "name": "key0", 13250 "module": "keyring_file", 13251 "removed": false, 13252 "probed": false, 13253 "refcnt": 1, 13254 "path": "/path/to/key0" 13255 }, 13256 { 13257 "name": "key1", 13258 "module": "keyring_file", 13259 "removed": false, 13260 "probed": false, 13261 "refcnt": 1, 13262 "path": "/path/to/key1" 13263 } 13264 ] 13265} 13266~~~ 13267 13268### keyring_linux_set_options {#keyring_linux_set_options} 13269 13270Set options of the keyring_linux module. 13271 13272#### Parameters 13273 13274Name | Optional | Type | Description 13275----------------------- | -------- | ----------- | ----------- 13276enable | Optional | boolean | Enable the module. 13277 13278#### Example 13279 13280Example request: 13281~~~json 13282{ 13283 "jsonrpc": "2.0", 13284 "method": "keyring_linux_set_options", 13285 "id": 1 13286 "params": { 13287 "enable": true 13288 } 13289} 13290~~~ 13291 13292Example response: 13293 13294~~~json 13295{ 13296 "jsonrpc": "2.0", 13297 "id": 1, 13298 "result": true 13299} 13300~~~ 13301 13302### nvmf_publish_mdns_prr {#rpc_nvmf_publish_mdns_prr} 13303 13304This interface is used to publish an NVMf target's service location using mDNS 13305(Multicast DNS) protocol. It allows clients to discover the NVMf target using 13306the published service location. 13307 13308#### Parameters 13309 13310Name | Optional | Type | Description 13311-------------------------- | -------- | ----------- | ----------- 13312tgt_name | Optional | string | Parent NVMe-oF target name. 13313 13314#### Example 13315 13316Example request: 13317 13318~~~json 13319{ 13320 "jsonrpc": "2.0", 13321 "method": "nvmf_publish_mdns_prr", 13322 "id": 1, 13323} 13324~~~ 13325 13326Example response: 13327 13328~~~json 13329{ 13330 "jsonrpc": "2.0", 13331 "id": 1, 13332 "result": true 13333} 13334~~~ 13335 13336### nvmf_stop_mdns_prr {#rpc_nvmf_stop_mdns_prr} 13337 13338This interface is used to stop publishing the NVMf target's service location 13339using mDNS (Multicast DNS) protocol. It removes the published service location, 13340preventing clients from discovering the NVMf target. 13341 13342#### Parameters 13343 13344Name | Optional | Type | Description 13345-------------------------- | -------- | ----------- | ----------- 13346tgt_name | Optional | string | Parent NVMe-oF target name. 13347 13348#### Example 13349 13350Example request: 13351 13352~~~json 13353{ 13354 "jsonrpc": "2.0", 13355 "method": "nvmf_stop_mdns_prr", 13356 "id": 1 13357} 13358~~~ 13359 13360Example response: 13361 13362~~~json 13363{ 13364 "jsonrpc": "2.0", 13365 "id": 1, 13366 "result": true 13367} 13368~~~ 13369