gzoned(8) · carta

NAME

gzoned – emulate a host-managed zoned device on top of a regular provider

SYNOPSIS

gzoned create [-uv] [-s zonesize] [-c zones] [-m maxopen] dev

gzoned fault [-v] -z zone -s state name

gzoned destroy [-fv] name ...

gzoned stop [-fv] name ...

gzoned clear [-v] dev ...

gzoned [--libxo] list

gzoned [--libxo] status

gzoned load

gzoned unload

DESCRIPTION

The gzoned utility presents to the system a host-managed zoned block device backed by a regular, non-zoned provider. The exposed device is of the kind described by the SCSI Zoned Block Commands (ZBC) and ATA Zoned ATA Command Set (ZAC) specifications.

The backing provider is divided into equally sized, sequential-write-required zones, unless marked conventional by the -c option. For each zone the GEOM class maintains a write pointer and answers the zone-management commands (see zonectl(8)) issued through the DIOCZONECMD ioctl.

Resetting a write pointer issues a best-effort BIO_DELETE for the zone's range to the backing provider, resembling a real drives de-allocating a reset zone. BIO_DELETE requests to the zoned device itself are rejected, as zoned devices have no unmap. Sequential zones are reclaimed by resetting the write pointer.

The configuration for a device is persistent. A metadata block and the per-zone state are stored in a small area reserved at the tail of the backing provider, so the zoned device is recreated automatically whenever the provider appears (at boot, module load or hot-plug), with its write pointers restored. Note that because of the metadata location on the backing provider, the zoned device is torn down if the backing provider is resized with unflushed zone state changes being discarded. Zone state changes are committed to the backing provider on a BIO_FLUSH. Changes made since the last flush may be rolled back by an unclean shutdown, resembling a drive whose zone state is volatile until flushed.

The first argument to gzoned indicates an action to be performed:

create: Mark dev as zoned, creating a device named after the backing provider with “.zoned” appended (e.g. /dev/da0.zoned). The number of zones is the usable size of dev divided by zonesize; a small reservation at the tail of dev holds the zone metadata; any trailing space that does not make up a full zone is not exposed. Host-managed zoned providers are refused: their tail normally lies in a sequential-write-required zone and cannot hold the metadata and zone state table.
fault: Inject a zone fault into the running device name. -z zone selects the zone by number and -s state is one of ro (readonly), offline, reset (zone needs a write-pointer reset) or clear (return the zone to its normal state implied by its write pointer). Readonly and offline zones reject writes and zone-management commands; the fault persists with the rest of the zone state until cleared.
clear: Permanently un-zone the given backing device(s) by clearing the on-disk metadata. A backing device carrying a live zoned device is held open and cannot be cleared: tear the device down with stop first.
stop: Tear down the given zoned device(s) without touching the on-disk metadata. name is the zoned device (e.g. da0.zoned). Unflushed zone state is committed to the backing provider first. The device comes back the next time the backing provider is tasted (e.g. at boot or when it is opened and closed again).
destroy: Same as stop.
list: See geom(8).
status: See geom(8).
load: See geom(8).
unload: See geom(8).
--libxo: Generate output via libxo(3) in a selection of different human and machine readable formats. See xo_options(7) for details on command line arguments.

Additional options:

-c zones: Mark the given zones as conventional (randomly writable, no write pointer). zones is a comma-separated list of zone numbers and inclusive ranges, counted from zero, e.g. 60, 60-70 or 0-3,60,90-95. At most 16 comma-separated entries may be given. By default all zones are sequential-write-required.
-f: Tear down the device even if it is still open.
-m maxopen: Limit the number of simultaneously open sequential zones. Once the limit is reached, implicitly opened zones are implicitly closed to make room. If every open zone was opened explicitly, further writes and explicit opens fail with ENOSPC. The default of 0 means unlimited.
-s zonesize: Size of a single zone. The value must be a multiple of the backing provider's sector size and may use the usual size suffixes (e.g. 7G, 64M). The default is 256M. It must also leave the device with at least one, and at most 4294967295 zones.
-u: Restrict reads in sequential-write-required zones (unset URSWRZ bit). Similarly to real zoned drives, the device supports unrestricted reads that are passed through unchecked by default. With -u the device instead reports URSWRZ as unset and rejects with EIO any read in a sequential zone that extends beyond that zone's write pointer, as well as any read that crosses out of a conventional zone into a sequential one. Note that this renders the device unreadable to zone-unaware consumers. Tasting the zoned provider (e.g. partition table scanning) will also fail until the accessed zones have been written.
-v: Be more verbose.

SYSCTL VARIABLES

The following sysctl(8) variable can be used to control the behavior of the ZONED GEOM class.

kern.geom.zoned.debug: 0: Debug level of the ZONED GEOM class. This can be set to a number between 0 and 3 inclusive. If set to 0, minimal debug information is printed; if set to 3, the maximum amount of debug information is printed.

EXIT STATUS

The gzoned utility exits 0 on success, and >0 if an error occurs.

EXAMPLES

Expose the memory disk /dev/md0 as a host-managed zoned device /dev/md0.zoned with one-gigabyte zones, the first four of which are conventional. Inspect its zones, then permanently un-zone it:

mdconfig -t malloc -s 10G -u md0
gzoned create -s 1G -c 0-3 /dev/md0
zonectl -d /dev/md0.zoned -c params
zonectl -d /dev/md0.zoned -c rz
gzoned clear /dev/md0

The same operations are also available through the geom(8) front end:

geom zoned create -s 128M /dev/da0
geom zoned stop da0.zoned
geom zoned clear /dev/da0

HISTORY

The gzoned utility appeared in FreeBSD 16.0.

AUTHORS

voidanix ⟨[email protected]⟩