null_blk.rst 4.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129
  1. .. SPDX-License-Identifier: GPL-2.0
  2. ========================
  3. Null block device driver
  4. ========================
  5. Overview
  6. ========
  7. The null block device (``/dev/nullb*``) is used for benchmarking the various
  8. block-layer implementations. It emulates a block device of X gigabytes in size.
  9. It does not execute any read/write operation, just mark them as complete in
  10. the request queue. The following instances are possible:
  11. Multi-queue block-layer
  12. - Request-based.
  13. - Configurable submission queues per device.
  14. No block-layer (Known as bio-based)
  15. - Bio-based. IO requests are submitted directly to the device driver.
  16. - Directly accepts bio data structure and returns them.
  17. All of them have a completion queue for each core in the system.
  18. Module parameters
  19. =================
  20. queue_mode=[0-2]: Default: 2-Multi-queue
  21. Selects which block-layer the module should instantiate with.
  22. = ============
  23. 0 Bio-based
  24. 1 Single-queue (deprecated)
  25. 2 Multi-queue
  26. = ============
  27. home_node=[0--nr_nodes]: Default: NUMA_NO_NODE
  28. Selects what CPU node the data structures are allocated from.
  29. gb=[Size in GB]: Default: 250GB
  30. The size of the device reported to the system.
  31. bs=[Block size (in bytes)]: Default: 512 bytes
  32. The block size reported to the system.
  33. nr_devices=[Number of devices]: Default: 1
  34. Number of block devices instantiated. They are instantiated as /dev/nullb0,
  35. etc.
  36. irqmode=[0-2]: Default: 1-Soft-irq
  37. The completion mode used for completing IOs to the block-layer.
  38. = ===========================================================================
  39. 0 None.
  40. 1 Soft-irq. Uses IPI to complete IOs across CPU nodes. Simulates the overhead
  41. when IOs are issued from another CPU node than the home the device is
  42. connected to.
  43. 2 Timer: Waits a specific period (completion_nsec) for each IO before
  44. completion.
  45. = ===========================================================================
  46. completion_nsec=[ns]: Default: 10,000ns
  47. Combined with irqmode=2 (timer). The time each completion event must wait.
  48. submit_queues=[1..nr_cpus]: Default: 1
  49. The number of submission queues attached to the device driver. If unset, it
  50. defaults to 1. For multi-queue, it is ignored when use_per_node_hctx module
  51. parameter is 1.
  52. hw_queue_depth=[0..qdepth]: Default: 64
  53. The hardware queue depth of the device.
  54. Multi-queue specific parameters
  55. -------------------------------
  56. use_per_node_hctx=[0/1]: Default: 0
  57. Number of hardware context queues.
  58. = =====================================================================
  59. 0 The number of submit queues are set to the value of the submit_queues
  60. parameter.
  61. 1 The multi-queue block layer is instantiated with a hardware dispatch
  62. queue for each CPU node in the system.
  63. = =====================================================================
  64. no_sched=[0/1]: Default: 0
  65. Enable/disable the io scheduler.
  66. = ======================================
  67. 0 nullb* use default blk-mq io scheduler
  68. 1 nullb* doesn't use io scheduler
  69. = ======================================
  70. blocking=[0/1]: Default: 0
  71. Blocking behavior of the request queue.
  72. = ===============================================================
  73. 0 Register as a non-blocking blk-mq driver device.
  74. 1 Register as a blocking blk-mq driver device, null_blk will set
  75. the BLK_MQ_F_BLOCKING flag, indicating that it sometimes/always
  76. needs to block in its ->queue_rq() function.
  77. = ===============================================================
  78. shared_tags=[0/1]: Default: 0
  79. Sharing tags between devices.
  80. = ================================================================
  81. 0 Tag set is not shared.
  82. 1 Tag set shared between devices for blk-mq. Only makes sense with
  83. nr_devices > 1, otherwise there's no tag set to share.
  84. = ================================================================
  85. zoned=[0/1]: Default: 0
  86. Device is a random-access or a zoned block device.
  87. = ======================================================================
  88. 0 Block device is exposed as a random-access block device.
  89. 1 Block device is exposed as a host-managed zoned block device. Requires
  90. CONFIG_BLK_DEV_ZONED.
  91. = ======================================================================
  92. zone_size=[MB]: Default: 256
  93. Per zone size when exposed as a zoned block device. Must be a power of two.
  94. zone_nr_conv=[nr_conv]: Default: 0
  95. The number of conventional zones to create when block device is zoned. If
  96. zone_nr_conv >= nr_zones, it will be reduced to nr_zones - 1.