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 Multi-queue specific parameters
  76 -------------------------------
  77
  78 use_per_node_hctx=[0/1]: Default: 0
  79   Number of hardware context queues.
  80
  81   =  =====================================================================
  82   0  The number of submit queues are set to the value of the submit_queues
  83      parameter.
  84   1  The multi-queue block layer is instantiated with a hardware dispatch
  85      queue for each CPU node in the system.
  86   =  =====================================================================
  87
  88 no_sched=[0/1]: Default: 0
  89   Enable/disable the io scheduler.
  90
  91   =  ======================================
  92   0  nullb* use default blk-mq io scheduler
  93   1  nullb* doesn't use io scheduler
  94   =  ======================================
  95
  96 blocking=[0/1]: Default: 0
  97   Blocking behavior of the request queue.
  98
  99   =  ===============================================================
 100   0  Register as a non-blocking blk-mq driver device.
 101   1  Register as a blocking blk-mq driver device, null_blk will set
 102      the BLK_MQ_F_BLOCKING flag, indicating that it sometimes/always
 103      needs to block in its ->queue_rq() function.
 104   =  ===============================================================
 105
 106 shared_tags=[0/1]: Default: 0
 107   Sharing tags between devices.
 108
 109   =  ================================================================
 110   0  Tag set is not shared.
 111   1  Tag set shared between devices for blk-mq. Only makes sense with
 112      nr_devices > 1, otherwise there's no tag set to share.
 113   =  ================================================================
 114
 115 zoned=[0/1]: Default: 0
 116   Device is a random-access or a zoned block device.
 117
 118   =  ======================================================================
 119   0  Block device is exposed as a random-access block device.
 120   1  Block device is exposed as a host-managed zoned block device. Requires
 121      CONFIG_BLK_DEV_ZONED.
 122   =  ======================================================================
 123
 124 zone_size=[MB]: Default: 256
 125   Per zone size when exposed as a zoned block device. Must be a power of two.
 126
 127 zone_nr_conv=[nr_conv]: Default: 0
 128   The number of conventional zones to create when block device is zoned.  If
 129   zone_nr_conv >= nr_zones, it will be reduced to nr_zones - 1.