ublk::raw Namespace Reference

Low-level io_uring command senders for ublk control and I/O commands. More...

Functions
template<typename Fd>
auto	get_queue_affinity (Fd fd, uint32_t dev_id, uint16_t q_id, void *data, uint16_t size, uint16_t dev_path_len) noexcept
	Unprivileged version of get_queue_affinity().
template<typename Fd>
auto	get_queue_affinity (Fd fd, uint32_t dev_id, uint16_t q_id, cpu_set_t *cpuset) noexcept
	Get the queue affinity for a specific ublk queue.
template<typename Fd>
auto	get_dev_info (Fd fd, uint32_t dev_id, void *data, uint16_t size, uint16_t dev_path_len) noexcept
	Unprivileged version of get_dev_info().
template<typename Fd>
auto	get_dev_info (Fd fd, uint32_t dev_id, ublksrv_ctrl_dev_info *info) noexcept
	Get the device information for a specific ublk device.
template<typename Fd>
auto	add_dev (Fd fd, ublksrv_ctrl_dev_info *info) noexcept
	Add a new ublk device.
template<typename Fd>
auto	del_dev (Fd fd, uint32_t dev_id, const char *dev_path, uint16_t dev_path_len) noexcept
	Unprivileged version of del_dev().
template<typename Fd>
auto	del_dev (Fd fd, uint32_t dev_id) noexcept
	Delete a ublk device.
template<typename Fd>
auto	start_dev (Fd fd, uint32_t dev_id, int32_t daemon_pid, const char *dev_path, uint16_t dev_path_len) noexcept
	Unprivileged version of start_dev().
template<typename Fd>
auto	start_dev (Fd fd, uint32_t dev_id, int32_t daemon_pid) noexcept
	Start a ublk device.
template<typename Fd>
auto	stop_dev (Fd fd, uint32_t dev_id, const char *dev_path, uint16_t dev_path_len) noexcept
	Unprivileged version of stop_dev().
template<typename Fd>
auto	stop_dev (Fd fd, uint32_t dev_id) noexcept
	Stop a ublk device.
template<typename Fd>
auto	set_params (Fd fd, uint32_t dev_id, const void *data, uint16_t size, uint16_t dev_path_len) noexcept
	Unprivileged version of set_params().
template<typename Fd>
auto	set_params (Fd fd, uint32_t dev_id, const ublk_params *params) noexcept
	Set the parameters of a ublk device.
template<typename Fd>
auto	get_params (Fd fd, uint32_t dev_id, void *data, uint16_t size, uint16_t dev_path_len) noexcept
	Unprivileged version of get_params().
template<typename Fd>
auto	get_params (Fd fd, uint32_t dev_id, ublk_params *params) noexcept
	Get the parameters of a ublk device.
template<typename Fd>
auto	start_user_recovery (Fd fd, uint32_t dev_id, const char *dev_path, uint16_t dev_path_len) noexcept
	Unprivileged version of start_user_recovery().
template<typename Fd>
auto	start_user_recovery (Fd fd, uint32_t dev_id) noexcept
	Start user recovery for a ublk device.
template<typename Fd>
auto	end_user_recovery (Fd fd, uint32_t dev_id, int32_t daemon_pid, const char *dev_path, uint16_t dev_path_len) noexcept
	Unprivileged version of end_user_recovery().
template<typename Fd>
auto	end_user_recovery (Fd fd, uint32_t dev_id, int32_t daemon_pid) noexcept
	End user recovery for a ublk device.
template<typename Fd>
auto	get_dev_info2 (Fd fd, uint32_t dev_id, void *data, uint16_t size, uint16_t dev_path_len) noexcept
	Get the device information of a ublk device, works both for privileged and unprivileged modes.
template<typename Fd>
auto	get_features (Fd fd, uint64_t *features) noexcept
	Get the feature flags supported by the ublk driver.
template<typename Fd>
auto	del_dev_async (Fd fd, uint32_t dev_id, const char *dev_path, uint16_t dev_path_len) noexcept
	Unprivileged version of del_dev_async().
