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=63MB" > /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 183