include/uapi/linux/ublk_cmd.h

Source file repositories/reference/linux-study-clean/include/uapi/linux/ublk_cmd.h

File Facts

System
Linux kernel
Corpus path
include/uapi/linux/ublk_cmd.h
Extension
.h
Size
26950 bytes
Lines
827
Domain
Core OS
Bucket
Core Kernel Interface
Inferred role
Core OS: implementation source
Status
source implementation candidate

Why This File Exists

Core operating-system implementation surface: boot, tasks, memory, VFS, syscall-facing interfaces, synchronization, credentials, and isolation.

Dependency Surface

Detected Declarations

Annotated Snippet

struct ublk_shmem_buf_reg {
	__u64	addr;	/* userspace virtual address of shared memory */
	__u64	len;	/* buffer size in bytes, page-aligned, default max 4GB */
	__u32	flags;
	__u32	reserved;
};

/* Pin pages without FOLL_WRITE; usable with write-sealed memfd */
#define UBLK_SHMEM_BUF_READ_ONLY	(1U << 0)
/*
 * 64bits are enough now, and it should be easy to extend in case of
 * running out of feature flags
 */
#define UBLK_FEATURES_LEN  8

/*
 * IO commands, issued by ublk server, and handled by ublk driver.
 *
 * FETCH_REQ: issued via sqe(URING_CMD) beforehand for fetching IO request
 *      from ublk driver, should be issued only when starting device. After
 *      the associated cqe is returned, request's tag can be retrieved via
 *      cqe->userdata.
 *
 * COMMIT_AND_FETCH_REQ: issued via sqe(URING_CMD) after ublkserver handled
 *      this IO request, request's handling result is committed to ublk
 *      driver, meantime FETCH_REQ is piggyback, and FETCH_REQ has to be
 *      handled before completing io request.
 *
 * NEED_GET_DATA: only used for write requests to set io addr and copy data
 *      When NEED_GET_DATA is set, ublksrv has to issue UBLK_IO_NEED_GET_DATA
 *      command after ublk driver returns UBLK_IO_RES_NEED_GET_DATA.
 *
 *      It is only used if ublksrv set UBLK_F_NEED_GET_DATA flag
 *      while starting a ublk device.
 */

/*
 * Legacy IO command definition, don't use in new application, and don't
 * add new such definition any more
 */
#define	UBLK_IO_FETCH_REQ		0x20
#define	UBLK_IO_COMMIT_AND_FETCH_REQ	0x21
#define	UBLK_IO_NEED_GET_DATA	0x22

/* Any new IO command should encode by __IOWR() */
#define	UBLK_U_IO_FETCH_REQ		\
	_IOWR('u', UBLK_IO_FETCH_REQ, struct ublksrv_io_cmd)
#define	UBLK_U_IO_COMMIT_AND_FETCH_REQ	\
	_IOWR('u', UBLK_IO_COMMIT_AND_FETCH_REQ, struct ublksrv_io_cmd)
#define	UBLK_U_IO_NEED_GET_DATA		\
	_IOWR('u', UBLK_IO_NEED_GET_DATA, struct ublksrv_io_cmd)
#define	UBLK_U_IO_REGISTER_IO_BUF	\
	_IOWR('u', 0x23, struct ublksrv_io_cmd)
#define	UBLK_U_IO_UNREGISTER_IO_BUF	\
	_IOWR('u', 0x24, struct ublksrv_io_cmd)

/*
 * return 0 if the command is run successfully, otherwise failure code
 * is returned
 */
#define	UBLK_U_IO_PREP_IO_CMDS	\
	_IOWR('u', 0x25, struct ublk_batch_io)
/*
 * If failure code is returned, nothing in the command buffer is handled.
 * Otherwise, the returned value means how many bytes in command buffer
 * are handled actually, then number of handled IOs can be calculated with
 * `elem_bytes` for each IO. IOs in the remained bytes are not committed,
 * userspace has to check return value for dealing with partial committing
 * correctly.
 */
#define	UBLK_U_IO_COMMIT_IO_CMDS	\
	_IOWR('u', 0x26, struct ublk_batch_io)

/*
 * Fetch io commands to provided buffer in multishot style,
 * `IORING_URING_CMD_MULTISHOT` is required for this command.
 */
#define	UBLK_U_IO_FETCH_IO_CMDS 	\
	_IOWR('u', 0x27, struct ublk_batch_io)

/* only ABORT means that no re-fetch */
#define UBLK_IO_RES_OK			0
#define UBLK_IO_RES_NEED_GET_DATA	1
#define UBLK_IO_RES_ABORT		(-ENODEV)

#define UBLKSRV_CMD_BUF_OFFSET	0
#define UBLKSRV_IO_BUF_OFFSET	0x80000000

/* tag bit is 16bit, so far limit at most 4096 IOs for each queue */
#define UBLK_MAX_QUEUE_DEPTH	4096

Annotation

Implementation Notes