libzbc
|
Data Structures | |
struct | zbc_zone |
Zone information data structure. More... | |
struct | zbc_device_info |
Device information data structure. More... | |
struct | zbc_errno |
Detailed error information data structure. More... | |
Macros | |
#define | zbc_zone_type(z) ((int)(z)->zbz_type) |
Get a zone type. | |
#define | zbc_zone_conventional(z) ((z)->zbz_type == ZBC_ZT_CONVENTIONAL) |
Test if a zone type is conventional. | |
#define | zbc_zone_sequential_req(z) ((z)->zbz_type == ZBC_ZT_SEQUENTIAL_REQ) |
Test if a zone type is sequential write required. | |
#define | zbc_zone_sequential_pref(z) ((z)->zbz_type == ZBC_ZT_SEQUENTIAL_PREF) |
Test if a zone type is sequential write preferred. | |
#define | zbc_zone_sequential(z) |
Test if a zone type is sequential write required or preferred. More... | |
#define | zbc_zone_condition(z) ((int)(z)->zbz_condition) |
Get a zone condition. | |
#define | zbc_zone_not_wp(z) ((z)->zbz_condition == ZBC_ZC_NOT_WP) |
Test if a zone condition is "not write pointer zone". | |
#define | zbc_zone_empty(z) ((z)->zbz_condition == ZBC_ZC_EMPTY) |
Test if a zone condition is empty. | |
#define | zbc_zone_imp_open(z) ((z)->zbz_condition == ZBC_ZC_IMP_OPEN) |
Test if a zone condition is implicit open. | |
#define | zbc_zone_exp_open(z) ((z)->zbz_condition == ZBC_ZC_EXP_OPEN) |
Test if a zone condition is explicit open. | |
#define | zbc_zone_is_open(z) |
Test if a zone condition is explicit or implicit open. More... | |
#define | zbc_zone_closed(z) ((z)->zbz_condition == ZBC_ZC_CLOSED) |
Test if a zone condition is closed. | |
#define | zbc_zone_full(z) ((z)->zbz_condition == ZBC_ZC_FULL) |
Test if a zone condition is full. | |
#define | zbc_zone_rdonly(z) ((z)->zbz_condition == ZBC_ZC_RDONLY) |
Test if a zone condition is read-only. | |
#define | zbc_zone_offline(z) ((z)->zbz_condition == ZBC_ZC_OFFLINE) |
Test if a zone condition is offline. | |
#define | zbc_zone_rwp_recommended(z) |
Test if a zone has the reset recommended flag set. More... | |
#define | zbc_zone_non_seq(z) ((z)->zbz_attributes & ZBC_ZA_NON_SEQ) |
Test if a zone has the non sequential write resource allocated flag set. | |
#define | zbc_zone_start(z) ((unsigned long long)(z)->zbz_start) |
Get a zone start 512B sector. | |
#define | zbc_zone_length(z) ((unsigned long long)(z)->zbz_length) |
Get a zone number of 512B sectors. | |
#define | zbc_zone_wp(z) ((unsigned long long)(z)->zbz_write_pointer) |
Get a zone write pointer 512B sector position. | |
#define | ZBC_DEVICE_INFO_LENGTH 32 |
#define | ZBC_NOT_REPORTED ((uint32_t)0xFFFFFFFF) |
#define | ZBC_NO_LIMIT ((uint32_t)0xFFFFFFFF) |
#define | zbc_lba2sect(info, lba) (((lba) * (info)->zbd_lblock_size) >> 9) |
Convert LBA value to 512-bytes sector. More... | |
#define | zbc_sect2lba(info, sect) (((sect) << 9) / (info)->zbd_lblock_size) |
Convert 512-bytes sector value to LBA. More... | |
Functions | |
void | zbc_set_log_level (char const *log_level) |
Set the library log level. More... | |
const char * | zbc_zone_type_str (enum zbc_zone_type type) |
returns a string describing a zone type More... | |
const char * | zbc_zone_condition_str (enum zbc_zone_condition cond) |
Returns a string describing a zone condition. More... | |
const char * | zbc_device_type_str (enum zbc_dev_type type) |
Returns a device type name. More... | |
const char * | zbc_device_model_str (enum zbc_dev_model model) |
Returns a device zone model name. More... | |
void | zbc_errno (struct zbc_device *dev, struct zbc_errno *err) |
Get detailed error code of last operation. More... | |
const char * | zbc_sk_str (enum zbc_sk sk) |
Returns a string describing a sense key. More... | |
const char * | zbc_asc_ascq_str (enum zbc_asc_ascq asc_ascq) |
Returns a string describing a sense code. More... | |
int | zbc_device_is_zoned (const char *filename, bool fake, struct zbc_device_info *info) |
Test if a device is a zoned block device. More... | |
int | zbc_open (const char *filename, int flags, struct zbc_device **dev) |
Open a ZBC device. More... | |
int | zbc_close (struct zbc_device *dev) |
Close a ZBC device. More... | |
void | zbc_get_device_info (struct zbc_device *dev, struct zbc_device_info *info) |
Get a ZBC device information. More... | |
void | zbc_print_device_info (struct zbc_device_info *info, FILE *out) |
Print a device information. More... | |
int | zbc_report_zones (struct zbc_device *dev, uint64_t sector, enum zbc_reporting_options ro, struct zbc_zone *zones, unsigned int *nr_zones) |
Get zone information. More... | |
int | zbc_list_zones (struct zbc_device *dev, uint64_t sector, enum zbc_reporting_options ro, struct zbc_zone **zones, unsigned int *nr_zones) |
Get zone information. More... | |
int | zbc_zone_operation (struct zbc_device *dev, uint64_t sector, enum zbc_zone_op op, unsigned int flags) |
Execute an operation on a zone. More... | |
ssize_t | zbc_pread (struct zbc_device *dev, void *buf, size_t count, uint64_t offset) |
Read sectors form a device. More... | |
ssize_t | zbc_pwrite (struct zbc_device *dev, const void *buf, size_t count, uint64_t offset) |
Write sectors to a device. More... | |
ssize_t | zbc_preadv (struct zbc_device *dev, const struct iovec *iov, int iovcnt, uint64_t offset) |
Read sectors from a device using mutliple buffers. More... | |
ssize_t | zbc_pwritev (struct zbc_device *dev, const struct iovec *iov, int iovcnt, uint64_t offset) |
Write sectors to a device unsig multiple buffers. More... | |
int | zbc_map_iov (const void *buf, size_t sectors, struct iovec *iov, int iovcnt, size_t iovlen) |
Map a buffer to an I/O vector. More... | |
int | zbc_flush (struct zbc_device *dev) |
Flush a device write cache. More... | |
#define ZBC_DEVICE_INFO_LENGTH 32 |
Vendor ID string maximum length.
#define zbc_lba2sect | ( | info, | |
lba | |||
) | (((lba) * (info)->zbd_lblock_size) >> 9) |
Convert LBA value to 512-bytes sector.
#define ZBC_NO_LIMIT ((uint32_t)0xFFFFFFFF) |
"no limit" value for the number of explicitly open sequential write required zones in the device information (zbd_max_nr_open_seq_req).
#define ZBC_NOT_REPORTED ((uint32_t)0xFFFFFFFF) |
"not reported" value for the number of zones limits in the device information (zbd_opt_nr_non_seq_write_seq_pref and zbd_max_nr_open_seq_req).
#define zbc_sect2lba | ( | info, | |
sect | |||
) | (((sect) << 9) / (info)->zbd_lblock_size) |
Convert 512-bytes sector value to LBA.
#define zbc_zone_is_open | ( | z | ) |
Test if a zone condition is explicit or implicit open.
#define zbc_zone_rwp_recommended | ( | z | ) |
Test if a zone has the reset recommended flag set.
#define zbc_zone_sequential | ( | z | ) |
Test if a zone type is sequential write required or preferred.
enum zbc_asc_ascq |
SCSI Additional sense codes and qualifiers definitions.
SCSI Additional sense codes and additional sense code qualifiers inspected in case of command error.
enum zbc_dev_flags |
enum zbc_dev_model |
Device model definitions.
Indicates the ZBC/ZAC device zone model, i.e host-aware, host-managed, device-managed or standard. Note that these last two models are not handled by libzbc (the device will be treated as a regular block device as it should).
enum zbc_dev_type |
enum zbc_oflags |
ZBC device open flags.
These flags can be combined together and passed to zbc_open to change that function default behavior. This is in particular useful for ATA devices to force using the ATA backend driver to bypass any SAT layer that may result in the SCSI backend driver being used.
Reporting options definitions.
Used to filter the zone information returned by the execution of a REPORT ZONES command. Filtering is based on the value of the reporting option and on the condition of the zones at the time of the execution of the REPORT ZONES command.
ZBC_RO_PARTIAL is not a filter: this reporting option can be combined (or'ed) with any other filter option to limit the number of reported zone information to the size of the REPORT ZONES command buffer.
enum zbc_sk |
enum zbc_zone_attributes |
Zone attributes definitions.
Defines the attributes of a zone. Attributes validity depend on the zone type and device model.
enum zbc_zone_condition |
Zone condition definitions.
A zone condition is determined by the zone type and the ZBC zone state machine, i.e. the operations performed on the zone.
enum zbc_zone_op |
enum zbc_zone_op_flags |
enum zbc_zone_type |
Zone type definitions.
Indicates the type of a zone.
const char* zbc_asc_ascq_str | ( | enum zbc_asc_ascq | asc_ascq | ) |
Returns a string describing a sense code.
[in] | asc_ascq | Sense code and sense code qualifier |
int zbc_close | ( | struct zbc_device * | dev | ) |
Close a ZBC device.
[in] | dev | Device handle obtained with zbc_open |
Performs the equivalent to close(2) for a ZBC device open using zbc_open.
int zbc_device_is_zoned | ( | const char * | filename, |
bool | fake, | ||
struct zbc_device_info * | info | ||
) |
Test if a device is a zoned block device.
[in] | filename | Path to the device file |
[in] | fake | If true, also test emulated devices |
[in] | info | Address where to store the device information |
Test if a device supports the ZBC/ZAC command set. If fake is false, only test physical devices. Otherwise, also test regular files and regular block devices that may be in use with the fake backend driver to create an emulated host-managed zoned block device. If info is not NULL and the device is identified as a zoned block device, the device information is returned at the address specified by info.
const char* zbc_device_model_str | ( | enum zbc_dev_model | model | ) |
Returns a device zone model name.
[in] | model | Device model |
const char* zbc_device_type_str | ( | enum zbc_dev_type | type | ) |
Returns a device type name.
[in] | type | Device type |
Get detailed error code of last operation.
[in] | dev | Device handle obtained with zbc_open |
[out] | err | Address where to return the error report |
Returns at the address specified by err a detailed error report of the last command execued. The error report is composed of the SCSI sense key, sense code and sense code qualifier. For successsful commands, all three information are set to 0.
int zbc_flush | ( | struct zbc_device * | dev | ) |
Flush a device write cache.
[in] | dev | Device handle obtained with zbc_open |
This an the equivalent to fsync/fdatasunc but operates at the device cache level.
void zbc_get_device_info | ( | struct zbc_device * | dev, |
struct zbc_device_info * | info | ||
) |
Get a ZBC device information.
[in] | dev | Device handle obtained with zbc_open |
[in] | info | Address of the information structure to fill |
Get information about an open device. The info parameter is used to return a device information. info must be allocated by the caller.
int zbc_list_zones | ( | struct zbc_device * | dev, |
uint64_t | sector, | ||
enum zbc_reporting_options | ro, | ||
struct zbc_zone ** | zones, | ||
unsigned int * | nr_zones | ||
) |
Get zone information.
[in] | dev | Device handle obtained with zbc_open |
[in] | sector | Sector from which to report zones |
[in] | ro | Reporting options |
[out] | zones | The array of zone information filled |
[out] | nr_zones | Number of zones in the array zones |
Similar to zbc_report_zones, but also allocates an appropriatly sized array of zone information structures and return the address of the array at the address specified by zones. The size of the array allocated and filled is returned at the address specified by nr_zones. Freeing of the memory used by the array of zone information strcutrues allocated by this function is the responsability of the caller.
int zbc_map_iov | ( | const void * | buf, |
size_t | sectors, | ||
struct iovec * | iov, | ||
int | iovcnt, | ||
size_t | iovlen | ||
) |
Map a buffer to an I/O vector.
[in] | buf | Data buffer to map |
[in] | sectors | Size of buf in 512B sectors unit |
[in] | iov | Array of I/O vectors to which buf will be mapped |
[in] | iovcnt | The maximum number of entries in the iov array |
[in] | iovlen | The maximum size of a single I/O vector entry in 512B sectors. |
Map the buffer buf to a set of I/O vectors of size iovlen. This is a utility function that is called by libzbc tools and test programs. It can be handy to library users as well.
int zbc_open | ( | const char * | filename, |
int | flags, | ||
struct zbc_device ** | dev | ||
) |
Open a ZBC device.
[in] | filename | Path to a device file |
[in] | flags | Device access mode flags |
[out] | dev | Opaque ZBC device handle |
Opens the device pointed by filename, and returns a handle to it at the address specified by dev if the device is a zoned block device supporting the ZBC or ZAC command set. filename may specify the path to a regular block device file or a regular file to be used with libzbc emulation mode (ZBC_DT_FAKE device type). flags specifies the device access mode flags.O_RDONLY, O_WRONLY and O_RDWR can be specified. Other POSIX defined O_xxx flags are ignored. Additionally, if filename specifies the path to a zoned block device file or an emulated device, O_DIRECT can also be specified (this is mandatory to avoid unaligned write errors with zoned block device files). flags can also be or'ed with one or more of the ZBC_O_DRV_xxx flags in order to restrict the possible backend device drivers that libzbc will try when opening the device.
ssize_t zbc_pread | ( | struct zbc_device * | dev, |
void * | buf, | ||
size_t | count, | ||
uint64_t | offset | ||
) |
Read sectors form a device.
[in] | dev | Device handle obtained with zbc_open |
[in] | buf | Caller supplied buffer to read into |
[in] | count | Number of 512B sectors to read |
[in] | offset | Offset where to start reading (512B sector unit) |
This is the equivalent of the standard system call pread(2) that operates on a ZBC device handle and uses 512B sector unit addressing for the amount of data and the position on the device of the data to read. Attempting to read data across zone boundaries or after the write pointer position of a write pointer zone is possible only if the device allows unrestricted reads. This is indicated by the device information structure flags field, using the flag ZBC_UNRESTRICTED_READ. The range of 512B sectors to read, starting at offset and spanning count 512B sectors must be aligned on logical blocks boundaries. That is, for a 4K logical block size device, count and offset must be multiples of 8.
ssize_t zbc_preadv | ( | struct zbc_device * | dev, |
const struct iovec * | iov, | ||
int | iovcnt, | ||
uint64_t | offset | ||
) |
Read sectors from a device using mutliple buffers.
[in] | dev | Device handle obtained with zbc_open |
[in] | iov | Caller supplied read buffers to read into. Read buffer length is specified in 512B sectors |
[in] | iovcnt | Number of iov buffers |
[in] | offset | Offset where to start reading (512B sector unit) |
This is the equivalent of the standard system call preadv(2) and behaves otherwise as described in zbc_pread. The call reads iovcnt buffers from the file associated with zbc_open into the buffers described by iov ("scatter input").
void zbc_print_device_info | ( | struct zbc_device_info * | info, |
FILE * | out | ||
) |
Print a device information.
[in] | info | The information to print |
[in] | out | File stream to print to |
Print the content of info to the file stream out.
ssize_t zbc_pwrite | ( | struct zbc_device * | dev, |
const void * | buf, | ||
size_t | count, | ||
uint64_t | offset | ||
) |
Write sectors to a device.
[in] | dev | Device handle obtained with zbc_open |
[in] | buf | Caller supplied buffer to write from |
[in] | count | Number of 512B sectors to write |
[in] | offset | Offset where to start writing (512B sector unit) |
This is the equivalent of the standard system call pwrite(2) that operates on a ZBC device handle, and uses 512B sector unit addressing for the amount of data and the position on the device of the data to write. On a host-aware device, any range of 512B sector is acceptable. On a host-managed device, the range os sectors to write can span several conventional zones but cannot span conventional and sequential write required zones. When writing to a sequential write required zone, offset must specify the current write pointer position of the zone. The range of 512B sectors to write, starting at offset and spanning count 512B sectors must be aligned on physical blocks boundaries. That is, for a 4K physical block size device, count and offset must be multiples of 8.
ssize_t zbc_pwritev | ( | struct zbc_device * | dev, |
const struct iovec * | iov, | ||
int | iovcnt, | ||
uint64_t | offset | ||
) |
Write sectors to a device unsig multiple buffers.
[in] | dev | Device handle obtained with zbc_open |
[in] | iov | Caller supplied write buffers to write from. Write buffer length is specified in 512B sectors |
[in] | iovcnt | Number of iov buffers |
[in] | offset | Offset where to start writing (512B sector unit) |
This is the equivalent of the standard system call pwritev(2) and behaves otherwise as described in zbc_pwrite. The call writes iovcnt buffers from the file associated with zbc_open from the buffers described by iov ("gather output").
int zbc_report_zones | ( | struct zbc_device * | dev, |
uint64_t | sector, | ||
enum zbc_reporting_options | ro, | ||
struct zbc_zone * | zones, | ||
unsigned int * | nr_zones | ||
) |
Get zone information.
[in] | dev | Device handle obtained with zbc_open |
[in] | sector | Sector from which to report zones |
[in] | ro | Reporting options |
[in] | zones | Pointer to the array of zone information to fill |
[out] | nr_zones | Number of zones in the array zones |
Get zone information matching the sector and ro arguments and return the information obtained in the array zones and the number of zone information obtained at the address specified by nr_zones. The array zones must be allocated by the caller and nr_zones must point to the size of the allocated array (number of zone information structures in the array). The first zone reported will be the zone containing or after sector.
void zbc_set_log_level | ( | char const * | log_level | ) |
Set the library log level.
[in] | log_level | Library log level |
Set the library log level using the level name specified by log_level. Log level are incremental: each level includes the levels preceding it. Valid log level names are: "none" : Silent operation (no messages) "warning" : Print device level standard compliance problems "error" : Print messages related to unexpected errors "info" : Print normal information messages "debug" : Verbose output decribing internally executed commands The default level is "warning".
const char* zbc_sk_str | ( | enum zbc_sk | sk | ) |
Returns a string describing a sense key.
[in] | sk | Sense key |
const char* zbc_zone_condition_str | ( | enum zbc_zone_condition | cond | ) |
Returns a string describing a zone condition.
[in] | cond | Zone condition |
int zbc_zone_operation | ( | struct zbc_device * | dev, |
uint64_t | sector, | ||
enum zbc_zone_op | op, | ||
unsigned int | flags | ||
) |
Execute an operation on a zone.
[in] | dev | Device handle obtained with zbc_open |
[in] | sector | First sector of the target zone |
[in] | op | The operation to perform |
[in] | flags | Zone operation flags |
Exexcute an operation on the zone of dev starting at the sector specified by sector. The target zone must be a write pointer zone, that is, its type must be ZBC_ZT_SEQUENTIAL_REQ or ZBC_ZT_SEQUENTIAL_PREF. The validity of the operation (reset, open, close or finish) depends on the condition of the target zone. See zbc_reset_zone, zbc_open_zone, zbc_close_zone and zbc_finish_zone for details. If ZBC_OP_ALL_ZONES is set in flags then sector is ignored and the operation is executed on all possible zones.
const char* zbc_zone_type_str | ( | enum zbc_zone_type | type | ) |
returns a string describing a zone type
[in] | type | Zone type |