|
| 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 |
0 commit comments