The main namespace of the ublk-cpp library. More...

Namespaces
namespace	daemon
	High-level API for running a ublk daemon.
namespace	raw
	Low-level io_uring command senders for ublk control and I/O commands.

Classes
struct	IoData
	Context of a single I/O request delivered to a handler. More...
struct	fetch_dev_info_t
	Environment query for the cached ublk device info. Returns nullptr if the environment doesn't provide it. More...
class	RuntimeOptions
	Runtime options for ublk device. More...

Concepts
concept	IoHandler
	Concept of an async handler with handle_io(const IoData&).
concept	QueueHandler
	Concept of a handler with per-queue init/destroy callbacks.
concept	ShmHandler
	Concept of a handler notified of shared memory buffer registration.

Functions
auto	get_queue_affinity (int control_fd, uint32_t dev_id, uint16_t q_id, cpu_set_t *cpuset) noexcept
	Get the queue affinity for a specific ublk queue.
auto	get_dev_info (int control_fd, uint32_t dev_id, ublksrv_ctrl_dev_info *info) noexcept
	Get the device information for a specific ublk device.
auto	add_dev (int control_fd, ublksrv_ctrl_dev_info *info) noexcept
	Add a new ublk device.
auto	del_dev (int control_fd, uint32_t dev_id) noexcept
	Delete a ublk device.
auto	start_dev (int control_fd, uint32_t dev_id, int32_t daemon_pid) noexcept
	Start a ublk device.
auto	stop_dev (int control_fd, uint32_t dev_id) noexcept
	Stop a ublk device.
auto	set_params (int control_fd, uint32_t dev_id, const ublk_params *params) noexcept
	Set the parameters of a ublk device.
auto	get_params (int control_fd, uint32_t dev_id, ublk_params *params) noexcept
	Get the parameters of a ublk device.
auto	start_user_recovery (int control_fd, uint32_t dev_id) noexcept
	Start user recovery for a ublk device.
auto	end_user_recovery (int control_fd, uint32_t dev_id, int32_t daemon_pid) noexcept
	End user recovery for a ublk device.
auto	get_features (int control_fd, uint64_t *features) noexcept
	Get the feature flags supported by the ublk driver.
auto	del_dev_async (int control_fd, uint32_t dev_id) noexcept
	Delete a ublk device asynchronously.
auto	update_size (int control_fd, uint32_t dev_id, uint64_t sectors) noexcept
	Update the size of a ublk device.
auto	quiesce_dev (int control_fd, uint32_t dev_id, uint64_t timeout_ms) noexcept
	Quiesce a ublk device (UBLK_F_QUIESCE).
auto	try_stop_dev (int control_fd, uint32_t dev_id) noexcept
	Try to stop a ublk device if it has no openers (UBLK_F_SAFE_STOP_DEV).
auto	register_shm_buf (int control_fd, uint32_t dev_id, const ublk_shmem_buf_reg *reg) noexcept
	Register a shared memory buffer for zero-copy I/O on a ublk device (UBLK_F_SHMEM_ZC).
auto	unregister_shm_buf (int control_fd, uint32_t dev_id, uint64_t buf_index) noexcept
	Unregister a shared memory buffer from a ublk device.
uint16_t	shmem_zc_index (uint64_t addr) noexcept
	Extract the buffer index from a shared memory zero-copy encoded address (UBLK_IO_F_SHMEM_ZC).
uint32_t	shmem_zc_offset (uint64_t addr) noexcept
	Extract the byte offset within the buffer from a shared memory zero-copy encoded address (UBLK_IO_F_SHMEM_ZC).
uint64_t	user_copy_pos (uint16_t q_id, uint16_t tag, uint32_t offset) noexcept
	Compute the byte position in /dev/ublkcN for user-space data copy (UBLK_F_USER_COPY).
template<IoHandler F>
auto	run_dev (int ublkc_fd, uint16_t q_id, const ublksrv_ctrl_dev_info *info, F &handler) noexcept
	Run the I/O loop of a single ublk queue until it stops.

Variables
constexpr fetch_dev_info_t	fetch_dev_info {}
	Query object instance of fetch_dev_info_t.
constexpr int	version_major = UBLKCPP_VERSION_MAJOR
	ublk-cpp major version.
constexpr int	version_minor = UBLKCPP_VERSION_MINOR
	ublk-cpp minor version.

Detailed Description

The main namespace of the ublk-cpp library.

Function Documentation

◆ add_dev()

auto ublk::add_dev	(	int	control_fd,
		ublksrv_ctrl_dev_info *	info )

inlinenoexcept

Add a new ublk device.

Parameters

control_fd	The control file descriptor for the ublk device.
info	A pointer to the device information structure describing the device to add.

Returns: sender () on success, std::error_code on failure.

Definition at line 47 of file control.hpp.

◆ del_dev()

auto ublk::del_dev	(	int	control_fd,
		uint32_t	dev_id )

inlinenoexcept

Delete a ublk device.

