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 "ioat_scan_accel_engine", 445 "idxd_scan_accel_engine", 446 "bdev_virtio_attach_controller", 447 "bdev_virtio_scsi_get_devices", 448 "bdev_virtio_detach_controller", 449 "bdev_virtio_blk_set_hotplug", 450 "bdev_aio_delete", 451 "bdev_aio_create", 452 "bdev_split_delete", 453 "bdev_split_create", 454 "bdev_error_inject_error", 455 "bdev_error_delete", 456 "bdev_error_create", 457 "bdev_passthru_create", 458 "bdev_passthru_delete" 459 "bdev_nvme_apply_firmware", 460 "bdev_nvme_get_transport_statistics", 461 "bdev_nvme_get_controller_health_info", 462 "bdev_nvme_detach_controller", 463 "bdev_nvme_attach_controller", 464 "bdev_null_create", 465 "bdev_malloc_delete", 466 "bdev_malloc_create", 467 "bdev_ftl_delete", 468 "bdev_ftl_create", 469 "bdev_lvol_get_lvstores", 470 "bdev_lvol_delete", 471 "bdev_lvol_resize", 472 "bdev_lvol_set_read_only", 473 "bdev_lvol_decouple_parent", 474 "bdev_lvol_inflate", 475 "bdev_lvol_rename", 476 "bdev_lvol_clone", 477 "bdev_lvol_snapshot", 478 "bdev_lvol_create", 479 "bdev_lvol_delete_lvstore", 480 "bdev_lvol_rename_lvstore", 481 "bdev_lvol_create_lvstore" 482 ] 483} 484~~~ 485 486### framework_get_subsystems {#rpc_framework_get_subsystems} 487 488Get an array of name and dependency relationship of SPDK subsystems in initialization order. 489 490#### Parameters 491 492None 493 494#### Response 495 496The response is an array of name and dependency relationship of SPDK subsystems in initialization order. 497 498#### Example 499 500Example request: 501 502~~~json 503{ 504 "jsonrpc": "2.0", 505 "id": 1, 506 "method": "framework_get_subsystems" 507} 508~~~ 509 510Example response: 511 512~~~json 513{ 514 "jsonrpc": "2.0", 515 "id": 1, 516 "result": [ 517 { 518 "subsystem": "accel", 519 "depends_on": [] 520 }, 521 { 522 "subsystem": "interface", 523 "depends_on": [] 524 }, 525 { 526 "subsystem": "net_framework", 527 "depends_on": [ 528 "interface" 529 ] 530 }, 531 { 532 "subsystem": "bdev", 533 "depends_on": [ 534 "accel" 535 ] 536 }, 537 { 538 "subsystem": "nbd", 539 "depends_on": [ 540 "bdev" 541 ] 542 }, 543 { 544 "subsystem": "nvmf", 545 "depends_on": [ 546 "bdev" 547 ] 548 }, 549 { 550 "subsystem": "scsi", 551 "depends_on": [ 552 "bdev" 553 ] 554 }, 555 { 556 "subsystem": "vhost", 557 "depends_on": [ 558 "scsi" 559 ] 560 }, 561 { 562 "subsystem": "iscsi", 563 "depends_on": [ 564 "scsi" 565 ] 566 } 567 ] 568} 569~~~ 570 571### framework_get_config {#rpc_framework_get_config} 572 573Get current configuration of the specified SPDK framework 574 575#### Parameters 576 577Name | Optional | Type | Description 578----------------------- | -------- | ----------- | ----------- 579name | Required | string | SPDK subsystem name 580 581#### Response 582 583The response is current configuration of the specified SPDK subsystem. 584Null is returned if it is not retrievable by the framework_get_config method and empty array is returned if it is empty. 585 586#### Example 587 588Example request: 589 590~~~json 591{ 592 "jsonrpc": "2.0", 593 "id": 1, 594 "method": "framework_get_config", 595 "params": { 596 "name": "bdev" 597 } 598} 599~~~ 600 601Example response: 602 603~~~json 604{ 605 "jsonrpc": "2.0", 606 "id": 1, 607 "result": [ 608 { 609 "params": { 610 "base_bdev": "Malloc2", 611 "split_size_mb": 0, 612 "split_count": 2 613 }, 614 "method": "bdev_split_create" 615 }, 616 { 617 "params": { 618 "trtype": "PCIe", 619 "name": "Nvme1", 620 "traddr": "0000:01:00.0" 621 }, 622 "method": "bdev_nvme_attach_controller" 623 }, 624 { 625 "params": { 626 "trtype": "PCIe", 627 "name": "Nvme2", 628 "traddr": "0000:03:00.0" 629 }, 630 "method": "bdev_nvme_attach_controller" 631 }, 632 { 633 "params": { 634 "block_size": 512, 635 "num_blocks": 131072, 636 "name": "Malloc0", 637 "uuid": "913fc008-79a7-447f-b2c4-c73543638c31" 638 }, 639 "method": "bdev_malloc_create" 640 }, 641 { 642 "params": { 643 "block_size": 512, 644 "num_blocks": 131072, 645 "name": "Malloc1", 646 "uuid": "dd5b8f6e-b67a-4506-b606-7fff5a859920" 647 }, 648 "method": "bdev_malloc_create" 649 } 650 ] 651} 652~~~ 653 654### framework_get_reactors {#rpc_framework_get_reactors} 655 656Retrieve an array of all reactors. 657 658#### Parameters 659 660This method has no parameters. 661 662#### Response 663 664The response is an array of all reactors. 665 666#### Example 667 668Example request: 669 670~~~json 671{ 672 "jsonrpc": "2.0", 673 "method": "framework_get_reactors", 674 "id": 1 675} 676~~~ 677 678Example response: 679 680~~~json 681{ 682 "jsonrpc": "2.0", 683 "id": 1, 684 "result": { 685 "tick_rate": 2400000000, 686 "reactors": [ 687 { 688 "lcore": 0, 689 "busy": 41289723495, 690 "idle": 3624832946, 691 "lw_threads": [ 692 { 693 "name": "app_thread", 694 "id", 1, 695 "cpumask": "1", 696 "elapsed": 44910853363 697 } 698 ] 699 } 700 ] 701 } 702} 703~~~ 704 705### framework_set_scheduler {#rpc_framework_set_scheduler} 706 707Select thread scheduler that will be activated. 708This feature is considered as experimental. 709 710#### Parameters 711 712Name | Optional | Type | Description 713----------------------- | -------- | ----------- | ----------- 714name | Required | string | Name of a scheduler 715period | Optional | number | Scheduler period 716load_limit | Optional | number | Thread load limit in % (dynamic only) 717core_limit | Optional | number | Load limit on the core to be considered full (dynamic only) 718core_busy | Optional | number | Indicates at what load on core scheduler should move threads to a different core (dynamic only) 719 720#### Response 721 722Completion status of the operation is returned as a boolean. 723 724#### Example 725 726Example request: 727 728~~~json 729{ 730 "jsonrpc": "2.0", 731 "method": "framework_set_scheduler", 732 "id": 1, 733 "params": { 734 "name": "static", 735 "period": "1000000" 736 } 737} 738~~~ 739 740Example response: 741 742~~~json 743{ 744 "jsonrpc": "2.0", 745 "id": 1, 746 "result": true 747} 748~~~ 749 750### framework_get_scheduler {#rpc_framework_get_scheduler} 751 752Retrieve currently set scheduler name and period, along with current governor name. 753 754#### Parameters 755 756This method has no parameters. 757 758#### Response 759 760Name | Description 761------------------------| ----------- 762scheduler_name | Current scheduler name 763scheduler_period | Currently set scheduler period in microseconds 764governor_name | Governor name 765 766#### Example 767 768Example request: 769 770~~~json 771{ 772 "jsonrpc": "2.0", 773 "method": "framework_set_scheduler", 774 "id": 1, 775} 776~~~ 777 778Example response: 779 780~~~json 781{ 782 "jsonrpc": "2.0", 783 "id": 1, 784 "result": { 785 "scheduler_name": "static", 786 "scheduler_period": 2800000000, 787 "governor_name": "default" 788 } 789} 790~~~ 791 792### thread_get_stats {#rpc_thread_get_stats} 793 794Retrieve current statistics of all the threads. 795 796#### Parameters 797 798This method has no parameters. 799 800#### Response 801 802The response is an array of objects containing threads statistics. 803 804#### Example 805 806Example request: 807 808~~~json 809{ 810 "jsonrpc": "2.0", 811 "method": "thread_get_stats", 812 "id": 1 813} 814~~~ 815 816Example response: 817 818~~~json 819{ 820 "jsonrpc": "2.0", 821 "id": 1, 822 "result": { 823 "tick_rate": 2400000000, 824 "threads": [ 825 { 826 "name": "app_thread", 827 "id": 1, 828 "cpumask": "1", 829 "busy": 139223208, 830 "idle": 8641080608, 831 "in_interrupt": false, 832 "active_pollers_count": 1, 833 "timed_pollers_count": 2, 834 "paused_pollers_count": 0 835 } 836 ] 837 } 838} 839~~~ 840 841### thread_set_cpumask {#rpc_thread_set_cpumask} 842 843Set the cpumask of the thread to the specified value. The thread may be migrated 844to one of the specified CPUs. 845 846#### Parameters 847 848Name | Optional | Type | Description 849----------------------- | -------- | ----------- | ----------- 850id | Required | string | Thread ID 851cpumask | Required | string | Cpumask for this thread 852 853#### Response 854 855Completion status of the operation is returned as a boolean. 856 857#### Example 858 859Example request: 860 861~~~json 862{ 863 "jsonrpc": "2.0", 864 "method": "thread_set_cpumask", 865 "id": 1, 866 "params": { 867 "id": "1", 868 "cpumask": "1" 869 } 870} 871~~~ 872 873Example response: 874 875~~~json 876{ 877 "jsonrpc": "2.0", 878 "id": 1, 879 "result": true 880} 881~~~ 882 883### trace_enable_tpoint_group {#rpc_trace_enable_tpoint_group} 884 885Enable trace on a specific tpoint group. For example "bdev" for bdev trace group, 886"all" for all trace groups. 887 888#### Parameters 889 890Name | Optional | Type | Description 891----------------------- | -------- | ----------- | ----------- 892name | Required | string | bdev, nvmf_rdma, nvmf_tcp, blobfs, scsi, iscsi_conn, ftl, all 893 894#### Example 895 896Example request: 897 898~~~json 899{ 900 "jsonrpc": "2.0", 901 "method": "trace_enable_tpoint_group", 902 "id": 1, 903 "params": { 904 "name": "bdev" 905 } 906} 907~~~ 908 909Example response: 910 911~~~json 912{ 913 "jsonrpc": "2.0", 914 "id": 1, 915 "result": true 916} 917~~~ 918 919### trace_disable_tpoint_group {#rpc_trace_disable_tpoint_group} 920 921Disable trace on a specific tpoint group. For example "bdev" for bdev trace group, 922"all" for all trace groups. 923 924#### Parameters 925 926Name | Optional | Type | Description 927----------------------- | -------- | ----------- | ----------- 928name | Required | string | bdev, nvmf_rdma, nvmf_tcp, blobfs, all 929 930#### Example 931 932Example request: 933 934~~~json 935{ 936 "jsonrpc": "2.0", 937 "method": "trace_disable_tpoint_group", 938 "id": 1, 939 "params": { 940 "name": "bdev" 941 } 942} 943~~~ 944 945Example response: 946 947~~~json 948{ 949 "jsonrpc": "2.0", 950 "id": 1, 951 "result": true 952} 953~~~ 954 955### trace_set_tpoint_mask {#rpc_trace_set_tpoint_mask} 956 957Enable tracepoint mask on a specific tpoint group. For example "bdev" for bdev trace group, 958and 0x1 to enable the first tracepoint inside the group (BDEV_IO_START). This command will not 959disable already active tracepoints or those not specified in the mask. For a full description 960of all available trace groups, see 961[tracepoint documentation](https://spdk.io/doc/nvmf_tgt_tracepoints.html). 962 963#### Parameters 964 965Name | Optional | Type | Description 966----------------------- | -------- | ----------- | ----------- 967name | Required | string | bdev, nvmf_rdma, nvmf_tcp, blobfs, scsi, iscsi_conn, ftl 968tpoint_mask | Required | number | mask to enable tracepoints inside a group 969 970#### Example 971 972Example request: 973 974~~~json 975{ 976 "jsonrpc": "2.0", 977 "method": "trace_set_tpoint_mask", 978 "id": 1, 979 "params": { 980 "name": "bdev", 981 "tpoint_mask": 0x1 982 } 983} 984~~~ 985 986Example response: 987 988~~~json 989{ 990 "jsonrpc": "2.0", 991 "id": 1, 992 "result": true 993} 994~~~ 995 996### trace_clear_tpoint_mask {#rpc_trace_clear_tpoint_mask} 997 998Disable tracepoint mask on a specific tpoint group. For example "bdev" for bdev trace group, 999and 0x1 to disable the first tracepoint inside the group (BDEV_IO_START). For a full description 1000of all available trace groups, see 1001[tracepoint documentation](https://spdk.io/doc/nvmf_tgt_tracepoints.html). 1002 1003#### Parameters 1004 1005Name | Optional | Type | Description 1006----------------------- | -------- | ----------- | ----------- 1007name | Required | string | bdev, nvmf_rdma, nvmf_tcp, blobfs, scsi, iscsi_conn, ftl 1008tpoint_mask | Required | number | mask to diesable tracepoints inside a group 1009 1010#### Example 1011 1012Example request: 1013 1014~~~json 1015{ 1016 "jsonrpc": "2.0", 1017 "method": "trace_clear_tpoint_mask", 1018 "id": 1, 1019 "params": { 1020 "name": "bdev", 1021 "tpoint_mask": 0x1 1022 } 1023} 1024~~~ 1025 1026Example response: 1027 1028~~~json 1029{ 1030 "jsonrpc": "2.0", 1031 "id": 1, 1032 "result": true 1033} 1034~~~ 1035 1036### trace_get_tpoint_group_mask {#rpc_trace_get_tpoint_group_mask} 1037 1038Display mask info for every group. 1039 1040#### Parameters 1041 1042No parameters required 1043 1044#### Example 1045 1046Example request: 1047 1048~~~json 1049{ 1050 "jsonrpc": "2.0", 1051 "method": "trace_get_tpoint_group_mask", 1052 "id": 1 1053} 1054~~~ 1055 1056Example response: 1057 1058~~~json 1059{ 1060 "jsonrpc": "2.0", 1061 "id": 1, 1062 "result": { 1063 "tpoint_group_mask": "0x0", 1064 "iscsi_conn": { 1065 "enabled": false, 1066 "mask": "0x2" 1067 }, 1068 "scsi": { 1069 "enabled": false, 1070 "mask": "0x4" 1071 }, 1072 "bdev": { 1073 "enabled": false, 1074 "mask": "0x8" 1075 }, 1076 "nvmf_tcp": { 1077 "enabled": false, 1078 "mask": "0x20" 1079 }, 1080 "ftl": { 1081 "enabled": false, 1082 "mask": "0x40" 1083 }, 1084 "blobfs": { 1085 "enabled": false, 1086 "mask": "0x80" 1087 } 1088 } 1089} 1090~~~ 1091 1092### log_set_print_level {#rpc_log_set_print_level} 1093 1094Set the current level at which output will additionally be 1095sent to the current console. 1096 1097#### Parameters 1098 1099Name | Optional | Type | Description 1100----------------------- | -------- | ----------- | ----------- 1101level | Required | string | ERROR, WARNING, NOTICE, INFO, DEBUG 1102 1103#### Example 1104 1105Example request: 1106 1107~~~json 1108{ 1109 "jsonrpc": "2.0", 1110 "method": "log_set_print_level", 1111 "id": 1, 1112 "params": { 1113 "level": "ERROR" 1114 } 1115} 1116~~~ 1117 1118Example response: 1119 1120~~~json 1121{ 1122 "jsonrpc": "2.0", 1123 "id": 1, 1124 "result": true 1125} 1126~~~ 1127 1128### log_get_print_level {#rpc_log_get_print_level} 1129 1130Get the current level at which output will additionally be 1131sent to the current console. 1132 1133#### Example 1134 1135Example request: 1136 1137~~~json 1138{ 1139 "jsonrpc": "2.0", 1140 "method": "log_get_print_level", 1141 "id": 1, 1142} 1143~~~ 1144 1145Example response: 1146 1147~~~json 1148{ 1149 "jsonrpc": "2.0", 1150 "id": 1, 1151 "result": "NOTICE" 1152} 1153~~~ 1154 1155### log_set_level {#rpc_log_set_level} 1156 1157Set the current logging level output by the `log` module. 1158 1159#### Parameters 1160 1161Name | Optional | Type | Description 1162----------------------- | -------- | ----------- | ----------- 1163level | Required | string | ERROR, WARNING, NOTICE, INFO, DEBUG 1164 1165#### Example 1166 1167Example request: 1168 1169~~~json 1170{ 1171 "jsonrpc": "2.0", 1172 "method": "log_set_level", 1173 "id": 1, 1174 "params": { 1175 "level": "ERROR" 1176 } 1177} 1178~~~ 1179 1180Example response: 1181 1182~~~json 1183{ 1184 "jsonrpc": "2.0", 1185 "id": 1, 1186 "result": true 1187} 1188~~~ 1189 1190### log_get_level {#rpc_log_get_level} 1191 1192Get the current logging level output by the `log` module. 1193 1194#### Example 1195 1196Example request: 1197 1198~~~json 1199{ 1200 "jsonrpc": "2.0", 1201 "method": "log_get_level", 1202 "id": 1, 1203} 1204~~~ 1205 1206Example response: 1207 1208~~~json 1209{ 1210 "jsonrpc": "2.0", 1211 "id": 1, 1212 "result": "NOTICE" 1213} 1214~~~ 1215 1216### log_set_flag {#rpc_log_set_flag} 1217 1218Enable logging for specific portions of the application. The list of possible 1219log flags can be obtained using the `log_get_flags` RPC and may be different 1220for each application. 1221 1222#### Parameters 1223 1224Name | Optional | Type | Description 1225----------------------- | -------- | ----------- | ----------- 1226flag | Required | string | A log flag, or 'all' 1227 1228#### Example 1229 1230Example request: 1231 1232~~~json 1233{ 1234 "jsonrpc": "2.0", 1235 "method": "log_set_flag", 1236 "id": 1, 1237 "params": { 1238 "flag": "all" 1239 } 1240} 1241~~~ 1242 1243Example response: 1244 1245~~~json 1246{ 1247 "jsonrpc": "2.0", 1248 "id": 1, 1249 "result": true 1250} 1251~~~ 1252 1253### log_clear_flag {#rpc_log_clear_flag} 1254 1255Disable logging for specific portions of the application. The list of possible 1256log flags can be obtained using the `log_get_flags` RPC and may be different 1257for each application. 1258 1259#### Parameters 1260 1261Name | Optional | Type | Description 1262----------------------- | -------- | ----------- | ----------- 1263flag | Required | string | A log flag, or 'all' 1264 1265#### Example 1266 1267Example request: 1268 1269~~~json 1270{ 1271 "jsonrpc": "2.0", 1272 "method": "log_clear_flag", 1273 "id": 1, 1274 "params": { 1275 "flag": "all" 1276 } 1277} 1278~~~ 1279 1280Example response: 1281 1282~~~json 1283{ 1284 "jsonrpc": "2.0", 1285 "id": 1, 1286 "result": true 1287} 1288~~~ 1289 1290### log_get_flags {#rpc_log_get_flags} 1291 1292Get the list of valid flags for this application and whether 1293they are currently enabled. 1294 1295#### Example 1296 1297Example request: 1298 1299~~~json 1300{ 1301 "jsonrpc": "2.0", 1302 "method": "log_get_flags", 1303 "id": 1, 1304} 1305~~~ 1306 1307Example response: 1308 1309~~~json 1310{ 1311 "jsonrpc": "2.0", 1312 "id": 1, 1313 "result": { 1314 "nvmf": true, 1315 "nvme": true, 1316 "aio": false, 1317 "bdev" false 1318 } 1319} 1320~~~ 1321 1322### log_enable_timestamps {#rpc_log_enable_timestamps} 1323 1324Enable or disable timestamps. 1325 1326#### Parameters 1327 1328Name | Optional | Type | Description 1329----------------------- | -------- | ----------- | ----------- 1330enabled | Required | boolean | on or off 1331 1332#### Example 1333 1334Example request: 1335 1336~~~json 1337{ 1338 "jsonrpc": "2.0", 1339 "method": "log_enable_timestamps", 1340 "id": 1, 1341 "params": { 1342 "enabled": true 1343 } 1344} 1345~~~ 1346 1347Example response: 1348 1349~~~json 1350{ 1351 "jsonrpc": "2.0", 1352 "id": 1, 1353 "result": true 1354} 1355~~~ 1356 1357### thread_get_pollers {#rpc_thread_get_pollers} 1358 1359Retrieve current pollers of all the threads. 1360 1361#### Parameters 1362 1363This method has no parameters. 1364 1365### Response 1366 1367The response is an array of objects containing pollers of all the threads. 1368 1369#### Example 1370 1371Example request: 1372 1373~~~json 1374{ 1375 "jsonrpc": "2.0", 1376 "method": "thread_get_pollers", 1377 "id": 1 1378} 1379~~~ 1380 1381Example response: 1382 1383~~~json 1384{ 1385 "jsonrpc": "2.0", 1386 "id": 1, 1387 "result": { 1388 "tick_rate": 2500000000, 1389 "threads": [ 1390 { 1391 "name": "app_thread", 1392 "id": 1, 1393 "active_pollers": [], 1394 "timed_pollers": [ 1395 { 1396 "name": "spdk_rpc_subsystem_poll", 1397 "id": 1, 1398 "state": "waiting", 1399 "run_count": 12345, 1400 "busy_count": 10000, 1401 "period_ticks": 10000000 1402 } 1403 ], 1404 "paused_pollers": [] 1405 } 1406 ] 1407 } 1408} 1409~~~ 1410 1411### thread_get_io_channels {#rpc_thread_get_io_channels} 1412 1413Retrieve current IO channels of all the threads. 1414 1415#### Parameters 1416 1417This method has no parameters. 1418 1419#### Response 1420 1421The response is an array of objects containing IO channels of all the threads. 1422 1423#### Example 1424 1425Example request: 1426 1427~~~json 1428{ 1429 "jsonrpc": "2.0", 1430 "method": "thread_get_io_channels", 1431 "id": 1 1432} 1433~~~ 1434 1435Example response: 1436 1437~~~json 1438{ 1439 "jsonrpc": "2.0", 1440 "id": 1, 1441 "result": { 1442 "tick_rate": 2500000000, 1443 "threads": [ 1444 { 1445 "name": "app_thread", 1446 "io_channels": [ 1447 { 1448 "name": "nvmf_tgt", 1449 "ref": 1 1450 } 1451 ] 1452 } 1453 ] 1454 } 1455} 1456~~~ 1457 1458### env_dpdk_get_mem_stats {#rpc_env_dpdk_get_mem_stats} 1459 1460Write the dpdk memory stats to a file. 1461 1462#### Parameters 1463 1464This method has no parameters. 1465 1466#### Response 1467 1468The response is a pathname to a text file containing the memory stats. 1469 1470#### Example 1471 1472Example request: 1473 1474~~~json 1475{ 1476 "jsonrpc": "2.0", 1477 "method": "env_dpdk_get_mem_stats", 1478 "id": 1 1479} 1480~~~ 1481 1482Example response: 1483 1484~~~json 1485{ 1486 "jsonrpc": "2.0", 1487 "id": 1, 1488 "result": { 1489 "filename": "/tmp/spdk_mem_dump.txt" 1490 } 1491} 1492~~~ 1493 1494## Acceleration Framework Layer {#jsonrpc_components_accel_fw} 1495 1496### idxd_scan_accel_engine {#rpc_idxd_scan_accel_engine} 1497 1498Set config and enable idxd accel engine offload. 1499This feature is considered as experimental. 1500 1501#### Parameters 1502 1503Name | Optional | Type | Description 1504----------------------- | -------- | ----------- | ----------- 1505config_kernel_mode | Optional | Boolean | If set, will use kernel idxd driver. 1506 1507#### Example 1508 1509Example request: 1510 1511~~~json 1512{ 1513 "params": { 1514 "config_kernel_mode": false 1515 }, 1516 "jsonrpc": "2.0", 1517 "method": "idxd_scan_accel_engine", 1518 "id": 1 1519} 1520~~~ 1521 1522Example response: 1523 1524~~~json 1525{ 1526 "jsonrpc": "2.0", 1527 "id": 1, 1528 "result": true 1529} 1530~~~ 1531 1532### ioat_scan_accel_engine {#rpc_ioat_scan_accel_engine} 1533 1534Enable ioat accel engine offload. 1535 1536#### Parameters 1537 1538None 1539 1540#### Example 1541 1542Example request: 1543 1544~~~json 1545{ 1546 "jsonrpc": "2.0", 1547 "method": "ioat_scan_accel_engine", 1548 "id": 1 1549} 1550~~~ 1551 1552Example response: 1553 1554~~~json 1555{ 1556 "jsonrpc": "2.0", 1557 "id": 1, 1558 "result": true 1559} 1560~~~ 1561 1562## Block Device Abstraction Layer {#jsonrpc_components_bdev} 1563 1564### bdev_set_options {#rpc_bdev_set_options} 1565 1566Set global parameters for the block device (bdev) subsystem. This RPC may only be called 1567before SPDK subsystems have been initialized. 1568 1569#### Parameters 1570 1571Name | Optional | Type | Description 1572----------------------- | -------- | ----------- | ----------- 1573bdev_io_pool_size | Optional | number | Number of spdk_bdev_io structures in shared buffer pool 1574bdev_io_cache_size | Optional | number | Maximum number of spdk_bdev_io structures cached per thread 1575bdev_auto_examine | Optional | boolean | If set to false, the bdev layer will not examine every disks automatically 1576 1577#### Example 1578 1579Example request: 1580 1581~~~json 1582{ 1583 "jsonrpc": "2.0", 1584 "id": 1, 1585 "method": "bdev_set_options", 1586 "params": { 1587 "bdev_io_pool_size": 65536, 1588 "bdev_io_cache_size": 256 1589 } 1590} 1591~~~ 1592 1593Example response: 1594 1595~~~json 1596{ 1597 "jsonrpc": "2.0", 1598 "id": 1, 1599 "result": true 1600} 1601~~~ 1602 1603### bdev_get_bdevs {#rpc_bdev_get_bdevs} 1604 1605Get information about block devices (bdevs). 1606 1607#### Parameters 1608 1609The user may specify no parameters in order to list all block devices, or a block device may be 1610specified by name. If a timeout is specified, the method will block until a bdev with a specified 1611name appears or the timeout expires. By default, the timeout is zero, meaning the method returns 1612immediately whether the bdev exists or not. 1613 1614Name | Optional | Type | Description 1615----------------------- | -------- | ----------- | ----------- 1616name | Optional | string | Block device name 1617timeout | Optional | number | Time (ms) to wait for a bdev with specified name to appear 1618 1619#### Response 1620 1621The response is an array of objects containing information about the requested block devices. 1622 1623#### Example 1624 1625Example request: 1626 1627~~~json 1628{ 1629 "jsonrpc": "2.0", 1630 "id": 1, 1631 "method": "bdev_get_bdevs", 1632 "params": { 1633 "name": "Malloc0" 1634 } 1635} 1636~~~ 1637 1638Example response: 1639 1640~~~json 1641{ 1642 "jsonrpc": "2.0", 1643 "id": 1, 1644 "result": [ 1645 { 1646 "name": "Malloc0", 1647 "product_name": "Malloc disk", 1648 "block_size": 512, 1649 "num_blocks": 20480, 1650 "claimed": false, 1651 "zoned": false, 1652 "supported_io_types": { 1653 "read": true, 1654 "write": true, 1655 "unmap": true, 1656 "write_zeroes": true, 1657 "flush": true, 1658 "reset": true, 1659 "nvme_admin": false, 1660 "nvme_io": false 1661 }, 1662 "driver_specific": {} 1663 } 1664 ] 1665} 1666~~~ 1667 1668### bdev_examine {#rpc_bdev_examine} 1669 1670Request that the bdev layer examines the given bdev for metadata and creates 1671new bdevs if metadata is found. This is only necessary if `auto_examine` has 1672been set to false using `bdev_set_options`. By default, `auto_examine` is true 1673and bdev examination is automatic. 1674 1675#### Parameters 1676 1677Name | Optional | Type | Description 1678----------------------- | -------- | ----------- | ----------- 1679name | Required | string | Block device name 1680 1681#### Response 1682 1683The response is an array of objects containing I/O statistics of the requested block devices. 1684 1685#### Example 1686 1687Example request: 1688 1689~~~json 1690{ 1691 "jsonrpc": "2.0", 1692 "id": 1, 1693 "method": "bdev_examine", 1694 "params": { 1695 "name": "Nvme0n1" 1696 } 1697} 1698~~~ 1699 1700Example response: 1701 1702~~~json 1703{ 1704 "jsonrpc": "2.0", 1705 "id": 1, 1706 "result": true 1707} 1708~~~ 1709 1710### bdev_wait_for_examine {#rpc_bdev_wait_for_examine} 1711 1712Report when all bdevs have been examined by every bdev module. 1713 1714#### Parameters 1715 1716None 1717 1718#### Response 1719 1720The response is sent when all bdev modules had a chance to examine every bdev. 1721 1722#### Example 1723 1724Example request: 1725 1726~~~json 1727{ 1728 "jsonrpc": "2.0", 1729 "method": "bdev_wait_for_examine", 1730 "id": 1 1731} 1732~~~ 1733 1734Example response: 1735 1736~~~json 1737{ 1738 "jsonrpc": "2.0", 1739 "id": 1, 1740 "result": true 1741} 1742~~~ 1743 1744### bdev_get_iostat {#rpc_bdev_get_iostat} 1745 1746Get I/O statistics of block devices (bdevs). 1747 1748#### Parameters 1749 1750The user may specify no parameters in order to list all block devices, or a block device may be 1751specified by name. 1752 1753Name | Optional | Type | Description 1754----------------------- | -------- | ----------- | ----------- 1755name | Optional | string | Block device name 1756 1757#### Response 1758 1759The response is an array of objects containing I/O statistics of the requested block devices. 1760 1761#### Example 1762 1763Example request: 1764 1765~~~json 1766{ 1767 "jsonrpc": "2.0", 1768 "id": 1, 1769 "method": "bdev_get_iostat", 1770 "params": { 1771 "name": "Nvme0n1" 1772 } 1773} 1774~~~ 1775 1776Example response: 1777 1778~~~json 1779{ 1780 "jsonrpc": "2.0", 1781 "id": 1, 1782 "result": { 1783 "tick_rate": 2200000000, 1784 "bdevs" : [ 1785 { 1786 "name": "Nvme0n1", 1787 "bytes_read": 36864, 1788 "num_read_ops": 2, 1789 "bytes_written": 0, 1790 "num_write_ops": 0, 1791 "bytes_unmapped": 0, 1792 "num_unmap_ops": 0, 1793 "read_latency_ticks": 178904, 1794 "write_latency_ticks": 0, 1795 "unmap_latency_ticks": 0, 1796 "queue_depth_polling_period": 2, 1797 "queue_depth": 0, 1798 "io_time": 0, 1799 "weighted_io_time": 0 1800 } 1801 ] 1802 } 1803} 1804~~~ 1805 1806### bdev_enable_histogram {#rpc_bdev_enable_histogram} 1807 1808Control whether collecting data for histogram is enabled for specified bdev. 1809 1810#### Parameters 1811 1812Name | Optional | Type | Description 1813----------------------- | -------- | ----------- | ----------- 1814name | Required | string | Block device name 1815enable | Required | boolean | Enable or disable histogram on specified device 1816 1817#### Example 1818 1819Example request: 1820 1821~~~json 1822{ 1823 "jsonrpc": "2.0", 1824 "id": 1, 1825 "method": "bdev_enable_histogram", 1826 "params": { 1827 "name": "Nvme0n1" 1828 "enable": true 1829 } 1830} 1831~~~ 1832 1833Example response: 1834 1835~~~json 1836{ 1837 "jsonrpc": "2.0", 1838 "id": 1, 1839 "result": true 1840} 1841~~~ 1842 1843### bdev_get_histogram {#rpc_bdev_get_histogram} 1844 1845Get latency histogram for specified bdev. 1846 1847#### Parameters 1848 1849Name | Optional | Type | Description 1850----------------------- | -------- | ----------- | ----------- 1851name | Required | string | Block device name 1852 1853#### Result 1854 1855Name | Description 1856------------------------| ----------- 1857histogram | Base64 encoded histogram 1858bucket_shift | Granularity of the histogram buckets 1859tsc_rate | Ticks per second 1860 1861#### Example 1862 1863Example request: 1864 1865~~~json 1866{ 1867 "jsonrpc": "2.0", 1868 "id": 1, 1869 "method": "bdev_get_histogram", 1870 "params": { 1871 "name": "Nvme0n1" 1872 } 1873} 1874~~~ 1875 1876Example response: 1877Note that histogram field is trimmed, actual encoded histogram length is ~80kb. 1878 1879~~~json 1880{ 1881 "jsonrpc": "2.0", 1882 "id": 1, 1883 "result": { 1884 "histogram": "AAAAAAAAAAAAAA...AAAAAAAAA==", 1885 "tsc_rate": 2300000000, 1886 "bucket_shift": 7 1887 } 1888} 1889~~~ 1890 1891### bdev_set_qos_limit {#rpc_bdev_set_qos_limit} 1892 1893Set the quality of service rate limit on a bdev. 1894 1895#### Parameters 1896 1897Name | Optional | Type | Description 1898----------------------- | -------- | ----------- | ----------- 1899name | Required | string | Block device name 1900rw_ios_per_sec | Optional | number | Number of R/W I/Os per second to allow. 0 means unlimited. 1901rw_mbytes_per_sec | Optional | number | Number of R/W megabytes per second to allow. 0 means unlimited. 1902r_mbytes_per_sec | Optional | number | Number of Read megabytes per second to allow. 0 means unlimited. 1903w_mbytes_per_sec | Optional | number | Number of Write megabytes per second to allow. 0 means unlimited. 1904 1905#### Example 1906 1907Example request: 1908 1909~~~json 1910{ 1911 "jsonrpc": "2.0", 1912 "id": 1, 1913 "method": "bdev_set_qos_limit", 1914 "params": { 1915 "name": "Malloc0" 1916 "rw_ios_per_sec": 20000 1917 "rw_mbytes_per_sec": 100 1918 "r_mbytes_per_sec": 50 1919 "w_mbytes_per_sec": 50 1920 } 1921} 1922~~~ 1923 1924Example response: 1925 1926~~~json 1927{ 1928 "jsonrpc": "2.0", 1929 "id": 1, 1930 "result": true 1931} 1932~~~ 1933 1934### bdev_set_qd_sampling_period {#rpc_bdev_set_qd_sampling_period} 1935 1936Enable queue depth tracking on a specified bdev. 1937 1938#### Parameters 1939 1940Name | Optional | Type | Description 1941----------------------- | -------- | ----------- | ----------- 1942name | Required | string | Block device name 1943period | Required | int | period (in microseconds).If set to 0, polling will be disabled. 1944 1945#### Example 1946 1947Example request: 1948 1949~~~json 1950{ 1951 "jsonrpc": "2.0", 1952 "method": "bdev_set_qd_sampling_period", 1953 "id": 1, 1954 "params": { 1955 "name": "Malloc0", 1956 "period": 20 1957 } 1958} 1959~~~ 1960 1961Example response: 1962 1963~~~json 1964{ 1965 "jsonrpc": "2.0", 1966 "id": 1, 1967 "result": true 1968} 1969~~~ 1970 1971### bdev_compress_create {#rpc_bdev_compress_create} 1972 1973Create a new compress bdev on a given base bdev. 1974 1975#### Parameters 1976 1977Name | Optional | Type | Description 1978----------------------- | -------- | ----------- | ----------- 1979base_bdev_name | Required | string | Name of the base bdev 1980pm_path | Required | string | Path to persistent memory 1981lb_size | Optional | int | Compressed vol logical block size (512 or 4096) 1982 1983#### Result 1984 1985Name of newly created bdev. 1986 1987#### Example 1988 1989Example request: 1990 1991~~~json 1992{ 1993 "params": { 1994 "base_bdev_name": "Nvme0n1", 1995 "pm_path": "/pm_files", 1996 "lb_size": 4096 1997 }, 1998 "jsonrpc": "2.0", 1999 "method": "bdev_compress_create", 2000 "id": 1 2001} 2002~~~ 2003 2004### bdev_compress_delete {#rpc_bdev_compress_delete} 2005 2006Delete a compressed bdev. 2007 2008#### Parameters 2009 2010Name | Optional | Type | Description 2011----------------------- | -------- | ----------- | ----------- 2012name | Required | string | Name of the compress bdev 2013 2014#### Example 2015 2016Example request: 2017 2018~~~json 2019{ 2020 "params": { 2021 "name": "COMP_Nvme0n1" 2022 }, 2023 "jsonrpc": "2.0", 2024 "method": "bdev_compress_delete", 2025 "id": 1 2026} 2027~~~ 2028 2029Example response: 2030 2031~~~json 2032{ 2033 "jsonrpc": "2.0", 2034 "id": 1, 2035 "result": true 2036} 2037~~~ 2038 2039### bdev_compress_get_orphans {#rpc_bdev_compress_get_orphans} 2040 2041Get a list of compressed volumes that are missing their pmem metadata. 2042 2043#### Parameters 2044 2045Name | Optional | Type | Description 2046----------------------- | -------- | ----------- | ----------- 2047name | Required | string | Name of the compress bdev 2048 2049#### Example 2050 2051Example request: 2052 2053~~~json 2054{ 2055 "params": { 2056 "name": "COMP_Nvme0n1" 2057 }, 2058 "jsonrpc": "2.0", 2059 "method": "bdev_compress_get_orphans", 2060 "id": 1 2061} 2062~~~ 2063 2064Example response: 2065 2066~~~json 2067{ 2068 "jsonrpc": "2.0", 2069 "id": 1, 2070 "name": "COMP_Nvme0n1" 2071} 2072~~~ 2073 2074### bdev_compress_set_pmd {#rpc_bdev_compress_set_pmd} 2075 2076Select the DPDK polled mode driver (pmd) for a compressed bdev, 20770 = auto-select, 1= QAT only, 2 = ISAL only, 3 = mlx5_pci only. 2078 2079#### Parameters 2080 2081Name | Optional | Type | Description 2082----------------------- | -------- | ----------- | ----------- 2083pmd | Required | int | pmd selection 2084 2085#### Example 2086 2087Example request: 2088 2089~~~json 2090{ 2091 "params": { 2092 "pmd": 1 2093 }, 2094 "jsonrpc": "2.0", 2095 "method": "bdev_compress_set_pmd", 2096 "id": 1 2097} 2098~~~ 2099 2100Example response: 2101 2102~~~json 2103{ 2104 "jsonrpc": "2.0", 2105 "id": 1, 2106 "result": true 2107} 2108~~~ 2109 2110### bdev_crypto_create {#rpc_bdev_crypto_create} 2111 2112Create a new crypto bdev on a given base bdev. 2113 2114#### Parameters 2115 2116Name | Optional | Type | Description 2117----------------------- | -------- | ----------- | ----------- 2118base_bdev_name | Required | string | Name of the base bdev 2119name | Required | string | Name of the crypto vbdev to create 2120crypto_pmd | Required | string | Name of the crypto device driver 2121key | Required | string | Key in hex form 2122cipher | Required | string | Cipher to use, AES_CBC or AES_XTS (QAT and MLX5) 2123key2 | Required | string | 2nd key in hex form only required for cipher AET_XTS 2124 2125Both key and key2 must be passed in the hexlified form. For example, 256bit AES key may look like this: 2126afd9477abf50254219ccb75965fbe39f23ebead5676e292582a0a67f66b88215 2127 2128#### Result 2129 2130Name of newly created bdev. 2131 2132#### Example 2133 2134Example request: 2135 2136~~~json 2137{ 2138 "params": { 2139 "base_bdev_name": "Nvme0n1", 2140 "name": "my_crypto_bdev", 2141 "crypto_pmd": "crypto_aesni_mb", 2142 "key": "12345678901234561234567890123456", 2143 "cipher": "AES_CBC" 2144 }, 2145 "jsonrpc": "2.0", 2146 "method": "bdev_crypto_create", 2147 "id": 1 2148} 2149~~~ 2150 2151Example response: 2152 2153~~~json 2154{ 2155 2156 "jsonrpc": "2.0", 2157 "id": 1, 2158 "result": "my_crypto_bdev" 2159} 2160~~~ 2161 2162### bdev_crypto_delete {#rpc_bdev_crypto_delete} 2163 2164Delete a crypto bdev. 2165 2166#### Parameters 2167 2168Name | Optional | Type | Description 2169----------------------- | -------- | ----------- | ----------- 2170name | Required | string | Name of the crypto bdev 2171 2172#### Example 2173 2174Example request: 2175 2176~~~json 2177{ 2178 "params": { 2179 "name": "my_crypto_bdev" 2180 }, 2181 "jsonrpc": "2.0", 2182 "method": "bdev_crypto_delete", 2183 "id": 1 2184} 2185~~~ 2186 2187Example response: 2188 2189~~~json 2190{ 2191 "jsonrpc": "2.0", 2192 "id": 1, 2193 "result": true 2194} 2195~~~ 2196 2197### bdev_ocf_create {#rpc_bdev_ocf_create} 2198 2199Construct new OCF bdev. 2200Command accepts cache mode that is going to be used. 2201You can find more details about supported cache modes in the [OCF documentation](https://open-cas.github.io/cache_configuration.html#cache-mode) 2202 2203#### Parameters 2204 2205Name | Optional | Type | Description 2206----------------------- | -------- | ----------- | ----------- 2207name | Required | string | Bdev name to use 2208mode | Required | string | OCF cache mode: wb, wt, pt, wa, wi, wo 2209cache_line_size | Optional | int | OCF cache line size in KiB: 4, 8, 16, 32, 64 2210cache_bdev_name | Required | string | Name of underlying cache bdev 2211core_bdev_name | Required | string | Name of underlying core bdev 2212 2213#### Result 2214 2215Name of newly created bdev. 2216 2217#### Example 2218 2219Example request: 2220 2221~~~json 2222{ 2223 "params": { 2224 "name": "ocf0", 2225 "mode": "wt", 2226 "cache_line_size": 64, 2227 "cache_bdev_name": "Nvme0n1", 2228 "core_bdev_name": "aio0" 2229 }, 2230 "jsonrpc": "2.0", 2231 "method": "bdev_ocf_create", 2232 "id": 1 2233} 2234~~~ 2235 2236Example response: 2237 2238~~~json 2239{ 2240 "jsonrpc": "2.0", 2241 "id": 1, 2242 "result": "ocf0" 2243} 2244~~~ 2245 2246### bdev_ocf_delete {#rpc_bdev_ocf_delete} 2247 2248Delete the OCF bdev 2249 2250#### Parameters 2251 2252Name | Optional | Type | Description 2253----------------------- | -------- | ----------- | ----------- 2254name | Required | string | Bdev name 2255 2256#### Example 2257 2258Example request: 2259 2260~~~json 2261{ 2262 "params": { 2263 "name": "ocf0" 2264 }, 2265 "jsonrpc": "2.0", 2266 "method": "bdev_ocf_delete", 2267 "id": 1 2268} 2269~~~ 2270 2271Example response: 2272 2273~~~json 2274{ 2275 "jsonrpc": "2.0", 2276 "id": 1, 2277 "result": true 2278} 2279~~~ 2280 2281### bdev_ocf_get_stats {#rpc_bdev_ocf_get_stats} 2282 2283Get statistics of chosen OCF block device. 2284 2285#### Parameters 2286 2287Name | Optional | Type | Description 2288----------------------- | -------- | ----------- | ----------- 2289name | Required | string | Block device name 2290 2291#### Response 2292 2293Statistics as json object. 2294 2295#### Example 2296 2297Example request: 2298 2299~~~json 2300{ 2301 "jsonrpc": "2.0", 2302 "method": "bdev_ocf_get_stats", 2303 "id": 1 2304} 2305~~~ 2306 2307Example response: 2308 2309~~~json 2310{ 2311 "jsonrpc": "2.0", 2312 "id": 1, 2313 "result": [ 2314 "usage": { 2315 "clean": { 2316 "count": 76033, 2317 "units": "4KiB blocks", 2318 "percentage": "100.0" 2319 }, 2320 "free": { 2321 "count": 767, 2322 "units": "4KiB blocks", 2323 "percentage": "0.9" 2324 }, 2325 "occupancy": { 2326 "count": 76033, 2327 "units": "4KiB blocks", 2328 "percentage": "99.0" 2329 }, 2330 "dirty": { 2331 "count": 0, 2332 "units": "4KiB blocks", 2333 "percentage": "0.0" 2334 } 2335 }, 2336 "requests": { 2337 "rd_total": { 2338 "count": 2, 2339 "units": "Requests", 2340 "percentage": "0.0" 2341 }, 2342 "wr_full_misses": { 2343 "count": 76280, 2344 "units": "Requests", 2345 "percentage": "35.6" 2346 }, 2347 "rd_full_misses": { 2348 "count": 1, 2349 "units": "Requests", 2350 "percentage": "0.0" 2351 }, 2352 "rd_partial_misses": { 2353 "count": 0, 2354 "units": "Requests", 2355 "percentage": "0.0" 2356 }, 2357 "wr_total": { 2358 "count": 212416, 2359 "units": "Requests", 2360 "percentage": "99.2" 2361 }, 2362 "wr_pt": { 2363 "count": 1535, 2364 "units": "Requests", 2365 "percentage": "0.7" 2366 }, 2367 "wr_partial_misses": { 2368 "count": 0, 2369 "units": "Requests", 2370 "percentage": "0.0" 2371 }, 2372 "serviced": { 2373 "count": 212418, 2374 "units": "Requests", 2375 "percentage": "99.2" 2376 }, 2377 "rd_pt": { 2378 "count": 0, 2379 "units": "Requests", 2380 "percentage": "0.0" 2381 }, 2382 "total": { 2383 "count": 213953, 2384 "units": "Requests", 2385 "percentage": "100.0" 2386 }, 2387 "rd_hits": { 2388 "count": 1, 2389 "units": "Requests", 2390 "percentage": "0.0" 2391 }, 2392 "wr_hits": { 2393 "count": 136136, 2394 "units": "Requests", 2395 "percentage": "63.6" 2396 } 2397 }, 2398 "errors": { 2399 "total": { 2400 "count": 0, 2401 "units": "Requests", 2402 "percentage": "0.0" 2403 }, 2404 "cache_obj_total": { 2405 "count": 0, 2406 "units": "Requests", 2407 "percentage": "0.0" 2408 }, 2409 "core_obj_total": { 2410 "count": 0, 2411 "units": "Requests", 2412 "percentage": "0.0" 2413 }, 2414 "cache_obj_rd": { 2415 "count": 0, 2416 "units": "Requests", 2417 "percentage": "0.0" 2418 }, 2419 "core_obj_wr": { 2420 "count": 0, 2421 "units": "Requests", 2422 "percentage": "0.0" 2423 }, 2424 "core_obj_rd": { 2425 "count": 0, 2426 "units": "Requests", 2427 "percentage": "0.0" 2428 }, 2429 "cache_obj_wr": { 2430 "count": 0, 2431 "units": "Requests", 2432 "percentage": "0.0" 2433 } 2434 }, 2435 "blocks": { 2436 "volume_rd": { 2437 "count": 9, 2438 "units": "4KiB blocks", 2439 "percentage": "0.0" 2440 }, 2441 "volume_wr": { 2442 "count": 213951, 2443 "units": "4KiB blocks", 2444 "percentage": "99.9" 2445 }, 2446 "cache_obj_total": { 2447 "count": 212425, 2448 "units": "4KiB blocks", 2449 "percentage": "100.0" 2450 }, 2451 "core_obj_total": { 2452 "count": 213959, 2453 "units": "4KiB blocks", 2454 "percentage": "100.0" 2455 }, 2456 "cache_obj_rd": { 2457 "count": 1, 2458 "units": "4KiB blocks", 2459 "percentage": "0.0" 2460 }, 2461 "core_obj_wr": { 2462 "count": 213951, 2463 "units": "4KiB blocks", 2464 "percentage": "99.9" 2465 }, 2466 "volume_total": { 2467 "count": 213960, 2468 "units": "4KiB blocks", 2469 "percentage": "100.0" 2470 }, 2471 "core_obj_rd": { 2472 "count": 8, 2473 "units": "4KiB blocks", 2474 "percentage": "0.0" 2475 }, 2476 "cache_obj_wr": { 2477 "count": 212424, 2478 "units": "4KiB blocks", 2479 "percentage": "99.9" 2480 } 2481 ] 2482} 2483~~~ 2484 2485### bdev_ocf_get_bdevs {#rpc_bdev_ocf_get_bdevs} 2486 2487Get list of OCF devices including unregistered ones. 2488 2489#### Parameters 2490 2491Name | Optional | Type | Description 2492----------------------- | -------- | ----------- | ----------- 2493name | Optional | string | Name of OCF vbdev or name of cache device or name of core device 2494 2495#### Response 2496 2497Array of OCF devices with their current status, along with core and cache bdevs. 2498 2499#### Example 2500 2501Example request: 2502 2503~~~json 2504{ 2505 "jsonrpc": "2.0", 2506 "method": "bdev_ocf_get_bdevs", 2507 "id": 1 2508} 2509~~~ 2510 2511Example response: 2512 2513~~~json 2514{ 2515 "jsonrpc": "2.0", 2516 "id": 1, 2517 "result": [ 2518 { 2519 "name": "PartCache", 2520 "started": false, 2521 "cache": { 2522 "name": "Malloc0", 2523 "attached": true 2524 }, 2525 "core": { 2526 "name": "Malloc1", 2527 "attached": false 2528 } 2529 } 2530 ] 2531} 2532~~~ 2533 2534### bdev_ocf_set_cache_mode {#rpc_bdev_ocf_set_cache_mode} 2535 2536Set new cache mode on OCF bdev. 2537 2538#### Parameters 2539 2540Name | Optional | Type | Description 2541----------------------- | -------- | ----------- | ----------- 2542name | Required | string | Bdev name 2543mode | Required | string | OCF cache mode: wb, wt, pt, wa, wi, wo 2544 2545#### Response 2546 2547New cache mode name. 2548 2549#### Example 2550 2551Example request: 2552 2553~~~json 2554{ 2555 "params": { 2556 "name": "ocf0", 2557 "mode": "pt", 2558 }, 2559 "jsonrpc": "2.0", 2560 "method": "bdev_ocf_set_cache_mode", 2561 "id": 1 2562} 2563~~~ 2564 2565Example response: 2566 2567~~~json 2568{ 2569 "jsonrpc": "2.0", 2570 "id": 1, 2571 "result": "pt" 2572} 2573~~~ 2574 2575### bdev_ocf_set_seqcutoff {#rpc_bdev_ocf_set_seqcutoff} 2576 2577Set sequential cutoff parameters on all cores for the given OCF cache device. 2578A brief description of this functionality can be found in [OpenCAS documentation](https://open-cas.github.io/guide_tool_details.html#seq-cutoff). 2579 2580#### Parameters 2581 2582Name | Optional | Type | Description 2583----------------------- | -------- | ----------- | ----------- 2584name | Required | string | Bdev name 2585policy | Required | string | Sequential cutoff policy: always, full, never 2586threshold | Optional | int | Activation threshold in KiB 2587promotion_count | Optional | int | Promotion request count 2588 2589#### Example 2590 2591Example request: 2592 2593~~~json 2594{ 2595 "params": { 2596 "name": "ocf0", 2597 "policy": "full", 2598 "threshold": 4, 2599 "promotion_count": 2 2600 }, 2601 "jsonrpc": "2.0", 2602 "method": "bdev_ocf_set_seqcutoff", 2603 "id": 1 2604} 2605~~~ 2606 2607Example response: 2608 2609~~~json 2610{ 2611 "jsonrpc": "2.0", 2612 "id": 1, 2613 "result": true 2614} 2615~~~ 2616 2617### bdev_malloc_create {#rpc_bdev_malloc_create} 2618 2619Construct @ref bdev_config_malloc 2620 2621#### Parameters 2622 2623Name | Optional | Type | Description 2624----------------------- | -------- | ----------- | ----------- 2625name | Optional | string | Bdev name to use 2626block_size | Required | number | Block size in bytes -must be multiple of 512 2627num_blocks | Required | number | Number of blocks 2628uuid | Optional | string | UUID of new bdev 2629optimal_io_boundary | Optional | number | Split on optimal IO boundary, in number of blocks, default 0 2630 2631#### Result 2632 2633Name of newly created bdev. 2634 2635#### Example 2636 2637Example request: 2638 2639~~~json 2640{ 2641 "params": { 2642 "block_size": 4096, 2643 "num_blocks": 16384, 2644 "name": "Malloc0", 2645 "uuid": "2b6601ba-eada-44fb-9a83-a20eb9eb9e90", 2646 "optimal_io_boundary": 16 2647 }, 2648 "jsonrpc": "2.0", 2649 "method": "bdev_malloc_create", 2650 "id": 1 2651} 2652~~~ 2653 2654Example response: 2655 2656~~~json 2657{ 2658 "jsonrpc": "2.0", 2659 "id": 1, 2660 "result": "Malloc0" 2661} 2662~~~ 2663 2664### bdev_malloc_delete {#rpc_bdev_malloc_delete} 2665 2666Delete @ref bdev_config_malloc 2667 2668#### Parameters 2669 2670Name | Optional | Type | Description 2671----------------------- | -------- | ----------- | ----------- 2672name | Required | string | Bdev name 2673 2674#### Example 2675 2676Example request: 2677 2678~~~json 2679{ 2680 "params": { 2681 "name": "Malloc0" 2682 }, 2683 "jsonrpc": "2.0", 2684 "method": "bdev_malloc_delete", 2685 "id": 1 2686} 2687~~~ 2688 2689Example response: 2690 2691~~~json 2692{ 2693 "jsonrpc": "2.0", 2694 "id": 1, 2695 "result": true 2696} 2697~~~ 2698 2699### bdev_null_create {#rpc_bdev_null_create} 2700 2701Construct @ref bdev_config_null 2702 2703#### Parameters 2704 2705Name | Optional | Type | Description 2706----------------------- | -------- | ----------- | ----------- 2707name | Optional | string | Bdev name to use 2708block_size | Required | number | Block size in bytes 2709num_blocks | Required | number | Number of blocks 2710uuid | Optional | string | UUID of new bdev 2711md_size | Optional | number | Metadata size for this bdev. Default=0. 2712dif_type | Optional | number | Protection information type. Parameter --md-size needs to be set along --dif-type. Default=0 - no protection. 2713dif_is_head_of_md | Optional | boolean | Protection information is in the first 8 bytes of metadata. Default=false. 2714 2715#### Result 2716 2717Name of newly created bdev. 2718 2719#### Example 2720 2721Example request: 2722 2723~~~json 2724{ 2725 "params": { 2726 "block_size": 4104, 2727 "num_blocks": 16384, 2728 "name": "Null0", 2729 "uuid": "2b6601ba-eada-44fb-9a83-a20eb9eb9e90", 2730 "md_size": 8, 2731 "dif_type": 1, 2732 "dif_is_head_of_md": true 2733 }, 2734 "jsonrpc": "2.0", 2735 "method": "bdev_null_create", 2736 "id": 1 2737} 2738~~~ 2739 2740Example response: 2741 2742~~~json 2743{ 2744 "jsonrpc": "2.0", 2745 "id": 1, 2746 "result": "Null0" 2747} 2748~~~ 2749 2750### bdev_null_delete {#rpc_bdev_null_delete} 2751 2752Delete @ref bdev_config_null. 2753 2754#### Parameters 2755 2756Name | Optional | Type | Description 2757----------------------- | -------- | ----------- | ----------- 2758name | Required | string | Bdev name 2759 2760#### Example 2761 2762Example request: 2763 2764~~~json 2765{ 2766 "params": { 2767 "name": "Null0" 2768 }, 2769 "jsonrpc": "2.0", 2770 "method": "bdev_null_delete", 2771 "id": 1 2772} 2773~~~ 2774 2775Example response: 2776 2777~~~json 2778{ 2779 "jsonrpc": "2.0", 2780 "id": 1, 2781 "result": true 2782} 2783~~~ 2784 2785### bdev_null_resize {#rpc_bdev_null_resize} 2786 2787Resize @ref bdev_config_null. 2788 2789#### Parameters 2790 2791Name | Optional | Type | Description 2792----------------------- | -------- | ----------- | ----------- 2793name | Required | string | Bdev name 2794new_size | Required | number | Bdev new capacity in MB 2795 2796#### Example 2797 2798Example request: 2799 2800~~~json 2801{ 2802 "params": { 2803 "name": "Null0", 2804 "new_size": 4096 2805 }, 2806 "jsonrpc": "2.0", 2807 "method": "bdev_null_resize", 2808 "id": 1 2809} 2810~~~ 2811 2812Example response: 2813 2814~~~json 2815{ 2816 "jsonrpc": "2.0", 2817 "id": 1, 2818 "result": true 2819} 2820~~~ 2821 2822### bdev_aio_create {#rpc_bdev_aio_create} 2823 2824Construct @ref bdev_config_aio. 2825 2826#### Parameters 2827 2828Name | Optional | Type | Description 2829----------------------- | -------- | ----------- | ----------- 2830name | Required | string | Bdev name to use 2831filename | Required | number | Path to device or file 2832block_size | Optional | number | Block size in bytes 2833 2834#### Result 2835 2836Name of newly created bdev. 2837 2838#### Example 2839 2840Example request: 2841 2842~~~json 2843{ 2844 "params": { 2845 "block_size": 4096, 2846 "name": "Aio0", 2847 "filename": "/tmp/aio_bdev_file" 2848 }, 2849 "jsonrpc": "2.0", 2850 "method": "bdev_aio_create", 2851 "id": 1 2852} 2853~~~ 2854 2855Example response: 2856 2857~~~json 2858{ 2859 "jsonrpc": "2.0", 2860 "id": 1, 2861 "result": "Aio0" 2862} 2863~~~ 2864 2865### bdev_aio_rescan {#rpc_bdev_aio_rescan} 2866 2867Rescan the size of @ref bdev_config_aio. 2868 2869#### Parameters 2870 2871Name | Optional | Type | Description 2872----------------------- | -------- | ----------- | ----------- 2873name | Required | string | Bdev name 2874 2875#### Example 2876 2877Example request: 2878 2879~~json 2880{ 2881 "params": { 2882 "name": "Aio0" 2883 }, 2884 "jsonrpc": "2.0", 2885 "method": "bdev_aio_rescan", 2886 "id": 1 2887} 2888~~ 2889 2890Example response: 2891 2892~~json 2893{ 2894 "jsonrpc": "2.0", 2895 "id": 1, 2896 "result": true 2897} 2898~~ 2899 2900### bdev_aio_delete {#rpc_bdev_aio_delete} 2901 2902Delete @ref bdev_config_aio. 2903 2904#### Parameters 2905 2906Name | Optional | Type | Description 2907----------------------- | -------- | ----------- | ----------- 2908name | Required | string | Bdev name 2909 2910#### Example 2911 2912Example request: 2913 2914~~~json 2915{ 2916 "params": { 2917 "name": "Aio0" 2918 }, 2919 "jsonrpc": "2.0", 2920 "method": "bdev_aio_delete", 2921 "id": 1 2922} 2923~~~ 2924 2925Example response: 2926 2927~~~json 2928{ 2929 "jsonrpc": "2.0", 2930 "id": 1, 2931 "result": true 2932} 2933~~~ 2934 2935### bdev_nvme_set_options {#rpc_bdev_nvme_set_options} 2936 2937Set global parameters for all bdev NVMe. This RPC may only be called before SPDK subsystems have been initialized 2938or any bdev NVMe has been created. 2939 2940Parameters, ctrlr_loss_timeout_sec, reconnect_delay_sec, and fast_io_fail_timeout_sec, are for I/O error resiliency. 2941They can be overridden if they are given by the RPC bdev_nvme_attach_controller. 2942 2943#### Parameters 2944 2945Name | Optional | Type | Description 2946-------------------------- | -------- | ----------- | ----------- 2947action_on_timeout | Optional | string | Action to take on command time out: none, reset or abort 2948timeout_us | Optional | number | Timeout for each command, in microseconds. If 0, don't track timeouts 2949timeout_admin_us | Optional | number | Timeout for each admin command, in microseconds. If 0, treat same as io timeouts ('timeout_us') 2950keep_alive_timeout_ms | Optional | number | Keep alive timeout period in milliseconds, default is 10s 2951retry_count | Optional | number | The number of attempts per I/O before an I/O fails. (Deprecated. Please use transport_retry_count instead.) 2952arbitration_burst | Optional | number | The value is expressed as a power of two, a value of 111b indicates no limit 2953low_priority_weight | Optional | number | The maximum number of commands that the controller may launch at one time from a low priority queue 2954medium_priority_weight | Optional | number | The maximum number of commands that the controller may launch at one time from a medium priority queue 2955high_priority_weight | Optional | number | The maximum number of commands that the controller may launch at one time from a high priority queue 2956nvme_adminq_poll_period_us | Optional | number | How often the admin queue is polled for asynchronous events in microseconds 2957nvme_ioq_poll_period_us | Optional | number | How often I/O queues are polled for completions, in microseconds. Default: 0 (as fast as possible). 2958io_queue_requests | Optional | number | The number of requests allocated for each NVMe I/O queue. Default: 512. 2959delay_cmd_submit | Optional | boolean | Enable delaying NVMe command submission to allow batching of multiple commands. Default: `true`. 2960transport_retry_count | Optional | number | The number of attempts per I/O in the transport layer before an I/O fails. 2961bdev_retry_count | Optional | number | The number of attempts per I/O in the bdev layer before an I/O fails. -1 means infinite retries. 2962transport_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. 2963ctrlr_loss_timeout_sec | Optional | number | Time to wait until ctrlr is reconnected before deleting ctrlr. -1 means infinite reconnects. 0 means no reconnect. 2964reconnect_delay_sec | Optional | number | Time to delay a reconnect trial. 0 means no reconnect. 2965fast_io_fail_timeout_sec | Optional | number | Time to wait until ctrlr is reconnected before failing I/O to ctrlr. 0 means no such timeout. 2966 2967#### Example 2968 2969Example request: 2970 2971~~~json 2972request: 2973{ 2974 "params": { 2975 "transport_retry_count": 5, 2976 "arbitration_burst": 3, 2977 "low_priority_weight": 8, 2978 "medium_priority_weight":8, 2979 "high_priority_weight": 8, 2980 "nvme_adminq_poll_period_us": 2000, 2981 "timeout_us": 10000000, 2982 "timeout_admin_us": 20000000, 2983 "keep_alive_timeout_ms": 600000, 2984 "action_on_timeout": "reset", 2985 "io_queue_requests" : 2048, 2986 "delay_cmd_submit": true 2987 }, 2988 "jsonrpc": "2.0", 2989 "method": "bdev_nvme_set_options", 2990 "id": 1 2991} 2992~~~ 2993 2994Example response: 2995 2996~~~json 2997{ 2998 "jsonrpc": "2.0", 2999 "id": 1, 3000 "result": true 3001} 3002~~~ 3003 3004### bdev_nvme_set_hotplug {#rpc_bdev_nvme_set_hotplug} 3005 3006Change settings of the NVMe hotplug feature. If enabled, PCIe NVMe bdevs will be automatically discovered on insertion 3007and deleted on removal. 3008 3009#### Parameters 3010 3011Name | Optional | Type | Description 3012----------------------- | -------- | ----------- | ----------- 3013enabled | Required | string | True to enable, false to disable 3014period_us | Optional | number | How often to poll for hot-insert and hot-remove events. Values: 0 - reset/use default or 1 to 10000000. 3015 3016#### Example 3017 3018Example request: 3019 3020~~~json 3021request: 3022{ 3023 "params": { 3024 "enabled": true, 3025 "period_us": 2000 3026 }, 3027 "jsonrpc": "2.0", 3028 "method": "bdev_nvme_set_hotplug", 3029 "id": 1 3030} 3031~~~ 3032 3033Example response: 3034 3035~~~json 3036{ 3037 "jsonrpc": "2.0", 3038 "id": 1, 3039 "result": true 3040} 3041~~~ 3042 3043### bdev_nvme_attach_controller {#rpc_bdev_nvme_attach_controller} 3044 3045Construct @ref bdev_config_nvme. This RPC can also be used to add additional paths to an existing controller to enable 3046multipathing. This is done by specifying the `name` parameter as an existing controller. When adding an additional 3047path, the hostnqn, hostsvcid, hostaddr, prchk_reftag, and prchk_guard_arguments must not be specified and are assumed 3048to have the same value as the existing path. 3049 3050The parameters, `ctrlr_loss_timeout_sec`, `reconnect_delay_sec`, and `fast_io_fail_timeout_sec`, are mutually dependent. 3051If `reconnect_delay_sec` is non-zero, `ctrlr_loss_timeout_sec` has to be -1 or not less than `reconnect_delay_sec`. 3052If `reconnect_delay_sec` is zero, `ctrlr_loss_timeout_sec` has to be zero. 3053If `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. 3054 3055#### Result 3056 3057Array of names of newly created bdevs. 3058 3059#### Parameters 3060 3061Name | Optional | Type | Description 3062-------------------------- | -------- | ----------- | ----------- 3063name | Required | string | Name of the NVMe controller, prefix for each bdev name 3064trtype | Required | string | NVMe-oF target trtype: rdma or pcie 3065traddr | Required | string | NVMe-oF target address: ip or BDF 3066adrfam | Optional | string | NVMe-oF target adrfam: ipv4, ipv6, ib, fc, intra_host 3067trsvcid | Optional | string | NVMe-oF target trsvcid: port number 3068subnqn | Optional | string | NVMe-oF target subnqn 3069hostnqn | Optional | string | NVMe-oF target hostnqn 3070hostaddr | Optional | string | NVMe-oF host address: ip address 3071hostsvcid | Optional | string | NVMe-oF host trsvcid: port number 3072prchk_reftag | Optional | bool | Enable checking of PI reference tag for I/O processing 3073prchk_guard | Optional | bool | Enable checking of PI guard for I/O processing 3074hdgst | Optional | bool | Enable TCP header digest 3075ddgst | Optional | bool | Enable TCP data digest 3076fabrics_connect_timeout_us | Optional | bool | Timeout for fabrics connect (in microseconds) 3077multipath | Optional | string | Multipathing behavior: disable, failover, multipath. Default is failover. 3078num_io_queues | Optional | uint32_t | The number of IO queues to request during initialization. Range: (0, UINT16_MAX + 1], Default is 1024. 3079ctrlr_loss_timeout_sec | Optional | number | Time to wait until ctrlr is reconnected before deleting ctrlr. -1 means infinite reconnects. 0 means no reconnect. 3080reconnect_delay_sec | Optional | number | Time to delay a reconnect trial. 0 means no reconnect. 3081fast_io_fail_timeout_sec | Optional | number | Time to wait until ctrlr is reconnected before failing I/O to ctrlr. 0 means no such timeout. 3082 3083#### Example 3084 3085Example request: 3086 3087~~~json 3088{ 3089 "params": { 3090 "trtype": "pcie", 3091 "name": "Nvme0", 3092 "traddr": "0000:0a:00.0" 3093 }, 3094 "jsonrpc": "2.0", 3095 "method": "bdev_nvme_attach_controller", 3096 "id": 1 3097} 3098~~~ 3099 3100Example response: 3101 3102~~~json 3103{ 3104 "jsonrpc": "2.0", 3105 "id": 1, 3106 "result": [ 3107 "Nvme0n1" 3108 ] 3109} 3110~~~ 3111 3112### bdev_nvme_get_controllers {#rpc_bdev_nvme_get_controllers} 3113 3114Get information about NVMe controllers. 3115 3116#### Parameters 3117 3118The user may specify no parameters in order to list all NVMe controllers, or one NVMe controller may be 3119specified by name. 3120 3121Name | Optional | Type | Description 3122----------------------- | -------- | ----------- | ----------- 3123name | Optional | string | NVMe controller name 3124 3125#### Response 3126 3127The response is an array of objects containing information about the requested NVMe controllers. 3128 3129#### Example 3130 3131Example request: 3132 3133~~~json 3134{ 3135 "jsonrpc": "2.0", 3136 "id": 1, 3137 "method": "bdev_nvme_get_controllers", 3138 "params": { 3139 "name": "Nvme0" 3140 } 3141} 3142~~~ 3143 3144Example response: 3145 3146~~~json 3147{ 3148 "jsonrpc": "2.0", 3149 "id": 1, 3150 "result": [ 3151 { 3152 "name": "Nvme0", 3153 "trid": { 3154 "trtype": "PCIe", 3155 "traddr": "0000:05:00.0" 3156 }, 3157 "cntlid": 0 3158 } 3159 ] 3160} 3161~~~ 3162 3163### bdev_nvme_detach_controller {#rpc_bdev_nvme_detach_controller} 3164 3165Detach NVMe controller and delete any associated bdevs. Optionally, 3166If all of the transport ID options are specified, only remove that 3167transport path from the specified controller. If that is the only 3168available path for the controller, this will also result in the 3169controller being detached and the associated bdevs being deleted. 3170 3171returns true if the controller and bdevs were successfully destroyed 3172or the address was properly removed, false otherwise. 3173 3174#### Parameters 3175 3176Name | Optional | Type | Description 3177----------------------- | -------- | ----------- | ----------- 3178name | Required | string | Controller name 3179trtype | Optional | string | NVMe-oF target trtype: rdma or tcp 3180traddr | Optional | string | NVMe-oF target address: ip or BDF 3181adrfam | Optional | string | NVMe-oF target adrfam: ipv4, ipv6, ib, fc, intra_host 3182trsvcid | Optional | string | NVMe-oF target trsvcid: port number 3183subnqn | Optional | string | NVMe-oF target subnqn 3184hostaddr | Optional | string | NVMe-oF host address: ip 3185hostsvcid | Optional | string | NVMe-oF host svcid: port number 3186 3187#### Example 3188 3189Example requests: 3190 3191~~~json 3192{ 3193 "params": { 3194 "name": "Nvme0" 3195 }, 3196 "jsonrpc": "2.0", 3197 "method": "bdev_nvme_detach_controller", 3198 "id": 1 3199} 3200~~~ 3201 3202Example response: 3203 3204~~~json 3205{ 3206 "jsonrpc": "2.0", 3207 "id": 1, 3208 "result": true 3209} 3210~~~ 3211 3212### bdev_nvme_reset_controller {#rpc_bdev_nvme_reset_controller} 3213 3214Reset NVMe controller. 3215 3216Returns true if the controller reset was successful, false otherwise. 3217 3218#### Parameters 3219 3220Name | Optional | Type | Description 3221----------------------- | -------- | ----------- | ----------- 3222name | Required | string | NVMe controller name 3223 3224#### Example 3225 3226Example request: 3227 3228~~~json 3229{ 3230 "jsonrpc": "2.0", 3231 "id": 1, 3232 "method": "bdev_nvme_reset_controller", 3233 "params": { 3234 "name": "Nvme0" 3235 } 3236} 3237~~~ 3238 3239Example response: 3240 3241~~~json 3242{ 3243 "jsonrpc": "2.0", 3244 "id": 1, 3245 "result": true 3246} 3247~~~ 3248 3249### bdev_nvme_start_discovery {#rpc_bdev_nvme_start_discovery} 3250 3251Start a discovery service for the discovery subsystem of the specified transport ID. 3252 3253The discovery service will read the discovery log page for the specified 3254discovery subsystem, and automatically attach to any subsystems found in the 3255log page. When determining a controller name to use when attaching, it will use 3256the 'name' parameter as a prefix, followed by a unique integer for that discovery 3257service. If the discovery service identifies a subsystem that has been previously 3258attached but is listed with a different path, it will use the same controller name 3259as the previous entry, and connect as a multipath. 3260 3261When the discovery service sees that a subsystem entry has been removed 3262from the log page, it will automatically detach from that controller as well. 3263 3264The 'name' is also used to later stop the discovery service. 3265 3266#### Parameters 3267 3268Name | Optional | Type | Description 3269-------------------------- | -------- | ----------- | ----------- 3270name | Required | string | Prefix for NVMe controllers 3271trtype | Required | string | NVMe-oF target trtype: rdma or tcp 3272traddr | Required | string | NVMe-oF target address: ip 3273adrfam | Optional | string | NVMe-oF target adrfam: ipv4, ipv6 3274trsvcid | Optional | string | NVMe-oF target trsvcid: port number 3275hostnqn | Optional | string | NVMe-oF target hostnqn 3276wait_for_attach | Optional | bool | Wait to complete until all discovered NVM subsystems are attached 3277ctrlr_loss_timeout_sec | Optional | number | Time to wait until ctrlr is reconnected before deleting ctrlr. -1 means infinite reconnects. 0 means no reconnect. 3278reconnect_delay_sec | Optional | number | Time to delay a reconnect trial. 0 means no reconnect. 3279fast_io_fail_timeout_sec | Optional | number | Time to wait until ctrlr is reconnected before failing I/O to ctrlr. 0 means no such timeout. 3280 3281#### Example 3282 3283Example request: 3284 3285~~~json 3286{ 3287 "jsonrpc": "2.0", 3288 "method": "bdev_nvme_start_discovery", 3289 "id": 1, 3290 "params": { 3291 "name": "nvme_auto", 3292 "trtype": "tcp", 3293 "traddr": "127.0.0.1", 3294 "hostnqn": "nqn.2021-12.io.spdk:host1", 3295 "adrfam": "ipv4", 3296 "trsvcid": "4420" 3297 } 3298} 3299~~~ 3300 3301Example response: 3302 3303~~~json 3304{ 3305 "jsonrpc": "2.0", 3306 "id": 1, 3307 "result": true 3308} 3309~~~ 3310 3311### bdev_nvme_stop_discovery {#rpc_bdev_nvme_stop_discovery} 3312 3313Stop a discovery service. This includes detaching any controllers that were 3314discovered via the service that is being stopped. 3315 3316#### Parameters 3317 3318Name | Optional | Type | Description 3319-------------------------- | -------- | ----------- | ----------- 3320name | Required | string | Name of service to stop 3321 3322#### Example 3323 3324Example request: 3325 3326~~~json 3327{ 3328 "jsonrpc": "2.0", 3329 "method": "bdev_nvme_stop_discovery", 3330 "id": 1, 3331 "params": { 3332 "name": "nvme_auto" 3333 } 3334} 3335~~~ 3336 3337Example response: 3338 3339~~~json 3340{ 3341 "jsonrpc": "2.0", 3342 "id": 1, 3343 "result": true 3344} 3345~~~ 3346 3347### bdev_nvme_get_discovery_info {#rpc_bdev_nvme_get_discovery_info} 3348 3349Get information about the discovery service. 3350 3351#### Example 3352 3353Example request: 3354~~~json 3355{ 3356 "jsonrpc": "2.0", 3357 "method": "bdev_nvme_get_discovery_info", 3358 "id": 1 3359} 3360~~~ 3361 3362Example response: 3363 3364~~~json 3365{ 3366 "jsonrpc": "2.0", 3367 "id": 1, 3368 "result": [ 3369 { 3370 "name": "nvme-disc", 3371 "trid": { 3372 "trtype": "TCP", 3373 "adrfam": "IPv4", 3374 "traddr": "127.0.0.1", 3375 "trsvcid": "8009", 3376 "subnqn": "nqn.2014-08.org.nvmexpress.discovery" 3377 }, 3378 "referrals": [] 3379 } 3380 ] 3381} 3382~~~ 3383 3384### bdev_nvme_get_io_paths {#rpc_bdev_nvme_get_io_paths} 3385 3386Display all or the specified NVMe bdev's active I/O paths. 3387 3388#### Parameters 3389 3390Name | Optional | Type | Description 3391----------------------- | -------- | ----------- | ----------- 3392name | Optional | string | Name of the NVMe bdev 3393 3394#### Example 3395 3396Example request: 3397 3398~~~json 3399{ 3400 "jsonrpc": "2.0", 3401 "method": "bdev_nvme_get_io_paths", 3402 "id": 1, 3403 "params": { 3404 "name": "Nvme0n1" 3405 } 3406} 3407~~~ 3408 3409Example response: 3410 3411~~~json 3412{ 3413 "jsonrpc": "2.0", 3414 "id": 1, 3415 "result": { 3416 "poll_groups": [ 3417 { 3418 "thread": "app_thread", 3419 "io_paths": [ 3420 { 3421 "bdev_name": "Nvme0n1", 3422 "cntlid": 0, 3423 "current": true, 3424 "connected": true, 3425 "accessible": true 3426 } 3427 ] 3428 } 3429 ] 3430 } 3431} 3432~~~ 3433 3434### bdev_nvme_set_preferred_path {#rpc_bdev_nvme_set_preferred_path} 3435 3436Set the preferred I/O path for an NVMe bdev in multipath mode. 3437 3438NOTE: This RPC does not support NVMe bdevs in failover mode. 3439 3440#### Parameters 3441 3442Name | Optional | Type | Description 3443----------------------- | -------- | ----------- | ----------- 3444name | Required | string | Name of the NVMe bdev 3445cntlid | Required | number | NVMe-oF controller ID 3446 3447#### Example 3448 3449Example request: 3450 3451~~~json 3452{ 3453 "jsonrpc": "2.0", 3454 "method": "bdev_nvme_set_preferred_path", 3455 "id": 1, 3456 "params": { 3457 "name": "Nvme0n1", 3458 "cntlid": 0 3459 } 3460} 3461~~~ 3462 3463Example response: 3464 3465~~~json 3466{ 3467 "jsonrpc": "2.0", 3468 "id": 1, 3469 "result": true 3470} 3471~~~ 3472 3473### bdev_nvme_set_multipath_policy {#rpc_bdev_nvme_set_multipath_policy} 3474 3475Set multipath policy of the NVMe bdev in multipath mode. 3476 3477#### Parameters 3478 3479Name | Optional | Type | Description 3480----------------------- | -------- | ----------- | ----------- 3481name | Required | string | Name of the NVMe bdev 3482policy | Required | string | Multipath policy: active_active or active_passive 3483 3484#### Example 3485 3486Example request: 3487 3488~~~json 3489{ 3490 "jsonrpc": "2.0", 3491 "method": "bdev_nvme_set_multipath_policy", 3492 "id": 1, 3493 "params": { 3494 "name": "Nvme0n1", 3495 "policy": "active_passive" 3496 } 3497} 3498~~~ 3499 3500Example response: 3501 3502~~~json 3503{ 3504 "jsonrpc": "2.0", 3505 "id": 1, 3506 "result": true 3507} 3508~~~ 3509 3510### bdev_nvme_cuse_register {#rpc_bdev_nvme_cuse_register} 3511 3512Register CUSE device on NVMe controller. 3513This feature is considered as experimental. 3514 3515#### Parameters 3516 3517Name | Optional | Type | Description 3518----------------------- | -------- | ----------- | ----------- 3519name | Required | string | Name of the NVMe controller 3520dev_path | Required | string | Path to the CUSE controller device, e.g. spdk/nvme0 3521 3522#### Example 3523 3524Example request: 3525 3526~~~json 3527{ 3528 "params": { 3529 "dev_path": "spdk/nvme0", 3530 "name": "Nvme0" 3531 }, 3532 "jsonrpc": "2.0", 3533 "method": "bdev_nvme_cuse_register", 3534 "id": 1 3535} 3536~~~ 3537 3538Example response: 3539 3540~~~json 3541{ 3542 "jsonrpc": "2.0", 3543 "id": 1, 3544 "result": true 3545} 3546~~~ 3547 3548### bdev_nvme_cuse_unregister {#rpc_bdev_nvme_cuse_unregister} 3549 3550Unregister CUSE device on NVMe controller. 3551This feature is considered as experimental. 3552 3553#### Parameters 3554 3555Name | Optional | Type | Description 3556----------------------- | -------- | ----------- | ----------- 3557name | Required | string | Name of the NVMe controller 3558 3559#### Example 3560 3561Example request: 3562 3563~~~json 3564{ 3565 "params": { 3566 "name": "Nvme0" 3567 }, 3568 "jsonrpc": "2.0", 3569 "method": "bdev_nvme_cuse_unregister", 3570 "id": 1 3571} 3572~~~ 3573 3574Example response: 3575 3576~~~json 3577{ 3578 "jsonrpc": "2.0", 3579 "id": 1, 3580 "result": true 3581} 3582~~~ 3583 3584### bdev_zone_block_create {#rpc_bdev_zone_block_create} 3585 3586Creates a virtual zone device on top of existing non-zoned bdev. 3587 3588#### Parameters 3589 3590Name | Optional | Type | Description 3591----------------------- | -------- | ----------- | ----------- 3592name | Required | string | Name of the Zone device 3593base_bdev | Required | string | Name of the Base bdev 3594zone_capacity | Required | number | Zone capacity in blocks 3595optimal_open_zones | Required | number | Number of zones required to reach optimal write speed 3596 3597#### Example 3598 3599Example request: 3600 3601~~~json 3602{ 3603 "jsonrpc": "2.0", 3604 "method": "bdev_zone_block_create", 3605 "id": 1, 3606 "params": { 3607 "name": "zone1", 3608 "base_bdev": "NVMe0n1", 3609 "zone_capacity": 4096, 3610 "optimal_open_zones": 32 3611 } 3612} 3613~~~ 3614 3615Example response: 3616 3617~~~json 3618{ 3619 "jsonrpc": "2.0", 3620 "id": 1, 3621 "result": "zone1" 3622} 3623~~~ 3624 3625### bdev_zone_block_delete {#rpc_bdev_zone_block_delete} 3626 3627Deletes a virtual zone device. 3628 3629#### Parameters 3630 3631Name | Optional | Type | Description 3632----------------------- | -------- | ----------- | ----------- 3633name | Required | string | Name of the Zone device 3634 3635#### Example 3636 3637Example request: 3638 3639~~~json 3640{ 3641 "jsonrpc": "2.0", 3642 "method": "bdev_zone_block_delete", 3643 "id": 1, 3644 "params": { 3645 "name": "zone1" 3646 } 3647} 3648~~~ 3649 3650Example response: 3651 3652~~~json 3653{ 3654 "jsonrpc": "2.0", 3655 "id": 1, 3656 "result": true 3657} 3658~~~ 3659 3660### bdev_nvme_apply_firmware {#rpc_bdev_nvme_apply_firmware} 3661 3662Download and commit firmware to NVMe device. 3663 3664#### Parameters 3665 3666Name | Optional | Type | Description 3667----------------------- | -------- | ----------- | ----------- 3668filename | Required | string | filename of the firmware to download 3669bdev_name | Required | string | Name of the NVMe block device 3670 3671#### Example 3672 3673Example request: 3674 3675~~~json 3676{ 3677 "jsonrpc": "2.0", 3678 "method": "bdev_nvme_apply_firmware", 3679 "id": 1, 3680 "params": { 3681 "filename": "firmware_file", 3682 "bdev_name": "NVMe0n1" 3683 } 3684} 3685~~~ 3686 3687### bdev_nvme_get_transport_statistics {#rpc_bdev_nvme_get_transport_statistics} 3688 3689Get bdev_nvme poll group transport statistics. 3690 3691#### Parameters 3692 3693This RPC method accepts no parameters 3694 3695#### Response 3696 3697The response is an array of objects containing information about transport statistics per NVME poll group. 3698 3699#### Example 3700 3701Example request: 3702 3703~~~json 3704{ 3705 "jsonrpc": "2.0", 3706 "id": 1, 3707 "method": "bdev_nvme_get_transport_statistics", 3708} 3709~~~ 3710 3711Example response: 3712 3713~~~json 3714{ 3715 "jsonrpc": "2.0", 3716 "id": 1, 3717 "result": { 3718 "poll_groups": [ 3719 { 3720 "thread": "nvmf_tgt_poll_group_0", 3721 "transports": [ 3722 { 3723 "trname": "RDMA", 3724 "devices": [ 3725 { 3726 "dev_name": "mlx5_1", 3727 "polls": 137492169, 3728 "idle_polls": 137492169, 3729 "completions": 0, 3730 "queued_requests": 0, 3731 "total_send_wrs": 0, 3732 "send_sq_doorbell_updates": 0, 3733 "total_recv_wrs": 0, 3734 "recv_sq_doorbell_updates": 0 3735 }, 3736 { 3737 "dev_name": "mlx5_0", 3738 "polls": 137985185, 3739 "idle_polls": 137492169, 3740 "completions": 1474593, 3741 "queued_requests": 0, 3742 "total_send_wrs": 1474593, 3743 "send_sq_doorbell_updates": 426147, 3744 "total_recv_wrs": 1474721, 3745 "recv_sq_doorbell_updates": 348445 3746 } 3747 ] 3748 }, 3749 { 3750 "trname": "PCIE", 3751 "polls": 435419831, 3752 "idle_polls": 434901004, 3753 "completions": 1485543, 3754 "cq_doorbell_updates": 518827, 3755 "queued_requests": 0, 3756 "submitted_requests": 1485543, 3757 "sq_doorbell_updates": 516081 3758 } 3759 ] 3760 }, 3761 { 3762 "thread": "nvmf_tgt_poll_group_1", 3763 "transports": [ 3764 { 3765 "trname": "RDMA", 3766 "devices": [ 3767 { 3768 "dev_name": "mlx5_1", 3769 "polls": 140245630, 3770 "idle_polls": 140245630, 3771 "completions": 0, 3772 "queued_requests": 0, 3773 "total_send_wrs": 0, 3774 "send_sq_doorbell_updates": 0, 3775 "total_recv_wrs": 0, 3776 "recv_sq_doorbell_updates": 0 3777 }, 3778 { 3779 "dev_name": "mlx5_0", 3780 "polls": 140751844, 3781 "idle_polls": 140245630, 3782 "completions": 1489298, 3783 "queued_requests": 0, 3784 "total_send_wrs": 1489298, 3785 "send_sq_doorbell_updates": 433510, 3786 "total_recv_wrs": 1489426, 3787 "recv_sq_doorbell_updates": 357956 3788 } 3789 ] 3790 }, 3791 { 3792 "trname": "PCIE", 3793 "polls": 429044294, 3794 "idle_polls": 428525658, 3795 "completions": 1478730, 3796 "cq_doorbell_updates": 518636, 3797 "queued_requests": 0, 3798 "submitted_requests": 1478730, 3799 "sq_doorbell_updates": 511658 3800 } 3801 ] 3802 } 3803 ] 3804 } 3805} 3806~~~ 3807 3808### bdev_nvme_get_controller_health_info {#rpc_bdev_nvme_get_controller_health_info} 3809 3810Display health log of the required NVMe bdev device. 3811 3812#### Parameters 3813 3814Name | Optional | Type | Description 3815----------------------- | -------- | ----------- | ----------- 3816name | Required | string | Name of the NVMe bdev controller 3817 3818#### Response 3819 3820The response is the object containing information about health log of the NVMe controller. 3821 3822#### Example 3823 3824Example request: 3825 3826~~~json 3827{ 3828 "jsonrpc": "2.0", 3829 "method": "bdev_nvme_get_controller_health_info", 3830 "id": 1, 3831 "params": { 3832 "name": "Nvme0" 3833 } 3834} 3835~~~ 3836 3837Example response: 3838 3839~~~json 3840{ 3841 "model_number": "INTEL SSDPE2KX020T8", 3842 "serial_number": "BTLJ72430ARH2P0BGN", 3843 "firmware_revision": "VDV10110", 3844 "traddr": "0000:08:00.0", 3845 "temperature_celsius": 32, 3846 "available_spare_percentage": 99, 3847 "available_spare_threshold_percentage": 10, 3848 "percentage_used": 2, 3849 "data_units_read": 1013408619, 3850 "data_units_written": 346792685, 3851 "host_read_commands": 30457773282, 3852 "host_write_commands": 18949677715, 3853 "controller_busy_time": 4979, 3854 "power_cycles": 49, 3855 "power_on_hours": 31118, 3856 "unsafe_shutdowns": 18, 3857 "media_errors": 17, 3858 "num_err_log_entries": 19, 3859 "warning_temperature_time_minutes": 0, 3860 "critical_composite_temperature_time_minutes": 0 3861} 3862~~~ 3863 3864### bdev_rbd_register_cluster {#rpc_bdev_rbd_register_cluster} 3865 3866This method is available only if SPDK was build with Ceph RBD support. 3867 3868#### Parameters 3869 3870Name | Optional | Type | Description 3871----------------------- | -------- | ----------- | ----------- 3872name | Required | string | Registerd Rados cluster object name 3873user_id | Optional | string | Ceph ID (i.e. admin, not client.admin) 3874config_param | Optional | string map | Explicit librados configuration 3875config_file | Optional | string | File path of libraodos configuration file 3876key_file | Optional | string | File path of libraodos key file 3877 3878This RPC registers a Rados Cluster object handle which is only known 3879to rbd module, it uses user_id + config_param or user_id + config_file + 3880key_file or user_id + config_param + config_file + key_file to identify 3881a Rados cluster object. 3882 3883When accessing the Ceph cluster as some user other than "admin" (the 3884default), the "user_id" has to be set. 3885 3886The configuration items and secret key can be specified by setting config_param, 3887config_file and key_file, all of them, or none of them. If only config_param is 3888passed, all key/value pairs are passed to rados_conf_set to configure cluster access. 3889In practice, "mon_host" (= list of monitor address+port) and "key" (= the secret key 3890stored in Ceph keyrings) are enough. If config_file and key_file are specified, they must 3891exist with all relevant settings for accessing the Ceph cluster. If config_param, config_file 3892and key_file are specified, get the key/value pairs from config_file first and set to 3893rados_conf_set function, then set pairs in config_param and keyring in key_file. If nothing 3894is specified, it will get configuration file and key file from the default location 3895/etc/ceph/ceph.conf and /etc/ceph/ceph.client.user_id.keyring. 3896 3897#### Result 3898 3899Name of newly created Rados cluster object. 3900 3901#### Example 3902 3903Example request: 3904 3905~~ 3906{ 3907 "params": { 3908 "name": "rbd_cluster", 3909 "user_id": cinder, 3910 "config_file": "/root/ceph_conf/ceph.conf", 3911 "key_file": "/root/ceph_conf/ceph.client.cinder.keyring" 3912 }, 3913 "jsonrpc": "2.0", 3914 "method": "bdev_rbd_register_cluster", 3915 "id": 1 3916} 3917~~ 3918 3919Example response: 3920 3921~~ 3922response: 3923{ 3924 "jsonrpc": "2.0", 3925 "id": 1, 3926 "result": "rbd_cluster" 3927} 3928~~ 3929 3930### bdev_rbd_unregister_cluster {#rpc_bdev_rbd_unregister_cluster} 3931 3932This method is available only if SPDK was build with Ceph RBD support. 3933If there is still rbd bdev using this cluster, the unregisteration operation 3934will fail. 3935 3936#### Result 3937 3938`true` if Rados cluster object with provided name was deleted or `false` otherwise. 3939 3940#### Parameters 3941 3942Name | Optional | Type | Description 3943----------------------- | -------- | ----------- | ------------------------- 3944name | Required | string | Rados cluster object name 3945 3946#### Example 3947 3948Example request: 3949 3950~~ 3951{ 3952 "params": { 3953 "name": "rbd_cluster" 3954 }, 3955 "jsonrpc": "2.0", 3956 "method": "bdev_rbd_unregister_cluster", 3957 "id": 1 3958} 3959~~ 3960 3961Example response: 3962 3963~~ 3964{ 3965 "jsonrpc": "2.0", 3966 "id": 1, 3967 "result": true 3968} 3969~~ 3970 3971### bdev_rbd_get_clusters_info {#rpc_bdev_rbd_get_clusters_info} 3972 3973This method is available only if SPDK was build with Ceph RBD support. 3974 3975#### Result 3976 3977Returns the cluster info of the Rados Cluster name if provided. Otherwise, it 3978returns the cluster info of every registered Raods Cluster name. 3979 3980#### Parameters 3981 3982Name | Optional | Type | Description 3983----------------------- | -------- | ----------- | ------------------------- 3984name | Optional | string | Rados cluster object name 3985 3986#### Example 3987 3988Example request: 3989 3990~~ 3991{ 3992 "params": { 3993 "name": "rbd_cluster" 3994 }, 3995 "jsonrpc": "2.0", 3996 "method": "bdev_rbd_get_clusters_info", 3997 "id": 1 3998} 3999~~ 4000 4001Example response: 4002 4003~~ 4004{ 4005 "jsonrpc": "2.0", 4006 "cluster_name": "rbd_cluster" 4007} 4008~~ 4009 4010### bdev_rbd_create {#rpc_bdev_rbd_create} 4011 4012Create @ref bdev_config_rbd bdev 4013 4014This method is available only if SPDK was build with Ceph RBD support. 4015 4016#### Parameters 4017 4018Name | Optional | Type | Description 4019----------------------- | -------- | ----------- | ----------- 4020name | Optional | string | Bdev name 4021user_id | Optional | string | Ceph ID (i.e. admin, not client.admin) 4022pool_name | Required | string | Pool name 4023rbd_name | Required | string | Image name 4024block_size | Required | number | Block size 4025config | Optional | string map | Explicit librados configuration 4026cluster_name | Optional | string | Rados cluster object name created in this module. 4027uuid | Optional | string | UUID of new bdev 4028 4029If no config is specified, Ceph configuration files must exist with 4030all relevant settings for accessing the pool. If a config map is 4031passed, the configuration files are ignored and instead all key/value 4032pairs are passed to rados_conf_set to configure cluster access. In 4033practice, "mon_host" (= list of monitor address+port) and "key" (= the 4034secret key stored in Ceph keyrings) are enough. 4035 4036When accessing the image as some user other than "admin" (the 4037default), the "user_id" has to be set. 4038 4039If provided with cluster_name option, it will use the Rados cluster object 4040referenced by the name (created by bdev_rbd_register_cluster RPC) and ignores 4041"user_id + config" combination to create its own Rados cluster. 4042 4043#### Result 4044 4045Name of newly created bdev. 4046 4047#### Example 4048 4049Example request with `key` from `/etc/ceph/ceph.client.admin.keyring`: 4050 4051~~~json 4052{ 4053 "params": { 4054 "pool_name": "rbd", 4055 "rbd_name": "foo", 4056 "config": { 4057 "mon_host": "192.168.7.1:6789,192.168.7.2:6789", 4058 "key": "AQDwf8db7zR1GRAA5k7NKXjS5S5V4mntwUDnGQ==", 4059 } 4060 "block_size": 4096, 4061 "uuid": "76210ea4-7920-40a0-a07b-8992a7443c76" 4062 }, 4063 "jsonrpc": "2.0", 4064 "method": "bdev_rbd_create", 4065 "id": 1 4066} 4067~~~ 4068 4069Example response: 4070 4071~~~json 4072response: 4073{ 4074 "jsonrpc": "2.0", 4075 "id": 1, 4076 "result": "Ceph0" 4077} 4078~~~ 4079 4080Example request with `cluster_name`: 4081 4082~~ 4083{ 4084 "params": { 4085 "pool_name": "rbd", 4086 "rbd_name": "foo", 4087 "block_size": 4096, 4088 "cluster_name": "rbd_cluster" 4089 }, 4090 "jsonrpc": "2.0", 4091 "method": "bdev_rbd_create", 4092 "id": 1 4093} 4094~~ 4095 4096Example response: 4097 4098~~ 4099response: 4100{ 4101 "jsonrpc": "2.0", 4102 "id": 1, 4103 "result": "Ceph0" 4104} 4105~~ 4106 4107### bdev_rbd_delete {#rpc_bdev_rbd_delete} 4108 4109Delete @ref bdev_config_rbd bdev 4110 4111This method is available only if SPDK was build with Ceph RBD support. 4112 4113#### Result 4114 4115`true` if bdev with provided name was deleted or `false` otherwise. 4116 4117#### Parameters 4118 4119Name | Optional | Type | Description 4120----------------------- | -------- | ----------- | ----------- 4121name | Required | string | Bdev name 4122 4123#### Example 4124 4125Example request: 4126 4127~~~json 4128{ 4129 "params": { 4130 "name": "Rbd0" 4131 }, 4132 "jsonrpc": "2.0", 4133 "method": "bdev_rbd_delete", 4134 "id": 1 4135} 4136~~~ 4137 4138Example response: 4139 4140~~~json 4141{ 4142 "jsonrpc": "2.0", 4143 "id": 1, 4144 "result": true 4145} 4146~~~ 4147 4148### bdev_rbd_resize {#rpc_bdev_rbd_resize} 4149 4150Resize @ref bdev_config_rbd bdev 4151 4152This method is available only if SPDK was build with Ceph RBD support. 4153 4154#### Result 4155 4156`true` if bdev with provided name was resized or `false` otherwise. 4157 4158#### Parameters 4159 4160Name | Optional | Type | Description 4161----------------------- | -------- | ----------- | ----------- 4162name | Required | string | Bdev name 4163new_size | Required | int | New bdev size for resize operation in MiB 4164 4165#### Example 4166 4167Example request: 4168 4169~~~json 4170{ 4171 "params": { 4172 "name": "Rbd0" 4173 "new_size": "4096" 4174 }, 4175 "jsonrpc": "2.0", 4176 "method": "bdev_rbd_resize", 4177 "id": 1 4178} 4179~~~ 4180 4181Example response: 4182 4183~~~json 4184{ 4185 "jsonrpc": "2.0", 4186 "id": 1, 4187 "result": true 4188} 4189~~~ 4190 4191### bdev_delay_create {#rpc_bdev_delay_create} 4192 4193Create delay bdev. This bdev type redirects all IO to it's base bdev and inserts a delay on the completion 4194path to create an artificial drive latency. All latency values supplied to this bdev should be in microseconds. 4195 4196#### Parameters 4197 4198Name | Optional | Type | Description 4199----------------------- | -------- | ----------- | ----------- 4200name | Required | string | Bdev name 4201base_bdev_name | Required | string | Base bdev name 4202avg_read_latency | Required | number | average read latency (us) 4203p99_read_latency | Required | number | p99 read latency (us) 4204avg_write_latency | Required | number | average write latency (us) 4205p99_write_latency | Required | number | p99 write latency (us) 4206 4207#### Result 4208 4209Name of newly created bdev. 4210 4211#### Example 4212 4213Example request: 4214 4215~~~json 4216{ 4217 "params": { 4218 "base_bdev_name": "Null0", 4219 "name": "Delay0", 4220 "avg_read_latency": "15", 4221 "p99_read_latency": "50", 4222 "avg_write_latency": "40", 4223 "p99_write_latency": "110", 4224 }, 4225 "jsonrpc": "2.0", 4226 "method": "bdev_delay_create", 4227 "id": 1 4228} 4229~~~ 4230 4231Example response: 4232 4233~~~json 4234{ 4235 "jsonrpc": "2.0", 4236 "id": 1, 4237 "result": "Delay0" 4238} 4239~~~ 4240 4241### bdev_delay_delete {#rpc_bdev_delay_delete} 4242 4243Delete delay bdev. 4244 4245#### Parameters 4246 4247Name | Optional | Type | Description 4248----------------------- | -------- | ----------- | ----------- 4249name | Required | string | Bdev name 4250 4251#### Example 4252 4253Example request: 4254 4255~~~json 4256{ 4257 "params": { 4258 "name": "Delay0" 4259 }, 4260 "jsonrpc": "2.0", 4261 "method": "bdev_delay_delete", 4262 "id": 1 4263} 4264 4265~~~ 4266 4267Example response: 4268 4269~~~json 4270{ 4271 "jsonrpc": "2.0", 4272 "id": 1, 4273 "result": true 4274} 4275~~~ 4276 4277### bdev_delay_update_latency {#rpc_bdev_delay_update_latency} 4278 4279Update a target latency value associated with a given delay bdev. Any currently 4280outstanding I/O will be completed with the old latency. 4281 4282#### Parameters 4283 4284Name | Optional | Type | Description 4285----------------------- | -------- | ----------- | ----------- 4286delay_bdev_name | Required | string | Name of the delay bdev 4287latency_type | Required | string | One of: avg_read, avg_write, p99_read, p99_write 4288latency_us | Required | number | The new latency value in microseconds 4289 4290#### Result 4291 4292Name of newly created bdev. 4293 4294#### Example 4295 4296Example request: 4297 4298~~~json 4299{ 4300 "params": { 4301 "delay_bdev_name": "Delay0", 4302 "latency_type": "avg_read", 4303 "latency_us": "100", 4304 }, 4305 "jsonrpc": "2.0", 4306 "method": "bdev_delay_update_latency", 4307 "id": 1 4308} 4309~~~ 4310 4311Example response: 4312 4313~~~json 4314{ 4315 "result": "true" 4316} 4317~~~ 4318 4319### bdev_error_create {#rpc_bdev_error_create} 4320 4321Construct error bdev. 4322 4323#### Parameters 4324 4325Name | Optional | Type | Description 4326----------------------- | -------- | ----------- | ----------- 4327base_name | Required | string | Base bdev name 4328 4329#### Example 4330 4331Example request: 4332 4333~~~json 4334{ 4335 "params": { 4336 "base_name": "Malloc0" 4337 }, 4338 "jsonrpc": "2.0", 4339 "method": "bdev_error_create", 4340 "id": 1 4341} 4342~~~ 4343 4344Example response: 4345 4346~~~json 4347{ 4348 "jsonrpc": "2.0", 4349 "id": 1, 4350 "result": true 4351} 4352~~~ 4353 4354### bdev_error_delete {#rpc_bdev_error_delete} 4355 4356Delete error bdev 4357 4358#### Result 4359 4360`true` if bdev with provided name was deleted or `false` otherwise. 4361 4362#### Parameters 4363 4364Name | Optional | Type | Description 4365----------------------- | -------- | ----------- | ----------- 4366name | Required | string | Error bdev name 4367 4368#### Example 4369 4370Example request: 4371 4372~~~json 4373{ 4374 "params": { 4375 "name": "EE_Malloc0" 4376 }, 4377 "jsonrpc": "2.0", 4378 "method": "bdev_error_delete", 4379 "id": 1 4380} 4381~~~ 4382 4383Example response: 4384 4385~~~json 4386{ 4387 "jsonrpc": "2.0", 4388 "id": 1, 4389 "result": true 4390} 4391~~~ 4392 4393### bdev_error_inject_error {#rpc_bdev_error_inject_error} 4394 4395Inject an error via an error bdev. Create an error bdev on base bdev first. Default 'num' 4396value is 1 and if 'num' is set to zero, the specified injection is disabled. 4397 4398#### Parameters 4399 4400Name | Optional | Type | Description 4401----------------------- | -------- | ----------- | ----------- 4402name | Required | string | Name of the error injection bdev 4403io_type | Required | string | io type 'clear' 'read' 'write' 'unmap' 'flush' 'all' 4404error_type | Required | string | error type 'failure' 'pending' 4405num | Optional | int | the number of commands you want to fail.(default:1) 4406 4407#### Example 4408 4409Example request: 4410 4411~~~json 4412{ 4413 "jsonrpc": "2.0", 4414 "method": "bdev_error_inject_error", 4415 "id": 1, 4416 "params": { 4417 "name": "EE_Malloc0", 4418 "io_type": "write", 4419 "error_type": "pending", 4420 "num": 1 4421 } 4422} 4423~~~ 4424 4425Example response: 4426 4427~~~json 4428{ 4429 "jsonrpc": "2.0", 4430 "id": 1, 4431 "result": true 4432} 4433~~~ 4434 4435### bdev_iscsi_create {#rpc_bdev_iscsi_create} 4436 4437Connect to iSCSI target and create bdev backed by this connection. 4438 4439This method is available only if SPDK was build with iSCSI initiator support. 4440 4441#### Parameters 4442 4443Name | Optional | Type | Description 4444----------------------- | -------- | ----------- | ----------- 4445name | Required | string | Bdev name 4446initiator_iqn | Required | string | IQN name used during connection 4447url | Required | string | iSCSI resource URI 4448 4449#### Result 4450 4451Name of newly created bdev. 4452 4453#### Example 4454 4455Example request: 4456 4457~~~json 4458{ 4459 "params": { 4460 "url": "iscsi://127.0.0.1/iqn.2016-06.io.spdk:disk1/0", 4461 "initiator_iqn": "iqn.2016-06.io.spdk:init", 4462 "name": "iSCSI0" 4463 }, 4464 "jsonrpc": "2.0", 4465 "method": "bdev_iscsi_create", 4466 "id": 1 4467} 4468~~~ 4469 4470Example response: 4471 4472~~~json 4473{ 4474 "jsonrpc": "2.0", 4475 "id": 1, 4476 "result": "iSCSI0" 4477} 4478~~~ 4479 4480### bdev_iscsi_delete {#rpc_bdev_iscsi_delete} 4481 4482Delete iSCSI bdev and terminate connection to target. 4483 4484This method is available only if SPDK was built with iSCSI initiator support. 4485 4486#### Parameters 4487 4488Name | Optional | Type | Description 4489----------------------- | -------- | ----------- | ----------- 4490name | Required | string | Bdev name 4491 4492#### Example 4493 4494Example request: 4495 4496~~~json 4497{ 4498 "params": { 4499 "name": "iSCSI0" 4500 }, 4501 "jsonrpc": "2.0", 4502 "method": "bdev_iscsi_delete", 4503 "id": 1 4504} 4505~~~ 4506 4507Example response: 4508 4509~~~json 4510{ 4511 "jsonrpc": "2.0", 4512 "id": 1, 4513 "result": true 4514} 4515~~~ 4516 4517### bdev_ftl_create {#rpc_bdev_ftl_create} 4518 4519Create FTL bdev. 4520 4521This RPC is subject to change. 4522 4523#### Parameters 4524 4525Name | Optional | Type | Description 4526----------------------- | -------- | ----------- | ----------- 4527name | Required | string | Bdev name 4528trtype | Required | string | Transport type 4529traddr | Required | string | NVMe target address 4530punits | Required | string | Parallel unit range in the form of start-end e.g 4-8 4531uuid | Optional | string | UUID of restored bdev (not applicable when creating new instance) 4532cache | Optional | string | Name of the bdev to be used as a write buffer cache 4533 4534#### Result 4535 4536Name of newly created bdev. 4537 4538#### Example 4539 4540Example request: 4541 4542~~~json 4543{ 4544 "params": { 4545 "name": "nvme0" 4546 "trtype" "pcie" 4547 "traddr": "0000:00:04.0" 4548 "punits": "0-3" 4549 "uuid": "4a7481ce-786f-41a0-9b86-8f7465c8f4d3" 4550 }, 4551 "jsonrpc": "2.0", 4552 "method": "bdev_ftl_create", 4553 "id": 1 4554} 4555~~~ 4556 4557Example response: 4558 4559~~~json 4560{ 4561 "jsonrpc": "2.0", 4562 "id": 1, 4563 "result": { 4564 "name" : "nvme0" 4565 "uuid" : "4a7481ce-786f-41a0-9b86-8f7465c8f4d3" 4566 } 4567} 4568~~~ 4569 4570### bdev_ftl_delete {#rpc_bdev_ftl_delete} 4571 4572Delete FTL bdev. 4573 4574This RPC is subject to change. 4575 4576#### Parameters 4577 4578Name | Optional | Type | Description 4579----------------------- | -------- | ----------- | ----------- 4580name | Required | string | Bdev name 4581 4582#### Example 4583 4584Example request: 4585 4586~~~json 4587{ 4588 "params": { 4589 "name": "nvme0" 4590 }, 4591 "jsonrpc": "2.0", 4592 "method": "bdev_ftl_delete", 4593 "id": 1 4594} 4595~~~ 4596 4597Example response: 4598 4599~~~json 4600{ 4601 "jsonrpc": "2.0", 4602 "id": 1, 4603 "result": true 4604} 4605~~~ 4606 4607### bdev_pmem_create_pool {#rpc_bdev_pmem_create_pool} 4608 4609Create a @ref bdev_config_pmem blk pool file. It is equivalent of following `pmempool create` command: 4610 4611~~~bash 4612pmempool create -s $((num_blocks * block_size)) blk $block_size $pmem_file 4613~~~ 4614 4615This method is available only if SPDK was built with PMDK support. 4616 4617#### Parameters 4618 4619Name | Optional | Type | Description 4620----------------------- | -------- | ----------- | ----------- 4621pmem_file | Required | string | Path to new pmem file 4622num_blocks | Required | number | Number of blocks 4623block_size | Required | number | Size of each block in bytes 4624 4625#### Example 4626 4627Example request: 4628 4629~~~json 4630{ 4631 "params": { 4632 "block_size": 512, 4633 "num_blocks": 131072, 4634 "pmem_file": "/tmp/pmem_file" 4635 }, 4636 "jsonrpc": "2.0", 4637 "method": "bdev_pmem_create_pool", 4638 "id": 1 4639} 4640~~~ 4641 4642Example response: 4643 4644~~~json 4645{ 4646 "jsonrpc": "2.0", 4647 "id": 1, 4648 "result": true 4649} 4650~~~ 4651 4652### bdev_pmem_get_pool_info {#rpc_bdev_pmem_get_pool_info} 4653 4654Retrieve basic information about PMDK memory pool. 4655 4656This method is available only if SPDK was built with PMDK support. 4657 4658#### Parameters 4659 4660Name | Optional | Type | Description 4661----------------------- | -------- | ----------- | ----------- 4662pmem_file | Required | string | Path to existing pmem file 4663 4664#### Result 4665 4666Array of objects describing memory pool: 4667 4668Name | Type | Description 4669----------------------- | ----------- | ----------- 4670num_blocks | number | Number of blocks 4671block_size | number | Size of each block in bytes 4672 4673#### Example 4674 4675Example request: 4676 4677~~~json 4678request: 4679{ 4680 "params": { 4681 "pmem_file": "/tmp/pmem_file" 4682 }, 4683 "jsonrpc": "2.0", 4684 "method": "bdev_pmem_get_pool_info", 4685 "id": 1 4686} 4687~~~ 4688 4689Example response: 4690 4691~~~json 4692{ 4693 "jsonrpc": "2.0", 4694 "id": 1, 4695 "result": [ 4696 { 4697 "block_size": 512, 4698 "num_blocks": 129728 4699 } 4700 ] 4701} 4702~~~ 4703 4704### bdev_pmem_delete_pool {#rpc_bdev_pmem_delete_pool} 4705 4706Delete pmem pool by removing file `pmem_file`. This method will fail if `pmem_file` is not a 4707valid pmem pool file. 4708 4709This method is available only if SPDK was built with PMDK support. 4710 4711#### Parameters 4712 4713Name | Optional | Type | Description 4714----------------------- | -------- | ----------- | ----------- 4715pmem_file | Required | string | Path to new pmem file 4716 4717#### Example 4718 4719Example request: 4720 4721~~~json 4722{ 4723 "params": { 4724 "pmem_file": "/tmp/pmem_file" 4725 }, 4726 "jsonrpc": "2.0", 4727 "method": "bdev_pmem_delete_pool", 4728 "id": 1 4729} 4730~~~ 4731 4732Example response: 4733 4734~~~json 4735{ 4736 "jsonrpc": "2.0", 4737 "id": 1, 4738 "result": true 4739} 4740~~~ 4741 4742### bdev_pmem_create {#rpc_bdev_pmem_create} 4743 4744Construct @ref bdev_config_pmem bdev. 4745 4746This method is available only if SPDK was built with PMDK support. 4747 4748#### Parameters 4749 4750Name | Optional | Type | Description 4751----------------------- | -------- | ----------- | ----------- 4752name | Required | string | Bdev name 4753pmem_file | Required | string | Path to existing pmem blk pool file 4754 4755#### Result 4756 4757Name of newly created bdev. 4758 4759#### Example 4760 4761Example request: 4762 4763~~~json 4764{ 4765 "params": { 4766 "pmem_file": "/tmp/pmem_file", 4767 "name": "Pmem0" 4768 }, 4769 "jsonrpc": "2.0", 4770 "method": "bdev_pmem_create", 4771 "id": 1 4772} 4773~~~ 4774 4775Example response: 4776 4777~~~json 4778{ 4779 "jsonrpc": "2.0", 4780 "id": 1, 4781 "result": "Pmem0" 4782} 4783~~~ 4784 4785### bdev_pmem_delete {#rpc_bdev_pmem_delete} 4786 4787Delete @ref bdev_config_pmem bdev. This call will not remove backing pool files. 4788 4789This method is available only if SPDK was built with PMDK support. 4790 4791#### Result 4792 4793`true` if bdev with provided name was deleted or `false` otherwise. 4794 4795#### Parameters 4796 4797Name | Optional | Type | Description 4798----------------------- | -------- | ----------- | ----------- 4799name | Required | string | Bdev name 4800 4801#### Example 4802 4803Example request: 4804 4805~~~json 4806{ 4807 "params": { 4808 "name": "Pmem0" 4809 }, 4810 "jsonrpc": "2.0", 4811 "method": "bdev_pmem_delete", 4812 "id": 1 4813} 4814~~~ 4815 4816Example response: 4817 4818~~~json 4819{ 4820 "jsonrpc": "2.0", 4821 "id": 1, 4822 "result": true 4823} 4824~~~ 4825 4826### bdev_passthru_create {#rpc_bdev_passthru_create} 4827 4828Create passthru bdev. This bdev type redirects all IO to it's base bdev. It has no other purpose than being an example 4829and a starting point in development of new bdev type. 4830 4831#### Parameters 4832 4833Name | Optional | Type | Description 4834----------------------- | -------- | ----------- | ----------- 4835name | Required | string | Bdev name 4836base_bdev_name | Required | string | Base bdev name 4837 4838#### Result 4839 4840Name of newly created bdev. 4841 4842#### Example 4843 4844Example request: 4845 4846~~~json 4847{ 4848 "params": { 4849 "base_bdev_name": "Malloc0", 4850 "name": "Passsthru0" 4851 }, 4852 "jsonrpc": "2.0", 4853 "method": "bdev_passthru_create", 4854 "id": 1 4855} 4856~~~ 4857 4858Example response: 4859 4860~~~json 4861{ 4862 "jsonrpc": "2.0", 4863 "id": 1, 4864 "result": "Passsthru0" 4865} 4866~~~ 4867 4868### bdev_passthru_delete {#rpc_bdev_passthru_delete} 4869 4870Delete passthru bdev. 4871 4872#### Parameters 4873 4874Name | Optional | Type | Description 4875----------------------- | -------- | ----------- | ----------- 4876name | Required | string | Bdev name 4877 4878#### Example 4879 4880Example request: 4881 4882~~~json 4883{ 4884 "params": { 4885 "name": "Passsthru0" 4886 }, 4887 "jsonrpc": "2.0", 4888 "method": "bdev_passthru_delete", 4889 "id": 1 4890} 4891 4892~~~ 4893 4894Example response: 4895 4896~~~json 4897{ 4898 "jsonrpc": "2.0", 4899 "id": 1, 4900 "result": true 4901} 4902~~~ 4903 4904### bdev_virtio_attach_controller {#rpc_bdev_virtio_attach_controller} 4905 4906Create new initiator @ref bdev_config_virtio_scsi or @ref bdev_config_virtio_blk and expose all found bdevs. 4907 4908#### Parameters 4909 4910Name | Optional | Type | Description 4911----------------------- | -------- | ----------- | ----------- 4912name | Required | string | Virtio SCSI base bdev name or Virtio Blk bdev name 4913trtype | Required | string | Virtio target trtype: pci or user 4914traddr | Required | string | target address: BDF or UNIX socket file path 4915dev_type | Required | string | Virtio device type: blk or scsi 4916vq_count | Optional | number | Number of queues this controller will utilize (default: 1) 4917vq_size | Optional | number | Size of each queue. Must be power of 2. (default: 512) 4918 4919In case of Virtio SCSI the `name` parameter will be base name for new created bdevs. For Virtio Blk `name` will be the 4920name of created bdev. 4921 4922`vq_count` and `vq_size` parameters are valid only if `trtype` is `user`. 4923 4924#### Result 4925 4926Array of names of newly created bdevs. 4927 4928#### Example 4929 4930Example request: 4931 4932~~~json 4933{ 4934 "params": { 4935 "name": "VirtioScsi0", 4936 "trtype": "user", 4937 "vq_size": 128, 4938 "dev_type": "scsi", 4939 "traddr": "/tmp/VhostScsi0", 4940 "vq_count": 4 4941 }, 4942 "jsonrpc": "2.0", 4943 "method": "bdev_virtio_attach_controller", 4944 "id": 1 4945} 4946~~~ 4947 4948Example response: 4949 4950~~~json 4951{ 4952 "jsonrpc": "2.0", 4953 "id": 1, 4954 "result": ["VirtioScsi0t2", "VirtioScsi0t4"] 4955} 4956~~~ 4957 4958### bdev_virtio_scsi_get_devices {#rpc_bdev_virtio_scsi_get_devices} 4959 4960Show information about all available Virtio SCSI devices. 4961 4962#### Parameters 4963 4964This method has no parameters. 4965 4966#### Result 4967 4968Array of Virtio SCSI information objects. 4969 4970#### Example 4971 4972Example request: 4973 4974~~~json 4975{ 4976 "jsonrpc": "2.0", 4977 "method": "bdev_virtio_scsi_get_devices", 4978 "id": 1 4979} 4980~~~ 4981 4982Example response: 4983 4984~~~json 4985{ 4986 "jsonrpc": "2.0", 4987 "id": 1, 4988 "result": [ 4989 { 4990 "name": "VirtioScsi0", 4991 "virtio": { 4992 "vq_size": 128, 4993 "vq_count": 4, 4994 "type": "user", 4995 "socket": "/tmp/VhostScsi0" 4996 } 4997 } 4998 ] 4999} 5000~~~ 5001 5002### bdev_virtio_detach_controller {#rpc_bdev_virtio_detach_controller} 5003 5004Remove a Virtio device. This command can be used to remove any type of virtio device. 5005 5006#### Parameters 5007 5008Name | Optional | Type | Description 5009----------------------- | -------- | ----------- | ----------- 5010name | Required | string | Virtio name 5011 5012#### Example 5013 5014Example request: 5015 5016~~~json 5017{ 5018 "params": { 5019 "name": "VirtioUser0" 5020 }, 5021 "jsonrpc": "2.0", 5022 "method": "bdev_virtio_detach_controller", 5023 "id": 1 5024} 5025 5026~~~ 5027 5028Example response: 5029 5030~~~json 5031{ 5032 "jsonrpc": "2.0", 5033 "id": 1, 5034 "result": true 5035} 5036~~~ 5037 5038### bdev_virtio_blk_set_hotplug {#rpc_bdev_virtio_blk_set_hotplug} 5039 5040Enable/Disable the virtio blk hotplug monitor or change the monitor period time 5041 5042#### Parameters 5043 5044Name | Optional | Type | Description 5045----------------------- | -------- | ----------- | ----------- 5046enable | Required | bool | Enable or disable the virtio blk hotplug monitor 5047period-us | Optional | number | The period time of the monitor 5048 5049When the enable is true then the period-us is optional. If user don't set the period time then use the default 5050value. When the enable is false then the period-us is not required. 5051 5052#### Result 5053 5054True the rpc is successful otherwise false 5055 5056#### Example 5057 5058Example request: 5059 5060~~~json 5061{ 5062 "params": { 5063 "enable": "true", 5064 "period-us": "1000000" 5065 }, 5066 "jsonrpc": "2.0", 5067 "method": "bdev_virtio_blk_set_hotplug", 5068 "id": 1 5069} 5070~~~ 5071 5072Example response: 5073 5074~~~json 5075{ 5076 "jsonrpc": "2.0", 5077 "id": 1, 5078 "result": true 5079} 5080~~~ 5081 5082## iSCSI Target {#jsonrpc_components_iscsi_tgt} 5083 5084### iscsi_set_options method {#rpc_iscsi_set_options} 5085 5086Set global parameters for iSCSI targets. 5087 5088This RPC may only be called before SPDK subsystems have been initialized. This RPC can be called only once. 5089 5090#### Parameters 5091 5092Name | Optional | Type | Description 5093------------------------------- | -------- | ------- | ----------- 5094auth_file | Optional | string | Path to CHAP shared secret file (default: "") 5095node_base | Optional | string | Prefix of the name of iSCSI target node (default: "iqn.2016-06.io.spdk") 5096nop_timeout | Optional | number | Timeout in seconds to nop-in request to the initiator (default: 60) 5097nop_in_interval | Optional | number | Time interval in secs between nop-in requests by the target (default: 30) 5098disable_chap | Optional | boolean | CHAP for discovery session should be disabled (default: `false`) 5099require_chap | Optional | boolean | CHAP for discovery session should be required (default: `false`) 5100mutual_chap | Optional | boolean | CHAP for discovery session should be unidirectional (`false`) or bidirectional (`true`) (default: `false`) 5101chap_group | Optional | number | CHAP group ID for discovery session (default: 0) 5102max_sessions | Optional | number | Maximum number of sessions in the host (default: 128) 5103max_queue_depth | Optional | number | Maximum number of outstanding I/Os per queue (default: 64) 5104max_connections_per_session | Optional | number | Session specific parameter, MaxConnections (default: 2) 5105default_time2wait | Optional | number | Session specific parameter, DefaultTime2Wait (default: 2) 5106default_time2retain | Optional | number | Session specific parameter, DefaultTime2Retain (default: 20) 5107first_burst_length | Optional | number | Session specific parameter, FirstBurstLength (default: 8192) 5108immediate_data | Optional | boolean | Session specific parameter, ImmediateData (default: `true`) 5109error_recovery_level | Optional | number | Session specific parameter, ErrorRecoveryLevel (default: 0) 5110allow_duplicated_isid | Optional | boolean | Allow duplicated initiator session ID (default: `false`) 5111max_large_datain_per_connection | Optional | number | Max number of outstanding split read I/Os per connection (default: 64) 5112max_r2t_per_connection | Optional | number | Max number of outstanding R2Ts per connection (default: 4) 5113pdu_pool_size | Optional | number | Number of PDUs in the pool (default: approximately 2 * max_sessions * (max_queue_depth + max_connections_per_session)) 5114immediate_data_pool_size | Optional | number | Number of immediate data buffers in the pool (default: 128 * max_sessions) 5115data_out_pool_size | Optional | number | Number of data out buffers in the pool (default: 16 * max_sessions) 5116 5117To load CHAP shared secret file, its path is required to specify explicitly in the parameter `auth_file`. 5118 5119Parameters `disable_chap` and `require_chap` are mutually exclusive. Parameters `no_discovery_auth`, `req_discovery_auth`, 5120`req_discovery_auth_mutual`, and `discovery_auth_group` are still available instead of `disable_chap`, `require_chap`, 5121`mutual_chap`, and `chap_group`, respectivey but will be removed in future releases. 5122 5123#### Example 5124 5125Example request: 5126 5127~~~json 5128{ 5129 "params": { 5130 "allow_duplicated_isid": true, 5131 "default_time2retain": 60, 5132 "first_burst_length": 8192, 5133 "immediate_data": true, 5134 "node_base": "iqn.2016-06.io.spdk", 5135 "max_sessions": 128, 5136 "nop_timeout": 30, 5137 "nop_in_interval": 30, 5138 "auth_file": "/usr/local/etc/spdk/auth.conf", 5139 "disable_chap": true, 5140 "default_time2wait": 2 5141 }, 5142 "jsonrpc": "2.0", 5143 "method": "iscsi_set_options", 5144 "id": 1 5145} 5146~~~ 5147 5148Example response: 5149 5150~~~json 5151{ 5152 "jsonrpc": "2.0", 5153 "id": 1, 5154 "result": true 5155} 5156~~~ 5157 5158### iscsi_get_options method {#rpc_iscsi_get_options} 5159 5160Show global parameters of iSCSI targets. 5161 5162#### Parameters 5163 5164This method has no parameters. 5165 5166#### Example 5167 5168Example request: 5169 5170~~~json 5171request: 5172{ 5173 "jsonrpc": "2.0", 5174 "method": "iscsi_get_options", 5175 "id": 1 5176} 5177~~~ 5178 5179Example response: 5180 5181~~~json 5182{ 5183 "jsonrpc": "2.0", 5184 "id": 1, 5185 "result": { 5186 "allow_duplicated_isid": true, 5187 "default_time2retain": 60, 5188 "first_burst_length": 8192, 5189 "immediate_data": true, 5190 "node_base": "iqn.2016-06.io.spdk", 5191 "mutual_chap": false, 5192 "nop_in_interval": 30, 5193 "chap_group": 0, 5194 "max_connections_per_session": 2, 5195 "max_queue_depth": 64, 5196 "nop_timeout": 30, 5197 "max_sessions": 128, 5198 "error_recovery_level": 0, 5199 "auth_file": "/usr/local/etc/spdk/auth.conf", 5200 "disable_chap": true, 5201 "default_time2wait": 2, 5202 "require_chap": false, 5203 "max_large_datain_per_connection": 64, 5204 "max_r2t_per_connection": 4 5205 } 5206} 5207~~~ 5208 5209### scsi_get_devices {#rpc_scsi_get_devices} 5210 5211Display SCSI devices 5212 5213#### Parameters 5214 5215This method has no parameters. 5216 5217#### Example 5218 5219Example request: 5220 5221~~~json 5222{ 5223 "jsonrpc": "2.0", 5224 "method": "scsi_get_devices", 5225 "id": 1 5226} 5227~~~ 5228 5229Example response: 5230 5231~~~json 5232{ 5233 "jsonrpc": "2.0", 5234 "id": 1, 5235 "result": [ 5236 { 5237 "id": 0, 5238 "device_name": "iqn.2016-06.io.spdk:Target3" 5239 } 5240 ] 5241} 5242~~~ 5243 5244### iscsi_set_discovery_auth method {#rpc_iscsi_set_discovery_auth} 5245 5246Set CHAP authentication for sessions dynamically. 5247 5248#### Parameters 5249 5250Name | Optional | Type | Description 5251--------------------------- | -------- | --------| ----------- 5252disable_chap | Optional | boolean | CHAP for discovery session should be disabled (default: `false`) 5253require_chap | Optional | boolean | CHAP for discovery session should be required (default: `false`) 5254mutual_chap | Optional | boolean | CHAP for discovery session should be unidirectional (`false`) or bidirectional (`true`) (default: `false`) 5255chap_group | Optional | number | CHAP group ID for discovery session (default: 0) 5256 5257Parameters `disable_chap` and `require_chap` are mutually exclusive. 5258 5259#### Example 5260 5261Example request: 5262 5263~~~json 5264request: 5265{ 5266 "params": { 5267 "chap_group": 1, 5268 "require_chap": true, 5269 "mutual_chap": true 5270 }, 5271 "jsonrpc": "2.0", 5272 "method": "iscsi_set_discovery_auth", 5273 "id": 1 5274} 5275~~~ 5276 5277Example response: 5278 5279~~~json 5280{ 5281 "jsonrpc": "2.0", 5282 "id": 1, 5283 "result": true 5284} 5285~~~ 5286 5287### iscsi_create_auth_group method {#rpc_iscsi_create_auth_group} 5288 5289Create an authentication group for CHAP authentication. 5290 5291#### Parameters 5292 5293Name | Optional | Type | Description 5294--------------------------- | -------- | --------| ----------- 5295tag | Required | number | Authentication group tag (unique, integer > 0) 5296secrets | Optional | array | Array of @ref rpc_iscsi_create_auth_group_secret objects 5297 5298#### secret {#rpc_iscsi_create_auth_group_secret} 5299 5300Name | Optional | Type | Description 5301--------------------------- | ---------| --------| ----------- 5302user | Required | string | Unidirectional CHAP name 5303secret | Required | string | Unidirectional CHAP secret 5304muser | Optional | string | Bidirectional CHAP name 5305msecret | Optional | string | Bidirectional CHAP secret 5306 5307#### Example 5308 5309Example request: 5310 5311~~~json 5312{ 5313 "params": { 5314 "secrets": [ 5315 { 5316 "muser": "mu1", 5317 "secret": "s1", 5318 "user": "u1", 5319 "msecret": "ms1" 5320 } 5321 ], 5322 "tag": 2 5323 }, 5324 "jsonrpc": "2.0", 5325 "method": "iscsi_create_auth_group", 5326 "id": 1 5327} 5328~~~ 5329 5330Example response: 5331 5332~~~json 5333{ 5334 "jsonrpc": "2.0", 5335 "id": 1, 5336 "result": true 5337} 5338~~~ 5339 5340### iscsi_delete_auth_group method {#rpc_iscsi_delete_auth_group} 5341 5342Delete an existing authentication group for CHAP authentication. 5343 5344#### Parameters 5345 5346Name | Optional | Type | Description 5347--------------------------- | -------- | --------| ----------- 5348tag | Required | number | Authentication group tag (unique, integer > 0) 5349 5350#### Example 5351 5352Example request: 5353 5354~~~json 5355{ 5356 "params": { 5357 "tag": 2 5358 }, 5359 "jsonrpc": "2.0", 5360 "method": "iscsi_delete_auth_group", 5361 "id": 1 5362} 5363~~~ 5364 5365Example response: 5366 5367~~~json 5368{ 5369 "jsonrpc": "2.0", 5370 "id": 1, 5371 "result": true 5372} 5373~~~ 5374 5375### iscsi_get_auth_groups {#rpc_iscsi_get_auth_groups} 5376 5377Show information about all existing authentication group for CHAP authentication. 5378 5379#### Parameters 5380 5381This method has no parameters. 5382 5383#### Result 5384 5385Array of objects describing authentication group. 5386 5387Name | Type | Description 5388--------------------------- | --------| ----------- 5389tag | number | Authentication group tag 5390secrets | array | Array of @ref rpc_iscsi_create_auth_group_secret objects 5391 5392#### Example 5393 5394Example request: 5395 5396~~~json 5397{ 5398 "jsonrpc": "2.0", 5399 "method": "iscsi_get_auth_groups", 5400 "id": 1 5401} 5402~~~ 5403 5404Example response: 5405 5406~~~json 5407{ 5408 "jsonrpc": "2.0", 5409 "id": 1, 5410 "result": [ 5411 { 5412 "secrets": [ 5413 { 5414 "muser": "mu1", 5415 "secret": "s1", 5416 "user": "u1", 5417 "msecret": "ms1" 5418 } 5419 ], 5420 "tag": 1 5421 }, 5422 { 5423 "secrets": [ 5424 { 5425 "secret": "s2", 5426 "user": "u2" 5427 } 5428 ], 5429 "tag": 2 5430 } 5431 ] 5432} 5433~~~ 5434 5435### iscsi_auth_group_add_secret {#rpc_iscsi_auth_group_add_secret} 5436 5437Add a secret to an existing authentication group for CHAP authentication. 5438 5439#### Parameters 5440 5441Name | Optional | Type | Description 5442--------------------------- | -------- | --------| ----------- 5443tag | Required | number | Authentication group tag (unique, integer > 0) 5444user | Required | string | Unidirectional CHAP name 5445secret | Required | string | Unidirectional CHAP secret 5446muser | Optional | string | Bidirectional CHAP name 5447msecret | Optional | string | Bidirectional CHAP secret 5448 5449#### Example 5450 5451Example request: 5452 5453~~~json 5454{ 5455 "params": { 5456 "muser": "mu3", 5457 "secret": "s3", 5458 "tag": 2, 5459 "user": "u3", 5460 "msecret": "ms3" 5461 }, 5462 "jsonrpc": "2.0", 5463 "method": "iscsi_auth_group_add_secret", 5464 "id": 1 5465} 5466~~~json 5467 5468Example response: 5469 5470~~~json 5471{ 5472 "jsonrpc": "2.0", 5473 "id": 1, 5474 "result": true 5475} 5476~~~ 5477 5478### iscsi_auth_group_remove_secret {#rpc_iscsi_auth_group_remove_secret} 5479 5480Remove a secret from an existing authentication group for CHAP authentication. 5481 5482#### Parameters 5483 5484Name | Optional | Type | Description 5485--------------------------- | -------- | --------| ----------- 5486tag | Required | number | Authentication group tag (unique, integer > 0) 5487user | Required | string | Unidirectional CHAP name 5488 5489#### Example 5490 5491Example request: 5492 5493~~~json 5494{ 5495 "params": { 5496 "tag": 2, 5497 "user": "u3" 5498 }, 5499 "jsonrpc": "2.0", 5500 "method": "iscsi_auth_group_remove_secret", 5501 "id": 1 5502} 5503~~~ 5504 5505Example response: 5506 5507~~~json 5508{ 5509 "jsonrpc": "2.0", 5510 "id": 1, 5511 "result": true 5512} 5513~~~ 5514 5515### iscsi_get_initiator_groups method {#rpc_iscsi_get_initiator_groups} 5516 5517Show information about all available initiator groups. 5518 5519#### Parameters 5520 5521This method has no parameters. 5522 5523#### Result 5524 5525Array of objects describing initiator groups. 5526 5527Name | Type | Description 5528--------------------------- | --------| ----------- 5529tag | number | Initiator group tag 5530initiators | array | Array of initiator hostnames or IP addresses 5531netmasks | array | Array of initiator netmasks 5532 5533#### Example 5534 5535Example request: 5536 5537~~~json 5538{ 5539 "jsonrpc": "2.0", 5540 "method": "iscsi_get_initiator_groups", 5541 "id": 1 5542} 5543~~~ 5544 5545Example response: 5546 5547~~~json 5548{ 5549 "jsonrpc": "2.0", 5550 "id": 1, 5551 "result": [ 5552 { 5553 "initiators": [ 5554 "iqn.2016-06.io.spdk:host1", 5555 "iqn.2016-06.io.spdk:host2" 5556 ], 5557 "tag": 1, 5558 "netmasks": [ 5559 "192.168.1.0/24" 5560 ] 5561 } 5562 ] 5563} 5564~~~ 5565 5566### iscsi_create_initiator_group method {#rpc_iscsi_create_initiator_group} 5567 5568Add an initiator group. 5569 5570#### Parameters 5571 5572Name | Optional | Type | Description 5573--------------------------- | -------- | --------| ----------- 5574tag | Required | number | Initiator group tag (unique, integer > 0) 5575initiators | Required | array | Not empty array of initiator hostnames or IP addresses 5576netmasks | Required | array | Not empty array of initiator netmasks 5577 5578#### Example 5579 5580Example request: 5581 5582~~~json 5583{ 5584 "params": { 5585 "initiators": [ 5586 "iqn.2016-06.io.spdk:host1", 5587 "iqn.2016-06.io.spdk:host2" 5588 ], 5589 "tag": 1, 5590 "netmasks": [ 5591 "192.168.1.0/24" 5592 ] 5593 }, 5594 "jsonrpc": "2.0", 5595 "method": "iscsi_create_initiator_group", 5596 "id": 1 5597} 5598~~~ 5599 5600Example response: 5601 5602~~~json 5603response: 5604{ 5605 "jsonrpc": "2.0", 5606 "id": 1, 5607 "result": true 5608} 5609~~~ 5610 5611### iscsi_delete_initiator_group method {#rpc_iscsi_delete_initiator_group} 5612 5613Delete an existing initiator group. 5614 5615#### Parameters 5616 5617Name | Optional | Type | Description 5618--------------------------- | -------- | --------| ----------- 5619tag | Required | number | Initiator group tag (unique, integer > 0) 5620 5621#### Example 5622 5623Example request: 5624 5625~~~json 5626{ 5627 "params": { 5628 "tag": 1 5629 }, 5630 "jsonrpc": "2.0", 5631 "method": "iscsi_delete_initiator_group", 5632 "id": 1 5633} 5634~~~ 5635 5636Example response: 5637 5638~~~json 5639{ 5640 "jsonrpc": "2.0", 5641 "id": 1, 5642 "result": true 5643} 5644~~~ 5645 5646### iscsi_initiator_group_add_initiators method {#rpc_iscsi_initiator_group_add_initiators} 5647 5648Add initiators to an existing initiator group. 5649 5650#### Parameters 5651 5652Name | Optional | Type | Description 5653--------------------------- | -------- | --------| ----------- 5654tag | Required | number | Existing initiator group tag. 5655initiators | Optional | array | Array of initiator hostnames or IP addresses 5656netmasks | Optional | array | Array of initiator netmasks 5657 5658#### Example 5659 5660Example request: 5661 5662~~~json 5663request: 5664{ 5665 "params": { 5666 "initiators": [ 5667 "iqn.2016-06.io.spdk:host3" 5668 ], 5669 "tag": 1, 5670 "netmasks": [ 5671 "255.255.255.1" 5672 ] 5673 }, 5674 "jsonrpc": "2.0", 5675 "method": "iscsi_initiator_group_add_initiators", 5676 "id": 1 5677} 5678~~~ 5679 5680Example response: 5681 5682~~~json 5683response: 5684{ 5685 "jsonrpc": "2.0", 5686 "id": 1, 5687 "result": true 5688} 5689~~~ 5690 5691### iscsi_initiator_group_remove_initiators method {#rpc_iscsi_initiator_group_remove_initiators} 5692 5693Remove initiators from an initiator group. 5694 5695#### Parameters 5696 5697Name | Optional | Type | Description 5698--------------------------- | -------- | --------| ----------- 5699tag | Required | number | Existing initiator group tag. 5700initiators | Optional | array | Array of initiator hostnames or IP addresses 5701netmasks | Optional | array | Array of initiator netmasks 5702 5703#### Example 5704 5705Example request: 5706 5707~~~json 5708request: 5709{ 5710 "params": { 5711 "initiators": [ 5712 "iqn.2016-06.io.spdk:host3" 5713 ], 5714 "tag": 1, 5715 "netmasks": [ 5716 "255.255.255.1" 5717 ] 5718 }, 5719 "jsonrpc": "2.0", 5720 "method": "iscsi_initiator_group_remove_initiators", 5721 "id": 1 5722} 5723~~~ 5724 5725Example response: 5726 5727~~~json 5728response: 5729{ 5730 "jsonrpc": "2.0", 5731 "id": 1, 5732 "result": true 5733} 5734~~~ 5735 5736### iscsi_get_target_nodes method {#rpc_iscsi_get_target_nodes} 5737 5738Show information about all available iSCSI target nodes. 5739 5740#### Parameters 5741 5742This method has no parameters. 5743 5744#### Result 5745 5746Array of objects describing target node. 5747 5748Name | Type | Description 5749--------------------------- | --------| ----------- 5750name | string | Target node name (ASCII) 5751alias_name | string | Target node alias name (ASCII) 5752pg_ig_maps | array | Array of Portal_Group_Tag:Initiator_Group_Tag mappings 5753luns | array | Array of Bdev names to LUN ID mappings 5754queue_depth | number | Target queue depth 5755disable_chap | boolean | CHAP authentication should be disabled for this target 5756require_chap | boolean | CHAP authentication should be required for this target 5757mutual_chap | boolean | CHAP authentication should be bidirectional (`true`) or unidirectional (`false`) 5758chap_group | number | Authentication group ID for this target node 5759header_digest | boolean | Header Digest should be required for this target node 5760data_digest | boolean | Data Digest should be required for this target node 5761 5762#### Example 5763 5764Example request: 5765 5766~~~json 5767{ 5768 "jsonrpc": "2.0", 5769 "method": "iscsi_get_target_nodes", 5770 "id": 1 5771} 5772~~~ 5773 5774Example response: 5775 5776~~~json 5777{ 5778 "jsonrpc": "2.0", 5779 "id": 1, 5780 "result": [ 5781 { 5782 "luns": [ 5783 { 5784 "lun_id": 0, 5785 "bdev_name": "Nvme0n1" 5786 } 5787 ], 5788 "mutual_chap": false, 5789 "name": "iqn.2016-06.io.spdk:target1", 5790 "alias_name": "iscsi-target1-alias", 5791 "require_chap": false, 5792 "chap_group": 0, 5793 "pg_ig_maps": [ 5794 { 5795 "ig_tag": 1, 5796 "pg_tag": 1 5797 } 5798 ], 5799 "data_digest": false, 5800 "disable_chap": false, 5801 "header_digest": false, 5802 "queue_depth": 64 5803 } 5804 ] 5805} 5806~~~ 5807 5808### iscsi_create_target_node method {#rpc_iscsi_create_target_node} 5809 5810Add an iSCSI target node. 5811 5812#### Parameters 5813 5814Name | Optional | Type | Description 5815--------------------------- | -------- | --------| ----------- 5816name | Required | string | Target node name (ASCII) 5817alias_name | Required | string | Target node alias name (ASCII) 5818pg_ig_maps | Required | array | Array of (Portal_Group_Tag:Initiator_Group_Tag) mappings 5819luns | Required | array | Array of Bdev names to LUN ID mappings 5820queue_depth | Required | number | Target queue depth 5821disable_chap | Optional | boolean | CHAP authentication should be disabled for this target 5822require_chap | Optional | boolean | CHAP authentication should be required for this target 5823mutual_chap | Optional | boolean | CHAP authentication should be bidirectional (`true`) or unidirectional (`false`) 5824chap_group | Optional | number | Authentication group ID for this target node 5825header_digest | Optional | boolean | Header Digest should be required for this target node 5826data_digest | Optional | boolean | Data Digest should be required for this target node 5827 5828Parameters `disable_chap` and `require_chap` are mutually exclusive. 5829 5830#### Example 5831 5832Example request: 5833 5834~~~json 5835{ 5836 "params": { 5837 "luns": [ 5838 { 5839 "lun_id": 0, 5840 "bdev_name": "Nvme0n1" 5841 } 5842 ], 5843 "mutual_chap": true, 5844 "name": "target2", 5845 "alias_name": "iscsi-target2-alias", 5846 "pg_ig_maps": [ 5847 { 5848 "ig_tag": 1, 5849 "pg_tag": 1 5850 }, 5851 { 5852 "ig_tag": 2, 5853 "pg_tag": 2 5854 } 5855 ], 5856 "data_digest": true, 5857 "disable_chap": true, 5858 "header_digest": true, 5859 "queue_depth": 24 5860 }, 5861 "jsonrpc": "2.0", 5862 "method": "iscsi_create_target_node", 5863 "id": 1 5864} 5865~~~ 5866 5867Example response: 5868 5869~~~json 5870{ 5871 "jsonrpc": "2.0", 5872 "id": 1, 5873 "result": true 5874} 5875~~~ 5876 5877### iscsi_target_node_set_auth method {#rpc_iscsi_target_node_set_auth} 5878 5879Set CHAP authentication to an existing iSCSI target node. 5880 5881#### Parameters 5882 5883Name | Optional | Type | Description 5884--------------------------- | -------- | --------| ----------- 5885name | Required | string | Target node name (ASCII) 5886disable_chap | Optional | boolean | CHAP authentication should be disabled for this target 5887require_chap | Optional | boolean | CHAP authentication should be required for this target 5888mutual_chap | Optional | boolean | CHAP authentication should be bidirectional (`true`) or unidirectional (`false`) 5889chap_group | Optional | number | Authentication group ID for this target node 5890 5891Parameters `disable_chap` and `require_chap` are mutually exclusive. 5892 5893#### Example 5894 5895Example request: 5896 5897~~~json 5898{ 5899 "params": { 5900 "chap_group": 1, 5901 "require_chap": true, 5902 "name": "iqn.2016-06.io.spdk:target1", 5903 "mutual_chap": true 5904 }, 5905 "jsonrpc": "2.0", 5906 "method": "iscsi_target_node_set_auth", 5907 "id": 1 5908} 5909~~~ 5910 5911Example response: 5912 5913~~~json 5914{ 5915 "jsonrpc": "2.0", 5916 "id": 1, 5917 "result": true 5918} 5919~~~ 5920 5921### iscsi_target_node_add_pg_ig_maps method {#rpc_iscsi_target_node_add_pg_ig_maps} 5922 5923Add initiator group to portal group mappings to an existing iSCSI target node. 5924 5925#### Parameters 5926 5927Name | Optional | Type | Description 5928--------------------------- | -------- | --------| ----------- 5929name | Required | string | Target node name (ASCII) 5930pg_ig_maps | Required | array | Not empty array of initiator to portal group mappings objects 5931 5932Portal to Initiator group mappings object: 5933 5934Name | Optional | Type | Description 5935--------------------------- | -------- | --------| ----------- 5936ig_tag | Required | number | Existing initiator group tag 5937pg_tag | Required | number | Existing portal group tag 5938 5939#### Example 5940 5941Example request: 5942 5943~~~json 5944{ 5945 "params": { 5946 "pg_ig_maps": [ 5947 { 5948 "ig_tag": 1, 5949 "pg_tag": 1 5950 }, 5951 { 5952 "ig_tag": 2, 5953 "pg_tag": 2 5954 }, 5955 { 5956 "ig_tag": 3, 5957 "pg_tag": 3 5958 } 5959 ], 5960 "name": "iqn.2016-06.io.spdk:target3" 5961 }, 5962 "jsonrpc": "2.0", 5963 "method": "iscsi_target_node_add_pg_ig_maps", 5964 "id": 1 5965} 5966~~~ 5967 5968Example response: 5969 5970~~~json 5971{ 5972 "jsonrpc": "2.0", 5973 "id": 1, 5974 "result": true 5975} 5976~~~ 5977 5978### iscsi_target_node_remove_pg_ig_maps method {#rpc_iscsi_target_node_remove_pg_ig_maps} 5979 5980Delete initiator group to portal group mappings from an existing iSCSI target node. 5981 5982#### Parameters 5983 5984Name | Optional | Type | Description 5985--------------------------- | -------- | --------| ----------- 5986name | Required | string | Target node name (ASCII) 5987pg_ig_maps | Required | array | Not empty array of Portal to Initiator group mappings objects 5988 5989Portal to Initiator group mappings object: 5990 5991Name | Optional | Type | Description 5992--------------------------- | -------- | --------| ----------- 5993ig_tag | Required | number | Existing initiator group tag 5994pg_tag | Required | number | Existing portal group tag 5995 5996#### Example 5997 5998Example request: 5999 6000~~~json 6001{ 6002 "params": { 6003 "pg_ig_maps": [ 6004 { 6005 "ig_tag": 1, 6006 "pg_tag": 1 6007 }, 6008 { 6009 "ig_tag": 2, 6010 "pg_tag": 2 6011 }, 6012 { 6013 "ig_tag": 3, 6014 "pg_tag": 3 6015 } 6016 ], 6017 "name": "iqn.2016-06.io.spdk:target3" 6018 }, 6019 "jsonrpc": "2.0", 6020 "method": "iscsi_target_node_remove_pg_ig_maps", 6021 "id": 1 6022} 6023~~~ 6024 6025Example response: 6026 6027~~~json 6028{ 6029 "jsonrpc": "2.0", 6030 "id": 1, 6031 "result": true 6032} 6033~~~ 6034 6035### iscsi_delete_target_node method {#rpc_iscsi_delete_target_node} 6036 6037Delete an iSCSI target node. 6038 6039#### Parameters 6040 6041Name | Optional | Type | Description 6042--------------------------- | -------- | --------| ----------- 6043name | Required | string | Target node name (ASCII) 6044 6045#### Example 6046 6047Example request: 6048 6049~~~json 6050{ 6051 "params": { 6052 "name": "iqn.2016-06.io.spdk:target1" 6053 }, 6054 "jsonrpc": "2.0", 6055 "method": "iscsi_delete_target_node", 6056 "id": 1 6057} 6058~~~ 6059 6060Example response: 6061 6062~~~json 6063{ 6064 "jsonrpc": "2.0", 6065 "id": 1, 6066 "result": true 6067} 6068~~~ 6069 6070### iscsi_get_portal_groups method {#rpc_iscsi_get_portal_groups} 6071 6072Show information about all available portal groups. 6073 6074#### Parameters 6075 6076This method has no parameters. 6077 6078#### Example 6079 6080Example request: 6081 6082~~~json 6083request: 6084{ 6085 "jsonrpc": "2.0", 6086 "method": "iscsi_get_portal_groups", 6087 "id": 1 6088} 6089~~~ 6090 6091Example response: 6092 6093~~~json 6094{ 6095 "jsonrpc": "2.0", 6096 "id": 1, 6097 "result": [ 6098 { 6099 "portals": [ 6100 { 6101 "host": "127.0.0.1", 6102 "port": "3260" 6103 } 6104 ], 6105 "tag": 1, 6106 "private": false 6107 } 6108 ] 6109} 6110~~~ 6111 6112### iscsi_create_portal_group method {#rpc_iscsi_create_portal_group} 6113 6114Add a portal group. 6115 6116#### Parameters 6117 6118Name | Optional | Type | Description 6119--------------------------- | -------- | --------| ----------- 6120tag | Required | number | Portal group tag 6121portals | Required | array | Not empty array of portals 6122private | Optional | boolean | When true, portals in this group are not returned by a discovery session. Used for login redirection. (default: `false`) 6123wait | Optional | boolean | When true, do not listen on portals until it is started explicitly. (default: `false`) 6124 6125Portal object 6126 6127Name | Optional | Type | Description 6128--------------------------- | -------- | --------| ----------- 6129host | Required | string | Hostname or IP address 6130port | Required | string | Port number 6131 6132#### Example 6133 6134Example request: 6135 6136~~~json 6137{ 6138 "params": { 6139 "portals": [ 6140 { 6141 "host": "127.0.0.1", 6142 "port": "3260" 6143 } 6144 ], 6145 "tag": 1 6146 }, 6147 "jsonrpc": "2.0", 6148 "method": "iscsi_create_portal_group", 6149 "id": 1 6150} 6151~~~ 6152 6153Example response: 6154 6155~~~json 6156{ 6157 "jsonrpc": "2.0", 6158 "id": 1, 6159 "result": true 6160} 6161~~~ 6162 6163### iscsi_start_portal_group method {#rpc_iscsi_start_portal_group} 6164 6165Start listening on portals if the portal group is not started yet, or do nothing 6166if the portal group already started. Return a success response for both cases. 6167 6168#### Parameters 6169 6170Name | Optional | Type | Description 6171--------------------------- | -------- | --------| ----------- 6172tag | Required | number | Existing portal group tag 6173 6174#### Example 6175 6176Example request: 6177 6178~~~json 6179{ 6180 "params": { 6181 "tag": 1 6182 }, 6183 "jsonrpc": "2.0", 6184 "method": "iscsi_start_portal_group", 6185 "id": 1 6186} 6187~~~ 6188 6189Example response: 6190 6191~~~json 6192{ 6193 "jsonrpc": "2.0", 6194 "id": 1, 6195 "result": true 6196} 6197~~~ 6198 6199### iscsi_delete_portal_group method {#rpc_iscsi_delete_portal_group} 6200 6201Delete an existing portal group. 6202 6203#### Parameters 6204 6205Name | Optional | Type | Description 6206--------------------------- | -------- | --------| ----------- 6207tag | Required | number | Existing portal group tag 6208 6209#### Example 6210 6211Example request: 6212 6213~~~json 6214{ 6215 "params": { 6216 "tag": 1 6217 }, 6218 "jsonrpc": "2.0", 6219 "method": "iscsi_delete_portal_group", 6220 "id": 1 6221} 6222~~~ 6223 6224Example response: 6225 6226~~~json 6227{ 6228 "jsonrpc": "2.0", 6229 "id": 1, 6230 "result": true 6231} 6232~~~ 6233 6234### iscsi_portal_group_set_auth method {#rpc_iscsi_portal_group_set_auth} 6235 6236Set CHAP authentication for discovery sessions specific for the existing iSCSI portal group. 6237This RPC overwrites the setting by the global parameters for the iSCSI portal group. 6238 6239#### Parameters 6240 6241Name | Optional | Type | Description 6242--------------------------- | -------- | --------| ----------- 6243disable_chap | Optional | boolean | CHAP for discovery session should be disabled (default: `false`) 6244require_chap | Optional | boolean | CHAP for discovery session should be required (default: `false`) 6245mutual_chap | Optional | boolean | CHAP for discovery session should be unidirectional (`false`) or bidirectional (`true`) (default: `false`) 6246chap_group | Optional | number | CHAP group ID for discovery session (default: 0) 6247 6248Parameters `disable_chap` and `require_chap` are mutually exclusive. 6249 6250#### Example 6251 6252Example request: 6253 6254~~~json 6255request: 6256{ 6257 "params": { 6258 "tag": 1, 6259 "chap_group": 1, 6260 "require_chap": true, 6261 "mutual_chap": true 6262 }, 6263 "jsonrpc": "2.0", 6264 "method": "iscsi_portal_group_set_auth", 6265 "id": 1 6266} 6267~~~ 6268 6269Example response: 6270 6271~~~json 6272{ 6273 "jsonrpc": "2.0", 6274 "id": 1, 6275 "result": true 6276} 6277~~~ 6278 6279### iscsi_get_connections method {#rpc_iscsi_get_connections} 6280 6281Show information about all active connections. 6282 6283#### Parameters 6284 6285This method has no parameters. 6286 6287#### Results 6288 6289Array of objects describing iSCSI connection. 6290 6291Name | Type | Description 6292--------------------------- | --------| ----------- 6293id | number | Index (used for TTT - Target Transfer Tag) 6294cid | number | CID (Connection ID) 6295tsih | number | TSIH (Target Session Identifying Handle) 6296lcore_id | number | Core number on which the iSCSI connection runs 6297initiator_addr | string | Initiator address 6298target_addr | string | Target address 6299target_node_name | string | Target node name (ASCII) without prefix 6300 6301#### Example 6302 6303Example request: 6304 6305~~~json 6306{ 6307 "jsonrpc": "2.0", 6308 "method": "iscsi_get_connections", 6309 "id": 1 6310} 6311~~~ 6312 6313Example response: 6314 6315~~~json 6316{ 6317 "jsonrpc": "2.0", 6318 "id": 1, 6319 "result": [ 6320 { 6321 "tsih": 4, 6322 "cid": 0, 6323 "target_node_name": "target1", 6324 "lcore_id": 0, 6325 "initiator_addr": "10.0.0.2", 6326 "target_addr": "10.0.0.1", 6327 "id": 0 6328 } 6329 ] 6330} 6331~~~ 6332 6333### iscsi_target_node_add_lun method {#rpc_iscsi_target_node_add_lun} 6334 6335Add an LUN to an existing iSCSI target node. 6336 6337#### Parameters 6338 6339Name | Optional | Type | Description 6340--------------------------- | -------- | --------| ----------- 6341name | Required | string | Target node name (ASCII) 6342bdev_name | Required | string | bdev name to be added as a LUN 6343lun_id | Optional | number | LUN ID (default: first free ID) 6344 6345#### Example 6346 6347Example request: 6348 6349~~~json 6350{ 6351 "params": { 6352 "lun_id": 2, 6353 "name": "iqn.2016-06.io.spdk:target1", 6354 "bdev_name": "Malloc0" 6355 }, 6356 "jsonrpc": "2.0", 6357 "method": "iscsi_target_node_add_lun", 6358 "id": 1 6359} 6360~~~ 6361 6362Example response: 6363 6364~~~json 6365{ 6366 "jsonrpc": "2.0", 6367 "id": 1, 6368 "result": true 6369} 6370~~~ 6371 6372### iscsi_target_node_set_redirect method {#rpc_iscsi_target_node_set_redirect} 6373 6374Update redirect portal of the primary portal group for the target node, 6375 6376#### Parameters 6377 6378Name | Optional | Type | Description 6379--------------------------- | -------- | --------| ----------- 6380name | Required | string | Target node name (ASCII) 6381pg_tag | Required | number | Existing portal group tag 6382redirect_host | Optional | string | Numeric IP address to which the target node is redirected 6383redirect_port | Optional | string | Numeric TCP port to which the target node is redirected 6384 6385If both redirect_host and redirect_port are omitted, clear the redirect portal. 6386 6387#### Example 6388 6389Example request: 6390 6391~~~json 6392{ 6393 "params": { 6394 "name": "iqn.2016-06.io.spdk:target1", 6395 "pg_tag": 1, 6396 "redirect_host": "10.0.0.3", 6397 "redirect_port": "3260" 6398 }, 6399 "jsonrpc": "2.0", 6400 "method": "iscsi_target_node_set_redirect", 6401 "id": 1 6402} 6403~~~ 6404 6405Example response: 6406 6407~~~json 6408{ 6409 "jsonrpc": "2.0", 6410 "id": 1, 6411 "result": true 6412} 6413~~~ 6414 6415### iscsi_target_node_request_logout method {#rpc_iscsi_target_node_request_logout} 6416 6417For the target node, request connections whose portal group tag match to logout, 6418or request all connections to logout if portal group tag is omitted. 6419 6420#### Parameters 6421 6422Name | Optional | Type | Description 6423--------------------------- | -------- | --------| ----------- 6424name | Required | string | Target node name (ASCII) 6425pg_tag | Optional | number | Existing portal group tag 6426 6427#### Example 6428 6429Example request: 6430 6431~~~json 6432{ 6433 "params": { 6434 "name": "iqn.2016-06.io.spdk:target1", 6435 "pg_tag": 1 6436 }, 6437 "jsonrpc": "2.0", 6438 "method": "iscsi_target_node_request_logout", 6439 "id": 1 6440} 6441~~~ 6442 6443Example response: 6444 6445~~~json 6446{ 6447 "jsonrpc": "2.0", 6448 "id": 1, 6449 "result": true 6450} 6451~~~ 6452 6453## NVMe-oF Target {#jsonrpc_components_nvmf_tgt} 6454 6455### nvmf_create_transport method {#rpc_nvmf_create_transport} 6456 6457Initialize an NVMe-oF transport with the given options. 6458 6459#### Parameters 6460 6461Name | Optional | Type | Description 6462--------------------------- | -------- | --------| ----------- 6463trtype | Required | string | Transport type (ex. RDMA) 6464tgt_name | Optional | string | Parent NVMe-oF target name. 6465max_queue_depth | Optional | number | Max number of outstanding I/O per queue 6466max_io_qpairs_per_ctrlr | Optional | number | Max number of IO qpairs per controller 6467in_capsule_data_size | Optional | number | Max number of in-capsule data size 6468max_io_size | Optional | number | Max I/O size (bytes) 6469io_unit_size | Optional | number | I/O unit size (bytes) 6470max_aq_depth | Optional | number | Max number of admin cmds per AQ 6471num_shared_buffers | Optional | number | The number of pooled data buffers available to the transport 6472buf_cache_size | Optional | number | The number of shared buffers to reserve for each poll group 6473num_cqe | Optional | number | The number of CQ entires. Only used when no_srq=true (RDMA only) 6474max_srq_depth | Optional | number | The number of elements in a per-thread shared receive queue (RDMA only) 6475no_srq | Optional | boolean | Disable shared receive queue even for devices that support it. (RDMA only) 6476c2h_success | Optional | boolean | Disable C2H success optimization (TCP only) 6477dif_insert_or_strip | Optional | boolean | Enable DIF insert for write I/O and DIF strip for read I/O DIF 6478sock_priority | Optional | number | The socket priority of the connection owned by this transport (TCP only) 6479acceptor_backlog | Optional | number | The number of pending connections allowed in backlog before failing new connection attempts (RDMA only) 6480abort_timeout_sec | Optional | number | Abort execution timeout value, in seconds 6481no_wr_batching | Optional | boolean | Disable work requests batching (RDMA only) 6482control_msg_num | Optional | number | The number of control messages per poll group (TCP only) 6483disable_mappable_bar0 | Optional | boolean | disable client mmap() of BAR0 (VFIO-USER only) 6484disable_adaptive_irq | Optional | boolean | Disable adaptive interrupt feature (VFIO-USER only) 6485disable_shadow_doorbells | Optional | boolean | disable shadow doorbell support (VFIO-USER only) 6486zcopy | Optional | boolean | Use zero-copy operations if the underlying bdev supports them 6487 6488#### Example 6489 6490Example request: 6491 6492~~~json 6493{ 6494 "jsonrpc": "2.0", 6495 "method": "nvmf_create_transport", 6496 "id": 1, 6497 "params": { 6498 "trtype": "RDMA", 6499 "max_queue_depth": 32 6500 } 6501} 6502~~~ 6503 6504Example response: 6505 6506~~~json 6507{ 6508 "jsonrpc": "2.0", 6509 "id": 1, 6510 "result": true 6511} 6512~~~ 6513 6514### nvmf_get_subsystems method {#rpc_nvmf_get_subsystems} 6515 6516#### Parameters 6517 6518Name | Optional | Type | Description 6519--------------------------- | -------- | ------------| ----------- 6520tgt_name | Optional | string | Parent NVMe-oF target name. 6521 6522#### Example 6523 6524Example request: 6525 6526~~~json 6527{ 6528 "jsonrpc": "2.0", 6529 "id": 1, 6530 "method": "nvmf_get_subsystems" 6531} 6532~~~ 6533 6534Example response: 6535 6536~~~json 6537{ 6538 "jsonrpc": "2.0", 6539 "id": 1, 6540 "result": [ 6541 { 6542 "nqn": "nqn.2014-08.org.nvmexpress.discovery", 6543 "subtype": "Discovery" 6544 "listen_addresses": [], 6545 "hosts": [], 6546 "allow_any_host": true 6547 }, 6548 { 6549 "nqn": "nqn.2016-06.io.spdk:cnode1", 6550 "subtype": "NVMe", 6551 "listen_addresses": [ 6552 { 6553 "trtype": "RDMA", 6554 "adrfam": "IPv4", 6555 "traddr": "192.168.0.123", 6556 "trsvcid": "4420" 6557 } 6558 ], 6559 "hosts": [ 6560 {"nqn": "nqn.2016-06.io.spdk:host1"} 6561 ], 6562 "allow_any_host": false, 6563 "serial_number": "abcdef", 6564 "model_number": "ghijklmnop", 6565 "namespaces": [ 6566 {"nsid": 1, "name": "Malloc2"}, 6567 {"nsid": 2, "name": "Nvme0n1"} 6568 ] 6569 } 6570 ] 6571} 6572~~~ 6573 6574### nvmf_create_subsystem method {#rpc_nvmf_create_subsystem} 6575 6576Construct an NVMe over Fabrics target subsystem. 6577 6578#### Parameters 6579 6580Name | Optional | Type | Description 6581----------------------- | -------- | ----------- | ----------- 6582nqn | Required | string | Subsystem NQN 6583tgt_name | Optional | string | Parent NVMe-oF target name. 6584serial_number | Optional | string | Serial number of virtual controller 6585model_number | Optional | string | Model number of virtual controller 6586max_namespaces | Optional | number | Maximum number of namespaces that can be attached to the subsystem. Default: 0 (Unlimited) 6587allow_any_host | Optional | boolean | Allow any host (`true`) or enforce allowed host list (`false`). Default: `false`. 6588ana_reporting | Optional | boolean | Enable ANA reporting feature (default: `false`). 6589min_cntlid | Optional | number | Minimum controller ID. Default: 1 6590max_cntlid | Optional | number | Maximum controller ID. Default: 0xffef 6591 6592#### Example 6593 6594Example request: 6595 6596~~~json 6597{ 6598 "jsonrpc": "2.0", 6599 "id": 1, 6600 "method": "nvmf_create_subsystem", 6601 "params": { 6602 "nqn": "nqn.2016-06.io.spdk:cnode1", 6603 "allow_any_host": false, 6604 "serial_number": "abcdef", 6605 "model_number": "ghijklmnop" 6606 } 6607} 6608~~~ 6609 6610Example response: 6611 6612~~~json 6613{ 6614 "jsonrpc": "2.0", 6615 "id": 1, 6616 "result": true 6617} 6618~~~ 6619 6620### nvmf_delete_subsystem method {#rpc_nvmf_delete_subsystem} 6621 6622Delete an existing NVMe-oF subsystem. 6623 6624#### Parameters 6625 6626Parameter | Optional | Type | Description 6627---------------------- | -------- | ----------- | ----------- 6628nqn | Required | string | Subsystem NQN to delete. 6629tgt_name | Optional | string | Parent NVMe-oF target name. 6630 6631#### Example 6632 6633Example request: 6634 6635~~~json 6636{ 6637 "jsonrpc": "2.0", 6638 "id": 1, 6639 "method": "nvmf_delete_subsystem", 6640 "params": { 6641 "nqn": "nqn.2016-06.io.spdk:cnode1" 6642 } 6643} 6644~~~ 6645 6646Example response: 6647 6648~~~json 6649{ 6650 "jsonrpc": "2.0", 6651 "id": 1, 6652 "result": true 6653} 6654~~~ 6655 6656### nvmf_subsystem_add_listener method {#rpc_nvmf_subsystem_add_listener} 6657 6658Add a new listen address to an NVMe-oF subsystem. 6659 6660#### Parameters 6661 6662Name | Optional | Type | Description 6663----------------------- | -------- | ----------- | ----------- 6664nqn | Required | string | Subsystem NQN 6665tgt_name | Optional | string | Parent NVMe-oF target name. 6666listen_address | Required | object | @ref rpc_nvmf_listen_address object 6667 6668#### listen_address {#rpc_nvmf_listen_address} 6669 6670Name | Optional | Type | Description 6671----------------------- | -------- | ----------- | ----------- 6672trtype | Required | string | Transport type ("RDMA") 6673adrfam | Required | string | Address family ("IPv4", "IPv6", "IB", or "FC") 6674traddr | Required | string | Transport address 6675trsvcid | Optional | string | Transport service ID (required for RDMA or TCP) 6676 6677#### Example 6678 6679Example request: 6680 6681~~~json 6682{ 6683 "jsonrpc": "2.0", 6684 "id": 1, 6685 "method": "nvmf_subsystem_add_listener", 6686 "params": { 6687 "nqn": "nqn.2016-06.io.spdk:cnode1", 6688 "listen_address": { 6689 "trtype": "RDMA", 6690 "adrfam": "IPv4", 6691 "traddr": "192.168.0.123", 6692 "trsvcid": "4420" 6693 } 6694 } 6695} 6696~~~ 6697 6698Example response: 6699 6700~~~json 6701{ 6702 "jsonrpc": "2.0", 6703 "id": 1, 6704 "result": true 6705} 6706~~~ 6707 6708### nvmf_subsystem_remove_listener method {#rpc_nvmf_subsystem_remove_listener} 6709 6710Remove a listen address from an NVMe-oF subsystem. 6711 6712#### Parameters 6713 6714Name | Optional | Type | Description 6715----------------------- | -------- | ----------- | ----------- 6716nqn | Required | string | Subsystem NQN 6717tgt_name | Optional | string | Parent NVMe-oF target name. 6718listen_address | Required | object | @ref rpc_nvmf_listen_address object 6719 6720#### Example 6721 6722Example request: 6723 6724~~~json 6725{ 6726 "jsonrpc": "2.0", 6727 "id": 1, 6728 "method": "nvmf_subsystem_remove_listener", 6729 "params": { 6730 "nqn": "nqn.2016-06.io.spdk:cnode1", 6731 "listen_address": { 6732 "trtype": "RDMA", 6733 "adrfam": "IPv4", 6734 "traddr": "192.168.0.123", 6735 "trsvcid": "4420" 6736 } 6737 } 6738} 6739~~~ 6740 6741Example response: 6742 6743~~~json 6744{ 6745 "jsonrpc": "2.0", 6746 "id": 1, 6747 "result": true 6748} 6749~~~ 6750 6751### nvmf_subsystem_listener_set_ana_state method {#rpc_nvmf_subsystem_listener_set_ana_state} 6752 6753Set ANA state of a listener for an NVMe-oF subsystem. Only the ANA state of the specified ANA 6754group is updated, or ANA states of all ANA groups if ANA group is not specified. 6755 6756#### Parameters 6757 6758Name | Optional | Type | Description 6759----------------------- | -------- | ----------- | ----------- 6760nqn | Required | string | Subsystem NQN 6761tgt_name | Optional | string | Parent NVMe-oF target name. 6762listen_address | Required | object | @ref rpc_nvmf_listen_address object 6763ana_state | Required | string | ANA state to set ("optimized", "non_optimized", or "inaccessible") 6764anagrpid | Optional | number | ANA group ID 6765 6766#### Example 6767 6768Example request: 6769 6770~~~json 6771{ 6772 "jsonrpc": "2.0", 6773 "id": 1, 6774 "method": "nvmf_subsystem_listener_set_ana_state", 6775 "params": { 6776 "nqn": "nqn.2016-06.io.spdk:cnode1", 6777 "listen_address": { 6778 "trtype": "RDMA", 6779 "adrfam": "IPv4", 6780 "traddr": "192.168.0.123", 6781 "trsvcid": "4420" 6782 }, 6783 "ana_state", "inaccessible" 6784 } 6785} 6786~~~ 6787 6788Example response: 6789 6790~~~json 6791{ 6792 "jsonrpc": "2.0", 6793 "id": 1, 6794 "result": true 6795} 6796~~~ 6797 6798### nvmf_subsystem_add_ns method {#rpc_nvmf_subsystem_add_ns} 6799 6800Add a namespace to a subsystem. The namespace ID is returned as the result. 6801 6802### Parameters 6803 6804Name | Optional | Type | Description 6805----------------------- | -------- | ----------- | ----------- 6806nqn | Required | string | Subsystem NQN 6807namespace | Required | object | @ref rpc_nvmf_namespace object 6808tgt_name | Optional | string | Parent NVMe-oF target name. 6809 6810#### namespace {#rpc_nvmf_namespace} 6811 6812Name | Optional | Type | Description 6813----------------------- | -------- | ----------- | ----------- 6814nsid | Optional | number | Namespace ID between 1 and 4294967294, inclusive. Default: Automatically assign NSID. 6815bdev_name | Required | string | Name of bdev to expose as a namespace. 6816nguid | Optional | string | 16-byte namespace globally unique identifier in hexadecimal (e.g. "ABCDEF0123456789ABCDEF0123456789") 6817eui64 | Optional | string | 8-byte namespace EUI-64 in hexadecimal (e.g. "ABCDEF0123456789") 6818uuid | Optional | string | RFC 4122 UUID (e.g. "ceccf520-691e-4b46-9546-34af789907c5") 6819ptpl_file | Optional | string | File path to save/restore persistent reservation information 6820anagrpid | Optional | number | ANA group ID. Default: Namespace ID. 6821 6822#### Example 6823 6824Example request: 6825 6826~~~json 6827{ 6828 "jsonrpc": "2.0", 6829 "id": 1, 6830 "method": "nvmf_subsystem_add_ns", 6831 "params": { 6832 "nqn": "nqn.2016-06.io.spdk:cnode1", 6833 "namespace": { 6834 "nsid": 3, 6835 "bdev_name": "Nvme0n1", 6836 "ptpl_file": "/opt/Nvme0n1PR.json" 6837 } 6838 } 6839} 6840~~~ 6841 6842Example response: 6843 6844~~~json 6845{ 6846 "jsonrpc": "2.0", 6847 "id": 1, 6848 "result": 3 6849} 6850~~~ 6851 6852### nvmf_subsystem_remove_ns method {#rpc_nvmf_subsystem_remove_ns} 6853 6854Remove a namespace from a subsystem. 6855 6856#### Parameters 6857 6858Name | Optional | Type | Description 6859----------------------- | -------- | ----------- | ----------- 6860nqn | Required | string | Subsystem NQN 6861nsid | Required | number | Namespace ID 6862tgt_name | Optional | string | Parent NVMe-oF target name. 6863 6864#### Example 6865 6866Example request: 6867 6868~~~json 6869{ 6870 "jsonrpc": "2.0", 6871 "id": 1, 6872 "method": "nvmf_subsystem_remove_ns", 6873 "params": { 6874 "nqn": "nqn.2016-06.io.spdk:cnode1", 6875 "nsid": 1 6876 } 6877} 6878~~~ 6879 6880Example response: 6881 6882~~~json 6883{ 6884 "jsonrpc": "2.0", 6885 "id": 1, 6886 "result": true 6887} 6888~~~ 6889 6890### nvmf_subsystem_add_host method {#rpc_nvmf_subsystem_add_host} 6891 6892Add a host NQN to the list of allowed hosts. 6893 6894#### Parameters 6895 6896Name | Optional | Type | Description 6897----------------------- | -------- | ----------- | ----------- 6898nqn | Required | string | Subsystem NQN 6899host | Required | string | Host NQN to add to the list of allowed host NQNs 6900tgt_name | Optional | string | Parent NVMe-oF target name. 6901 6902#### Example 6903 6904Example request: 6905 6906~~~json 6907{ 6908 "jsonrpc": "2.0", 6909 "id": 1, 6910 "method": "nvmf_subsystem_add_host", 6911 "params": { 6912 "nqn": "nqn.2016-06.io.spdk:cnode1", 6913 "host": "nqn.2016-06.io.spdk:host1" 6914 } 6915} 6916~~~ 6917 6918Example response: 6919 6920~~~json 6921{ 6922 "jsonrpc": "2.0", 6923 "id": 1, 6924 "result": true 6925} 6926~~~ 6927 6928### nvmf_subsystem_remove_host method {#rpc_nvmf_subsystem_remove_host} 6929 6930Remove a host NQN from the list of allowed hosts. 6931 6932#### Parameters 6933 6934Name | Optional | Type | Description 6935----------------------- | -------- | ----------- | ----------- 6936nqn | Required | string | Subsystem NQN 6937host | Required | string | Host NQN to remove from the list of allowed host NQNs 6938tgt_name | Optional | string | Parent NVMe-oF target name. 6939 6940#### Example 6941 6942Example request: 6943 6944~~~json 6945{ 6946 "jsonrpc": "2.0", 6947 "id": 1, 6948 "method": "nvmf_subsystem_remove_host", 6949 "params": { 6950 "nqn": "nqn.2016-06.io.spdk:cnode1", 6951 "host": "nqn.2016-06.io.spdk:host1" 6952 } 6953} 6954~~~ 6955 6956Example response: 6957 6958~~~json 6959{ 6960 "jsonrpc": "2.0", 6961 "id": 1, 6962 "result": true 6963} 6964~~~ 6965 6966### nvmf_subsystem_allow_any_host method {#rpc_nvmf_subsystem_allow_any_host} 6967 6968Configure a subsystem to allow any host to connect or to enforce the host NQN list. 6969 6970#### Parameters 6971 6972Name | Optional | Type | Description 6973----------------------- | -------- | ----------- | ----------- 6974nqn | Required | string | Subsystem NQN 6975allow_any_host | Required | boolean | Allow any host (`true`) or enforce allowed host list (`false`). 6976tgt_name | Optional | string | Parent NVMe-oF target name. 6977 6978#### Example 6979 6980Example request: 6981 6982~~~json 6983{ 6984 "jsonrpc": "2.0", 6985 "id": 1, 6986 "method": "nvmf_subsystem_allow_any_host", 6987 "params": { 6988 "nqn": "nqn.2016-06.io.spdk:cnode1", 6989 "allow_any_host": true 6990 } 6991} 6992~~~ 6993 6994Example response: 6995 6996~~~json 6997{ 6998 "jsonrpc": "2.0", 6999 "id": 1, 7000 "result": true 7001} 7002~~~ 7003 7004### nvmf_subsystem_get_controllers {#rpc_nvmf_subsystem_get_controllers} 7005 7006#### Parameters 7007 7008Name | Optional | Type | Description 7009----------------------- | -------- | ----------- | ----------- 7010nqn | Required | string | Subsystem NQN 7011tgt_name | Optional | string | Parent NVMe-oF target name. 7012 7013#### Example 7014 7015Example request: 7016 7017~~~json 7018{ 7019 "jsonrpc": "2.0", 7020 "id": 1, 7021 "method": "nvmf_subsystem_get_controllers", 7022 "params": { 7023 "nqn": "nqn.2016-06.io.spdk:cnode1" 7024 } 7025} 7026~~~ 7027 7028Example response: 7029 7030~~~json 7031{ 7032 "jsonrpc": "2.0", 7033 "id": 1, 7034 "result": [ 7035 { 7036 "cntlid": 1, 7037 "hostnqn": "nqn.2016-06.io.spdk:host1", 7038 "hostid": "27dad528-6368-41c3-82d3-0b956b49025d", 7039 "num_io_qpairs": 5 7040 } 7041 ] 7042} 7043~~~ 7044 7045### nvmf_subsystem_get_qpairs {#rpc_nvmf_subsystem_get_qpairs} 7046 7047#### Parameters 7048 7049Name | Optional | Type | Description 7050----------------------- | -------- | ----------- | ----------- 7051nqn | Required | string | Subsystem NQN 7052tgt_name | Optional | string | Parent NVMe-oF target name. 7053 7054#### Example 7055 7056Example request: 7057 7058~~~json 7059{ 7060 "jsonrpc": "2.0", 7061 "id": 1, 7062 "method": "nvmf_subsystem_get_qpairs", 7063 "params": { 7064 "nqn": "nqn.2016-06.io.spdk:cnode1" 7065 } 7066} 7067~~~ 7068 7069Example response: 7070 7071~~~json 7072{ 7073 "jsonrpc": "2.0", 7074 "id": 1, 7075 "result": [ 7076 { 7077 "cntlid": 1, 7078 "qid": 0, 7079 "state": "active", 7080 "listen_address": { 7081 "trtype": "RDMA", 7082 "adrfam": "IPv4", 7083 "traddr": "192.168.0.123", 7084 "trsvcid": "4420" 7085 } 7086 }, 7087 { 7088 "cntlid": 1, 7089 "qid": 1, 7090 "state": "active", 7091 "listen_address": { 7092 "trtype": "RDMA", 7093 "adrfam": "IPv4", 7094 "traddr": "192.168.0.123", 7095 "trsvcid": "4420" 7096 } 7097 } 7098 ] 7099} 7100~~~ 7101 7102### nvmf_subsystem_get_listeners {#rpc_nvmf_subsystem_get_listeners} 7103 7104#### Parameters 7105 7106Name | Optional | Type | Description 7107----------------------- | -------- | ----------- | ----------- 7108nqn | Required | string | Subsystem NQN 7109tgt_name | Optional | string | Parent NVMe-oF target name. 7110 7111#### Example 7112 7113Example request: 7114 7115~~~json 7116{ 7117 "jsonrpc": "2.0", 7118 "id": 1, 7119 "method": "nvmf_subsystem_get_listeners", 7120 "params": { 7121 "nqn": "nqn.2016-06.io.spdk:cnode1" 7122 } 7123} 7124~~~ 7125 7126Example response: 7127 7128~~~json 7129{ 7130 "jsonrpc": "2.0", 7131 "id": 1, 7132 "result": [ 7133 { 7134 "address": { 7135 "trtype": "RDMA", 7136 "adrfam": "IPv4", 7137 "traddr": "192.168.0.123", 7138 "trsvcid": "4420" 7139 }, 7140 "ana_state": "optimized" 7141 } 7142 ] 7143} 7144~~~ 7145 7146### nvmf_set_max_subsystems {#rpc_nvmf_set_max_subsystems} 7147 7148Set the maximum allowed subsystems for the NVMe-oF target. This RPC may only be called 7149before SPDK subsystems have been initialized. 7150 7151#### Parameters 7152 7153Name | Optional | Type | Description 7154----------------------- | -------- | ----------- | ----------- 7155max_subsystems | Required | number | Maximum number of NVMe-oF subsystems 7156 7157#### Example 7158 7159Example request: 7160 7161~~~json 7162{ 7163 "jsonrpc": "2.0", 7164 "id": 1, 7165 "method": "nvmf_set_max_subsystems", 7166 "params": { 7167 "max_subsystems": 1024 7168 } 7169} 7170~~~ 7171 7172Example response: 7173 7174~~~json 7175{ 7176 "jsonrpc": "2.0", 7177 "id": 1, 7178 "result": true 7179} 7180~~~ 7181 7182### nvmf_set_config {#rpc_nvmf_set_config} 7183 7184Set global configuration of NVMe-oF target. This RPC may only be called before SPDK subsystems 7185have been initialized. 7186 7187#### Parameters 7188 7189Name | Optional | Type | Description 7190----------------------- | -------- | ----------- | ----------- 7191acceptor_poll_rate | Optional | number | Polling interval of the acceptor for incoming connections (microseconds) 7192admin_cmd_passthru | Optional | object | Admin command passthru configuration 7193poll_groups_mask | Optional | string | Set cpumask for NVMf poll groups 7194discovery_filter | Optional | string | Set discovery filter, possible values are: `match_any` (default) or comma separated values: `transport`, `address`, `svcid` 7195 7196#### admin_cmd_passthru {#spdk_nvmf_admin_passthru_conf} 7197 7198Name | Optional | Type | Description 7199----------------------- | -------- | ----------- | ----------- 7200identify_ctrlr | Required | bool | If true, enables custom identify handler that reports some identify attributes from the underlying NVMe drive 7201 7202#### Example 7203 7204Example request: 7205 7206~~~json 7207{ 7208 "jsonrpc": "2.0", 7209 "id": 1, 7210 "method": "nvmf_set_config", 7211 "params": { 7212 "acceptor_poll_rate": 10000 7213 } 7214} 7215~~~ 7216 7217Example response: 7218 7219~~~json 7220{ 7221 "jsonrpc": "2.0", 7222 "id": 1, 7223 "result": true 7224} 7225~~~ 7226 7227### nvmf_get_transports method {#rpc_nvmf_get_transports} 7228 7229#### Parameters 7230 7231The user may specify no parameters in order to list all transports, or a transport may be 7232specified by type. 7233 7234Name | Optional | Type | Description 7235--------------------------- | -------- | ------------| ----------- 7236tgt_name | Optional | string | Parent NVMe-oF target name. 7237trtype | Optional | string | Transport type. 7238 7239#### Example 7240 7241Example request: 7242 7243~~~json 7244{ 7245 "jsonrpc": "2.0", 7246 "id": 1, 7247 "method": "nvmf_get_transports" 7248} 7249~~~ 7250 7251Example response: 7252 7253~~~json 7254{ 7255 "jsonrpc": "2.0", 7256 "id": 1, 7257 "result": [ 7258 { 7259 "type": "RDMA". 7260 "max_queue_depth": 128, 7261 "max_io_qpairs_per_ctrlr": 64, 7262 "in_capsule_data_size": 4096, 7263 "max_io_size": 131072, 7264 "io_unit_size": 131072, 7265 "abort_timeout_sec": 1 7266 } 7267 ] 7268} 7269~~~ 7270 7271### nvmf_get_stats method {#rpc_nvmf_get_stats} 7272 7273Retrieve current statistics of the NVMf subsystem. 7274 7275#### Parameters 7276 7277Name | Optional | Type | Description 7278--------------------------- | -------- | ------------| ----------- 7279tgt_name | Optional | string | Parent NVMe-oF target name. 7280 7281#### Response 7282 7283The response is an object containing NVMf subsystem statistics. 7284In the response, `admin_qpairs` and `io_qpairs` are reflecting cumulative queue pair counts while 7285`current_admin_qpairs` and `current_io_qpairs` are showing the current number. 7286 7287#### Example 7288 7289Example request: 7290 7291~~~json 7292{ 7293 "jsonrpc": "2.0", 7294 "method": "nvmf_get_stats", 7295 "id": 1 7296} 7297~~~ 7298 7299Example response: 7300 7301~~~json 7302{ 7303 "jsonrpc": "2.0", 7304 "id": 1, 7305 "result": { 7306 "tick_rate": 2400000000, 7307 "poll_groups": [ 7308 { 7309 "name": "app_thread", 7310 "admin_qpairs": 1, 7311 "io_qpairs": 4, 7312 "current_admin_qpairs": 1, 7313 "current_io_qpairs": 2, 7314 "pending_bdev_io": 1721, 7315 "transports": [ 7316 { 7317 "trtype": "RDMA", 7318 "pending_data_buffer": 12131888, 7319 "devices": [ 7320 { 7321 "name": "mlx5_1", 7322 "polls": 72284105, 7323 "completions": 0, 7324 "requests": 0, 7325 "request_latency": 0, 7326 "pending_free_request": 0, 7327 "pending_rdma_read": 0, 7328 "pending_rdma_write": 0, 7329 "total_send_wrs": 0, 7330 "send_doorbell_updates": 0, 7331 "total_recv_wrs": 0, 7332 "recv_doorbell_updates": 1 7333 }, 7334 { 7335 "name": "mlx5_0", 7336 "polls": 72284105, 7337 "completions": 15165875, 7338 "requests": 7582935, 7339 "request_latency": 1249323766184, 7340 "pending_free_request": 0, 7341 "pending_rdma_read": 337602, 7342 "pending_rdma_write": 0, 7343 "total_send_wrs": 15165875, 7344 "send_doorbell_updates": 1516587, 7345 "total_recv_wrs": 15165875, 7346 "recv_doorbell_updates": 1516587 7347 } 7348 ] 7349 } 7350 ] 7351 } 7352 ] 7353 } 7354} 7355~~~ 7356 7357### nvmf_set_crdt {#rpc_nvmf_set_crdt} 7358 7359Set the 3 CRDT (Command Retry Delay Time) values. For details about 7360CRDT, please refer to the NVMe specification. Currently all the 7361SPDK nvmf subsystems share the same CRDT values. The default values 7362are 0. This rpc can only be invoked in STARTUP stage. All values are 7363in units of 100 milliseconds (same as the NVMe specification). 7364 7365#### Parameters 7366 7367Name | Optional | Type | Description 7368----------------------- | -------- | ----------- | ----------- 7369crdt1 | Optional | number | Command Retry Delay Time 1 7370crdt2 | Optional | number | Command Retry Delay Time 2 7371crdt3 | Optional | number | Command Retry Delay Time 3 7372 7373## Vhost Target {#jsonrpc_components_vhost_tgt} 7374 7375The following common preconditions need to be met in all target types. 7376 7377Controller name will be used to create UNIX domain socket. This implies that name concatenated with vhost socket 7378directory path needs to be valid UNIX socket name. 7379 7380@ref cpu_mask parameter is used to choose CPU on which pollers will be launched when new initiator is connecting. 7381It must be a subset of application CPU mask. Default value is CPU mask of the application. 7382 7383### vhost_controller_set_coalescing {#rpc_vhost_controller_set_coalescing} 7384 7385Controls interrupt coalescing for specific target. Because `delay_base_us` is used to calculate delay in CPU ticks 7386there is no hardcoded limit for this parameter. Only limitation is that final delay in CPU ticks might not overflow 738732 bit unsigned integer (which is more than 1s @ 4GHz CPU). In real scenarios `delay_base_us` should be much lower 7388than 150us. To disable coalescing set `delay_base_us` to 0. 7389 7390#### Parameters 7391 7392Name | Optional | Type | Description 7393----------------------- | -------- | ----------- | ----------- 7394ctrlr | Required | string | Controller name 7395delay_base_us | Required | number | Base (minimum) coalescing time in microseconds 7396iops_threshold | Required | number | Coalescing activation level greater than 0 in IO per second 7397 7398#### Example 7399 7400Example request: 7401 7402~~~json 7403{ 7404 "params": { 7405 "iops_threshold": 100000, 7406 "ctrlr": "VhostScsi0", 7407 "delay_base_us": 80 7408 }, 7409 "jsonrpc": "2.0", 7410 "method": "vhost_controller_set_coalescing", 7411 "id": 1 7412} 7413~~~ 7414 7415Example response: 7416 7417~~~json 7418{ 7419 "jsonrpc": "2.0", 7420 "id": 1, 7421 "result": true 7422} 7423~~~ 7424 7425### vhost_create_scsi_controller {#rpc_vhost_create_scsi_controller} 7426 7427Construct vhost SCSI target. 7428 7429#### Parameters 7430 7431Name | Optional | Type | Description 7432----------------------- | -------- | ----------- | ----------- 7433ctrlr | Required | string | Controller name 7434cpumask | Optional | string | @ref cpu_mask for this controller 7435 7436#### Example 7437 7438Example request: 7439 7440~~~json 7441{ 7442 "params": { 7443 "cpumask": "0x2", 7444 "ctrlr": "VhostScsi0" 7445 }, 7446 "jsonrpc": "2.0", 7447 "method": "vhost_create_scsi_controller", 7448 "id": 1 7449} 7450~~~ 7451 7452Example response: 7453 7454~~~json 7455{ 7456 "jsonrpc": "2.0", 7457 "id": 1, 7458 "result": true 7459} 7460~~~ 7461 7462### vhost_scsi_controller_add_target {#rpc_vhost_scsi_controller_add_target} 7463 7464In vhost target `ctrlr` create SCSI target with ID `scsi_target_num` and add `bdev_name` as LUN 0. 7465 7466#### Parameters 7467 7468Name | Optional | Type | Description 7469----------------------- | -------- | ----------- | ----------- 7470ctrlr | Required | string | Controller name 7471scsi_target_num | Required | number | SCSI target ID between 0 and 7 or -1 to use first free ID. 7472bdev_name | Required | string | Name of bdev to expose as a LUN 0 7473 7474#### Response 7475 7476SCSI target ID. 7477 7478#### Example 7479 7480Example request: 7481 7482~~~json 7483{ 7484 "params": { 7485 "scsi_target_num": 1, 7486 "bdev_name": "Malloc0", 7487 "ctrlr": "VhostScsi0" 7488 }, 7489 "jsonrpc": "2.0", 7490 "method": "vhost_scsi_controller_add_target", 7491 "id": 1 7492} 7493~~~ 7494 7495Example response: 7496 7497~~~json 7498response: 7499{ 7500 "jsonrpc": "2.0", 7501 "id": 1, 7502 "result": 1 7503} 7504~~~ 7505 7506### vhost_scsi_controller_remove_target {#rpc_vhost_scsi_controller_remove_target} 7507 7508Remove SCSI target ID `scsi_target_num` from vhost target `scsi_target_num`. 7509 7510This method will fail if initiator is connected, but doesn't support hot-remove (the `VIRTIO_SCSI_F_HOTPLUG` is not negotiated). 7511 7512#### Parameters 7513 7514Name | Optional | Type | Description 7515----------------------- | -------- | ----------- | ----------- 7516ctrlr | Required | string | Controller name 7517scsi_target_num | Required | number | SCSI target ID between 0 and 7 7518 7519#### Example 7520 7521Example request: 7522 7523~~~json 7524request: 7525{ 7526 "params": { 7527 "scsi_target_num": 1, 7528 "ctrlr": "VhostScsi0" 7529 }, 7530 "jsonrpc": "2.0", 7531 "method": "vhost_scsi_controller_remove_target", 7532 "id": 1 7533} 7534~~~ 7535 7536Example response: 7537 7538~~~json 7539{ 7540 "jsonrpc": "2.0", 7541 "id": 1, 7542 "result": true 7543} 7544~~~ 7545 7546### vhost_create_blk_controller {#rpc_vhost_create_blk_controller} 7547 7548Create vhost block controller 7549 7550If `readonly` is `true` then vhost block target will be created as read only and fail any write requests. 7551The `VIRTIO_BLK_F_RO` feature flag will be offered to the initiator. 7552 7553#### Parameters 7554 7555Name | Optional | Type | Description 7556----------------------- | -------- | ----------- | ----------- 7557ctrlr | Required | string | Controller name 7558bdev_name | Required | string | Name of bdev to expose block device 7559readonly | Optional | boolean | If true, this target will be read only (default: false) 7560cpumask | Optional | string | @ref cpu_mask for this controller 7561 7562#### Example 7563 7564Example request: 7565 7566~~~json 7567{ 7568 "params": { 7569 "dev_name": "Malloc0", 7570 "ctrlr": "VhostBlk0" 7571 }, 7572 "jsonrpc": "2.0", 7573 "method": "vhost_create_blk_controller", 7574 "id": 1 7575} 7576~~~ 7577 7578Example response: 7579 7580~~~json 7581{ 7582 "jsonrpc": "2.0", 7583 "id": 1, 7584 "result": true 7585} 7586~~~ 7587 7588### vhost_get_controllers {#rpc_vhost_get_controllers} 7589 7590Display information about all or specific vhost controller(s). 7591 7592#### Parameters 7593 7594The user may specify no parameters in order to list all controllers, or a controller may be 7595specified by name. 7596 7597Name | Optional | Type | Description 7598----------------------- | -------- | ----------- | ----------- 7599name | Optional | string | Vhost controller name 7600 7601#### Response {#rpc_vhost_get_controllers_response} 7602 7603Response is an array of objects describing requested controller(s). Common fields are: 7604 7605Name | Type | Description 7606----------------------- | ----------- | ----------- 7607ctrlr | string | Controller name 7608cpumask | string | @ref cpu_mask of this controller 7609delay_base_us | number | Base (minimum) coalescing time in microseconds (0 if disabled) 7610iops_threshold | number | Coalescing activation level 7611backend_specific | object | Backend specific informations 7612 7613### Vhost block {#rpc_vhost_get_controllers_blk} 7614 7615`backend_specific` contains one `block` object of type: 7616 7617Name | Type | Description 7618----------------------- | ----------- | ----------- 7619bdev | string | Backing bdev name or Null if bdev is hot-removed 7620readonly | boolean | True if controllers is readonly, false otherwise 7621 7622### Vhost SCSI {#rpc_vhost_get_controllers_scsi} 7623 7624`backend_specific` contains `scsi` array of following objects: 7625 7626Name | Type | Description 7627----------------------- | ----------- | ----------- 7628target_name | string | Name of this SCSI target 7629id | number | Unique SPDK global SCSI target ID 7630scsi_dev_num | number | SCSI target ID initiator will see when scanning this controller 7631luns | array | array of objects describing @ref rpc_vhost_get_controllers_scsi_luns 7632 7633### Vhost SCSI LUN {#rpc_vhost_get_controllers_scsi_luns} 7634 7635Object of type: 7636 7637Name | Type | Description 7638----------------------- | ----------- | ----------- 7639id | number | SCSI LUN ID 7640bdev_name | string | Backing bdev name 7641 7642### Vhost NVMe {#rpc_vhost_get_controllers_nvme} 7643 7644`backend_specific` contains `namespaces` array of following objects: 7645 7646Name | Type | Description 7647----------------------- | ----------- | ----------- 7648nsid | number | Namespace ID 7649bdev | string | Backing bdev name 7650 7651#### Example 7652 7653Example request: 7654 7655~~~json 7656{ 7657 "jsonrpc": "2.0", 7658 "method": "vhost_get_controllers", 7659 "id": 1 7660} 7661~~~ 7662 7663Example response: 7664 7665~~~json 7666{ 7667 "jsonrpc": "2.0", 7668 "id": 1, 7669 "result": [ 7670 { 7671 "cpumask": "0x2", 7672 "backend_specific": { 7673 "block": { 7674 "readonly": false, 7675 "bdev": "Malloc0" 7676 } 7677 }, 7678 "iops_threshold": 60000, 7679 "ctrlr": "VhostBlk0", 7680 "delay_base_us": 100 7681 }, 7682 { 7683 "cpumask": "0x2", 7684 "backend_specific": { 7685 "scsi": [ 7686 { 7687 "target_name": "Target 2", 7688 "luns": [ 7689 { 7690 "id": 0, 7691 "bdev_name": "Malloc1" 7692 } 7693 ], 7694 "id": 0, 7695 "scsi_dev_num": 2 7696 }, 7697 { 7698 "target_name": "Target 5", 7699 "luns": [ 7700 { 7701 "id": 0, 7702 "bdev_name": "Malloc2" 7703 } 7704 ], 7705 "id": 1, 7706 "scsi_dev_num": 5 7707 } 7708 ] 7709 }, 7710 "iops_threshold": 60000, 7711 "ctrlr": "VhostScsi0", 7712 "delay_base_us": 0 7713 }, 7714 { 7715 "cpumask": "0x2", 7716 "backend_specific": { 7717 "namespaces": [ 7718 { 7719 "bdev": "Malloc3", 7720 "nsid": 1 7721 }, 7722 { 7723 "bdev": "Malloc4", 7724 "nsid": 2 7725 } 7726 ] 7727 }, 7728 "iops_threshold": 60000, 7729 "ctrlr": "VhostNvme0", 7730 "delay_base_us": 0 7731 } 7732 ] 7733} 7734~~~ 7735 7736### vhost_delete_controller {#rpc_vhost_delete_controller} 7737 7738Remove vhost target. 7739 7740This call will fail if there is an initiator connected or there is at least one SCSI target configured in case of 7741vhost SCSI target. In the later case please remove all SCSI targets first using @ref rpc_vhost_scsi_controller_remove_target. 7742 7743#### Parameters 7744 7745Name | Optional | Type | Description 7746----------------------- | -------- | ----------- | ----------- 7747ctrlr | Required | string | Controller name 7748 7749#### Example 7750 7751Example request: 7752 7753~~~json 7754{ 7755 "params": { 7756 "ctrlr": "VhostNvme0" 7757 }, 7758 "jsonrpc": "2.0", 7759 "method": "vhost_delete_controller", 7760 "id": 1 7761} 7762~~~ 7763 7764Example response: 7765 7766~~~json 7767{ 7768 "jsonrpc": "2.0", 7769 "id": 1, 7770 "result": true 7771} 7772~~~ 7773 7774## Logical Volume {#jsonrpc_components_lvol} 7775 7776Identification of logical volume store and logical volume is explained first. 7777 7778A logical volume store has a UUID and a name for its identification. 7779The UUID is generated on creation and it can be used as a unique identifier. 7780The name is specified on creation and can be renamed. 7781Either UUID or name is used to access logical volume store in RPCs. 7782 7783A logical volume has a UUID and a name for its identification. 7784The UUID of the logical volume is generated on creation and it can be unique identifier. 7785The alias of the logical volume takes the format _lvs_name/lvol_name_ where: 7786 7787* _lvs_name_ is the name of the logical volume store. 7788* _lvol_name_ is specified on creation and can be renamed. 7789 7790### bdev_lvol_create_lvstore {#rpc_bdev_lvol_create_lvstore} 7791 7792Construct a logical volume store. 7793 7794#### Parameters 7795 7796Name | Optional | Type | Description 7797----------------------- | -------- | ----------- | ----------- 7798bdev_name | Required | string | Bdev on which to construct logical volume store 7799lvs_name | Required | string | Name of the logical volume store to create 7800cluster_sz | Optional | number | Cluster size of the logical volume store in bytes 7801clear_method | Optional | string | Change clear method for data region. Available: none, unmap (default), write_zeroes 7802 7803#### Response 7804 7805UUID of the created logical volume store is returned. 7806 7807#### Example 7808 7809Example request: 7810 7811~~~json 7812{ 7813 "jsonrpc": "2.0", 7814 "id": 1, 7815 "method": "bdev_lvol_create_lvstore", 7816 "params": { 7817 "lvs_name": "LVS0", 7818 "bdev_name": "Malloc0" 7819 "clear_method": "write_zeroes" 7820 } 7821} 7822~~~ 7823 7824Example response: 7825 7826~~~json 7827{ 7828 "jsonrpc": "2.0", 7829 "id": 1, 7830 "result": "a9959197-b5e2-4f2d-8095-251ffb6985a5" 7831} 7832~~~ 7833 7834### bdev_lvol_delete_lvstore {#rpc_bdev_lvol_delete_lvstore} 7835 7836Destroy a logical volume store. 7837 7838#### Parameters 7839 7840Name | Optional | Type | Description 7841----------------------- | -------- | ----------- | ----------- 7842uuid | Optional | string | UUID of the logical volume store to destroy 7843lvs_name | Optional | string | Name of the logical volume store to destroy 7844 7845Either uuid or lvs_name must be specified, but not both. 7846 7847#### Example 7848 7849Example request: 7850 7851~~~json 7852{ 7853 "jsonrpc": "2.0", 7854 "method": "bdev_lvol_delete_lvstore", 7855 "id": 1 7856 "params": { 7857 "uuid": "a9959197-b5e2-4f2d-8095-251ffb6985a5" 7858 } 7859} 7860~~~ 7861 7862Example response: 7863 7864~~~json 7865{ 7866 "jsonrpc": "2.0", 7867 "id": 1, 7868 "result": true 7869} 7870~~~ 7871 7872### bdev_lvol_get_lvstores {#rpc_bdev_lvol_get_lvstores} 7873 7874Get a list of logical volume stores. 7875 7876#### Parameters 7877 7878Name | Optional | Type | Description 7879----------------------- | -------- | ----------- | ----------- 7880uuid | Optional | string | UUID of the logical volume store to retrieve information about 7881lvs_name | Optional | string | Name of the logical volume store to retrieve information about 7882 7883Either uuid or lvs_name may be specified, but not both. 7884If both uuid and lvs_name are omitted, information about all logical volume stores is returned. 7885 7886#### Example 7887 7888Example request: 7889 7890~~~json 7891{ 7892 "jsonrpc": "2.0", 7893 "method": "bdev_lvol_get_lvstores", 7894 "id": 1, 7895 "params": { 7896 "lvs_name": "LVS0" 7897 } 7898} 7899~~~ 7900 7901Example response: 7902 7903~~~json 7904{ 7905 "jsonrpc": "2.0", 7906 "id": 1, 7907 "result": [ 7908 { 7909 "uuid": "a9959197-b5e2-4f2d-8095-251ffb6985a5", 7910 "base_bdev": "Malloc0", 7911 "free_clusters": 31, 7912 "cluster_size": 4194304, 7913 "total_data_clusters": 31, 7914 "block_size": 4096, 7915 "name": "LVS0" 7916 } 7917 ] 7918} 7919~~~ 7920 7921### bdev_lvol_rename_lvstore {#rpc_bdev_lvol_rename_lvstore} 7922 7923Rename a logical volume store. 7924 7925#### Parameters 7926 7927Name | Optional | Type | Description 7928----------------------- | -------- | ----------- | ----------- 7929old_name | Required | string | Existing logical volume store name 7930new_name | Required | string | New logical volume store name 7931 7932#### Example 7933 7934Example request: 7935 7936~~~json 7937{ 7938 "jsonrpc": "2.0", 7939 "method": "bdev_lvol_rename_lvstore", 7940 "id": 1, 7941 "params": { 7942 "old_name": "LVS0", 7943 "new_name": "LVS2" 7944 } 7945} 7946~~~ 7947 7948Example response: 7949 7950~~~json 7951{ 7952 "jsonrpc": "2.0", 7953 "id": 1, 7954 "result": true 7955} 7956~~~ 7957 7958### bdev_lvol_create {#rpc_bdev_lvol_create} 7959 7960Create a logical volume on a logical volume store. 7961 7962#### Parameters 7963 7964Name | Optional | Type | Description 7965----------------------- | -------- | ----------- | ----------- 7966lvol_name | Required | string | Name of logical volume to create 7967size | Required | number | Desired size of logical volume in bytes 7968thin_provision | Optional | boolean | True to enable thin provisioning 7969uuid | Optional | string | UUID of logical volume store to create logical volume on 7970lvs_name | Optional | string | Name of logical volume store to create logical volume on 7971clear_method | Optional | string | Change default data clusters clear method. Available: none, unmap, write_zeroes 7972 7973Size will be rounded up to a multiple of cluster size. Either uuid or lvs_name must be specified, but not both. 7974lvol_name will be used in the alias of the created logical volume. 7975 7976#### Response 7977 7978UUID of the created logical volume is returned. 7979 7980#### Example 7981 7982Example request: 7983 7984~~~json 7985{ 7986 "jsonrpc": "2.0", 7987 "method": "bdev_lvol_create", 7988 "id": 1, 7989 "params": { 7990 "lvol_name": "LVOL0", 7991 "size": 1048576, 7992 "lvs_name": "LVS0", 7993 "clear_method": "unmap", 7994 "thin_provision": true 7995 } 7996} 7997~~~ 7998 7999Example response: 8000 8001~~~json 8002{ 8003 "jsonrpc": "2.0", 8004 "id": 1, 8005 "result": "1b38702c-7f0c-411e-a962-92c6a5a8a602" 8006} 8007~~~ 8008 8009### bdev_lvol_snapshot {#rpc_bdev_lvol_snapshot} 8010 8011Capture a snapshot of the current state of a logical volume. 8012 8013#### Parameters 8014 8015Name | Optional | Type | Description 8016----------------------- | -------- | ----------- | ----------- 8017lvol_name | Required | string | UUID or alias of the logical volume to create a snapshot from 8018snapshot_name | Required | string | Name for the newly created snapshot 8019 8020#### Response 8021 8022UUID of the created logical volume snapshot is returned. 8023 8024#### Example 8025 8026Example request: 8027 8028~~~json 8029{ 8030 "jsonrpc": "2.0", 8031 "method": "bdev_lvol_snapshot", 8032 "id": 1, 8033 "params": { 8034 "lvol_name": "1b38702c-7f0c-411e-a962-92c6a5a8a602", 8035 "snapshot_name": "SNAP1" 8036 } 8037} 8038~~~ 8039 8040Example response: 8041 8042~~~json 8043{ 8044 "jsonrpc": "2.0", 8045 "id": 1, 8046 "result": "cc8d7fdf-7865-4d1f-9fc6-35da8e368670" 8047} 8048~~~ 8049 8050### bdev_lvol_clone {#rpc_bdev_lvol_clone} 8051 8052Create a logical volume based on a snapshot. 8053 8054#### Parameters 8055 8056Name | Optional | Type | Description 8057----------------------- | -------- | ----------- | ----------- 8058snapshot_name | Required | string | UUID or alias of the snapshot to clone 8059clone_name | Required | string | Name for the logical volume to create 8060 8061#### Response 8062 8063UUID of the created logical volume clone is returned. 8064 8065#### Example 8066 8067Example request: 8068 8069~~~json 8070{ 8071 "jsonrpc": "2.0" 8072 "method": "bdev_lvol_clone", 8073 "id": 1, 8074 "params": { 8075 "snapshot_name": "cc8d7fdf-7865-4d1f-9fc6-35da8e368670", 8076 "clone_name": "CLONE1" 8077 } 8078} 8079~~~ 8080 8081Example response: 8082 8083~~~json 8084{ 8085 "jsonrpc": "2.0", 8086 "id": 1, 8087 "result": "8d87fccc-c278-49f0-9d4c-6237951aca09" 8088} 8089~~~ 8090 8091### bdev_lvol_rename {#rpc_bdev_lvol_rename} 8092 8093Rename a logical volume. New name will rename only the alias of the logical volume. 8094 8095#### Parameters 8096 8097Name | Optional | Type | Description 8098----------------------- | -------- | ----------- | ----------- 8099old_name | Required | string | UUID or alias of the existing logical volume 8100new_name | Required | string | New logical volume name 8101 8102#### Example 8103 8104Example request: 8105 8106~~~json 8107{ 8108 "jsonrpc": "2.0", 8109 "method": "bdev_lvol_rename", 8110 "id": 1, 8111 "params": { 8112 "old_name": "067df606-6dbc-4143-a499-0d05855cb3b8", 8113 "new_name": "LVOL2" 8114 } 8115} 8116~~~ 8117 8118Example response: 8119 8120~~~json 8121{ 8122 "jsonrpc": "2.0", 8123 "id": 1, 8124 "result": true 8125} 8126~~~ 8127 8128### bdev_lvol_resize {#rpc_bdev_lvol_resize} 8129 8130Resize a logical volume. 8131 8132#### Parameters 8133 8134Name | Optional | Type | Description 8135----------------------- | -------- | ----------- | ----------- 8136name | Required | string | UUID or alias of the logical volume to resize 8137size | Required | number | Desired size of the logical volume in bytes 8138 8139#### Example 8140 8141Example request: 8142 8143~~~json 8144{ 8145 "jsonrpc": "2.0", 8146 "method": "bdev_lvol_resize", 8147 "id": 1, 8148 "params": { 8149 "name": "51638754-ca16-43a7-9f8f-294a0805ab0a", 8150 "size": 2097152 8151 } 8152} 8153~~~ 8154 8155Example response: 8156 8157~~~json 8158{ 8159 "jsonrpc": "2.0", 8160 "id": 1, 8161 "result": true 8162} 8163~~~ 8164 8165### bdev_lvol_set_read_only{#rpc_bdev_lvol_set_read_only} 8166 8167Mark logical volume as read only. 8168 8169#### Parameters 8170 8171Name | Optional | Type | Description 8172----------------------- | -------- | ----------- | ----------- 8173name | Required | string | UUID or alias of the logical volume to set as read only 8174 8175#### Example 8176 8177Example request: 8178 8179~~~json 8180{ 8181 "jsonrpc": "2.0", 8182 "method": "bdev_lvol_set_read_only", 8183 "id": 1, 8184 "params": { 8185 "name": "51638754-ca16-43a7-9f8f-294a0805ab0a", 8186 } 8187} 8188~~~ 8189 8190Example response: 8191 8192~~~json 8193{ 8194 "jsonrpc": "2.0", 8195 "id": 1, 8196 "result": true 8197} 8198~~~ 8199 8200### bdev_lvol_delete {#rpc_bdev_lvol_delete} 8201 8202Destroy a logical volume. 8203 8204#### Parameters 8205 8206Name | Optional | Type | Description 8207----------------------- | -------- | ----------- | ----------- 8208name | Required | string | UUID or alias of the logical volume to destroy 8209 8210#### Example 8211 8212Example request: 8213 8214~~~json 8215{ 8216 "jsonrpc": "2.0", 8217 "method": "bdev_lvol_delete", 8218 "id": 1, 8219 "params": { 8220 "name": "51638754-ca16-43a7-9f8f-294a0805ab0a" 8221 } 8222} 8223~~~ 8224 8225Example response: 8226 8227~~~json 8228{ 8229 "jsonrpc": "2.0", 8230 "id": 1, 8231 "result": true 8232} 8233~~~ 8234 8235### bdev_lvol_inflate {#rpc_bdev_lvol_inflate} 8236 8237Inflate a logical volume. All unallocated clusters are allocated and copied from the parent or zero filled 8238if not allocated in the parent. Then all dependencies on the parent are removed. 8239 8240### Parameters 8241 8242Name | Optional | Type | Description 8243----------------------- | -------- | ----------- | ----------- 8244name | Required | string | UUID or alias of the logical volume to inflate 8245 8246#### Example 8247 8248Example request: 8249 8250~~~json 8251{ 8252 "jsonrpc": "2.0", 8253 "method": "bdev_lvol_inflate", 8254 "id": 1, 8255 "params": { 8256 "name": "8d87fccc-c278-49f0-9d4c-6237951aca09" 8257 } 8258} 8259~~~ 8260 8261Example response: 8262 8263~~~json 8264{ 8265 "jsonrpc": "2.0", 8266 "id": 1, 8267 "result": true 8268} 8269~~~ 8270 8271### bdev_lvol_decouple_parent {#rpc_bdev_lvol_decouple_parent} 8272 8273Decouple the parent of a logical volume. For unallocated clusters which is allocated in the parent, they are 8274allocated and copied from the parent, but for unallocated clusters which is thin provisioned in the parent, 8275they are kept thin provisioned. Then all dependencies on the parent are removed. 8276 8277#### Parameters 8278 8279Name | Optional | Type | Description 8280----------------------- | -------- | ----------- | ----------- 8281name | Required | string | UUID or alias of the logical volume to decouple the parent of it 8282 8283#### Example 8284 8285Example request: 8286 8287~~~json 8288{ 8289 "jsonrpc": "2.0", 8290 "method": "bdev_lvol_decouple_parent", 8291 "id": 1. 8292 "params": { 8293 "name": "8d87fccc-c278-49f0-9d4c-6237951aca09" 8294 } 8295} 8296~~~ 8297 8298Example response: 8299 8300~~~json 8301{ 8302 "jsonrpc": "2.0", 8303 "id": 1, 8304 "result": true 8305} 8306~~~ 8307 8308## RAID 8309 8310### bdev_raid_get_bdevs {#rpc_bdev_raid_get_bdevs} 8311 8312This is used to list all the raid bdev names based on the input category requested. Category should be one 8313of 'all', 'online', 'configuring' or 'offline'. 'all' means all the raid bdevs whether they are online or 8314configuring or offline. 'online' is the raid bdev which is registered with bdev layer. 'configuring' is 8315the raid bdev which does not have full configuration discovered yet. 'offline' is the raid bdev which is 8316not registered with bdev as of now and it has encountered any error or user has requested to offline 8317the raid bdev. 8318 8319#### Parameters 8320 8321Name | Optional | Type | Description 8322----------------------- | -------- | ----------- | ----------- 8323category | Required | string | all or online or configuring or offline 8324 8325#### Example 8326 8327Example request: 8328 8329~~~json 8330{ 8331 "jsonrpc": "2.0", 8332 "method": "bdev_raid_get_bdevs", 8333 "id": 1, 8334 "params": { 8335 "category": "all" 8336 } 8337} 8338~~~ 8339 8340Example response: 8341 8342~~~json 8343{ 8344 "jsonrpc": "2.0", 8345 "id": 1, 8346 "result": [ 8347 "Raid0" 8348 ] 8349} 8350~~~ 8351 8352### bdev_raid_create {#rpc_bdev_raid_create} 8353 8354Constructs new RAID bdev. 8355 8356#### Parameters 8357 8358Name | Optional | Type | Description 8359----------------------- | -------- | ----------- | ----------- 8360name | Required | string | RAID bdev name 8361strip_size_kb | Required | number | Strip size in KB 8362raid_level | Required | string | RAID level 8363base_bdevs | Required | string | Base bdevs name, whitespace separated list in quotes 8364 8365#### Example 8366 8367Example request: 8368 8369~~~json 8370{ 8371 "jsonrpc": "2.0", 8372 "method": "bdev_raid_create", 8373 "id": 1, 8374 "params": { 8375 "name": "Raid0", 8376 "raid_level": "0", 8377 "base_bdevs": [ 8378 "Malloc0", 8379 "Malloc1", 8380 "Malloc2", 8381 "Malloc3" 8382 ], 8383 "strip_size_kb": 4 8384 } 8385} 8386~~~ 8387 8388Example response: 8389 8390~~~json 8391{ 8392 "jsonrpc": "2.0", 8393 "id": 1, 8394 "result": true 8395} 8396~~~ 8397 8398### bdev_raid_delete {#rpc_bdev_raid_delete} 8399 8400Removes RAID bdev. 8401 8402#### Parameters 8403 8404Name | Optional | Type | Description 8405----------------------- | -------- | ----------- | ----------- 8406name | Required | string | RAID bdev name 8407 8408#### Example 8409 8410Example request: 8411 8412~~~json 8413{ 8414 "jsonrpc": "2.0", 8415 "method": "bdev_raid_delete", 8416 "id": 1, 8417 "params": { 8418 "name": "Raid0" 8419 } 8420} 8421~~~ 8422 8423Example response: 8424 8425~~~json 8426{ 8427 "jsonrpc": "2.0", 8428 "id": 1, 8429 "result": true 8430} 8431~~~ 8432 8433## SPLIT 8434 8435### bdev_split_create {#rpc_bdev_split_create} 8436 8437This is used to split an underlying block device and create several smaller equal-sized vbdevs. 8438 8439#### Parameters 8440 8441Name | Optional | Type | Description 8442----------------------- | -------- | ----------- | ----------- 8443base_bdev | Required | string | base bdev name 8444split_count | Required | number | number of splits 8445split_size_mb | Optional | number | size in MB to restrict the size 8446 8447#### Example 8448 8449Example request: 8450 8451~~~json 8452{ 8453 "jsonrpc": "2.0", 8454 "method": "bdev_split_create", 8455 "id": 1, 8456 "params": { 8457 "base_bdev": "Malloc0", 8458 "split_count": 4 8459 } 8460} 8461~~~ 8462 8463Example response: 8464 8465~~~json 8466{ 8467 "jsonrpc": "2.0", 8468 "id": 1, 8469 "result": [ 8470 "Malloc0p0", 8471 "Malloc0p1", 8472 "Malloc0p2", 8473 "Malloc0p3" 8474 ] 8475} 8476~~~ 8477 8478### bdev_split_delete {#rpc_bdev_split_delete} 8479 8480This is used to remove the split vbdevs. 8481 8482#### Parameters 8483 8484Name | Optional | Type | Description 8485----------------------- | -------- | ----------- | ----------- 8486base_bdev | Required | string | base bdev name 8487 8488#### Example 8489 8490Example request: 8491 8492~~~json 8493{ 8494 "jsonrpc": "2.0", 8495 "method": "bdev_split_delete", 8496 "id": 1, 8497 "params": { 8498 "base_bdev": "Malloc0" 8499 } 8500} 8501~~~ 8502 8503Example response: 8504 8505~~~json 8506{ 8507 "jsonrpc": "2.0", 8508 "id": 1, 8509 "result": true 8510} 8511~~~ 8512 8513## Uring 8514 8515### bdev_uring_create {#rpc_bdev_uring_create} 8516 8517Create a bdev with io_uring backend. 8518 8519#### Parameters 8520 8521Name | Optional | Type | Description 8522----------------------- | -------- | ----------- | ----------- 8523filename | Required | string | path to device or file (ex: /dev/nvme0n1) 8524name | Required | string | name of bdev 8525block_size | Optional | number | block size of device (If omitted, get the block size from the file) 8526 8527#### Example 8528 8529Example request: 8530 8531~~~json 8532{ 8533 "jsonrpc": "2.0", 8534 "method": "bdev_uring_create", 8535 "id": 1, 8536 "params": { 8537 "name": "bdev_u0", 8538 "filename": "/dev/nvme0n1", 8539 "block_size": 512 8540 } 8541} 8542~~~ 8543 8544Example response: 8545 8546~~~json 8547{ 8548 "jsonrpc": "2.0", 8549 "id": 1, 8550 "result": "bdev_u0" 8551} 8552~~~ 8553 8554### bdev_uring_delete {#rpc_bdev_uring_delete} 8555 8556Remove a uring bdev. 8557 8558#### Parameters 8559 8560Name | Optional | Type | Description 8561----------------------- | -------- | ----------- | ----------- 8562name | Required | string | name of uring bdev to delete 8563 8564#### Example 8565 8566Example request: 8567 8568~~~json 8569{ 8570 "jsonrpc": "2.0", 8571 "method": "bdev_uring_delete", 8572 "id": 1, 8573 "params": { 8574 "name": "bdev_u0" 8575 } 8576} 8577~~~ 8578 8579Example response: 8580 8581~~~json 8582{ 8583 "jsonrpc": "2.0", 8584 "id": 1, 8585 "result": true 8586} 8587~~~ 8588 8589## OPAL 8590 8591### bdev_nvme_opal_init {#rpc_bdev_nvme_opal_init} 8592 8593This is used to initialize OPAL of a given NVMe ctrlr, including taking ownership and activating. 8594 8595#### Parameters 8596 8597Name | Optional | Type | Description 8598----------------------- | -------- | ----------- | ----------- 8599nvme_ctrlr_name | Required | string | name of nvme ctrlr 8600password | Required | string | admin password of OPAL 8601 8602#### Example 8603 8604Example request: 8605 8606~~~json 8607{ 8608 "jsonrpc": "2.0", 8609 "method": "bdev_nvme_opal_init", 8610 "id": 1, 8611 "params": { 8612 "nvme_ctrlr_name": "nvme0", 8613 "password": "*****" 8614 } 8615} 8616~~~ 8617 8618Example response: 8619 8620~~~json 8621{ 8622 "jsonrpc": "2.0", 8623 "id": 1, 8624 "result": true 8625} 8626~~~ 8627 8628### bdev_nvme_opal_revert {#rpc_bdev_nvme_opal_revert} 8629 8630This is used to revert OPAL to its factory settings. Erase all user configuration and data. 8631 8632#### Parameters 8633 8634Name | Optional | Type | Description 8635----------------------- | -------- | ----------- | ----------- 8636nvme_ctrlr_name | Required | string | name of nvme ctrlr 8637password | Required | string | admin password of OPAL 8638 8639#### Example 8640 8641Example request: 8642 8643~~~json 8644{ 8645 "jsonrpc": "2.0", 8646 "method": "bdev_nvme_opal_revert", 8647 "id": 1, 8648 "params": { 8649 "nvme_ctrlr_name": "nvme0", 8650 "password": "*****" 8651 } 8652} 8653~~~ 8654 8655Example response: 8656 8657~~~json 8658{ 8659 "jsonrpc": "2.0", 8660 "id": 1, 8661 "result": true 8662} 8663~~~ 8664 8665### bdev_opal_create {#rpc_bdev_opal_create} 8666 8667This is used to create an OPAL virtual bdev. 8668 8669#### Parameters 8670 8671Name | Optional | Type | Description 8672----------------------- | -------- | ----------- | ----------- 8673nvme_ctrlr_name | Required | string | name of nvme ctrlr that supports OPAL 8674nsid | Required | number | namespace ID 8675locking_range_id | Required | number | OPAL locking range ID 8676range_start | Required | number | locking range start LBA 8677range_length | Required | number | locking range length 8678password | Required | string | admin password of OPAL 8679 8680#### Response 8681 8682The response is the name of created OPAL virtual bdev. 8683 8684#### Example 8685 8686Example request: 8687 8688~~~json 8689{ 8690 "jsonrpc": "2.0", 8691 "method": "bdev_opal_create", 8692 "id": 1, 8693 "params": { 8694 "nvme_ctrlr_name": "nvme0", 8695 "nsid": 1, 8696 "locking_range_id": 1, 8697 "range_start": 0, 8698 "range_length": 4096, 8699 "password": "*****" 8700 } 8701} 8702~~~ 8703 8704Example response: 8705 8706~~~json 8707{ 8708 "jsonrpc": "2.0", 8709 "id": 1, 8710 "result": "nvme0n1r1" 8711} 8712~~~ 8713 8714### bdev_opal_get_info {#rpc_bdev_opal_get_info} 8715 8716This is used to get information of a given OPAL bdev. 8717 8718#### Parameters 8719 8720Name | Optional | Type | Description 8721----------------------- | -------- | ----------- | ----------- 8722bdev_name | Required | string | name of OPAL vbdev 8723password | Required | string | admin password 8724 8725#### Response 8726 8727The response is the locking info of OPAL virtual bdev. 8728 8729#### Example 8730 8731Example request: 8732 8733~~~json 8734{ 8735 "jsonrpc": "2.0", 8736 "method": "bdev_opal_get_info", 8737 "id": 1, 8738 "params": { 8739 "bdev_name": "nvme0n1r1", 8740 "password": "*****" 8741 } 8742} 8743~~~ 8744 8745Example response: 8746 8747~~~json 8748{ 8749 "jsonrpc": "2.0", 8750 "id": 1, 8751 "result": { 8752 "name": "nvme0n1r1", 8753 "range_start": 0, 8754 "range_length": 4096, 8755 "read_lock_enabled": true, 8756 "write_lock_enabled": true, 8757 "read_locked": false, 8758 "write_locked": false 8759 } 8760} 8761~~~ 8762 8763### bdev_opal_delete {#rpc_bdev_opal_delete} 8764 8765This is used to delete OPAL vbdev. 8766 8767#### Parameters 8768 8769Name | Optional | Type | Description 8770----------------------- | -------- | ----------- | ----------- 8771bdev_name | Required | string | name of OPAL vbdev 8772password | Required | string | admin password 8773 8774#### Example 8775 8776Example request: 8777 8778~~~json 8779{ 8780 "jsonrpc": "2.0", 8781 "method": "bdev_opal_delete", 8782 "id": 1, 8783 "params": { 8784 "bdev_name": "nvme0n1r1", 8785 "password": "*****" 8786 } 8787} 8788~~~ 8789 8790Example response: 8791 8792~~~json 8793{ 8794 "jsonrpc": "2.0", 8795 "id": 1, 8796 "result": true 8797} 8798~~~ 8799 8800### bdev_opal_new_user {#rpc_bdev_opal_new_user} 8801 8802This enables a new user to the specified opal bdev so that the user can lock/unlock the bdev. 8803Recalling this for the same opal bdev, only the newest user will have the privilege. 8804 8805#### Parameters 8806 8807Name | Optional | Type | Description 8808----------------------- | -------- | ----------- | ----------- 8809bdev_name | Required | string | name of OPAL vbdev 8810admin_password | Required | string | admin password 8811user_id | Required | number | user ID 8812user_password | Required | string | user password 8813 8814#### Example 8815 8816Example request: 8817 8818~~~json 8819{ 8820 "jsonrpc": "2.0", 8821 "method": "bdev_opal_new_user", 8822 "id": 1, 8823 "params": { 8824 "bdev_name": "nvme0n1r1", 8825 "admin_password": "*****", 8826 "user_id": "1", 8827 "user_password": "********" 8828 } 8829} 8830~~~ 8831 8832Example response: 8833 8834~~~json 8835{ 8836 "jsonrpc": "2.0", 8837 "id": 1, 8838 "result": true 8839} 8840~~~ 8841 8842### bdev_opal_set_lock_state {#rpc_bdev_opal_set_lock_state} 8843 8844This is used to lock/unlock specific opal bdev providing user ID and password. 8845 8846#### Parameters 8847 8848Name | Optional | Type | Description 8849----------------------- | -------- | ----------- | ----------- 8850bdev_name | Required | string | name of OPAL vbdev 8851user_id | Required | number | user ID 8852password | Required | string | user password 8853lock_state | Required | string | lock state 8854 8855#### Example 8856 8857Example request: 8858 8859~~~json 8860{ 8861 "jsonrpc": "2.0", 8862 "method": "bdev_opal_set_lock_state", 8863 "id": 1, 8864 "params": { 8865 "bdev_name": "nvme0n1r1", 8866 "user_id": "1", 8867 "user_password": "********", 8868 "lock_state": "rwlock" 8869 } 8870} 8871~~~ 8872 8873Example response: 8874 8875~~~json 8876{ 8877 "jsonrpc": "2.0", 8878 "id": 1, 8879 "result": true 8880} 8881~~~ 8882 8883## Notifications 8884 8885### notify_get_types {#rpc_notify_get_types} 8886 8887Return list of all supported notification types. 8888 8889#### Parameters 8890 8891None 8892 8893#### Response 8894 8895The response is an array of strings - supported RPC notification types. 8896 8897#### Example 8898 8899Example request: 8900 8901~~~json 8902{ 8903 "jsonrpc": "2.0", 8904 "method": "notify_get_types", 8905 "id": 1 8906} 8907~~~ 8908 8909Example response: 8910 8911~~~json 8912{ 8913 "id": 1, 8914 "result": [ 8915 "bdev_register", 8916 "bdev_unregister" 8917 ], 8918 "jsonrpc": "2.0" 8919} 8920~~~ 8921 8922### notify_get_notifications {#notify_get_notifications} 8923 8924Request notifications. Returns array of notifications that happend since the specified id (or first that is available). 8925 8926Notice: Notifications are kept in circular buffer with limited size. Older notifications might be inaccessible 8927due to being overwritten by new ones. 8928 8929#### Parameters 8930 8931Name | Optional | Type | Description 8932----------------------- | -------- | ----------- | ----------- 8933id | Optional | number | First Event ID to fetch (default: first available). 8934max | Optional | number | Maximum number of event to return (default: no limit). 8935 8936#### Response 8937 8938Response is an array of event objects. 8939 8940Name | Optional | Type | Description 8941----------------------- | -------- | ----------- | ----------- 8942id | Optional | number | Event ID. 8943type | Optional | number | Type of the event. 8944ctx | Optional | string | Event context. 8945 8946#### Example 8947 8948Example request: 8949 8950~~~json 8951{ 8952 "id": 1, 8953 "jsonrpc": "2.0", 8954 "method": "notify_get_notifications", 8955 "params": { 8956 "id": 1, 8957 "max": 10 8958 } 8959} 8960 8961~~~ 8962 8963Example response: 8964 8965~~~json 8966{ 8967 "jsonrpc": "2.0", 8968 "id": 1, 8969 "result": [ 8970 { 8971 "ctx": "Malloc0", 8972 "type": "bdev_register", 8973 "id": 1 8974 }, 8975 { 8976 "ctx": "Malloc2", 8977 "type": "bdev_register", 8978 "id": 2 8979 } 8980 ] 8981} 8982~~~ 8983 8984## Linux Network Block Device (NBD) {#jsonrpc_components_nbd} 8985 8986SPDK supports exporting bdevs through Linux nbd. These devices then appear as standard Linux kernel block devices 8987and can be accessed using standard utilities like fdisk. 8988 8989In order to export a device over nbd, first make sure the Linux kernel nbd driver is loaded by running 'modprobe nbd'. 8990 8991### nbd_start_disk {#rpc_nbd_start_disk} 8992 8993Start to export one SPDK bdev as NBD disk 8994 8995#### Parameters 8996 8997Name | Optional | Type | Description 8998----------------------- | -------- | ----------- | ----------- 8999bdev_name | Required | string | Bdev name to export 9000nbd_device | Optional | string | NBD device name to assign 9001 9002#### Response 9003 9004Path of exported NBD disk 9005 9006#### Example 9007 9008Example request: 9009 9010~~~json 9011{ 9012 "params": { 9013 "nbd_device": "/dev/nbd1", 9014 "bdev_name": "Malloc1" 9015 }, 9016 "jsonrpc": "2.0", 9017 "method": "nbd_start_disk", 9018 "id": 1 9019} 9020~~~ 9021 9022Example response: 9023 9024~~~json 9025{ 9026 "jsonrpc": "2.0", 9027 "id": 1, 9028 "result": "/dev/nbd1" 9029} 9030~~~ 9031 9032### nbd_stop_disk {#rpc_nbd_stop_disk} 9033 9034Stop one NBD disk which is based on SPDK bdev. 9035 9036#### Parameters 9037 9038Name | Optional | Type | Description 9039----------------------- | -------- | ----------- | ----------- 9040nbd_device | Required | string | NBD device name to stop 9041 9042#### Example 9043 9044Example request: 9045 9046~~~json 9047{ 9048 "params": { 9049 "nbd_device": "/dev/nbd1", 9050 }, 9051 "jsonrpc": "2.0", 9052 "method": "nbd_stop_disk", 9053 "id": 1 9054} 9055~~~ 9056 9057Example response: 9058 9059~~~json 9060{ 9061 "jsonrpc": "2.0", 9062 "id": 1, 9063 "result": "true" 9064} 9065~~~ 9066 9067### nbd_get_disks {#rpc_nbd_get_disks} 9068 9069Display all or specified NBD device list 9070 9071#### Parameters 9072 9073Name | Optional | Type | Description 9074----------------------- | -------- | ----------- | ----------- 9075nbd_device | Optional | string | NBD device name to display 9076 9077#### Response 9078 9079The response is an array of exported NBD devices and their corresponding SPDK bdev. 9080 9081#### Example 9082 9083Example request: 9084 9085~~~json 9086{ 9087 "jsonrpc": "2.0", 9088 "method": "nbd_get_disks", 9089 "id": 1 9090} 9091~~~ 9092 9093Example response: 9094 9095~~~json 9096{ 9097 "jsonrpc": "2.0", 9098 "id": 1, 9099 "result": [ 9100 { 9101 "bdev_name": "Malloc0", 9102 "nbd_device": "/dev/nbd0" 9103 }, 9104 { 9105 "bdev_name": "Malloc1", 9106 "nbd_device": "/dev/nbd1" 9107 } 9108 ] 9109} 9110~~~ 9111 9112## Blobfs {#jsonrpc_components_blobfs} 9113 9114### blobfs_detect {#rpc_blobfs_detect} 9115 9116Detect whether a blobfs exists on bdev. 9117 9118#### Parameters 9119 9120Name | Optional | Type | Description 9121----------------------- | -------- | ----------- | ----------- 9122bdev_name | Required | string | Block device name to detect blobfs 9123 9124#### Response 9125 9126True if a blobfs exists on the bdev; False otherwise. 9127 9128#### Example 9129 9130Example request: 9131 9132~~~json 9133{ 9134 "jsonrpc": "2.0", 9135 "id": 1, 9136 "method": "blobfs_detect", 9137 "params": { 9138 "bdev_name": "Malloc0" 9139 } 9140} 9141~~~ 9142 9143Example response: 9144 9145~~~json 9146{ 9147 "jsonrpc": "2.0", 9148 "id": 1, 9149 "result": "true" 9150} 9151~~~ 9152 9153### blobfs_create {#rpc_blobfs_create} 9154 9155Build blobfs on bdev. 9156 9157#### Parameters 9158 9159Name | Optional | Type | Description 9160----------------------- | -------- | ----------- | ----------- 9161bdev_name | Required | string | Block device name to create blobfs 9162cluster_sz | Optional | number | Size of cluster in bytes. Must be multiple of 4KiB page size, default and minimal value is 1M. 9163 9164#### Example 9165 9166Example request: 9167 9168~~~json 9169{ 9170 "jsonrpc": "2.0", 9171 "id": 1, 9172 "method": "blobfs_create", 9173 "params": { 9174 "bdev_name": "Malloc0", 9175 "cluster_sz": 1M 9176 } 9177} 9178~~~ 9179 9180Example response: 9181 9182~~~json 9183{ 9184 "jsonrpc": "2.0", 9185 "id": 1, 9186 "result": "true" 9187} 9188~~~ 9189 9190### blobfs_mount {#rpc_blobfs_mount} 9191 9192Mount a blobfs on bdev to one host path through FUSE 9193 9194#### Parameters 9195 9196Name | Optional | Type | Description 9197----------------------- | -------- | ----------- | ----------- 9198bdev_name | Required | string | Block device name where the blobfs is 9199mountpoint | Required | string | Mountpoint path in host to mount blobfs 9200 9201#### Example 9202 9203Example request: 9204 9205~~~json 9206{ 9207 "jsonrpc": "2.0", 9208 "id": 1, 9209 "method": ""blobfs_mount"", 9210 "params": { 9211 "bdev_name": "Malloc0", 9212 "mountpoint": "/mnt/" 9213 } 9214} 9215~~~ 9216 9217Example response: 9218 9219~~~json 9220{ 9221 "jsonrpc": "2.0", 9222 "id": 1, 9223 "result": "true" 9224} 9225~~~ 9226 9227### blobfs_set_cache_size {#rpc_blobfs_set_cache_size} 9228 9229Set cache pool size for blobfs filesystems. This RPC is only permitted when the cache pool is not already initialized. 9230 9231The cache pool is initialized when the first blobfs filesystem is initialized or loaded. It is freed when the all 9232initialized or loaded filesystems are unloaded. 9233 9234#### Parameters 9235 9236Name | Optional | Type | Description 9237----------------------- | -------- | ----------- | ----------- 9238size_in_mb | Required | number | Cache size in megabytes 9239 9240#### Response 9241 9242True if cache size is set successfully; False if failed to set. 9243 9244#### Example 9245 9246Example request: 9247 9248~~~json 9249{ 9250 "jsonrpc": "2.0", 9251 "id": 1, 9252 "method": "blobfs_set_cache_size", 9253 "params": { 9254 "size_in_mb": 512, 9255 } 9256} 9257~~~ 9258 9259Example response: 9260 9261~~~json 9262{ 9263 "jsonrpc": "2.0", 9264 "id": 1, 9265 "result": true 9266} 9267~~~ 9268 9269## Socket layer {#jsonrpc_components_sock} 9270 9271### sock_impl_get_options {#rpc_sock_impl_get_options} 9272 9273Get parameters for the socket layer implementation. 9274 9275#### Parameters 9276 9277Name | Optional | Type | Description 9278----------------------- | -------- | ----------- | ----------- 9279impl_name | Required | string | Name of socket implementation, e.g. posix 9280 9281#### Response 9282 9283Response is an object with current socket layer options for requested implementation. 9284 9285#### Example 9286 9287Example request: 9288 9289~~~json 9290{ 9291 "jsonrpc": "2.0", 9292 "method": "sock_impl_get_options", 9293 "id": 1, 9294 "params": { 9295 "impl_name": "posix" 9296 } 9297} 9298~~~ 9299 9300Example response: 9301 9302~~~json 9303{ 9304 "jsonrpc": "2.0", 9305 "id": 1, 9306 "result": { 9307 "recv_buf_size": 2097152, 9308 "send_buf_size": 2097152, 9309 "enable_recv_pipe": true, 9310 "enable_quickack": true, 9311 "enable_placement_id": 0, 9312 "enable_zerocopy_send_server": true, 9313 "enable_zerocopy_send_client": false 9314 } 9315} 9316~~~ 9317 9318### sock_impl_set_options {#rpc_sock_impl_set_options} 9319 9320Set parameters for the socket layer implementation. 9321 9322#### Parameters 9323 9324Name | Optional | Type | Description 9325--------------------------- | -------- | ----------- | ----------- 9326impl_name | Required | string | Name of socket implementation, e.g. posix 9327recv_buf_size | Optional | number | Size of socket receive buffer in bytes 9328send_buf_size | Optional | number | Size of socket send buffer in bytes 9329enable_recv_pipe | Optional | boolean | Enable or disable receive pipe 9330enable_quick_ack | Optional | boolean | Enable or disable quick ACK 9331enable_placement_id | Optional | number | Enable or disable placement_id. 0:disable,1:incoming_napi,2:incoming_cpu 9332enable_zerocopy_send_server | Optional | boolean | Enable or disable zero copy on send for server sockets 9333enable_zerocopy_send_client | Optional | boolean | Enable or disable zero copy on send for client sockets 9334 9335#### Response 9336 9337True if socket layer options were set successfully. 9338 9339#### Example 9340 9341Example request: 9342 9343~~~json 9344{ 9345 "jsonrpc": "2.0", 9346 "method": "sock_impl_set_options", 9347 "id": 1, 9348 "params": { 9349 "impl_name": "posix", 9350 "recv_buf_size": 2097152, 9351 "send_buf_size": 2097152, 9352 "enable_recv_pipe": false, 9353 "enable_quick_ack": false, 9354 "enable_placement_id": 0, 9355 "enable_zerocopy_send_server": true, 9356 "enable_zerocopy_send_client": false 9357 } 9358} 9359~~~ 9360 9361Example response: 9362 9363~~~json 9364{ 9365 "jsonrpc": "2.0", 9366 "id": 1, 9367 "result": true 9368} 9369~~~ 9370 9371### sock_set_default_impl {#rpc_sock_set_default_impl} 9372 9373Set the default sock implementation. 9374 9375#### Parameters 9376 9377Name | Optional | Type | Description 9378----------------------- | -------- | ----------- | ----------- 9379impl_name | Required | string | Name of socket implementation, e.g. posix 9380 9381#### Response 9382 9383True if the default socket layer configuration was set successfully. 9384 9385#### Example 9386 9387Example request: 9388 9389~~~json 9390{ 9391 "jsonrpc": "2.0", 9392 "method": "sock_set_default_impl", 9393 "id": 1, 9394 "params": { 9395 "impl_name": "posix" 9396 } 9397} 9398~~~ 9399 9400Example response: 9401 9402~~~json 9403{ 9404 "jsonrpc": "2.0", 9405 "id": 1, 9406 "result": true 9407} 9408~~~ 9409 9410## Miscellaneous RPC commands 9411 9412### bdev_nvme_send_cmd {#rpc_bdev_nvme_send_cmd} 9413 9414Send NVMe command directly to NVMe controller or namespace. Parameters and responses encoded by base64 urlsafe need further processing. 9415 9416Notice: bdev_nvme_send_cmd requires user to guarentee the correctness of NVMe command itself, and also optional parameters. 9417Illegal command contents or mismatching buffer size may result in unpredictable behavior. 9418 9419#### Parameters 9420 9421Name | Optional | Type | Description 9422----------------------- | -------- | ----------- | ----------- 9423name | Required | string | Name of the operating NVMe controller 9424cmd_type | Required | string | Type of nvme cmd. Valid values are: admin, io 9425data_direction | Required | string | Direction of data transfer. Valid values are: c2h, h2c 9426cmdbuf | Required | string | NVMe command encoded by base64 urlsafe 9427data | Optional | string | Data transferring to controller from host, encoded by base64 urlsafe 9428metadata | Optional | string | Metadata transferring to controller from host, encoded by base64 urlsafe 9429data_len | Optional | number | Data length required to transfer from controller to host 9430metadata_len | Optional | number | Metadata length required to transfer from controller to host 9431timeout_ms | Optional | number | Command execution timeout value, in milliseconds 9432 9433#### Response 9434 9435Name | Type | Description 9436----------------------- | ----------- | ----------- 9437cpl | string | NVMe completion queue entry, encoded by base64 urlsafe 9438data | string | Data transferred from controller to host, encoded by base64 urlsafe 9439metadata | string | Metadata transferred from controller to host, encoded by base64 urlsafe 9440 9441#### Example 9442 9443Example request: 9444 9445~~~json 9446{ 9447 "jsonrpc": "2.0", 9448 "method": "bdev_nvme_send_cmd", 9449 "id": 1, 9450 "params": { 9451 "name": "Nvme0", 9452 "cmd_type": "admin" 9453 "data_direction": "c2h", 9454 "cmdbuf": "BgAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAsGUs9P5_AAAAAAAAABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==", 9455 "data_len": 60, 9456 } 9457} 9458~~~ 9459 9460Example response: 9461 9462~~~json 9463{ 9464 "jsonrpc": "2.0", 9465 "id": 1, 9466 "result": { 9467 "cpl": "AAAAAAAAAAARAAAAWrmwABAA==", 9468 "data": "sIjg6AAAAACwiODoAAAAALCI4OgAAAAAAAYAAREAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" 9469 } 9470 9471} 9472~~~ 9473 9474### enable_vmd {#rpc_enable_vmd} 9475 9476Enable VMD enumeration. 9477 9478#### Parameters 9479 9480This method has no parameters. 9481 9482#### Response 9483 9484Completion status of enumeration is returned as a boolean. 9485 9486### Example 9487 9488Example request: 9489 9490~~~json 9491{ 9492 "jsonrpc": "2.0", 9493 "method": "enable_vmd", 9494 "id": 1 9495} 9496~~~ 9497 9498Example response: 9499 9500~~~json 9501{ 9502 "jsonrpc": "2.0", 9503 "id": 1, 9504 "result": true 9505} 9506~~~ 9507 9508### spdk_get_version {#rpc_spdk_get_version} 9509 9510Get the version info of the running SPDK application. 9511 9512#### Parameters 9513 9514This method has no parameters. 9515 9516#### Response 9517 9518The response is the version number including major version number, minor version number, patch level number and suffix string. 9519 9520#### Example 9521 9522Example request: 9523~~ 9524{ 9525 "jsonrpc": "2.0", 9526 "id": 1, 9527 "method": "spdk_get_version" 9528} 9529~~ 9530 9531Example response: 9532~~ 9533{ 9534 "jsonrpc": "2.0", 9535 "id": 1, 9536 "result": { 9537 "version": "19.04-pre", 9538 "fields" : { 9539 "major": 19, 9540 "minor": 4, 9541 "patch": 0, 9542 "suffix": "-pre" 9543 } 9544 } 9545} 9546~~ 9547 9548### framework_get_pci_devices 9549 9550List PCIe devices attached to an SPDK application and the contents of their config space. 9551 9552#### Parameters 9553 9554This method has no parameters. 9555 9556#### Response 9557 9558The response is an array of attached PCIe devices. 9559 9560#### Example 9561 9562Example request: 9563~~ 9564{ 9565 "jsonrpc": "2.0", 9566 "id": 1, 9567 "method": "framework_get_pci_devices" 9568} 9569~~ 9570 9571Example response: 9572Note that the config space buffer was trimmed. 9573~~ 9574{ 9575 "jsonrpc": "2.0", 9576 "id": 1, 9577 "result": { 9578 [ 9579 { 9580 "address": "0000:00:04.0", 9581 "config_space": "8680455807051000...0000000000000000" 9582 }, 9583 { 9584 "address": "0000:00:03.0", 9585 "config_space": "8680455807051000...0000000000000000" 9586 } 9587 ] 9588 } 9589} 9590~~ 9591 9592### bdev_nvme_add_error_injection {#rpc_bdev_nvme_add_error_injection} 9593 9594Add a NVMe command error injection for a bdev nvme controller. 9595 9596#### Parameters 9597 9598Name | Optional | Type | Description 9599----------------------- | -------- | ----------- | ----------- 9600name | Required | string | Name of the operating NVMe controller 9601cmd_type | Required | string | Type of NVMe command. Valid values are: admin, io 9602opc | Required | number | Opcode for which the error injection is applied 9603do_not_submit | Optional | boolean | Set to true if request should not be submitted to the controller (default false) 9604timeout_in_us | Optional | number | Wait specified microseconds when do_not_submit is true 9605err_count | Optional | number | Number of matching NVMe commands to inject errors 9606sct | Optional | number | Status code type (default 0) 9607sc | Optional | number | Status code (default 0) 9608 9609#### Response 9610 9611true on success 9612 9613#### Example 9614 9615Example request: 9616 9617~~~json 9618{ 9619 "jsonrpc": "2.0", 9620 "method": "bdev_nvme_add_error_injection", 9621 "id": 1, 9622 "params": { 9623 "name": "HotInNvme0", 9624 "opc": 2, 9625 "cmd_type": "io", 9626 "err_count": 1111111, 9627 "sct": 11, 9628 "sc": 33 9629 } 9630} 9631 9632~~~ 9633 9634Example response: 9635 9636~~~json 9637{ 9638 "jsonrpc": "2.0", 9639 "id": 1, 9640 "result": true 9641} 9642 9643~~~ 9644 9645### bdev_nvme_remove_error_injection {#rpc_bdev_nvme_remove_error_injection} 9646 9647Remove a NVMe command error injection. 9648 9649#### Parameters 9650 9651Name | Optional | Type | Description 9652----------------------- | -------- | ----------- | ----------- 9653name | Required | string | Name of the operating NVMe controller 9654cmd_type | Required | string | Type of NVMe command. Valid values are: admin, io 9655opc | Required | number | Opcode for which the error injection is applied 9656 9657#### Response 9658 9659true on success 9660 9661#### Example 9662 9663Example request: 9664 9665~~~json 9666{ 9667 "jsonrpc": "2.0", 9668 "method": "bdev_nvme_remove_error_injection", 9669 "id": 1, 9670 "params": { 9671 "name": "HotInNvme0", 9672 "opc": 2, 9673 "cmd_type": "io" 9674 } 9675} 9676 9677 9678~~~ 9679 9680Example response: 9681 9682~~~json 9683{ 9684 "jsonrpc": "2.0", 9685 "id": 1, 9686 "result": true 9687} 9688 9689~~~ 9690