template<typename Fd>
auto	del_dev_async (Fd fd, uint32_t dev_id) noexcept
	Delete a ublk device asynchronously.
template<typename Fd>
auto	update_size (Fd fd, uint32_t dev_id, uint64_t sectors, const char *dev_path, uint16_t dev_path_len) noexcept
	Unprivileged version of update_size().
template<typename Fd>
auto	update_size (Fd fd, uint32_t dev_id, uint64_t sectors) noexcept
	Update the size of a ublk device.
template<typename Fd>
auto	quiesce_dev (Fd fd, uint32_t dev_id, uint64_t timeout_ms, const char *dev_path, uint16_t dev_path_len) noexcept
	Unprivileged version of quiesce_dev().
template<typename Fd>
auto	quiesce_dev (Fd fd, uint32_t dev_id, uint64_t timeout_ms) noexcept
	Quiesce a ublk device (UBLK_F_QUIESCE).
template<typename Fd>
auto	try_stop_dev (Fd fd, uint32_t dev_id, const char *dev_path, uint16_t dev_path_len) noexcept
	Unprivileged version of try_stop_dev().
template<typename Fd>
auto	try_stop_dev (Fd fd, uint32_t dev_id) noexcept
	Try to stop a ublk device if it has no openers (UBLK_F_SAFE_STOP_DEV).
template<typename Fd>
auto	register_shm_buf (Fd fd, uint32_t dev_id, const void *data, uint16_t size, uint16_t dev_path_len) noexcept
	Unprivileged version of register_shm_buf().
template<typename Fd>
auto	register_shm_buf (Fd 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).
template<typename Fd>
auto	unregister_shm_buf (Fd fd, uint32_t dev_id, uint64_t buf_index, const char *dev_path, uint16_t dev_path_len) noexcept
	Unprivileged version of unregister_shm_buf().
template<typename Fd>
auto	unregister_shm_buf (Fd fd, uint32_t dev_id, uint64_t buf_index) noexcept
	Unregister a shared memory buffer from a ublk device.
template<typename Fd>
auto	fetch_req (Fd fd, uint16_t q_id, uint16_t tag, uint64_t buf_addr, uint64_t sqe_addr) noexcept
	Overload of fetch_req() with an explicit sqe->addr, used for automatic request buffer registration (UBLK_F_AUTO_BUF_REG).
template<typename Fd>
auto	fetch_req (Fd fd, uint16_t q_id, uint16_t tag, uint64_t buf_addr) noexcept
	Fetch an I/O request from a ublk queue.
template<typename Fd>
auto	commit_and_fetch_req (Fd fd, uint16_t q_id, uint16_t tag, int32_t result, uint64_t buf_addr, uint64_t sqe_addr) noexcept
	Overload of commit_and_fetch_req() with an explicit sqe->addr, used for automatic request buffer registration (UBLK_F_AUTO_BUF_REG).
template<typename Fd>
auto	commit_and_fetch_req (Fd fd, uint16_t q_id, uint16_t tag, int32_t result, uint64_t buf_addr) noexcept
	Commit the result of an I/O request to the driver and fetch the next request for the same queue.
template<typename Fd>
auto	need_get_data (Fd fd, uint16_t q_id, uint16_t tag, uint64_t buf_addr) noexcept
	Copy the data of a write request into the user buffer after the driver returns UBLK_IO_RES_NEED_GET_DATA.
template<typename Fd>
auto	register_io_buf (Fd fd, uint16_t q_id, uint16_t tag, uint64_t buf_index) noexcept
	Register the buffer of an in-flight request into the io_uring buffer table for zero-copy I/O (UBLK_F_SUPPORT_ZERO_COPY).
template<typename Fd>
auto	unregister_io_buf (Fd fd, uint16_t q_id, uint16_t tag, uint64_t buf_index) noexcept
	Unregister the buffer of an in-flight request from the io_uring buffer table after zero-copy I/O completes.
template<typename Fd>
auto	prep_io_cmds (Fd fd, uint16_t q_id, uint16_t flags, uint16_t nr_elem, uint8_t elem_bytes, const void *elems, uint32_t elems_len) noexcept
	Prepare a batch of I/O commands for a queue (UBLK_F_BATCH_IO).
