Describe the zoned, zoned.zone_size and zoned.max_open properties of ufs-lu with an example, what a zoned logical unit emulates and what it rejects, that reads above the write pointer return what the drive holds, that zone state is not persistent and that the drive cannot be resized.
Signed-off-by: Daejun Park <[email protected]> --- docs/system/devices/ufs.rst | 55 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/docs/system/devices/ufs.rst b/docs/system/devices/ufs.rst index d3482e9299..f719b2f145 100644 --- a/docs/system/devices/ufs.rst +++ b/docs/system/devices/ufs.rst @@ -74,6 +74,61 @@ Logical Unit Properties Logical unit number, 0 to 31. A host controller accepts up to 32 logical units. +``zoned`` (default off) + Present the logical unit as a host-managed zoned block device (ZBC). + All zones are sequential write required zones whose capacity is their + size. The drive must be writable. + +``zoned.zone_size`` (default 128M) + Zone size in bytes: a multiple of the 4 KiB logical block size, below + 16 TiB and not larger than the drive. A logical unit has at most + 67108862 zones. Linux also requires a power of two. The last zone is + smaller when the capacity is not a multiple of the zone size. + +``zoned.max_open`` (default 6) + Maximum number of open zones; 0 means no limit. When the limit is + reached, a write to another zone closes an implicitly open zone, and + fails with INSUFFICIENT ZONE RESOURCES if every open zone was opened + explicitly. f2fs needs at least as many as its active logs, 6 by + default. + +Zoned Logical Units +=================== + +The following adds a regular logical unit and a zoned one with 64 MiB +zones: + +.. code-block:: console + + -drive file=lu0.img,if=none,id=lu0,format=raw \ + -drive file=lu1.img,if=none,id=lu1,format=raw \ + -device ufs,id=ufs0,serial=0001 \ + -device ufs-lu,drive=lu0,bus=ufs0,lun=0 \ + -device ufs-lu,drive=lu1,bus=ufs0,lun=1,zoned=on,zoned.zone_size=64M + +A Linux guest needs ``CONFIG_BLK_DEV_ZONED``. f2fs keeps its metadata on +a regular logical unit, for example ``mkfs.f2fs -m -c /dev/sdb /dev/sda`` +with the zoned logical unit as ``/dev/sdb``. + +The zoned logical unit reports the ZBC device type in its INQUIRY data, +handles REPORT ZONES and the OPEN, CLOSE, FINISH and RESET WRITE POINTER +zone operations, and checks every WRITE, WRITE AND VERIFY and WRITE SAME +command against the write pointer of its zone. Zone operations act on +one zone or, with the ALL bit, on every zone; a ZONE COUNT above 1 is +rejected. The logical unit does not support UNMAP and reports no logical +block provisioning. All other commands, including reads, MODE SENSE and +SYNCHRONIZE CACHE, behave as on a regular logical unit. FORMAT UNIT +changes neither data nor zones. + +Reads are not restricted by the write pointer: reads above it, including +reads of a zone after RESET WRITE POINTER, return whatever the drive +holds. Zone conditions and write pointers are kept in memory only: after +QEMU restarts every zone is empty again while the drive keeps its data, +so the write pointers no longer match what a file system wrote. The zone +layout is set when the logical unit is created; resizing its drive is +not supported. Zone conditions and write pointers, open zones included, +are kept across a host controller reset and a system reset. + Limitations =========== -- 2.43.0
