libzbd is a user library providing functions for manipulating zoned block devices.
Unlike the libzbc library, libzbd does not implement direct command access to zoned block devices. Rather, libzbd uses the kernel provided zoned block device interface based on the ioctl() system call. A direct consequence of this is that libzbd will only allow access to zoned block devices supported by the kernel running. This includes both physical devices such as hard-disks supporting the ZBC and ZAC standards, as well as all logical block devices implemented by various device drivers such as null_blk and device mapper drivers.
libzbd provides functions for discovering and managing the state of zones of zoned block devices. Read and write accesses to the devices can be done using standard standard I/O system calls.
The execution of libzbd functions as well as of write operations to zones of a device may result in changes to the condition or attributes of the device zones (such as write pointer location in sequential zones). These changes are not internally tracked by libzbd. In other words, libzbd is stateless. It is the responsibility of applications to implement tracking of the changes to zones conditions such as the increasing write pointer position of a sequential zone after the completion of a write request to the zone.
All libzbd functions use bytes unit for zones information such as the zone start position on the device, a zone size or the zone write pointer location. Zoned block devices are identified using regular file descriptor numbers that can be used as is with standard I/O system calls.
However, application programmers must be careful to always implement read accesses aligned to the device logical block size. Furthermore, on host managed zoned block devices, write operations to sequential zones must be aligned to the device physical block size.
The main functions provided by libzbd are as follows.
|zbd_open()||Open a zoned block device|
|zbd_close()||Close an open zoned block device|
|zbd_get_info()||Get a device information|
|zbd_report_nr_zones()||Get the number of zones of a device|
|zbd_report_zones()||Get a device zone information|
|zbd_list_zones()||Get a device zone information|
|zbd_zones_operation()||Execute an operation on a range of zones|
|zbd_open_zones()||Explicitly open a range of zone|
|zbd_close_zones()||Close a range of zones|
|zbd_reset_zones()||Reset the write pointer of a range of zones|
|zbd_finish_zones()||Finish a range of zone|
More detailed information about these functions usage and behavior can be found
in the comments of libzbd header file. This header file is by default
libzbd does not implement any mutual exclusion mechanism for multi-thread or multi-process applications. This implies that it is the responsibility of applications to synchronize the execution of conflicting operations targeting the same zone. A typical example of such case is concurrent write operations to the same zone by multiple threads which may result in write errors without write ordering control by the application.
The following functions are also provided by libzbd to facilitate application development and tests.
|zbd_device_is_zoned()||Test if a device is a zoned block device|
|zbd_device_model_str()||Get a string description of a device model|
|zbd_zone_type_str()||Get a string description of a zone type|
|zbd_zone_cond_str()||Get a string description of a zone condition|
|zbd_set_log_level()||Set the library verbosity level|
All functions will behave in the same manner regardless of the type of disk being used.
libzbd also provides several command line applications to manipulate zoned block devices by calling the library functions. The list of applications provided is shown in the table below.
|zbd||Command line utility to report, open, close, reset and finish zones of a device|
|gzbd||Similar to the zbd tool but using a graphical user interface|
|gzbd-viewer||Graphical user interface showing the condition and state of zones of a zoned block device|
All utilities output a help message when executed without any argument.
Manual pages are also provided for each tool.
The following examples use a null zoned block device with 4 conventional zones and 12 sequential zones of 32 MB created using the nullblk-zoned.sh script.
The following command can be used to list the zone information for all zones of a device, including the device information such as logical block size and capacity.
The same zone information can also be obtained in csv format to facilitate parsing using scripting languages, including shell scripts.
The zbd tool also allow executing zone management operations over a range of zones. The following example explicitely opens the first 2 sequential zones of the null_blk device.
Writing 32MB to the first zone using dd will transition the zone to full state.
Other possible zone operations are close, reset and finish.
gzbd provides a graphical user interface showing the zone configuration and state of a zoned block device. gzbd also displays the write status (write pointer position) of zones graphically using color coding (red for written sectors and green for unwritten sectors). Operations on zones can also be executed directly from the interface (reset zone write pointer, open zone, close zone, etc).
The gzbd-viewer graphical interface is a simpler tool than gzbd that only allows displaying the current zone condition and state of a zoned block device. The zone state is refreshed by defaul twice per second. This period can be adjusted using a command line option.
Using gzbd enables simple visual cues as to how an application is performaing and using the zones of a zoned block device. The following example illustrates this.