template<typename Fd>
auto	commit_io_cmds (Fd fd, uint16_t q_id, uint16_t flags, uint16_t nr_elem, uint8_t elem_bytes, const void *elems, uint32_t elems_len) noexcept
	Commit a batch of completed I/O commands for a queue (UBLK_F_BATCH_IO).
template<typename Fd, typename MultiShotFunc>
auto	fetch_io_cmds (Fd fd, condy::ProvidedBufferQueue &buffers, uint16_t q_id, MultiShotFunc &&func) noexcept
	Fetch I/O commands in multishot style into a provided buffer queue (UBLK_F_BATCH_IO).

Detailed Description

Low-level io_uring command senders for ublk control and I/O commands.

Function Documentation

add_dev()

template<typename Fd>

auto ublk::raw::add_dev ( Fd fd, ublksrv_ctrl_dev_info * info )

inlinenoexcept

Add a new ublk device.

Parameters

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

Returns

sender int32_t on success, std::error_code on failure.

Definition at line 80 of file raw.hpp.

commit_and_fetch_req()

template<typename Fd>

auto ublk::raw::commit_and_fetch_req ( Fd fd, uint16_t q_id, uint16_t tag, int32_t result, uint64_t buf_addr )

inlinenoexcept

Commit the result of an I/O request to the driver and fetch the next request for the same queue.

Parameters

fd	The file descriptor of the ublk queue (/dev/ublkcN).
q_id	The queue ID of the queue the request belongs to.
tag	The tag of the request whose result is committed.
result	The I/O completion result to commit for the request.
buf_addr	The address of the buffer to receive the next request's data.

Returns

sender int32_t on success, std::error_code on failure.

Definition at line 466 of file raw.hpp.

commit_io_cmds()

template<typename Fd>

auto ublk::raw::commit_io_cmds ( Fd fd, uint16_t q_id, uint16_t flags, uint16_t nr_elem, uint8_t elem_bytes, const void * elems, uint32_t elems_len )

inlinenoexcept

Commit a batch of completed I/O commands for a queue (UBLK_F_BATCH_IO).

Parameters

fd	The file descriptor of the ublk queue (/dev/ublkcN).
q_id	The queue ID of the queue the batch belongs to.
flags	Batch flags (UBLK_BATCH_F_*).
nr_elem	The number of I/O command elements in the batch.
elem_bytes	The size in bytes of each I/O command element.
elems	A pointer to the batch buffer holding the I/O command elements.
elems_len	The size in bytes of the batch buffer.

Returns

sender int32_t (the number of bytes of elems actually committed) on success, std::error_code on failure.

Definition at line 555 of file raw.hpp.

del_dev()

template<typename Fd>

auto ublk::raw::del_dev ( Fd fd, uint32_t dev_id )

inlinenoexcept

Delete a ublk device.

Parameters

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

Returns

sender int32_t on success, std::error_code on failure.

Definition at line 103 of file raw.hpp.

del_dev_async()

template<typename Fd>

auto ublk::raw::del_dev_async ( Fd fd, uint32_t dev_id )

inlinenoexcept

Delete a ublk device asynchronously.

Parameters

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

Returns

sender int32_t on success, std::error_code on failure.

Definition at line 291 of file raw.hpp.

end_user_recovery()

template<typename Fd>

auto ublk::raw::end_user_recovery ( Fd fd, uint32_t dev_id, int32_t daemon_pid )

inlinenoexcept

End user recovery for a ublk device.

Parameters

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 int32_t on success, std::error_code on failure.

Definition at line 242 of file raw.hpp.

fetch_io_cmds()

template<typename Fd, typename MultiShotFunc>

auto ublk::raw::fetch_io_cmds ( Fd fd, condy::ProvidedBufferQueue & buffers, uint16_t q_id, MultiShotFunc && func )

inlinenoexcept

Fetch I/O commands in multishot style into a provided buffer queue (UBLK_F_BATCH_IO).

