Documentation/block/null_blk.rst

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