tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
Documentation: Document the new zoned loop block device driver
Introduce the zoned_loop.rst documentation file under
admin-guide/blockdev to document the zoned loop block device driver.
An overview of the driver is provided and its usage to create and delete
zoned devices described.
Signed-off-by: Damien Le Moal <dlemoal@kernel.org>
Reviewed-by: Christoph Hellwig <hch@lst.de>
Reviewed-by: Johannes Thumshirn <johannes.thumshirn@wdc.com>
Link: https://lore.kernel.org/r/20250407075222.170336-3-dlemoal@kernel.org
Signed-off-by: Jens Axboe <axboe@kernel.dk>
authored by
Damien Le Moal
and committed by
Jens Axboe
9e4f11c1
eb0570c7
+174
+1
Documentation/admin-guide/blockdev/index.rst
+1
Documentation/admin-guide/blockdev/index.rst
+169
Documentation/admin-guide/blockdev/zoned_loop.rst
+169
Documentation/admin-guide/blockdev/zoned_loop.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
3
+
=======================
4
+
Zoned 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
+
15
+
1) Overview
16
+
-----------
17
+
18
+
The zoned loop block device driver (zloop) allows a user to create a zoned block
19
+
device using one regular file per zone as backing storage. This driver does not
20
+
directly control any hardware and uses read, write and truncate operations to
21
+
regular files of a file system to emulate a zoned block device.
22
+
23
+
Using zloop, zoned block devices with a configurable capacity, zone size and
24
+
number of conventional zones can be created. The storage for each zone of the
25
+
device is implemented using a regular file with a maximum size equal to the zone
26
+
size. The size of a file backing a conventional zone is always equal to the zone
27
+
size. The size of a file backing a sequential zone indicates the amount of data
28
+
sequentially written to the file, that is, the size of the file directly
29
+
indicates the position of the write pointer of the zone.
30
+
31
+
When resetting a sequential zone, its backing file size is truncated to zero.
32
+
Conversely, for a zone finish operation, the backing file is truncated to the
33
+
zone size. With this, the maximum capacity of a zloop zoned block device created
34
+
can be larger configured to be larger than the storage space available on the
35
+
backing file system. Of course, for such configuration, writing more data than
36
+
the storage space available on the backing file system will result in write
37
+
errors.
38
+
39
+
The zoned loop block device driver implements a complete zone transition state
40
+
machine. That is, zones can be empty, implicitly opened, explicitly opened,
41
+
closed or full. The current implementation does not support any limits on the
42
+
maximum number of open and active zones.
43
+
44
+
No user tools are necessary to create and delete zloop devices.
45
+
46
+
2) Creating a Zoned Device
47
+
--------------------------
48
+
49
+
Once the zloop module is loaded (or if zloop is compiled in the kernel), the
50
+
character device file /dev/zloop-control can be used to add a zloop device.
51
+
This is done by writing an "add" command directly to the /dev/zloop-control
52
+
device::
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
+
61
+
The 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
+
68
+
In more details, the options that can be used with the "add" command are as
69
+
follows.
70
+
71
+
================ ===========================================================
72
+
id Device number (the X in /dev/zloopX).
73
+
Default: automatically assigned.
74
+
capacity_mb Device total capacity in MiB. This is always rounded up to
75
+
the nearest higher multiple of the zone size.
76
+
Default: 16384 MiB (16 GiB).
77
+
zone_size_mb Device zone size in MiB. Default: 256 MiB.
78
+
zone_capacity_mb Device zone capacity (must always be equal to or lower than
79
+
the zone size. Default: zone size.
80
+
conv_zones Total number of conventioanl zones starting from sector 0.
81
+
Default: 8.
82
+
base_dir Path to the base directoy where to create the directory
83
+
containing the zone files of the device.
84
+
Default=/var/local/zloop.
85
+
The device directory containing the zone files is always
86
+
named with the device ID. E.g. the default zone file
87
+
directory for /dev/zloop0 is /var/local/zloop/0.
88
+
nr_queues Number of I/O queues of the zoned block device. This value is
89
+
always capped by the number of online CPUs
90
+
Default: 1
91
+
queue_depth Maximum I/O queue depth per I/O queue.
92
+
Default: 64
93
+
buffered_io Do buffered IOs instead of direct IOs (default: false)
94
+
================ ===========================================================
95
+
96
+
3) Deleting a Zoned Device
97
+
--------------------------
98
+
99
+
Deleting an unused zoned loop block device is done by issuing the "remove"
100
+
command to /dev/zloop-control, specifying the ID of the device to remove::
101
+
102
+
$ echo "remove id=X" > /dev/zloop-control
103
+
104
+
The remove command does not have any option.
105
+
106
+
A zoned device that was removed can be re-added again without any change to the
107
+
state of the device zones: the device zones are restored to their last state
108
+
before the device was removed. Adding again a zoned device after it was removed
109
+
must always be done using the same configuration as when the device was first
110
+
added. If a zone configuration change is detected, an error will be returned and
111
+
the zoned device will not be created.
112
+
113
+
To fully delete a zoned device, after executing the remove operation, the device
114
+
base directory containing the backing files of the device zones must be deleted.
115
+
116
+
4) Example
117
+
----------
118
+
119
+
The following sequence of commands creates a 2GB zoned device with zones of 64
120
+
MB and a zone capacity of 63 MB::
121
+
122
+
$ modprobe zloop
123
+
$ mkdir -p /var/local/zloop/0
124
+
$ echo "add capacity_mb=2048,zone_size_mb=64,zone_capacity=63MB" > /dev/zloop-control
125
+
126
+
For the device created (/dev/zloop0), the zone backing files are all created
127
+
under the default base directory (/var/local/zloop)::
128
+
129
+
$ ls -l /var/local/zloop/0
130
+
total 0
131
+
-rw-------. 1 root root 67108864 Jan 6 22:23 cnv-000000
132
+
-rw-------. 1 root root 67108864 Jan 6 22:23 cnv-000001
133
+
-rw-------. 1 root root 67108864 Jan 6 22:23 cnv-000002
134
+
-rw-------. 1 root root 67108864 Jan 6 22:23 cnv-000003
135
+
-rw-------. 1 root root 67108864 Jan 6 22:23 cnv-000004
136
+
-rw-------. 1 root root 67108864 Jan 6 22:23 cnv-000005
137
+
-rw-------. 1 root root 67108864 Jan 6 22:23 cnv-000006
138
+
-rw-------. 1 root root 67108864 Jan 6 22:23 cnv-000007
139
+
-rw-------. 1 root root 0 Jan 6 22:23 seq-000008
140
+
-rw-------. 1 root root 0 Jan 6 22:23 seq-000009
141
+
...
142
+
143
+
The zoned device created (/dev/zloop0) can then be used normally::
144
+
145
+
$ lsblk -z
146
+
NAME ZONED ZONE-SZ ZONE-NR ZONE-AMAX ZONE-OMAX ZONE-APP ZONE-WGRAN
147
+
zloop0 host-managed 64M 32 0 0 1M 4K
148
+
$ blkzone report /dev/zloop0
149
+
start: 0x000000000, len 0x020000, cap 0x020000, wptr 0x000000 reset:0 non-seq:0, zcond: 0(nw) [type: 1(CONVENTIONAL)]
150
+
start: 0x000020000, len 0x020000, cap 0x020000, wptr 0x000000 reset:0 non-seq:0, zcond: 0(nw) [type: 1(CONVENTIONAL)]
151
+
start: 0x000040000, len 0x020000, cap 0x020000, wptr 0x000000 reset:0 non-seq:0, zcond: 0(nw) [type: 1(CONVENTIONAL)]
152
+
start: 0x000060000, len 0x020000, cap 0x020000, wptr 0x000000 reset:0 non-seq:0, zcond: 0(nw) [type: 1(CONVENTIONAL)]
153
+
start: 0x000080000, len 0x020000, cap 0x020000, wptr 0x000000 reset:0 non-seq:0, zcond: 0(nw) [type: 1(CONVENTIONAL)]
154
+
start: 0x0000a0000, len 0x020000, cap 0x020000, wptr 0x000000 reset:0 non-seq:0, zcond: 0(nw) [type: 1(CONVENTIONAL)]
155
+
start: 0x0000c0000, len 0x020000, cap 0x020000, wptr 0x000000 reset:0 non-seq:0, zcond: 0(nw) [type: 1(CONVENTIONAL)]
156
+
start: 0x0000e0000, len 0x020000, cap 0x020000, wptr 0x000000 reset:0 non-seq:0, zcond: 0(nw) [type: 1(CONVENTIONAL)]
157
+
start: 0x000100000, len 0x020000, cap 0x01f800, wptr 0x000000 reset:0 non-seq:0, zcond: 1(em) [type: 2(SEQ_WRITE_REQUIRED)]
158
+
start: 0x000120000, len 0x020000, cap 0x01f800, wptr 0x000000 reset:0 non-seq:0, zcond: 1(em) [type: 2(SEQ_WRITE_REQUIRED)]
159
+
...
160
+
161
+
Deleting this device is done using the command::
162
+
163
+
$ echo "remove id=0" > /dev/zloop-control
164
+
165
+
The removed device can be re-added again using the same "add" command as when
166
+
the device was first created. To fully delete a zoned device, its backing files
167
+
should also be deleted after executing the remove command::
168
+
169
+
$ rm -r /var/local/zloop/0
+1
MAINTAINERS
+1
MAINTAINERS