include/uapi/linux/ublk_cmd.h

   1 /* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
   2 #ifndef USER_BLK_DRV_CMD_INC_H
   3 #define USER_BLK_DRV_CMD_INC_H
   4
   5 #include <linux/types.h>
   6
   7 /* ublk server command definition */
   8
   9 /*
  10  * Admin commands, issued by ublk server, and handled by ublk driver.
  11  */
  12 #define UBLK_CMD_GET_QUEUE_AFFINITY     0x01
  13 #define UBLK_CMD_GET_DEV_INFO   0x02
  14 #define UBLK_CMD_ADD_DEV                0x04
  15 #define UBLK_CMD_DEL_DEV                0x05
  16 #define UBLK_CMD_START_DEV      0x06
  17 #define UBLK_CMD_STOP_DEV       0x07
  18 #define UBLK_CMD_SET_PARAMS     0x08
  19 #define UBLK_CMD_GET_PARAMS     0x09
  20 #define UBLK_CMD_START_USER_RECOVERY    0x10
  21 #define UBLK_CMD_END_USER_RECOVERY      0x11
  22 /*
  23  * IO commands, issued by ublk server, and handled by ublk driver.
  24  *
  25  * FETCH_REQ: issued via sqe(URING_CMD) beforehand for fetching IO request
  26  *      from ublk driver, should be issued only when starting device. After
  27  *      the associated cqe is returned, request's tag can be retrieved via
  28  *      cqe->userdata.
  29  *
  30  * COMMIT_AND_FETCH_REQ: issued via sqe(URING_CMD) after ublkserver handled
  31  *      this IO request, request's handling result is committed to ublk
  32  *      driver, meantime FETCH_REQ is piggyback, and FETCH_REQ has to be
  33  *      handled before completing io request.
  34  *
  35  * NEED_GET_DATA: only used for write requests to set io addr and copy data
  36  *      When NEED_GET_DATA is set, ublksrv has to issue UBLK_IO_NEED_GET_DATA
  37  *      command after ublk driver returns UBLK_IO_RES_NEED_GET_DATA.
  38  *
  39  *      It is only used if ublksrv set UBLK_F_NEED_GET_DATA flag
  40  *      while starting a ublk device.
  41  */
  42 #define UBLK_IO_FETCH_REQ               0x20
  43 #define UBLK_IO_COMMIT_AND_FETCH_REQ    0x21
  44 #define UBLK_IO_NEED_GET_DATA   0x22
  45
  46 /* only ABORT means that no re-fetch */
  47 #define UBLK_IO_RES_OK                  0
  48 #define UBLK_IO_RES_NEED_GET_DATA       1
  49 #define UBLK_IO_RES_ABORT               (-ENODEV)
  50
  51 #define UBLKSRV_CMD_BUF_OFFSET  0
  52 #define UBLKSRV_IO_BUF_OFFSET   0x80000000
  53
  54 /* tag bit is 12bit, so at most 4096 IOs for each queue */
  55 #define UBLK_MAX_QUEUE_DEPTH    4096
  56
  57 /*
  58  * zero copy requires 4k block size, and can remap ublk driver's io
  59  * request into ublksrv's vm space
  60  */
  61 #define UBLK_F_SUPPORT_ZERO_COPY        (1ULL << 0)
  62
  63 /*
  64  * Force to complete io cmd via io_uring_cmd_complete_in_task so that
  65  * performance comparison is done easily with using task_work_add
  66  */
  67 #define UBLK_F_URING_CMD_COMP_IN_TASK   (1ULL << 1)
  68
  69 /*
  70  * User should issue io cmd again for write requests to
  71  * set io buffer address and copy data from bio vectors
  72  * to the userspace io buffer.
  73  *
  74  * In this mode, task_work is not used.
  75  */
  76 #define UBLK_F_NEED_GET_DATA (1UL << 2)
  77
  78 #define UBLK_F_USER_RECOVERY    (1UL << 3)
  79
  80 #define UBLK_F_USER_RECOVERY_REISSUE    (1UL << 4)
  81
  82 /* device state */
  83 #define UBLK_S_DEV_DEAD 0
  84 #define UBLK_S_DEV_LIVE 1
  85 #define UBLK_S_DEV_QUIESCED     2
  86
  87 /* shipped via sqe->cmd of io_uring command */
  88 struct ublksrv_ctrl_cmd {
  89         /* sent to which device, must be valid */
  90         __u32   dev_id;
  91
  92         /* sent to which queue, must be -1 if the cmd isn't for queue */
  93         __u16   queue_id;
  94         /*
  95          * cmd specific buffer, can be IN or OUT.
  96          */
  97         __u16   len;
  98         __u64   addr;
  99
 100         /* inline data */
 101         __u64   data[2];
 102 };
 103
 104 struct ublksrv_ctrl_dev_info {
 105         __u16   nr_hw_queues;
 106         __u16   queue_depth;
 107         __u16   state;
 108         __u16   pad0;
 109
 110         __u32   max_io_buf_bytes;
 111         __u32   dev_id;
 112
 113         __s32   ublksrv_pid;
 114         __u32   pad1;
 115
 116         __u64   flags;
 117
 118         /* For ublksrv internal use, invisible to ublk driver */
 119         __u64   ublksrv_flags;
 120
 121         __u64   reserved0;
 122         __u64   reserved1;
 123         __u64   reserved2;
 124 };
 125
 126 #define         UBLK_IO_OP_READ         0
 127 #define         UBLK_IO_OP_WRITE                1
 128 #define         UBLK_IO_OP_FLUSH                2
 129 #define         UBLK_IO_OP_DISCARD      3
 130 #define         UBLK_IO_OP_WRITE_SAME   4
 131 #define         UBLK_IO_OP_WRITE_ZEROES 5
 132
 133 #define         UBLK_IO_F_FAILFAST_DEV          (1U << 8)
 134 #define         UBLK_IO_F_FAILFAST_TRANSPORT    (1U << 9)
 135 #define         UBLK_IO_F_FAILFAST_DRIVER       (1U << 10)
 136 #define         UBLK_IO_F_META                  (1U << 11)
 137 #define         UBLK_IO_F_FUA                   (1U << 13)
 138 #define         UBLK_IO_F_NOUNMAP               (1U << 15)
 139 #define         UBLK_IO_F_SWAP                  (1U << 16)
 140
 141 /*
 142  * io cmd is described by this structure, and stored in share memory, indexed
 143  * by request tag.
 144  *
 145  * The data is stored by ublk driver, and read by ublksrv after one fetch command
 146  * returns.
 147  */
 148 struct ublksrv_io_desc {
 149         /* op: bit 0-7, flags: bit 8-31 */
 150         __u32           op_flags;
 151
 152         __u32           nr_sectors;
 153
 154         /* start sector for this io */
 155         __u64           start_sector;
 156
 157         /* buffer address in ublksrv daemon vm space, from ublk driver */
 158         __u64           addr;
 159 };
 160
 161 static inline __u8 ublksrv_get_op(const struct ublksrv_io_desc *iod)
 162 {
 163         return iod->op_flags & 0xff;
 164 }
 165
 166 static inline __u32 ublksrv_get_flags(const struct ublksrv_io_desc *iod)
 167 {
 168         return iod->op_flags >> 8;
 169 }
 170
 171 /* issued to ublk driver via /dev/ublkcN */
 172 struct ublksrv_io_cmd {
 173         __u16   q_id;
 174
 175         /* for fetch/commit which result */
 176         __u16   tag;
 177
 178         /* io result, it is valid for COMMIT* command only */
 179         __s32   result;
 180
 181         /*
 182          * userspace buffer address in ublksrv daemon process, valid for
 183          * FETCH* command only
 184          */
 185         __u64   addr;
 186 };
 187
 188 struct ublk_param_basic {
 189 #define UBLK_ATTR_READ_ONLY            (1 << 0)
 190 #define UBLK_ATTR_ROTATIONAL           (1 << 1)
 191 #define UBLK_ATTR_VOLATILE_CACHE       (1 << 2)
 192 #define UBLK_ATTR_FUA                  (1 << 3)
 193         __u32   attrs;
 194         __u8    logical_bs_shift;
 195         __u8    physical_bs_shift;
 196         __u8    io_opt_shift;
 197         __u8    io_min_shift;
 198
 199         __u32   max_sectors;
 200         __u32   chunk_sectors;
 201
 202         __u64   dev_sectors;
 203         __u64   virt_boundary_mask;
 204 };
 205
 206 struct ublk_param_discard {
 207         __u32   discard_alignment;
 208
 209         __u32   discard_granularity;
 210         __u32   max_discard_sectors;
 211
 212         __u32   max_write_zeroes_sectors;
 213         __u16   max_discard_segments;
 214         __u16   reserved0;
 215 };
 216
 217 struct ublk_params {
 218         /*
 219          * Total length of parameters, userspace has to set 'len' for both
 220          * SET_PARAMS and GET_PARAMS command, and driver may update len
 221          * if two sides use different version of 'ublk_params', same with
 222          * 'types' fields.
 223          */
 224         __u32   len;
 225 #define UBLK_PARAM_TYPE_BASIC           (1 << 0)
 226 #define UBLK_PARAM_TYPE_DISCARD         (1 << 1)
 227         __u32   types;                  /* types of parameter included */
 228
 229         struct ublk_param_basic         basic;
 230         struct ublk_param_discard       discard;
 231 };
 232
 233 #endif