Parameters

control_fd	The control file descriptor for the ublk device.
dev_id	The device ID of the ublk device to delete.

Returns: sender () on success, std::exception_ptr on failure.

Definition at line 58 of file control.hpp.

◆ del_dev_async()

auto ublk::del_dev_async	(	int	control_fd,
		uint32_t	dev_id )

inlinenoexcept

Delete a ublk device asynchronously.

Parameters

control_fd	The control file descriptor for the ublk device.
dev_id	The device ID of the ublk device to delete.

Returns: sender () on success, std::exception_ptr on failure.

Definition at line 153 of file control.hpp.

◆ end_user_recovery()

auto ublk::end_user_recovery	(	int	control_fd,
		uint32_t	dev_id,
		int32_t	daemon_pid )

inlinenoexcept

End user recovery for a ublk device.

Parameters

control_fd	The control file descriptor for the ublk device.
dev_id	The device ID of the ublk device.
daemon_pid	The PID of the daemon process that serves the device.

Returns: sender () on success, std::exception_ptr on failure.

Definition at line 130 of file control.hpp.

◆ get_dev_info()

auto ublk::get_dev_info	(	int	control_fd,
		uint32_t	dev_id,
		ublksrv_ctrl_dev_info *	info )

inlinenoexcept

Get the device information for a specific ublk device.

Parameters

control_fd	The control file descriptor for the ublk device.
dev_id	The device ID of the ublk device.
info	A pointer to the device information structure to populate.

Returns: sender () on success, std::exception_ptr on failure.

Definition at line 34 of file control.hpp.

◆ get_features()

auto ublk::get_features	(	int	control_fd,
		uint64_t *	features )

inlinenoexcept

Get the feature flags supported by the ublk driver.

Parameters

control_fd	The control file descriptor for the ublk device.
features	A pointer to store the returned UBLK_F_* feature flags.

Returns: sender () on success, std::error_code on failure.

Definition at line 142 of file control.hpp.

◆ get_params()

auto ublk::get_params	(	int	control_fd,
		uint32_t	dev_id,
		ublk_params *	params )

inlinenoexcept

Get the parameters of a ublk device.

Parameters

control_fd	The control file descriptor for the ublk device.
dev_id	The device ID of the ublk device.
params	A pointer to the parameters structure to populate.

Returns: sender () on success, std::exception_ptr on failure.

Definition at line 106 of file control.hpp.

◆ get_queue_affinity()

auto ublk::get_queue_affinity	(	int	control_fd,
		uint32_t	dev_id,
		uint16_t	q_id,
		cpu_set_t *	cpuset )

inlinenoexcept

Get the queue affinity for a specific ublk queue.

Parameters

control_fd	The control file descriptor for the ublk device.
dev_id	The device ID of the ublk device.
q_id	The queue ID for which to retrieve the affinity information.
cpuset	A pointer to the CPU set to store the affinity information.

Returns: sender () on success, std::exception_ptr on failure.

Definition at line 21 of file control.hpp.

◆ quiesce_dev()

auto ublk::quiesce_dev	(	int	control_fd,
		uint32_t	dev_id,
		uint64_t	timeout_ms )

inlinenoexcept

Quiesce a ublk device (UBLK_F_QUIESCE).

Parameters

control_fd	The control file descriptor for the ublk device.
dev_id	The device ID of the ublk device.
timeout_ms	The timeout in milliseconds allowed for the device to quiesce.

Returns: sender () on success, std::exception_ptr on failure.

Definition at line 179 of file control.hpp.

◆ register_shm_buf()

auto ublk::register_shm_buf	(	int	control_fd,
		uint32_t	dev_id,
		const ublk_shmem_buf_reg *	reg )

inlinenoexcept

Register a shared memory buffer for zero-copy I/O on a ublk device (UBLK_F_SHMEM_ZC).

Parameters

control_fd	The control file descriptor for the ublk device.
dev_id	The device ID of the ublk device.
reg	A pointer to the shared memory buffer registration describing the buffer to register.

Returns: sender int32_t (the assigned buffer index) on success, std::exception_ptr on failure.

Definition at line 206 of file control.hpp.

◆ run_dev()

template<IoHandler F>

auto ublk::run_dev	(	int	ublkc_fd,
		uint16_t	q_id,
		const ublksrv_ctrl_dev_info *	info,
		F &	handler )

inlinenoexcept

Run the I/O loop of a single ublk queue until it stops.

Parameters

ublkc_fd	The file descriptor of the ublk queue (/dev/ublkcN).
q_id	The queue ID of the queue to run.
info	A pointer to the device information of the ublk device.
handler	The IoHandler invoked for each fetched request.

Returns: A sender completing when the queue stops, or with an error on failure.

Definition at line 23 of file io.hpp.

◆ set_params()

auto ublk::set_params	(	int	control_fd,
		uint32_t	dev_id,
		const ublk_params *	params )

inlinenoexcept

Set the parameters of a ublk device.

Parameters