Parameters

fd	The file descriptor of the ublk queue (/dev/ublkcN).
buffers	The provided buffer queue that receives the fetched I/O commands.
q_id	The queue ID of the queue to fetch I/O commands from.
func	The callback invoked for each fetched batch of I/O commands.

Returns

sender (int32_t, condy::BufferInfo) on success, std::error_code on failure.

Definition at line 575 of file raw.hpp.

fetch_req()

template<typename Fd>

auto ublk::raw::fetch_req ( Fd fd, uint16_t q_id, uint16_t tag, uint64_t buf_addr )

inlinenoexcept

Fetch an I/O request from a ublk queue.

Parameters

fd	The file descriptor of the ublk queue (/dev/ublkcN).
q_id	The queue ID of the queue to fetch the request from.
tag	The tag identifying the request slot to fetch.
buf_addr	The address of the buffer to receive the request's data.

Returns

sender int32_t on success, std::error_code on failure.

Definition at line 437 of file raw.hpp.

get_dev_info()

template<typename Fd>

auto ublk::raw::get_dev_info ( Fd fd, uint32_t dev_id, ublksrv_ctrl_dev_info * info )

inlinenoexcept

Get the device information for a specific ublk device.

Parameters

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 int32_t on success, std::error_code on failure.

Definition at line 67 of file raw.hpp.

get_dev_info2()

template<typename Fd>

auto ublk::raw::get_dev_info2 ( Fd fd, uint32_t dev_id, void * data, uint16_t size, uint16_t dev_path_len )

inlinenoexcept

Get the device information of a ublk device, works both for privileged and unprivileged modes.

Returns

sender int32_t on success, std::error_code on failure.

Definition at line 253 of file raw.hpp.

get_features()

template<typename Fd>

auto ublk::raw::get_features ( Fd fd, uint64_t * features )

inlinenoexcept

Get the feature flags supported by the ublk driver.

Parameters

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

Returns

sender int32_t on success, std::error_code on failure.

Definition at line 267 of file raw.hpp.

get_params()

template<typename Fd>

auto ublk::raw::get_params ( Fd fd, uint32_t dev_id, ublk_params * params )

inlinenoexcept

Get the parameters of a ublk device.

Parameters

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 int32_t on success, std::error_code on failure.

Definition at line 195 of file raw.hpp.

get_queue_affinity()

template<typename Fd>

auto ublk::raw::get_queue_affinity ( Fd fd, uint32_t dev_id, uint16_t q_id, cpu_set_t * cpuset )

inlinenoexcept

Get the queue affinity for a specific ublk queue.

Parameters

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 int32_t on success, std::error_code on failure.

Definition at line 43 of file raw.hpp.

need_get_data()

template<typename Fd>

auto ublk::raw::need_get_data ( Fd fd, uint16_t q_id, uint16_t tag, uint64_t buf_addr )

inlinenoexcept

Copy the data of a write request into the user buffer after the driver returns UBLK_IO_RES_NEED_GET_DATA.

Parameters

fd	The file descriptor of the ublk queue (/dev/ublkcN).
q_id	The queue ID of the request.
tag	The tag of the request.
buf_addr	The address of the buffer to receive the request data.

Returns

sender int32_t on success, std::error_code on failure.

Definition at line 481 of file raw.hpp.

prep_io_cmds()

template<typename Fd>

auto ublk::raw::prep_io_cmds ( Fd fd, uint16_t q_id, uint16_t flags, uint16_t nr_elem, uint8_t elem_bytes, const void * elems, uint32_t elems_len )

inlinenoexcept

Prepare a batch of I/O commands for a queue (UBLK_F_BATCH_IO).

Parameters

fd	The file descriptor of the ublk queue (/dev/ublkcN).
q_id	The queue ID of the queue the batch belongs to.
flags	Batch flags (UBLK_BATCH_F_*).
nr_elem	The number of I/O command elements in the batch.
elem_bytes	The size in bytes of each I/O command element.
elems	A pointer to the batch buffer holding the I/O command elements.
elems_len	The size in bytes of the batch buffer.

