[linux-2.6-block.git] / Documentation / block / null_blk.txt

Null block device driver
================================================================================

I. Overview

The null block device (/dev/nullb*) is used for benchmarking the various
block-layer implementations. It emulates a block device of X gigabytes in size.
The following instances are possible:

  Single-queue block-layer
    - Request-based.
    - Single submission queue per device.
    - Implements IO scheduling algorithms (CFQ, Deadline, noop).
  Multi-queue block-layer
    - Request-based.
    - Configurable submission queues per device.
  No block-layer (Known as bio-based)
    - Bio-based. IO requests are submitted directly to the device driver.
    - Directly accepts bio data structure and returns them.

All of them have a completion queue for each core in the system.

II. Module parameters applicable for all instances:

queue_mode=[0-2]: Default: 2-Multi-queue
  Selects which block-layer the module should instantiate with.

  0: Bio-based.
  1: Single-queue.
  2: Multi-queue.

home_node=[0--nr_nodes]: Default: NUMA_NO_NODE
  Selects what CPU node the data structures are allocated from.

gb=[Size in GB]: Default: 250GB
  The size of the device reported to the system.

bs=[Block size (in bytes)]: Default: 512 bytes
  The block size reported to the system.

nr_devices=[Number of devices]: Default: 2
  Number of block devices instantiated. They are instantiated as /dev/nullb0,
  etc.

irqmode=[0-2]: Default: 1-Soft-irq
  The completion mode used for completing IOs to the block-layer.

  0: None.
  1: Soft-irq. Uses IPI to complete IOs across CPU nodes. Simulates the overhead
     when IOs are issued from another CPU node than the home the device is
     connected to.
  2: Timer: Waits a specific period (completion_nsec) for each IO before
     completion.

completion_nsec=[ns]: Default: 10.000ns
  Combined with irqmode=2 (timer). The time each completion event must wait.

submit_queues=[0..nr_cpus]:
  The number of submission queues attached to the device driver. If unset, it
  defaults to 1 on single-queue and bio-based instances. For multi-queue,
  it is ignored when use_per_node_hctx module parameter is 1.

hw_queue_depth=[0..qdepth]: Default: 64
  The hardware queue depth of the device.

III: Multi-queue specific parameters

use_per_node_hctx=[0/1]: Default: 0
  0: The number of submit queues are set to the value of the submit_queues
     parameter.
  1: The multi-queue block layer is instantiated with a hardware dispatch
     queue for each CPU node in the system.

use_lightnvm=[0/1]: Default: 0
  Register device with LightNVM. Requires blk-mq to be used.
Commit	Line	Data
12f8f4fc MB	1	Null block device driver
	2	================================================================================
	3
	4	I. Overview
	5
	6	The null block device (/dev/nullb*) is used for benchmarking the various
	7	block-layer implementations. It emulates a block device of X gigabytes in size.
	8	The following instances are possible:
	9
	10	Single-queue block-layer
	11	- Request-based.
	12	- Single submission queue per device.
	13	- Implements IO scheduling algorithms (CFQ, Deadline, noop).
	14	Multi-queue block-layer
	15	- Request-based.
	16	- Configurable submission queues per device.
	17	No block-layer (Known as bio-based)
	18	- Bio-based. IO requests are submitted directly to the device driver.
	19	- Directly accepts bio data structure and returns them.
	20
89ed05ee	21	All of them have a completion queue for each core in the system.
12f8f4fc MB	22
	23	II. Module parameters applicable for all instances:
	24
	25	queue_mode=[0-2]: Default: 2-Multi-queue
	26	Selects which block-layer the module should instantiate with.
	27
	28	0: Bio-based.
	29	1: Single-queue.
	30	2: Multi-queue.
	31
	32	home_node=[0--nr_nodes]: Default: NUMA_NO_NODE
89ed05ee	33	Selects what CPU node the data structures are allocated from.
12f8f4fc MB	34
	35	gb=[Size in GB]: Default: 250GB
	36	The size of the device reported to the system.
	37
	38	bs=[Block size (in bytes)]: Default: 512 bytes
	39	The block size reported to the system.
	40
89ed05ee	41	nr_devices=[Number of devices]: Default: 2
12f8f4fc MB	42	Number of block devices instantiated. They are instantiated as /dev/nullb0,
	43	etc.
	44
a2787312	45	irqmode=[0-2]: Default: 1-Soft-irq
12f8f4fc MB	46	The completion mode used for completing IOs to the block-layer.
	47
	48	0: None.
89ed05ee MB	49	1: Soft-irq. Uses IPI to complete IOs across CPU nodes. Simulates the overhead
89ed05ee MB	50	when IOs are issued from another CPU node than the home the device is
12f8f4fc MB	51	connected to.
	52	2: Timer: Waits a specific period (completion_nsec) for each IO before
	53	completion.
	54
89ed05ee	55	completion_nsec=[ns]: Default: 10.000ns
a2787312	56	Combined with irqmode=2 (timer). The time each completion event must wait.
12f8f4fc MB	57
	58	submit_queues=[0..nr_cpus]:
	59	The number of submission queues attached to the device driver. If unset, it
	60	defaults to 1 on single-queue and bio-based instances. For multi-queue,
89ed05ee	61	it is ignored when use_per_node_hctx module parameter is 1.
12f8f4fc	62
89ed05ee	63	hw_queue_depth=[0..qdepth]: Default: 64
12f8f4fc MB	64	The hardware queue depth of the device.
	65
	66	III: Multi-queue specific parameters
	67
20005244 MB	68	use_per_node_hctx=[0/1]: Default: 0
	69	0: The number of submit queues are set to the value of the submit_queues
	70	parameter.
	71	1: The multi-queue block layer is instantiated with a hardware dispatch
	72	queue for each CPU node in the system.
b2b7e001 MB	73
	74	use_lightnvm=[0/1]: Default: 0
	75	Register device with LightNVM. Requires blk-mq to be used.