control_fd	The control file descriptor for the ublk device.
dev_id	The device ID of the ublk device.
params	A pointer to the parameters to apply to the device.

Returns: sender () on success, std::exception_ptr on failure.

Definition at line 93 of file control.hpp.

◆ shmem_zc_index()

uint16_t ublk::shmem_zc_index ( uint64_t addr )

inlinenoexcept

Extract the buffer index from a shared memory zero-copy encoded address (UBLK_IO_F_SHMEM_ZC).

Parameters

addr	The encoded addr field of an I/O descriptor, set by the driver when a request's pages match a registered shared memory buffer.

Returns: The buffer index.

Definition at line 21 of file helpers.hpp.

◆ shmem_zc_offset()

uint32_t ublk::shmem_zc_offset ( uint64_t addr )

inlinenoexcept

Extract the byte offset within the buffer from a shared memory zero-copy encoded address (UBLK_IO_F_SHMEM_ZC).

Parameters

addr	The encoded addr field of an I/O descriptor, set by the driver when a request's pages match a registered shared memory buffer.

Returns: The byte offset.

Definition at line 32 of file helpers.hpp.

◆ start_dev()

auto ublk::start_dev	(	int	control_fd,
		uint32_t	dev_id,
		int32_t	daemon_pid )

inlinenoexcept

Start a ublk device.

Parameters

control_fd	The control file descriptor for the ublk device.
dev_id	The device ID of the ublk device.
daemon_pid	The PID of the daemon process that serves the device.

Returns: sender () on success, std::exception_ptr on failure.

Definition at line 69 of file control.hpp.

◆ start_user_recovery()

auto ublk::start_user_recovery	(	int	control_fd,
		uint32_t	dev_id )

inlinenoexcept

Start user recovery for a ublk device.

Parameters

control_fd	The control file descriptor for the ublk device.
dev_id	The device ID of the ublk device.

Returns: sender () on success, std::exception_ptr on failure.

Definition at line 118 of file control.hpp.

◆ stop_dev()

auto ublk::stop_dev	(	int	control_fd,
		uint32_t	dev_id )

inlinenoexcept

Stop a ublk device.

Parameters

control_fd	The control file descriptor for the ublk device.
dev_id	The device ID of the ublk device to stop.

Returns: sender () on success, std::exception_ptr on failure.

Definition at line 81 of file control.hpp.

◆ try_stop_dev()

auto ublk::try_stop_dev	(	int	control_fd,
		uint32_t	dev_id )

inlinenoexcept

Try to stop a ublk device if it has no openers (UBLK_F_SAFE_STOP_DEV).

Parameters

control_fd	The control file descriptor for the ublk device.
dev_id	The device ID of the ublk device to stop.

Returns: sender () on success, std::exception_ptr on failure.

Definition at line 191 of file control.hpp.

◆ unregister_shm_buf()

auto ublk::unregister_shm_buf	(	int	control_fd,
		uint32_t	dev_id,
		uint64_t	buf_index )

inlinenoexcept

Unregister a shared memory buffer from a ublk device.

Parameters

control_fd	The control file descriptor for the ublk device.
dev_id	The device ID of the ublk device.
buf_index	The index of the shared memory buffer to unregister, as returned by register_shm_buf().

Returns: sender () on success, std::exception_ptr on failure.

Definition at line 220 of file control.hpp.

◆ update_size()

auto ublk::update_size	(	int	control_fd,
		uint32_t	dev_id,
		uint64_t	sectors )

inlinenoexcept

Update the size of a ublk device.

Parameters

control_fd	The control file descriptor for the ublk device.
dev_id	The device ID of the ublk device.
sectors	The new device size in sectors.

Returns: sender () on success, std::exception_ptr on failure.

Definition at line 165 of file control.hpp.

◆ user_copy_pos()

uint64_t ublk::user_copy_pos	(	uint16_t	q_id,
		uint16_t	tag,
		uint32_t	offset )

inlinenoexcept

Compute the byte position in /dev/ublkcN for user-space data copy (UBLK_F_USER_COPY).

Parameters

q_id	The queue ID of the request.
tag	The tag of the request.
offset	The byte offset within the request buffer.

Returns: The absolute byte position to pass to pread()/pwrite() for accessing the request data at offset.

Definition at line 45 of file helpers.hpp.

Namespaces

Classes

Concepts

Functions

Variables

Detailed Description

Function Documentation

◆ add_dev()

◆ del_dev()

◆ del_dev_async()

◆ end_user_recovery()

◆ get_dev_info()

◆ get_features()

◆ get_params()

◆ get_queue_affinity()

◆ quiesce_dev()

◆ register_shm_buf()

◆ run_dev()

◆ set_params()

◆ shmem_zc_index()

◆ shmem_zc_offset()

◆ start_dev()

◆ start_user_recovery()

◆ stop_dev()

◆ try_stop_dev()

◆ unregister_shm_buf()

◆ update_size()

◆ user_copy_pos()