Returns

sender int32_t on success, std::error_code on failure.

Definition at line 533 of file raw.hpp.

quiesce_dev()

template<typename Fd>

auto ublk::raw::quiesce_dev ( Fd fd, uint32_t dev_id, uint64_t timeout_ms )

inlinenoexcept

Quiesce a ublk device (UBLK_F_QUIESCE).

Parameters

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 int32_t on success, std::error_code on failure.

Definition at line 338 of file raw.hpp.

register_io_buf()

template<typename Fd>

auto ublk::raw::register_io_buf ( Fd fd, uint16_t q_id, uint16_t tag, uint64_t buf_index )

inlinenoexcept

Register the buffer of an in-flight request into the io_uring buffer table for zero-copy I/O (UBLK_F_SUPPORT_ZERO_COPY).

Parameters

fd	The file descriptor of the ublk queue (/dev/ublkcN).
q_id	The queue ID of the request.
tag	The tag of the request.
buf_index	The index in the io_uring buffer table to install the request buffer at.

Returns

sender int32_t on success, std::error_code on failure.

Definition at line 498 of file raw.hpp.

register_shm_buf()

template<typename Fd>

auto ublk::raw::register_shm_buf ( Fd 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

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::error_code on failure.

Definition at line 386 of file raw.hpp.

set_params()

template<typename Fd>

auto ublk::raw::set_params ( Fd fd, uint32_t dev_id, const ublk_params * params )

inlinenoexcept

Set the parameters of a ublk device.

Parameters

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 int32_t on success, std::error_code on failure.

Definition at line 171 of file raw.hpp.

start_dev()

template<typename Fd>

auto ublk::raw::start_dev ( Fd fd, uint32_t dev_id, int32_t daemon_pid )

inlinenoexcept

Start a ublk device.

Parameters

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 int32_t on success, std::error_code on failure.

Definition at line 127 of file raw.hpp.

start_user_recovery()

template<typename Fd>

auto ublk::raw::start_user_recovery ( Fd fd, uint32_t dev_id )

inlinenoexcept

Start user recovery for a ublk device.

Parameters

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

Returns

sender int32_t on success, std::error_code on failure.

Definition at line 217 of file raw.hpp.

stop_dev()

template<typename Fd>

auto ublk::raw::stop_dev ( Fd fd, uint32_t dev_id )

inlinenoexcept

Stop a ublk device.

Parameters

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

Returns

sender int32_t on success, std::error_code on failure.

Definition at line 148 of file raw.hpp.

try_stop_dev()

template<typename Fd>

auto ublk::raw::try_stop_dev ( Fd fd, uint32_t dev_id )

inlinenoexcept

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

Parameters

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

Returns

sender int32_t on success, std::error_code on failure.

Definition at line 360 of file raw.hpp.

unregister_io_buf()

template<typename Fd>

auto ublk::raw::unregister_io_buf ( Fd fd, uint16_t q_id, uint16_t tag, uint64_t buf_index )

inlinenoexcept

Unregister the buffer of an in-flight request from the io_uring buffer table after zero-copy I/O completes.

Parameters

fd	The file descriptor of the ublk queue (/dev/ublkcN).
q_id	The queue ID of the request.
tag	The tag of the request.
buf_index	The index in the io_uring buffer table the request buffer was installed at.

Returns

sender int32_t on success, std::error_code on failure.

Definition at line 515 of file raw.hpp.

unregister_shm_buf()

template<typename Fd>

auto ublk::raw::unregister_shm_buf ( Fd fd, uint32_t dev_id, uint64_t buf_index )

inlinenoexcept

Unregister a shared memory buffer from a ublk device.

Parameters

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 int32_t on success, std::error_code on failure.

Definition at line 412 of file raw.hpp.

update_size()

template<typename Fd>

auto ublk::raw::update_size ( Fd fd, uint32_t dev_id, uint64_t sectors )

inlinenoexcept

Update the size of a ublk device.

Parameters

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 int32_t on success, std::error_code on failure.

Definition at line 314 of file raw.hpp.