1from .helpers import deprecated_alias 2 3 4def bdev_set_options(client, bdev_io_pool_size=None, bdev_io_cache_size=None, bdev_auto_examine=None, 5 small_buf_pool_size=None, large_buf_pool_size=None): 6 """Set parameters for the bdev subsystem. 7 8 Args: 9 bdev_io_pool_size: number of bdev_io structures in shared buffer pool (optional) 10 bdev_io_cache_size: maximum number of bdev_io structures cached per thread (optional) 11 bdev_auto_examine: if set to false, the bdev layer will not examine every disks automatically (optional) 12 small_buf_pool_size: maximum number of small buffer (8KB buffer) pool size (optional) 13 large_buf_pool_size: maximum number of large buffer (64KB buffer) pool size (optional) 14 """ 15 params = {} 16 17 if bdev_io_pool_size: 18 params['bdev_io_pool_size'] = bdev_io_pool_size 19 if bdev_io_cache_size: 20 params['bdev_io_cache_size'] = bdev_io_cache_size 21 if bdev_auto_examine is not None: 22 params["bdev_auto_examine"] = bdev_auto_examine 23 if small_buf_pool_size: 24 params['small_buf_pool_size'] = small_buf_pool_size 25 if large_buf_pool_size: 26 params['large_buf_pool_size'] = large_buf_pool_size 27 return client.call('bdev_set_options', params) 28 29 30def bdev_examine(client, name): 31 """Examine a bdev manually. If the bdev does not exist yet when this RPC is called, 32 it will be examined when it is created 33 34 Args: 35 name: name of the bdev 36 """ 37 params = { 38 'name': name 39 } 40 return client.call('bdev_examine', params) 41 42 43def bdev_wait_for_examine(client): 44 """Report when all bdevs have been examined 45 """ 46 return client.call('bdev_wait_for_examine') 47 48 49def bdev_compress_create(client, base_bdev_name, pm_path, lb_size): 50 """Construct a compress virtual block device. 51 52 Args: 53 base_bdev_name: name of the underlying base bdev 54 pm_path: path to persistent memory 55 lb_size: logical block size for the compressed vol in bytes. Must be 4K or 512. 56 57 Returns: 58 Name of created virtual block device. 59 """ 60 params = {'base_bdev_name': base_bdev_name, 'pm_path': pm_path, 'lb_size': lb_size} 61 62 return client.call('bdev_compress_create', params) 63 64 65def bdev_compress_delete(client, name): 66 """Delete compress virtual block device. 67 68 Args: 69 name: name of compress vbdev to delete 70 """ 71 params = {'name': name} 72 return client.call('bdev_compress_delete', params) 73 74 75def bdev_compress_set_pmd(client, pmd): 76 """Set pmd options for the bdev compress. 77 78 Args: 79 pmd: 0 = auto-select, 1 = QAT, 2 = ISAL, 3 = mlx5_pci 80 """ 81 params = {'pmd': pmd} 82 83 return client.call('bdev_compress_set_pmd', params) 84 85 86def bdev_compress_get_orphans(client, name=None): 87 """Get a list of comp bdevs that do not have a pmem file (aka orphaned). 88 89 Args: 90 name: comp bdev name to query (optional; if omitted, query all comp bdevs) 91 92 Returns: 93 List of comp bdev names. 94 """ 95 params = {} 96 if name: 97 params['name'] = name 98 return client.call('bdev_compress_get_orphans', params) 99 100 101def bdev_crypto_create(client, base_bdev_name, name, crypto_pmd, key, cipher=None, key2=None): 102 """Construct a crypto virtual block device. 103 104 Args: 105 base_bdev_name: name of the underlying base bdev 106 name: name for the crypto vbdev 107 crypto_pmd: name of of the DPDK crypto driver to use 108 key: key 109 110 Returns: 111 Name of created virtual block device. 112 """ 113 params = {'base_bdev_name': base_bdev_name, 'name': name, 'crypto_pmd': crypto_pmd, 'key': key} 114 if cipher: 115 params['cipher'] = cipher 116 if key2: 117 params['key2'] = key2 118 return client.call('bdev_crypto_create', params) 119 120 121def bdev_crypto_delete(client, name): 122 """Delete crypto virtual block device. 123 124 Args: 125 name: name of crypto vbdev to delete 126 """ 127 params = {'name': name} 128 return client.call('bdev_crypto_delete', params) 129 130 131def bdev_ocf_create(client, name, mode, cache_line_size, cache_bdev_name, core_bdev_name): 132 """Add an OCF block device 133 134 Args: 135 name: name of constructed OCF bdev 136 mode: OCF cache mode: {'wb', 'wt', 'pt', 'wa', 'wi', 'wo'} 137 cache_line_size: OCF cache line size. The unit is KiB: {4, 8, 16, 32, 64} 138 cache_bdev_name: name of underlying cache bdev 139 core_bdev_name: name of underlying core bdev 140 141 Returns: 142 Name of created block device 143 """ 144 params = { 145 'name': name, 146 'mode': mode, 147 'cache_line_size': cache_line_size, 148 'cache_bdev_name': cache_bdev_name, 149 'core_bdev_name': core_bdev_name, 150 } 151 152 return client.call('bdev_ocf_create', params) 153 154 155def bdev_ocf_delete(client, name): 156 """Delete an OCF device 157 158 Args: 159 name: name of OCF bdev 160 161 """ 162 params = {'name': name} 163 164 return client.call('bdev_ocf_delete', params) 165 166 167def bdev_ocf_get_stats(client, name): 168 """Get statistics of chosen OCF block device 169 170 Args: 171 name: name of OCF bdev 172 173 Returns: 174 Statistics as json object 175 """ 176 params = {'name': name} 177 178 return client.call('bdev_ocf_get_stats', params) 179 180 181def bdev_ocf_get_bdevs(client, name=None): 182 """Get list of OCF devices including unregistered ones 183 184 Args: 185 name: name of OCF vbdev or name of cache device or name of core device (optional) 186 187 Returns: 188 Array of OCF devices with their current status 189 """ 190 params = None 191 if name: 192 params = {'name': name} 193 return client.call('bdev_ocf_get_bdevs', params) 194 195 196def bdev_ocf_set_cache_mode(client, name, mode): 197 """Set cache mode of OCF block device 198 199 Args: 200 name: name of OCF bdev 201 mode: OCF cache mode: {'wb', 'wt', 'pt', 'wa', 'wi', 'wo'} 202 203 Returns: 204 New cache mode name 205 """ 206 params = { 207 'name': name, 208 'mode': mode, 209 } 210 211 return client.call('bdev_ocf_set_cache_mode', params) 212 213 214def bdev_ocf_set_seqcutoff(client, name, policy, threshold, promotion_count): 215 """Set sequential cutoff parameters on all cores for the given OCF cache device 216 217 Args: 218 name: Name of OCF cache bdev 219 policy: Sequential cutoff policy 220 threshold: Activation threshold [KiB] (optional) 221 promotion_count: Promotion request count (optional) 222 """ 223 params = { 224 'name': name, 225 'policy': policy, 226 } 227 if threshold: 228 params['threshold'] = threshold 229 if promotion_count: 230 params['promotion_count'] = promotion_count 231 232 return client.call('bdev_ocf_set_seqcutoff', params) 233 234 235def bdev_malloc_create(client, num_blocks, block_size, name=None, uuid=None, optimal_io_boundary=None): 236 """Construct a malloc block device. 237 238 Args: 239 num_blocks: size of block device in blocks 240 block_size: block size of device; must be a power of 2 and at least 512 241 name: name of block device (optional) 242 uuid: UUID of block device (optional) 243 optimal_io_boundary: Split on optimal IO boundary, in number of blocks, default 0 (disabled, optional) 244 245 Returns: 246 Name of created block device. 247 """ 248 params = {'num_blocks': num_blocks, 'block_size': block_size} 249 if name: 250 params['name'] = name 251 if uuid: 252 params['uuid'] = uuid 253 if optimal_io_boundary: 254 params['optimal_io_boundary'] = optimal_io_boundary 255 return client.call('bdev_malloc_create', params) 256 257 258def bdev_malloc_delete(client, name): 259 """Delete malloc block device. 260 261 Args: 262 bdev_name: name of malloc bdev to delete 263 """ 264 params = {'name': name} 265 return client.call('bdev_malloc_delete', params) 266 267 268def bdev_null_create(client, num_blocks, block_size, name, uuid=None, md_size=None, 269 dif_type=None, dif_is_head_of_md=None): 270 """Construct a null block device. 271 272 Args: 273 num_blocks: size of block device in blocks 274 block_size: block size of device; data part size must be a power of 2 and at least 512 275 name: name of block device 276 uuid: UUID of block device (optional) 277 md_size: metadata size of device (optional) 278 dif_type: protection information type (optional) 279 dif_is_head_of_md: protection information is in the first 8 bytes of metadata (optional) 280 281 Returns: 282 Name of created block device. 283 """ 284 params = {'name': name, 'num_blocks': num_blocks, 285 'block_size': block_size} 286 if uuid: 287 params['uuid'] = uuid 288 if md_size: 289 params['md_size'] = md_size 290 if dif_type: 291 params['dif_type'] = dif_type 292 if dif_is_head_of_md: 293 params['dif_is_head_of_md'] = dif_is_head_of_md 294 return client.call('bdev_null_create', params) 295 296 297def bdev_null_delete(client, name): 298 """Remove null bdev from the system. 299 300 Args: 301 name: name of null bdev to delete 302 """ 303 params = {'name': name} 304 return client.call('bdev_null_delete', params) 305 306 307def bdev_null_resize(client, name, new_size): 308 """Resize null bdev in the system. 309 310 Args: 311 name: name of null bdev to resize 312 new_size: new bdev size of resize operation. The unit is MiB 313 """ 314 params = { 315 'name': name, 316 'new_size': new_size, 317 } 318 return client.call('bdev_null_resize', params) 319 320 321def bdev_raid_get_bdevs(client, category): 322 """Get list of raid bdevs based on category 323 324 Args: 325 category: any one of all or online or configuring or offline 326 327 Returns: 328 List of raid bdev names 329 """ 330 params = {'category': category} 331 return client.call('bdev_raid_get_bdevs', params) 332 333 334def bdev_raid_create(client, name, raid_level, base_bdevs, strip_size=None, strip_size_kb=None): 335 """Create raid bdev. Either strip size arg will work but one is required. 336 337 Args: 338 name: user defined raid bdev name 339 strip_size (deprecated): strip size of raid bdev in KB, supported values like 8, 16, 32, 64, 128, 256, etc 340 strip_size_kb: strip size of raid bdev in KB, supported values like 8, 16, 32, 64, 128, 256, etc 341 raid_level: raid level of raid bdev, supported values 0 342 base_bdevs: Space separated names of Nvme bdevs in double quotes, like "Nvme0n1 Nvme1n1 Nvme2n1" 343 344 Returns: 345 None 346 """ 347 params = {'name': name, 'raid_level': raid_level, 'base_bdevs': base_bdevs} 348 349 if strip_size: 350 params['strip_size'] = strip_size 351 352 if strip_size_kb: 353 params['strip_size_kb'] = strip_size_kb 354 355 return client.call('bdev_raid_create', params) 356 357 358def bdev_raid_delete(client, name): 359 """Delete raid bdev 360 361 Args: 362 name: raid bdev name 363 364 Returns: 365 None 366 """ 367 params = {'name': name} 368 return client.call('bdev_raid_delete', params) 369 370 371def bdev_aio_create(client, filename, name, block_size=None): 372 """Construct a Linux AIO block device. 373 374 Args: 375 filename: path to device or file (ex: /dev/sda) 376 name: name of block device 377 block_size: block size of device (optional; autodetected if omitted) 378 379 Returns: 380 Name of created block device. 381 """ 382 params = {'name': name, 383 'filename': filename} 384 385 if block_size: 386 params['block_size'] = block_size 387 388 return client.call('bdev_aio_create', params) 389 390 391def bdev_aio_rescan(client, name): 392 """Rescan a Linux AIO block device. 393 394 Args: 395 bdev_name: name of aio bdev to delete 396 """ 397 params = {'name': name} 398 return client.call('bdev_aio_rescan', params) 399 400 401def bdev_aio_delete(client, name): 402 """Remove aio bdev from the system. 403 404 Args: 405 bdev_name: name of aio bdev to delete 406 """ 407 params = {'name': name} 408 return client.call('bdev_aio_delete', params) 409 410 411def bdev_uring_create(client, filename, name, block_size=None): 412 """Create a bdev with Linux io_uring backend. 413 414 Args: 415 filename: path to device or file (ex: /dev/nvme0n1) 416 name: name of bdev 417 block_size: block size of device (optional; autodetected if omitted) 418 419 Returns: 420 Name of created bdev. 421 """ 422 params = {'name': name, 423 'filename': filename} 424 425 if block_size: 426 params['block_size'] = block_size 427 428 return client.call('bdev_uring_create', params) 429 430 431def bdev_uring_delete(client, name): 432 """Delete a uring bdev. 433 434 Args: 435 name: name of uring bdev to delete 436 """ 437 params = {'name': name} 438 return client.call('bdev_uring_delete', params) 439 440 441def bdev_nvme_set_options(client, action_on_timeout=None, timeout_us=None, timeout_admin_us=None, 442 keep_alive_timeout_ms=None, retry_count=None, arbitration_burst=None, 443 low_priority_weight=None, medium_priority_weight=None, high_priority_weight=None, 444 nvme_adminq_poll_period_us=None, nvme_ioq_poll_period_us=None, io_queue_requests=None, 445 delay_cmd_submit=None, transport_retry_count=None, bdev_retry_count=None, 446 transport_ack_timeout=None, ctrlr_loss_timeout_sec=None, reconnect_delay_sec=None, 447 fast_io_fail_timeout_sec=None, disable_auto_failback=None): 448 """Set options for the bdev nvme. This is startup command. 449 450 Args: 451 action_on_timeout: action to take on command time out. Valid values are: none, reset, abort (optional) 452 timeout_us: Timeout for each command, in microseconds. If 0, don't track timeouts (optional) 453 timeout_admin_us: Timeout for each admin command, in microseconds. If 0, treat same as io timeouts (optional) 454 keep_alive_timeout_ms: Keep alive timeout period in millisecond, default is 10s (optional) 455 retry_count: The number of attempts per I/O when an I/O fails (deprecated) (optional) 456 arbitration_burst: The value is expressed as a power of two (optional) 457 low_priority_weight: The number of commands that may be executed from the low priority queue at one time (optional) 458 medium_priority_weight: The number of commands that may be executed from the medium priority queue at one time (optional) 459 high_priority_weight: The number of commands that may be executed from the high priority queue at one time (optional) 460 nvme_adminq_poll_period_us: How often the admin queue is polled for asynchronous events in microseconds (optional) 461 nvme_ioq_poll_period_us: How often to poll I/O queues for completions in microseconds (optional) 462 io_queue_requests: The number of requests allocated for each NVMe I/O queue. Default: 512 (optional) 463 delay_cmd_submit: Enable delayed NVMe command submission to allow batching of multiple commands (optional) 464 transport_retry_count: The number of attempts per I/O in the transport layer when an I/O fails (optional) 465 bdev_retry_count: The number of attempts per I/O in the bdev layer when an I/O fails. -1 means infinite retries. (optional) 466 transport_ack_timeout: Time to wait ack until packet retransmission for RDMA or until closes connection for TCP. 467 Range 0-31 where 0 is driver-specific default value (optional) 468 ctrlr_loss_timeout_sec: Time to wait until ctrlr is reconnected before deleting ctrlr. 469 -1 means infinite reconnect retries. 0 means no reconnect retry. 470 If reconnect_delay_sec is zero, ctrlr_loss_timeout_sec has to be zero. 471 If reconnect_delay_sec is non-zero, ctrlr_loss_timeout_sec has to be -1 or not less than reconnect_delay_sec. 472 This can be overridden by bdev_nvme_attach_controller. (optional) 473 reconnect_delay_sec: Time to delay a reconnect retry. 474 If ctrlr_loss_timeout_sec is zero, reconnect_delay_sec has to be zero. 475 If ctrlr_loss_timeout_sec is -1, reconnect_delay_sec has to be non-zero. 476 If ctrlr_loss_timeout_sec is not -1 or zero, reconnect_sec has to be non-zero and less than ctrlr_loss_timeout_sec. 477 This can be overridden by bdev_nvme_attach_controller. (optional) 478 fail_io_fast_timeout_sec: Time to wait until ctrlr is reconnected before failing I/O to ctrlr. 479 0 means no such timeout. 480 If fast_io_fail_timeout_sec is not zero, it has to be not less than reconnect_delay_sec and less than 481 ctrlr_loss_timeout_sec if ctrlr_loss_timeout_sec is not -1. 482 This can be overridden by bdev_nvme_attach_controller. (optional) 483 disable_auto_failback: Disable automatic failback. bdev_nvme_set_preferred_path can be used to do manual failback. 484 By default, immediately failback to the preferred I/O path if it is restored. (optional) 485 486 """ 487 params = {} 488 489 if action_on_timeout: 490 params['action_on_timeout'] = action_on_timeout 491 492 if timeout_us is not None: 493 params['timeout_us'] = timeout_us 494 495 if timeout_admin_us is not None: 496 params['timeout_admin_us'] = timeout_admin_us 497 498 if keep_alive_timeout_ms is not None: 499 params['keep_alive_timeout_ms'] = keep_alive_timeout_ms 500 501 if retry_count is not None: 502 print("WARNING: retry_count is deprecated, please use transport_retry_count.") 503 params['retry_count'] = retry_count 504 505 if arbitration_burst is not None: 506 params['arbitration_burst'] = arbitration_burst 507 508 if low_priority_weight is not None: 509 params['low_priority_weight'] = low_priority_weight 510 511 if medium_priority_weight is not None: 512 params['medium_priority_weight'] = medium_priority_weight 513 514 if high_priority_weight is not None: 515 params['high_priority_weight'] = high_priority_weight 516 517 if nvme_adminq_poll_period_us: 518 params['nvme_adminq_poll_period_us'] = nvme_adminq_poll_period_us 519 520 if nvme_ioq_poll_period_us is not None: 521 params['nvme_ioq_poll_period_us'] = nvme_ioq_poll_period_us 522 523 if io_queue_requests is not None: 524 params['io_queue_requests'] = io_queue_requests 525 526 if delay_cmd_submit is not None: 527 params['delay_cmd_submit'] = delay_cmd_submit 528 529 if transport_retry_count is not None: 530 params['transport_retry_count'] = transport_retry_count 531 532 if bdev_retry_count is not None: 533 params['bdev_retry_count'] = bdev_retry_count 534 535 if transport_ack_timeout is not None: 536 params['transport_ack_timeout'] = transport_ack_timeout 537 538 if ctrlr_loss_timeout_sec is not None: 539 params['ctrlr_loss_timeout_sec'] = ctrlr_loss_timeout_sec 540 541 if reconnect_delay_sec is not None: 542 params['reconnect_delay_sec'] = reconnect_delay_sec 543 544 if fast_io_fail_timeout_sec is not None: 545 params['fast_io_fail_timeout_sec'] = fast_io_fail_timeout_sec 546 547 if disable_auto_failback is not None: 548 params['disable_auto_failback'] = disable_auto_failback 549 550 return client.call('bdev_nvme_set_options', params) 551 552 553def bdev_nvme_set_hotplug(client, enable, period_us=None): 554 """Set options for the bdev nvme. This is startup command. 555 556 Args: 557 enable: True to enable hotplug, False to disable. 558 period_us: how often the hotplug is processed for insert and remove events. Set 0 to reset to default. (optional) 559 """ 560 params = {'enable': enable} 561 562 if period_us: 563 params['period_us'] = period_us 564 565 return client.call('bdev_nvme_set_hotplug', params) 566 567 568def bdev_nvme_attach_controller(client, name, trtype, traddr, adrfam=None, trsvcid=None, 569 priority=None, subnqn=None, hostnqn=None, hostaddr=None, 570 hostsvcid=None, prchk_reftag=None, prchk_guard=None, 571 hdgst=None, ddgst=None, fabrics_timeout=None, multipath=None, num_io_queues=None, 572 ctrlr_loss_timeout_sec=None, reconnect_delay_sec=None, 573 fast_io_fail_timeout_sec=None): 574 """Construct block device for each NVMe namespace in the attached controller. 575 576 Args: 577 name: bdev name prefix; "n" + namespace ID will be appended to create unique names 578 trtype: transport type ("PCIe", "RDMA", "FC", "TCP") 579 traddr: transport address (PCI BDF or IP address) 580 adrfam: address family ("IPv4", "IPv6", "IB", or "FC") 581 trsvcid: transport service ID (port number for IP-based addresses) 582 priority: transport connection priority (Sock priority for TCP-based transports; optional) 583 subnqn: subsystem NQN to connect to (optional) 584 hostnqn: NQN to connect from (optional) 585 hostaddr: host transport address (IP address for IP-based transports, NULL for PCIe or FC; optional) 586 hostsvcid: host transport service ID (port number for IP-based transports, NULL for PCIe or FC; optional) 587 prchk_reftag: Enable checking of PI reference tag for I/O processing (optional) 588 prchk_guard: Enable checking of PI guard for I/O processing (optional) 589 hdgst: Enable TCP header digest (optional) 590 ddgst: Enable TCP data digest (optional) 591 fabrics_timeout: Fabrics connect timeout in us (optional) 592 multipath: The behavior when multiple paths are created ("disable", "failover", or "multipath"; failover if not specified) 593 num_io_queues: The number of IO queues to request during initialization. (optional) 594 ctrlr_loss_timeout_sec: Time to wait until ctrlr is reconnected before deleting ctrlr. 595 -1 means infinite reconnect retries. 0 means no reconnect retry. 596 If reconnect_delay_sec is zero, ctrlr_loss_timeout_sec has to be zero. 597 If reconnect_delay_sec is non-zero, ctrlr_loss_timeout_sec has to be -1 or not less than reconnect_delay_sec. 598 (optional) 599 reconnect_delay_sec: Time to delay a reconnect retry. 600 If ctrlr_loss_timeout_sec is zero, reconnect_delay_sec has to be zero. 601 If ctrlr_loss_timeout_sec is -1, reconnect_delay_sec has to be non-zero. 602 If ctrlr_loss_timeout_sec is not -1 or zero, reconnect_sec has to be non-zero and less than ctrlr_loss_timeout_sec. 603 (optional) 604 fail_io_fast_timeout_sec: Time to wait until ctrlr is reconnected before failing I/O to ctrlr. 605 0 means no such timeout. 606 If fast_io_fail_timeout_sec is not zero, it has to be not less than reconnect_delay_sec and less than 607 ctrlr_loss_timeout_sec if ctrlr_loss_timeout_sec is not -1. (optional) 608 609 Returns: 610 Names of created block devices. 611 """ 612 params = {'name': name, 613 'trtype': trtype, 614 'traddr': traddr} 615 616 if hostnqn: 617 params['hostnqn'] = hostnqn 618 619 if hostaddr: 620 params['hostaddr'] = hostaddr 621 622 if hostsvcid: 623 params['hostsvcid'] = hostsvcid 624 625 if adrfam: 626 params['adrfam'] = adrfam 627 628 if trsvcid: 629 params['trsvcid'] = trsvcid 630 631 if priority: 632 params['priority'] = priority 633 634 if subnqn: 635 params['subnqn'] = subnqn 636 637 if prchk_reftag: 638 params['prchk_reftag'] = prchk_reftag 639 640 if prchk_guard: 641 params['prchk_guard'] = prchk_guard 642 643 if hdgst: 644 params['hdgst'] = hdgst 645 646 if ddgst: 647 params['ddgst'] = ddgst 648 649 if fabrics_timeout: 650 params['fabrics_connect_timeout_us'] = fabrics_timeout 651 652 if multipath: 653 params['multipath'] = multipath 654 655 if num_io_queues: 656 params['num_io_queues'] = num_io_queues 657 658 if ctrlr_loss_timeout_sec is not None: 659 params['ctrlr_loss_timeout_sec'] = ctrlr_loss_timeout_sec 660 661 if reconnect_delay_sec is not None: 662 params['reconnect_delay_sec'] = reconnect_delay_sec 663 664 if fast_io_fail_timeout_sec is not None: 665 params['fast_io_fail_timeout_sec'] = fast_io_fail_timeout_sec 666 667 return client.call('bdev_nvme_attach_controller', params) 668 669 670def bdev_nvme_detach_controller(client, name, trtype=None, traddr=None, 671 adrfam=None, trsvcid=None, subnqn=None, 672 hostaddr=None, hostsvcid=None): 673 """Detach NVMe controller and delete any associated bdevs. Optionally, 674 If all of the transport ID options are specified, only remove that 675 transport path from the specified controller. If that is the only 676 available path for the controller, this will also result in the 677 controller being detached and the associated bdevs being deleted. 678 679 Args: 680 name: controller name 681 trtype: transport type ("PCIe", "RDMA") 682 traddr: transport address (PCI BDF or IP address) 683 adrfam: address family ("IPv4", "IPv6", "IB", or "FC") 684 trsvcid: transport service ID (port number for IP-based addresses) 685 subnqn: subsystem NQN to connect to (optional) 686 hostaddr: Host address (IP address) 687 hostsvcid: transport service ID on host side (port number) 688 """ 689 690 params = {'name': name} 691 692 if trtype: 693 params['trtype'] = trtype 694 695 if traddr: 696 params['traddr'] = traddr 697 698 if adrfam: 699 params['adrfam'] = adrfam 700 701 if trsvcid: 702 params['trsvcid'] = trsvcid 703 704 if subnqn: 705 params['subnqn'] = subnqn 706 707 if hostaddr: 708 params['hostaddr'] = hostaddr 709 710 if hostsvcid: 711 params['hostsvcid'] = hostsvcid 712 713 return client.call('bdev_nvme_detach_controller', params) 714 715 716def bdev_nvme_reset_controller(client, name): 717 """Reset NVMe controller. 718 719 Args: 720 name: controller name 721 """ 722 723 params = {'name': name} 724 725 return client.call('bdev_nvme_reset_controller', params) 726 727 728def bdev_nvme_start_discovery(client, name, trtype, traddr, adrfam=None, trsvcid=None, 729 hostnqn=None, wait_for_attach=None, ctrlr_loss_timeout_sec=None, 730 reconnect_delay_sec=None, fast_io_fail_timeout_sec=None, 731 attach_timeout_ms=None): 732 """Start discovery with the specified discovery subsystem 733 734 Args: 735 name: bdev name prefix; "n" + namespace ID will be appended to create unique names 736 trtype: transport type ("PCIe", "RDMA", "FC", "TCP") 737 traddr: transport address (PCI BDF or IP address) 738 adrfam: address family ("IPv4", "IPv6", "IB", or "FC") 739 trsvcid: transport service ID (port number for IP-based addresses) 740 hostnqn: NQN to connect from (optional) 741 wait_for_attach: Wait to complete RPC until all discovered NVM subsystems have attached (optional) 742 ctrlr_loss_timeout_sec: Time to wait until ctrlr is reconnected before deleting ctrlr. 743 -1 means infinite reconnect retries. 0 means no reconnect retry. 744 If reconnect_delay_sec is zero, ctrlr_loss_timeout_sec has to be zero. 745 If reconnect_delay_sec is non-zero, ctrlr_loss_timeout_sec has to be -1 or not less than reconnect_delay_sec. 746 (optional) 747 reconnect_delay_sec: Time to delay a reconnect retry. 748 If ctrlr_loss_timeout_sec is zero, reconnect_delay_sec has to be zero. 749 If ctrlr_loss_timeout_sec is -1, reconnect_delay_sec has to be non-zero. 750 If ctrlr_loss_timeout_sec is not -1 or zero, reconnect_sec has to be non-zero and less than ctrlr_loss_timeout_sec. 751 (optional) 752 fail_io_fast_timeout_sec: Time to wait until ctrlr is reconnected before failing I/O to ctrlr. 753 0 means no such timeout. 754 If fast_io_fail_timeout_sec is not zero, it has to be not less than reconnect_delay_sec and less than 755 ctrlr_loss_timeout_sec if ctrlr_loss_timeout_sec is not -1. (optional) 756 attach_timeout_ms: Time to wait until the discovery and all discovered NVM subsystems are attached (optional) 757 """ 758 params = {'name': name, 759 'trtype': trtype, 760 'traddr': traddr} 761 762 if hostnqn: 763 params['hostnqn'] = hostnqn 764 765 if adrfam: 766 params['adrfam'] = adrfam 767 768 if trsvcid: 769 params['trsvcid'] = trsvcid 770 771 if wait_for_attach: 772 params['wait_for_attach'] = True 773 774 if attach_timeout_ms is not None: 775 params['attach_timeout_ms'] = attach_timeout_ms 776 777 if ctrlr_loss_timeout_sec is not None: 778 params['ctrlr_loss_timeout_sec'] = ctrlr_loss_timeout_sec 779 780 if reconnect_delay_sec is not None: 781 params['reconnect_delay_sec'] = reconnect_delay_sec 782 783 if fast_io_fail_timeout_sec is not None: 784 params['fast_io_fail_timeout_sec'] = fast_io_fail_timeout_sec 785 786 return client.call('bdev_nvme_start_discovery', params) 787 788 789def bdev_nvme_stop_discovery(client, name): 790 """Stop a previously started discovery service 791 792 Args: 793 name: name of discovery service to start 794 """ 795 params = {'name': name} 796 797 return client.call('bdev_nvme_stop_discovery', params) 798 799 800def bdev_nvme_get_discovery_info(client): 801 """Get information about the automatic discovery 802 """ 803 return client.call('bdev_nvme_get_discovery_info') 804 805 806def bdev_nvme_get_io_paths(client, name): 807 """Display all or the specified NVMe bdev's active I/O paths 808 809 Args: 810 name: Name of the NVMe bdev (optional) 811 812 Returns: 813 List of active I/O paths 814 """ 815 params = {} 816 if name: 817 params['name'] = name 818 return client.call('bdev_nvme_get_io_paths', params) 819 820 821def bdev_nvme_set_preferred_path(client, name, cntlid): 822 """Set the preferred I/O path for an NVMe bdev when in multipath mode 823 824 Args: 825 name: NVMe bdev name 826 cntlid: NVMe-oF controller ID 827 """ 828 829 params = {'name': name, 830 'cntlid': cntlid} 831 832 return client.call('bdev_nvme_set_preferred_path', params) 833 834 835def bdev_nvme_set_multipath_policy(client, name, policy): 836 """Set multipath policy of the NVMe bdev 837 838 Args: 839 name: NVMe bdev name 840 policy: Multipath policy (active_passive or active_active) 841 """ 842 843 params = {'name': name, 844 'policy': policy} 845 846 return client.call('bdev_nvme_set_multipath_policy', params) 847 848 849def bdev_nvme_cuse_register(client, name): 850 """Register CUSE devices on NVMe controller. 851 852 Args: 853 name: Name of the operating NVMe controller 854 """ 855 params = {'name': name} 856 857 return client.call('bdev_nvme_cuse_register', params) 858 859 860def bdev_nvme_cuse_unregister(client, name): 861 """Unregister CUSE devices on NVMe controller. 862 863 Args: 864 name: Name of the operating NVMe controller 865 """ 866 params = {'name': name} 867 868 return client.call('bdev_nvme_cuse_unregister', params) 869 870 871def bdev_zone_block_create(client, name, base_bdev, zone_capacity, optimal_open_zones): 872 """Creates a virtual zone device on top of existing non-zoned bdev. 873 874 Args: 875 name: Zone device name 876 base_bdev: Base Nvme bdev name 877 zone_capacity: Surfaced zone capacity in blocks 878 optimal_open_zones: Number of zones required to reach optimal write speed (optional, default: 1) 879 880 Returns: 881 Name of created block device. 882 """ 883 params = {'name': name, 884 'base_bdev': base_bdev, 885 'zone_capacity': zone_capacity, 886 'optimal_open_zones': optimal_open_zones} 887 888 return client.call('bdev_zone_block_create', params) 889 890 891def bdev_zone_block_delete(client, name): 892 """Remove block zone bdev from the system. 893 894 Args: 895 name: name of block zone bdev to delete 896 """ 897 params = {'name': name} 898 return client.call('bdev_zone_block_delete', params) 899 900 901def bdev_rbd_register_cluster(client, name, user=None, config_param=None, config_file=None, key_file=None): 902 """Create a Rados Cluster object of the Ceph RBD backend. 903 904 Args: 905 name: name of Rados Cluster 906 user: Ceph user name (optional) 907 config_param: map of config keys to values (optional) 908 config_file: file path of Ceph configuration file (optional) 909 key_file: file path of Ceph key file (optional) 910 911 Returns: 912 Name of registered Rados Cluster object. 913 """ 914 params = {'name': name} 915 916 if user is not None: 917 params['user_id'] = user 918 if config_param is not None: 919 params['config_param'] = config_param 920 if config_file is not None: 921 params['config_file'] = config_file 922 if key_file is not None: 923 params['key_file'] = key_file 924 925 return client.call('bdev_rbd_register_cluster', params) 926 927 928def bdev_rbd_unregister_cluster(client, name): 929 """Remove Rados cluster object from the system. 930 931 Args: 932 name: name of Rados cluster object to unregister 933 """ 934 params = {'name': name} 935 return client.call('bdev_rbd_unregister_cluster', params) 936 937 938def bdev_rbd_get_clusters_info(client, name): 939 """Get the cluster(s) info 940 941 Args: 942 name: name of Rados cluster object to query (optional; if omitted, query all clusters) 943 944 Returns: 945 List of registered Rados cluster information objects. 946 """ 947 params = {} 948 if name: 949 params['name'] = name 950 return client.call('bdev_rbd_get_clusters_info', params) 951 952 953def bdev_rbd_create(client, pool_name, rbd_name, block_size, name=None, user=None, config=None, cluster_name=None, uuid=None): 954 """Create a Ceph RBD block device. 955 956 Args: 957 pool_name: Ceph RBD pool name 958 rbd_name: Ceph RBD image name 959 block_size: block size of RBD volume 960 name: name of block device (optional) 961 user: Ceph user name (optional) 962 config: map of config keys to values (optional) 963 cluster_name: Name to identify Rados cluster (optional) 964 uuid: UUID of block device (optional) 965 966 Returns: 967 Name of created block device. 968 """ 969 params = { 970 'pool_name': pool_name, 971 'rbd_name': rbd_name, 972 'block_size': block_size, 973 } 974 975 if name: 976 params['name'] = name 977 if user is not None: 978 params['user_id'] = user 979 if config is not None: 980 params['config'] = config 981 if cluster_name is not None: 982 params['cluster_name'] = cluster_name 983 if uuid is not None: 984 params['uuid'] = uuid 985 986 return client.call('bdev_rbd_create', params) 987 988 989def bdev_rbd_delete(client, name): 990 """Remove rbd bdev from the system. 991 992 Args: 993 name: name of rbd bdev to delete 994 """ 995 params = {'name': name} 996 return client.call('bdev_rbd_delete', params) 997 998 999def bdev_rbd_resize(client, name, new_size): 1000 """Resize rbd bdev in the system. 1001 1002 Args: 1003 name: name of rbd bdev to resize 1004 new_size: new bdev size of resize operation. The unit is MiB 1005 """ 1006 params = { 1007 'name': name, 1008 'new_size': new_size, 1009 } 1010 return client.call('bdev_rbd_resize', params) 1011 1012 1013def bdev_error_create(client, base_name): 1014 """Construct an error injection block device. 1015 1016 Args: 1017 base_name: base bdev name 1018 """ 1019 params = {'base_name': base_name} 1020 return client.call('bdev_error_create', params) 1021 1022 1023def bdev_delay_create(client, base_bdev_name, name, avg_read_latency, p99_read_latency, avg_write_latency, p99_write_latency): 1024 """Construct a delay block device. 1025 1026 Args: 1027 base_bdev_name: name of the existing bdev 1028 name: name of block device 1029 avg_read_latency: complete 99% of read ops with this delay 1030 p99_read_latency: complete 1% of read ops with this delay 1031 avg_write_latency: complete 99% of write ops with this delay 1032 p99_write_latency: complete 1% of write ops with this delay 1033 1034 Returns: 1035 Name of created block device. 1036 """ 1037 params = { 1038 'base_bdev_name': base_bdev_name, 1039 'name': name, 1040 'avg_read_latency': avg_read_latency, 1041 'p99_read_latency': p99_read_latency, 1042 'avg_write_latency': avg_write_latency, 1043 'p99_write_latency': p99_write_latency, 1044 } 1045 return client.call('bdev_delay_create', params) 1046 1047 1048def bdev_delay_delete(client, name): 1049 """Remove delay bdev from the system. 1050 1051 Args: 1052 name: name of delay bdev to delete 1053 """ 1054 params = {'name': name} 1055 return client.call('bdev_delay_delete', params) 1056 1057 1058def bdev_delay_update_latency(client, delay_bdev_name, latency_type, latency_us): 1059 """Update the latency value for a delay block device 1060 1061 Args: 1062 delay_bdev_name: name of the delay bdev 1063 latency_type: 'one of: avg_read, avg_write, p99_read, p99_write. No other values accepted.' 1064 latency_us: 'new latency value.' 1065 1066 Returns: 1067 True if successful, or a specific error otherwise. 1068 """ 1069 params = { 1070 'delay_bdev_name': delay_bdev_name, 1071 'latency_type': latency_type, 1072 'latency_us': latency_us, 1073 } 1074 return client.call('bdev_delay_update_latency', params) 1075 1076 1077def bdev_error_delete(client, name): 1078 """Remove error bdev from the system. 1079 1080 Args: 1081 bdev_name: name of error bdev to delete 1082 """ 1083 params = {'name': name} 1084 return client.call('bdev_error_delete', params) 1085 1086 1087def bdev_iscsi_create(client, name, url, initiator_iqn): 1088 """Construct an iSCSI block device. 1089 1090 Args: 1091 name: name of block device 1092 url: iSCSI URL 1093 initiator_iqn: IQN name to be used by initiator 1094 1095 Returns: 1096 Name of created block device. 1097 """ 1098 params = { 1099 'name': name, 1100 'url': url, 1101 'initiator_iqn': initiator_iqn, 1102 } 1103 return client.call('bdev_iscsi_create', params) 1104 1105 1106def bdev_iscsi_delete(client, name): 1107 """Remove iSCSI bdev from the system. 1108 1109 Args: 1110 bdev_name: name of iSCSI bdev to delete 1111 """ 1112 params = {'name': name} 1113 return client.call('bdev_iscsi_delete', params) 1114 1115 1116def bdev_pmem_create(client, pmem_file, name): 1117 """Construct a libpmemblk block device. 1118 1119 Args: 1120 pmem_file: path to pmemblk pool file 1121 name: name of block device 1122 1123 Returns: 1124 Name of created block device. 1125 """ 1126 params = { 1127 'pmem_file': pmem_file, 1128 'name': name 1129 } 1130 return client.call('bdev_pmem_create', params) 1131 1132 1133def bdev_pmem_delete(client, name): 1134 """Remove pmem bdev from the system. 1135 1136 Args: 1137 name: name of pmem bdev to delete 1138 """ 1139 params = {'name': name} 1140 return client.call('bdev_pmem_delete', params) 1141 1142 1143def bdev_passthru_create(client, base_bdev_name, name): 1144 """Construct a pass-through block device. 1145 1146 Args: 1147 base_bdev_name: name of the existing bdev 1148 name: name of block device 1149 1150 Returns: 1151 Name of created block device. 1152 """ 1153 params = { 1154 'base_bdev_name': base_bdev_name, 1155 'name': name, 1156 } 1157 return client.call('bdev_passthru_create', params) 1158 1159 1160def bdev_passthru_delete(client, name): 1161 """Remove pass through bdev from the system. 1162 1163 Args: 1164 name: name of pass through bdev to delete 1165 """ 1166 params = {'name': name} 1167 return client.call('bdev_passthru_delete', params) 1168 1169 1170def bdev_opal_create(client, nvme_ctrlr_name, nsid, locking_range_id, range_start, range_length, password): 1171 """Create opal virtual block devices from a base nvme bdev. 1172 1173 Args: 1174 nvme_ctrlr_name: name of the nvme ctrlr 1175 nsid: namespace ID of nvme ctrlr 1176 locking_range_id: locking range ID corresponding to this virtual bdev 1177 range_start: start address of this locking range 1178 range_length: length of this locking range 1179 password: admin password of base nvme bdev 1180 1181 Returns: 1182 Name of the new created block devices. 1183 """ 1184 params = { 1185 'nvme_ctrlr_name': nvme_ctrlr_name, 1186 'nsid': nsid, 1187 'locking_range_id': locking_range_id, 1188 'range_start': range_start, 1189 'range_length': range_length, 1190 'password': password, 1191 } 1192 1193 return client.call('bdev_opal_create', params) 1194 1195 1196def bdev_opal_get_info(client, bdev_name, password): 1197 """Get opal locking range info. 1198 1199 Args: 1200 bdev_name: name of opal vbdev to get info 1201 password: admin password 1202 1203 Returns: 1204 Locking range info. 1205 """ 1206 params = { 1207 'bdev_name': bdev_name, 1208 'password': password, 1209 } 1210 1211 return client.call('bdev_opal_get_info', params) 1212 1213 1214def bdev_opal_delete(client, bdev_name, password): 1215 """Delete opal virtual bdev from the system. 1216 1217 Args: 1218 bdev_name: name of opal vbdev to delete 1219 password: admin password of base nvme bdev 1220 """ 1221 params = { 1222 'bdev_name': bdev_name, 1223 'password': password, 1224 } 1225 1226 return client.call('bdev_opal_delete', params) 1227 1228 1229def bdev_opal_new_user(client, bdev_name, admin_password, user_id, user_password): 1230 """Add a user to opal bdev who can set lock state for this bdev. 1231 1232 Args: 1233 bdev_name: name of opal vbdev 1234 admin_password: admin password 1235 user_id: ID of the user who will be added to this opal bdev 1236 user_password: password set for this user 1237 """ 1238 params = { 1239 'bdev_name': bdev_name, 1240 'admin_password': admin_password, 1241 'user_id': user_id, 1242 'user_password': user_password, 1243 } 1244 1245 return client.call('bdev_opal_new_user', params) 1246 1247 1248def bdev_opal_set_lock_state(client, bdev_name, user_id, password, lock_state): 1249 """set lock state for an opal bdev. 1250 1251 Args: 1252 bdev_name: name of opal vbdev 1253 user_id: ID of the user who will set lock state 1254 password: password of the user 1255 lock_state: lock state to set 1256 """ 1257 params = { 1258 'bdev_name': bdev_name, 1259 'user_id': user_id, 1260 'password': password, 1261 'lock_state': lock_state, 1262 } 1263 1264 return client.call('bdev_opal_set_lock_state', params) 1265 1266 1267def bdev_split_create(client, base_bdev, split_count, split_size_mb=None): 1268 """Create split block devices from a base bdev. 1269 1270 Args: 1271 base_bdev: name of bdev to split 1272 split_count: number of split bdevs to create 1273 split_size_mb: size of each split volume in MiB (optional) 1274 1275 Returns: 1276 List of created block devices. 1277 """ 1278 params = { 1279 'base_bdev': base_bdev, 1280 'split_count': split_count, 1281 } 1282 if split_size_mb: 1283 params['split_size_mb'] = split_size_mb 1284 1285 return client.call('bdev_split_create', params) 1286 1287 1288def bdev_split_delete(client, base_bdev): 1289 """Delete split block devices. 1290 1291 Args: 1292 base_bdev: name of previously split bdev 1293 """ 1294 params = { 1295 'base_bdev': base_bdev, 1296 } 1297 1298 return client.call('bdev_split_delete', params) 1299 1300 1301def bdev_ftl_create(client, name, base_bdev, **kwargs): 1302 """Construct FTL bdev 1303 1304 Args: 1305 name: name of the bdev 1306 base_bdev: name of the base bdev 1307 kwargs: optional parameters 1308 """ 1309 params = {'name': name, 1310 'base_bdev': base_bdev} 1311 for key, value in kwargs.items(): 1312 if value is not None: 1313 params[key] = value 1314 1315 return client.call('bdev_ftl_create', params) 1316 1317 1318def bdev_ftl_delete(client, name): 1319 """Delete FTL bdev 1320 1321 Args: 1322 name: name of the bdev 1323 """ 1324 params = {'name': name} 1325 1326 return client.call('bdev_ftl_delete', params) 1327 1328 1329def bdev_get_bdevs(client, name=None, timeout=None): 1330 """Get information about block devices. 1331 1332 Args: 1333 name: bdev name to query (optional; if omitted, query all bdevs) 1334 timeout: time in ms to wait for the bdev with specified name to appear 1335 1336 Returns: 1337 List of bdev information objects. 1338 """ 1339 params = {} 1340 if name: 1341 params['name'] = name 1342 if timeout: 1343 params['timeout'] = timeout 1344 return client.call('bdev_get_bdevs', params) 1345 1346 1347def bdev_get_iostat(client, name=None): 1348 """Get I/O statistics for block devices. 1349 1350 Args: 1351 name: bdev name to query (optional; if omitted, query all bdevs) 1352 1353 Returns: 1354 I/O statistics for the requested block devices. 1355 """ 1356 params = {} 1357 if name: 1358 params['name'] = name 1359 return client.call('bdev_get_iostat', params) 1360 1361 1362def bdev_enable_histogram(client, name, enable): 1363 """Control whether histogram is enabled for specified bdev. 1364 1365 Args: 1366 bdev_name: name of bdev 1367 """ 1368 params = {'name': name, "enable": enable} 1369 return client.call('bdev_enable_histogram', params) 1370 1371 1372def bdev_get_histogram(client, name): 1373 """Get histogram for specified bdev. 1374 1375 Args: 1376 bdev_name: name of bdev 1377 """ 1378 params = {'name': name} 1379 return client.call('bdev_get_histogram', params) 1380 1381 1382def bdev_error_inject_error(client, name, io_type, error_type, num=1): 1383 """Inject an error via an error bdev. 1384 1385 Args: 1386 name: name of error bdev 1387 io_type: one of "clear", "read", "write", "unmap", "flush", or "all" 1388 error_type: one of "failure" or "pending" 1389 num: number of commands to fail 1390 """ 1391 params = { 1392 'name': name, 1393 'io_type': io_type, 1394 'error_type': error_type, 1395 'num': num, 1396 } 1397 1398 return client.call('bdev_error_inject_error', params) 1399 1400 1401def bdev_set_qd_sampling_period(client, name, period): 1402 """Enable queue depth tracking on a specified bdev. 1403 1404 Args: 1405 name: name of a bdev on which to track queue depth. 1406 period: period (in microseconds) at which to update the queue depth reading. If set to 0, polling will be disabled. 1407 """ 1408 1409 params = {} 1410 params['name'] = name 1411 params['period'] = period 1412 return client.call('bdev_set_qd_sampling_period', params) 1413 1414 1415def bdev_set_qos_limit( 1416 client, 1417 name, 1418 rw_ios_per_sec=None, 1419 rw_mbytes_per_sec=None, 1420 r_mbytes_per_sec=None, 1421 w_mbytes_per_sec=None): 1422 """Set QoS rate limit on a block device. 1423 1424 Args: 1425 name: name of block device 1426 rw_ios_per_sec: R/W IOs per second limit (>=1000, example: 20000). 0 means unlimited. 1427 rw_mbytes_per_sec: R/W megabytes per second limit (>=10, example: 100). 0 means unlimited. 1428 r_mbytes_per_sec: Read megabytes per second limit (>=10, example: 100). 0 means unlimited. 1429 w_mbytes_per_sec: Write megabytes per second limit (>=10, example: 100). 0 means unlimited. 1430 """ 1431 params = {} 1432 params['name'] = name 1433 if rw_ios_per_sec is not None: 1434 params['rw_ios_per_sec'] = rw_ios_per_sec 1435 if rw_mbytes_per_sec is not None: 1436 params['rw_mbytes_per_sec'] = rw_mbytes_per_sec 1437 if r_mbytes_per_sec is not None: 1438 params['r_mbytes_per_sec'] = r_mbytes_per_sec 1439 if w_mbytes_per_sec is not None: 1440 params['w_mbytes_per_sec'] = w_mbytes_per_sec 1441 return client.call('bdev_set_qos_limit', params) 1442 1443 1444def bdev_nvme_apply_firmware(client, bdev_name, filename): 1445 """Download and commit firmware to NVMe device. 1446 1447 Args: 1448 bdev_name: name of NVMe block device 1449 filename: filename of the firmware to download 1450 """ 1451 params = { 1452 'filename': filename, 1453 'bdev_name': bdev_name, 1454 } 1455 return client.call('bdev_nvme_apply_firmware', params) 1456 1457 1458def bdev_nvme_get_transport_statistics(client): 1459 """Get bdev_nvme poll group transport statistics""" 1460 return client.call('bdev_nvme_get_transport_statistics') 1461 1462 1463def bdev_nvme_get_controller_health_info(client, name): 1464 """Display health log of the required NVMe bdev controller. 1465 1466 Args: 1467 name: name of the required NVMe bdev controller 1468 1469 Returns: 1470 Health log for the requested NVMe bdev controller. 1471 """ 1472 params = {} 1473 params['name'] = name 1474 return client.call('bdev_nvme_get_controller_health_info', params) 1475