uapi/linux/ublk_cmd.h

0001 /* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
0002 #ifndef USER_BLK_DRV_CMD_INC_H
0003 #define USER_BLK_DRV_CMD_INC_H
0004
0005 #include <linux/types.h>
0006
0007 /* ublk server command definition */
0008
0009 /*
0010  * Admin commands, issued by ublk server, and handled by ublk driver.
0011  */
0012 #define UBLK_CMD_GET_QUEUE_AFFINITY 0x01
0013 #define UBLK_CMD_GET_DEV_INFO   0x02
0014 #define UBLK_CMD_ADD_DEV        0x04
0015 #define UBLK_CMD_DEL_DEV        0x05
0016 #define UBLK_CMD_START_DEV  0x06
0017 #define UBLK_CMD_STOP_DEV   0x07
0018 #define UBLK_CMD_SET_PARAMS 0x08
0019 #define UBLK_CMD_GET_PARAMS 0x09
0020
0021 /*
0022  * IO commands, issued by ublk server, and handled by ublk driver.
0023  *
0024  * FETCH_REQ: issued via sqe(URING_CMD) beforehand for fetching IO request
0025  *      from ublk driver, should be issued only when starting device. After
0026  *      the associated cqe is returned, request's tag can be retrieved via
0027  *      cqe->userdata.
0028  *
0029  * COMMIT_AND_FETCH_REQ: issued via sqe(URING_CMD) after ublkserver handled
0030  *      this IO request, request's handling result is committed to ublk
0031  *      driver, meantime FETCH_REQ is piggyback, and FETCH_REQ has to be
0032  *      handled before completing io request.
0033  *
0034  * NEED_GET_DATA: only used for write requests to set io addr and copy data
0035  *      When NEED_GET_DATA is set, ublksrv has to issue UBLK_IO_NEED_GET_DATA
0036  *      command after ublk driver returns UBLK_IO_RES_NEED_GET_DATA.
0037  *
0038  *      It is only used if ublksrv set UBLK_F_NEED_GET_DATA flag
0039  *      while starting a ublk device.
0040  */
0041 #define UBLK_IO_FETCH_REQ       0x20
0042 #define UBLK_IO_COMMIT_AND_FETCH_REQ    0x21
0043 #define UBLK_IO_NEED_GET_DATA   0x22
0044
0045 /* only ABORT means that no re-fetch */
0046 #define UBLK_IO_RES_OK          0
0047 #define UBLK_IO_RES_NEED_GET_DATA   1
0048 #define UBLK_IO_RES_ABORT       (-ENODEV)
0049
0050 #define UBLKSRV_CMD_BUF_OFFSET  0
0051 #define UBLKSRV_IO_BUF_OFFSET   0x80000000
0052
0053 /* tag bit is 12bit, so at most 4096 IOs for each queue */
0054 #define UBLK_MAX_QUEUE_DEPTH    4096
0055
0056 /*
0057  * zero copy requires 4k block size, and can remap ublk driver's io
0058  * request into ublksrv's vm space
0059  */
0060 #define UBLK_F_SUPPORT_ZERO_COPY    (1ULL << 0)
0061
0062 /*
0063  * Force to complete io cmd via io_uring_cmd_complete_in_task so that
0064  * performance comparison is done easily with using task_work_add
0065  */
0066 #define UBLK_F_URING_CMD_COMP_IN_TASK   (1ULL << 1)
0067
0068 /*
0069  * User should issue io cmd again for write requests to
0070  * set io buffer address and copy data from bio vectors
0071  * to the userspace io buffer.
0072  *
0073  * In this mode, task_work is not used.
0074  */
0075 #define UBLK_F_NEED_GET_DATA (1UL << 2)
0076
0077 /* device state */
0078 #define UBLK_S_DEV_DEAD 0
0079 #define UBLK_S_DEV_LIVE 1
0080
0081 /* shipped via sqe->cmd of io_uring command */
0082 struct ublksrv_ctrl_cmd {
0083     /* sent to which device, must be valid */
0084     __u32   dev_id;
0085
0086     /* sent to which queue, must be -1 if the cmd isn't for queue */
0087     __u16   queue_id;
0088     /*
0089      * cmd specific buffer, can be IN or OUT.
0090      */
0091     __u16   len;
0092     __u64   addr;
0093
0094     /* inline data */
0095     __u64   data[2];
0096 };
0097
0098 struct ublksrv_ctrl_dev_info {
0099     __u16   nr_hw_queues;
0100     __u16   queue_depth;
0101     __u16   state;
0102     __u16   pad0;
0103
0104     __u32   max_io_buf_bytes;
0105     __u32   dev_id;
0106
0107     __s32   ublksrv_pid;
0108     __u32   pad1;
0109
0110     __u64   flags;
0111
0112     /* For ublksrv internal use, invisible to ublk driver */
0113     __u64   ublksrv_flags;
0114
0115     __u64   reserved0;
0116     __u64   reserved1;
0117     __u64   reserved2;
0118 };
0119
0120 #define     UBLK_IO_OP_READ     0
0121 #define     UBLK_IO_OP_WRITE        1
0122 #define     UBLK_IO_OP_FLUSH        2
0123 #define     UBLK_IO_OP_DISCARD  3
0124 #define     UBLK_IO_OP_WRITE_SAME   4
0125 #define     UBLK_IO_OP_WRITE_ZEROES 5
0126
0127 #define     UBLK_IO_F_FAILFAST_DEV      (1U << 8)
0128 #define     UBLK_IO_F_FAILFAST_TRANSPORT    (1U << 9)
0129 #define     UBLK_IO_F_FAILFAST_DRIVER   (1U << 10)
0130 #define     UBLK_IO_F_META          (1U << 11)
0131 #define     UBLK_IO_F_FUA           (1U << 13)
0132 #define     UBLK_IO_F_NOUNMAP       (1U << 15)
0133 #define     UBLK_IO_F_SWAP          (1U << 16)
0134
0135 /*
0136  * io cmd is described by this structure, and stored in share memory, indexed
0137  * by request tag.
0138  *
0139  * The data is stored by ublk driver, and read by ublksrv after one fetch command
0140  * returns.
0141  */
0142 struct ublksrv_io_desc {
0143     /* op: bit 0-7, flags: bit 8-31 */
0144     __u32       op_flags;
0145
0146     __u32       nr_sectors;
0147
0148     /* start sector for this io */
0149     __u64       start_sector;
0150
0151     /* buffer address in ublksrv daemon vm space, from ublk driver */
0152     __u64       addr;
0153 };
0154
0155 static inline __u8 ublksrv_get_op(const struct ublksrv_io_desc *iod)
0156 {
0157     return iod->op_flags & 0xff;
0158 }
0159
0160 static inline __u32 ublksrv_get_flags(const struct ublksrv_io_desc *iod)
0161 {
0162     return iod->op_flags >> 8;
0163 }
0164
0165 /* issued to ublk driver via /dev/ublkcN */
0166 struct ublksrv_io_cmd {
0167     __u16   q_id;
0168
0169     /* for fetch/commit which result */
0170     __u16   tag;
0171
0172     /* io result, it is valid for COMMIT* command only */
0173     __s32   result;
0174
0175     /*
0176      * userspace buffer address in ublksrv daemon process, valid for
0177      * FETCH* command only
0178      */
0179     __u64   addr;
0180 };
0181
0182 struct ublk_param_basic {
0183 #define UBLK_ATTR_READ_ONLY            (1 << 0)
0184 #define UBLK_ATTR_ROTATIONAL           (1 << 1)
0185 #define UBLK_ATTR_VOLATILE_CACHE       (1 << 2)
0186 #define UBLK_ATTR_FUA                  (1 << 3)
0187     __u32   attrs;
0188     __u8    logical_bs_shift;
0189     __u8    physical_bs_shift;
0190     __u8    io_opt_shift;
0191     __u8    io_min_shift;
0192
0193     __u32   max_sectors;
0194     __u32   chunk_sectors;
0195
0196     __u64   dev_sectors;
0197     __u64   virt_boundary_mask;
0198 };
0199
0200 struct ublk_param_discard {
0201     __u32   discard_alignment;
0202
0203     __u32   discard_granularity;
0204     __u32   max_discard_sectors;
0205
0206     __u32   max_write_zeroes_sectors;
0207     __u16   max_discard_segments;
0208     __u16   reserved0;
0209 };
0210
0211 struct ublk_params {
0212     /*
0213      * Total length of parameters, userspace has to set 'len' for both
0214      * SET_PARAMS and GET_PARAMS command, and driver may update len
0215      * if two sides use different version of 'ublk_params', same with
0216      * 'types' fields.
0217      */
0218     __u32   len;
0219 #define UBLK_PARAM_TYPE_BASIC           (1 << 0)
0220 #define UBLK_PARAM_TYPE_DISCARD         (1 << 1)
0221     __u32   types;          /* types of parameter included */
0222
0223     struct ublk_param_basic     basic;
0224     struct ublk_param_discard   discard;
0225 };
0226
0227 #endif