zoned_loop.rst

  1.. SPDX-License-Identifier: GPL-2.0
  2
  3=======================
  4Zoned Loop Block Device
  5=======================
  6
  7.. Contents:
  8
  9	1) Overview
 10	2) Creating a Zoned Device
 11	3) Deleting a Zoned Device
 12	4) Example
 13
 14
 151) Overview
 16-----------
 17
 18The zoned loop block device driver (zloop) allows a user to create a zoned block
 19device using one regular file per zone as backing storage. This driver does not
 20directly control any hardware and uses read, write and truncate operations to
 21regular files of a file system to emulate a zoned block device.
 22
 23Using zloop, zoned block devices with a configurable capacity, zone size and
 24number of conventional zones can be created. The storage for each zone of the
 25device is implemented using a regular file with a maximum size equal to the zone
 26size. The size of a file backing a conventional zone is always equal to the zone
 27size. The size of a file backing a sequential zone indicates the amount of data
 28sequentially written to the file, that is, the size of the file directly
 29indicates the position of the write pointer of the zone.
 30
 31When resetting a sequential zone, its backing file size is truncated to zero.
 32Conversely, for a zone finish operation, the backing file is truncated to the
 33zone size. With this, the maximum capacity of a zloop zoned block device created
 34can be larger configured to be larger than the storage space available on the
 35backing file system. Of course, for such configuration, writing more data than
 36the storage space available on the backing file system will result in write
 37errors.
 38
 39The zoned loop block device driver implements a complete zone transition state
 40machine. That is, zones can be empty, implicitly opened, explicitly opened,
 41closed or full. The current implementation does not support any limits on the
 42maximum number of open and active zones.
 43
 44No user tools are necessary to create and delete zloop devices.
 45
 462) Creating a Zoned Device
 47--------------------------
 48
 49Once the zloop module is loaded (or if zloop is compiled in the kernel), the
 50character device file /dev/zloop-control can be used to add a zloop device.
 51This is done by writing an "add" command directly to the /dev/zloop-control
 52device::
 53
 54	$ modprobe zloop
 55        $ ls -l /dev/zloop*
 56        crw-------. 1 root root 10, 123 Jan  6 19:18 /dev/zloop-control
 57
 58        $ mkdir -p <base directory/<device ID>
 59        $ echo "add [options]" > /dev/zloop-control
 60
 61The options available for the add command can be listed by reading the
 62/dev/zloop-control device::
 63
 64	$ cat /dev/zloop-control
 65        add id=%d,capacity_mb=%u,zone_size_mb=%u,zone_capacity_mb=%u,conv_zones=%u,base_dir=%s,nr_queues=%u,queue_depth=%u,buffered_io
 66        remove id=%d
 67
 68In more details, the options that can be used with the "add" command are as
 69follows.
 70
 71===================   =========================================================
 72id                    Device number (the X in /dev/zloopX).
 73                      Default: automatically assigned.
 74capacity_mb           Device total capacity in MiB. This is always rounded up
 75                      to the nearest higher multiple of the zone size.
 76                      Default: 16384 MiB (16 GiB).
 77zone_size_mb          Device zone size in MiB. Default: 256 MiB.
 78zone_capacity_mb      Device zone capacity (must always be equal to or lower
 79                      than the zone size. Default: zone size.
 80conv_zones            Total number of conventioanl zones starting from
 81                      sector 0
 82                      Default: 8
 83base_dir              Path to the base directory where to create the directory
 84                      containing the zone files of the device.
 85                      Default=/var/local/zloop.
 86                      The device directory containing the zone files is always
 87                      named with the device ID. E.g. the default zone file
 88                      directory for /dev/zloop0 is /var/local/zloop/0.
 89nr_queues             Number of I/O queues of the zoned block device. This
 90                      value is always capped by the number of online CPUs
 91                      Default: 1
 92queue_depth           Maximum I/O queue depth per I/O queue.
 93                      Default: 64
 94buffered_io           Do buffered IOs instead of direct IOs (default: false)
 95zone_append           Enable or disable a zloop device native zone append
 96                      support.
 97                      Default: 1 (enabled).
 98                      If native zone append support is disabled, the block layer
 99                      will emulate this operation using regular write
100                      operations.
101ordered_zone_append   Enable zloop mitigation of zone append reordering.
102                      Default: disabled.
103                      This is useful for testing file systems file data mapping
104                      (extents), as when enabled, this can significantly reduce
105                      the number of data extents needed to for a file data
106                      mapping.
107===================   =========================================================
108
1093) Deleting a Zoned Device
110--------------------------
111
112Deleting an unused zoned loop block device is done by issuing the "remove"
113command to /dev/zloop-control, specifying the ID of the device to remove::
114
115        $ echo "remove id=X" > /dev/zloop-control
116
117The remove command does not have any option.
118
119A zoned device that was removed can be re-added again without any change to the
120state of the device zones: the device zones are restored to their last state
121before the device was removed. Adding again a zoned device after it was removed
122must always be done using the same configuration as when the device was first
123added. If a zone configuration change is detected, an error will be returned and
124the zoned device will not be created.
125
126To fully delete a zoned device, after executing the remove operation, the device
127base directory containing the backing files of the device zones must be deleted.
128
1294) Example
130----------
131
132The following sequence of commands creates a 2GB zoned device with zones of 64
133MB and a zone capacity of 63 MB::
134
135        $ modprobe zloop
136        $ mkdir -p /var/local/zloop/0
137        $ echo "add capacity_mb=2048,zone_size_mb=64,zone_capacity_mb=63" > /dev/zloop-control
138
139For the device created (/dev/zloop0), the zone backing files are all created
140under the default base directory (/var/local/zloop)::
141
142        $ ls -l /var/local/zloop/0
143        total 0
144        -rw-------. 1 root root 67108864 Jan  6 22:23 cnv-000000
145        -rw-------. 1 root root 67108864 Jan  6 22:23 cnv-000001
146        -rw-------. 1 root root 67108864 Jan  6 22:23 cnv-000002
147        -rw-------. 1 root root 67108864 Jan  6 22:23 cnv-000003
148        -rw-------. 1 root root 67108864 Jan  6 22:23 cnv-000004
149        -rw-------. 1 root root 67108864 Jan  6 22:23 cnv-000005
150        -rw-------. 1 root root 67108864 Jan  6 22:23 cnv-000006
151        -rw-------. 1 root root 67108864 Jan  6 22:23 cnv-000007
152        -rw-------. 1 root root        0 Jan  6 22:23 seq-000008
153        -rw-------. 1 root root        0 Jan  6 22:23 seq-000009
154        ...
155
156The zoned device created (/dev/zloop0) can then be used normally::
157
158        $ lsblk -z
159        NAME   ZONED        ZONE-SZ ZONE-NR ZONE-AMAX ZONE-OMAX ZONE-APP ZONE-WGRAN
160        zloop0 host-managed     64M      32         0         0       1M         4K
161        $ blkzone report /dev/zloop0
162          start: 0x000000000, len 0x020000, cap 0x020000, wptr 0x000000 reset:0 non-seq:0, zcond: 0(nw) [type: 1(CONVENTIONAL)]
163          start: 0x000020000, len 0x020000, cap 0x020000, wptr 0x000000 reset:0 non-seq:0, zcond: 0(nw) [type: 1(CONVENTIONAL)]
164          start: 0x000040000, len 0x020000, cap 0x020000, wptr 0x000000 reset:0 non-seq:0, zcond: 0(nw) [type: 1(CONVENTIONAL)]
165          start: 0x000060000, len 0x020000, cap 0x020000, wptr 0x000000 reset:0 non-seq:0, zcond: 0(nw) [type: 1(CONVENTIONAL)]
166          start: 0x000080000, len 0x020000, cap 0x020000, wptr 0x000000 reset:0 non-seq:0, zcond: 0(nw) [type: 1(CONVENTIONAL)]
167          start: 0x0000a0000, len 0x020000, cap 0x020000, wptr 0x000000 reset:0 non-seq:0, zcond: 0(nw) [type: 1(CONVENTIONAL)]
168          start: 0x0000c0000, len 0x020000, cap 0x020000, wptr 0x000000 reset:0 non-seq:0, zcond: 0(nw) [type: 1(CONVENTIONAL)]
169          start: 0x0000e0000, len 0x020000, cap 0x020000, wptr 0x000000 reset:0 non-seq:0, zcond: 0(nw) [type: 1(CONVENTIONAL)]
170          start: 0x000100000, len 0x020000, cap 0x01f800, wptr 0x000000 reset:0 non-seq:0, zcond: 1(em) [type: 2(SEQ_WRITE_REQUIRED)]
171          start: 0x000120000, len 0x020000, cap 0x01f800, wptr 0x000000 reset:0 non-seq:0, zcond: 1(em) [type: 2(SEQ_WRITE_REQUIRED)]
172          ...
173
174Deleting this device is done using the command::
175
176        $ echo "remove id=0" > /dev/zloop-control
177
178The removed device can be re-added again using the same "add" command as when
179the device was first created. To fully delete a zoned device, its backing files
180should also be deleted after executing the remove command::
181
182        $ rm -r /var/local/zloop/0