linux/Documentation/block/null_blk.rst
<<
>>
Prefs
   1.. SPDX-License-Identifier: GPL-2.0
   2
   3========================
   4Null block device driver
   5========================
   6
   7Overview
   8========
   9
  10The null block device (``/dev/nullb*``) is used for benchmarking the various
  11block-layer implementations. It emulates a block device of X gigabytes in size.
  12It does not execute any read/write operation, just mark them as complete in
  13the 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
  25All of them have a completion queue for each core in the system.
  26
  27Module parameters
  28=================
  29
  30queue_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
  39home_node=[0--nr_nodes]: Default: NUMA_NO_NODE
  40  Selects what CPU node the data structures are allocated from.
  41
  42gb=[Size in GB]: Default: 250GB
  43  The size of the device reported to the system.
  44
  45bs=[Block size (in bytes)]: Default: 512 bytes
  46  The block size reported to the system.
  47
  48nr_devices=[Number of devices]: Default: 1
  49  Number of block devices instantiated. They are instantiated as /dev/nullb0,
  50  etc.
  51
  52irqmode=[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
  64completion_nsec=[ns]: Default: 10,000ns
  65  Combined with irqmode=2 (timer). The time each completion event must wait.
  66
  67submit_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
  72hw_queue_depth=[0..qdepth]: Default: 64
  73  The hardware queue depth of the device.
  74
  75Multi-queue specific parameters
  76-------------------------------
  77
  78use_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
  88no_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
  96blocking=[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
 106shared_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
 115zoned=[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
 124zone_size=[MB]: Default: 256
 125  Per zone size when exposed as a zoned block device. Must be a power of two.
 126
 127zone_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.
 130