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