16. Block Device Library

The block device library provides a generic, extensible interface for managing block devices in high-performance environments. It abstracts block device operations such as read, write, flush, reset, and statistics, supporting multiple device types (e.g., RAM disk). The library is designed for integration into DPU offload and storage acceleration solutions, enabling efficient and flexible block storage management.

16.1. Features

The library is designed to support various block device types, with extensibility for new types. Current supported devices are:

  • RAM Disk: In-memory block device for fast, volatile storage.

The library supports the following generic features on a block device:

  • Read/Write Operations: Efficient APIs for reading from and writing to block devices using IO vectors.

  • Flush: Ensures all buffered data is written to the device.

  • Reset: Resets the block device.

  • Unmap: Deallocates or unmaps specified sectors/blocks.

  • Write Zeroes: Writes zeroes to a specified region, with optional unmap support.

  • Discard: Discards data in a specified sector range.

  • Device Identification: Retrieve device identifiers as a string.

  • Statistics: Collects and provides detailed statistics on read, write, flush, reset, unmap, and write zeroes operations.

  • Statistics Management: APIs to retrieve and clear device statistics.

  • Extensible Handlers: All operations are handled via a callback structure, allowing for easy extension and customization for new device types.

16.2. Library APIs

16.2.1. Control Path API

The control path API mainly consists of block device creation and deletion, and statistics management.

  • Create a Block Device

Block Device Configuration Structure

struct dao_blkdev_conf {
	/** Block device capacity in sectors/blocks */
	uint64_t capacity;
	/** Block size */
	uint32_t blk_size;
	/** block device type */
	uint8_t dev_type;
};

Initializes a block device with the given configuration and name.

int dao_blkdev_create(uint16_t dev_id, struct dao_blkdev_conf *conf, const char *name);

  • Delete a Block Device

Cleans up and removes the specified block device.

int dao_blkdev_destroy(uint16_t dev_id);

  • Get Block Device Statistics

Retrieves statistics for the device (read/write ops, bytes, etc.).

void dao_blkdev_get_stats(uint16_t dev_id, dao_blkdev_stats_t *stats);

  • Clear Block Device Statistics

Clears the statistics counters for the device.

void dao_blkdev_clear_stats(uint16_t dev_id);

16.2.2. Data Path API

Data path operations on the block device and the corresponding API are listed below:

  • Block Device Read

Reads data from the specified sector(s) into the provided IO vector.

int dao_blkdev_read(uint16_t dev_id, uint64_t sector, blk_io_vec_t *iov, size_t len);

  • Block Device Write

Writes data to the specified sector(s) from the provided IO vector.

int dao_blkdev_write(uint16_t dev_id, uint64_t sector, blk_io_vec_t *iov, size_t len);

  • Block Device Flush

Flushes any cached data to the device.

int dao_blkdev_flush(uint16_t dev_id);

  • Block Device Reset

Resets the block device.

int dao_blkdev_reset(uint16_t dev_id);

  • Unmap Sectors of a Block Device

Unmaps the specified range of sectors.

int dao_blkdev_unmap(uint16_t dev_id, uint64_t sector, size_t len);

  • Write Zeroes to a Block Device

Writes zeroes to the specified range, with optional unmap.

int dao_blkdev_write_zeroes(uint16_t dev_id, uint64_t sector, size_t len, uint8_t unmap);

  • Get Device Identifier of a Block Device

Retrieves the string identifier for the device.

int dao_blkdev_get_id(uint16_t dev_id, char *name, size_t max_len);

  • Discard Data

Discards data in the specified sector range.

int dao_blkdev_discard(uint16_t dev_id, uint64_t sector, size_t len);