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 #define UBLK_CMD_GET_DEV_INFO2          0x12
  23
  24 /*
  25  * IO commands, issued by ublk server, and handled by ublk driver.
  26  *
  27  * FETCH_REQ: issued via sqe(URING_CMD) beforehand for fetching IO request
  28  *      from ublk driver, should be issued only when starting device. After
  29  *      the associated cqe is returned, request's tag can be retrieved via
  30  *      cqe->userdata.
  31  *
  32  * COMMIT_AND_FETCH_REQ: issued via sqe(URING_CMD) after ublkserver handled
  33  *      this IO request, request's handling result is committed to ublk
  34  *      driver, meantime FETCH_REQ is piggyback, and FETCH_REQ has to be
  35  *      handled before completing io request.
  36  *
  37  * NEED_GET_DATA: only used for write requests to set io addr and copy data
  38  *      When NEED_GET_DATA is set, ublksrv has to issue UBLK_IO_NEED_GET_DATA
  39  *      command after ublk driver returns UBLK_IO_RES_NEED_GET_DATA.
  40  *
  41  *      It is only used if ublksrv set UBLK_F_NEED_GET_DATA flag
  42  *      while starting a ublk device.
  43  */
  44 #define UBLK_IO_FETCH_REQ               0x20
  45 #define UBLK_IO_COMMIT_AND_FETCH_REQ    0x21
  46 #define UBLK_IO_NEED_GET_DATA   0x22
  47
  48 /* only ABORT means that no re-fetch */
  49 #define UBLK_IO_RES_OK                  0
  50 #define UBLK_IO_RES_NEED_GET_DATA       1
  51 #define UBLK_IO_RES_ABORT               (-ENODEV)
  52
  53 #define UBLKSRV_CMD_BUF_OFFSET  0
  54 #define UBLKSRV_IO_BUF_OFFSET   0x80000000
  55
  56 /* tag bit is 12bit, so at most 4096 IOs for each queue */
  57 #define UBLK_MAX_QUEUE_DEPTH    4096
  58
  59 /*
  60  * zero copy requires 4k block size, and can remap ublk driver's io
  61  * request into ublksrv's vm space
  62  */
  63 #define UBLK_F_SUPPORT_ZERO_COPY        (1ULL << 0)
  64
  65 /*
  66  * Force to complete io cmd via io_uring_cmd_complete_in_task so that
  67  * performance comparison is done easily with using task_work_add
  68  */
  69 #define UBLK_F_URING_CMD_COMP_IN_TASK   (1ULL << 1)
  70
  71 /*
  72  * User should issue io cmd again for write requests to
  73  * set io buffer address and copy data from bio vectors
  74  * to the userspace io buffer.
  75  *
  76  * In this mode, task_work is not used.
  77  */
  78 #define UBLK_F_NEED_GET_DATA (1UL << 2)
  79
  80 #define UBLK_F_USER_RECOVERY    (1UL << 3)
  81
  82 #define UBLK_F_USER_RECOVERY_REISSUE    (1UL << 4)
  83
  84 /*
  85  * Unprivileged user can create /dev/ublkcN and /dev/ublkbN.
  86  *
  87  * /dev/ublk-control needs to be available for unprivileged user, and it
  88  * can be done via udev rule to make all control commands available to
  89  * unprivileged user. Except for the command of UBLK_CMD_ADD_DEV, all
  90  * other commands are only allowed for the owner of the specified device.
  91  *
  92  * When userspace sends UBLK_CMD_ADD_DEV, the device pair's owner_uid and
  93  * owner_gid are stored to ublksrv_ctrl_dev_info by kernel, so far only
  94  * the current user's uid/gid is stored, that said owner of the created
  95  * device is always the current user.
  96  *
  97  * We still need udev rule to apply OWNER/GROUP with the stored owner_uid
  98  * and owner_gid.
  99  *
 100  * Then ublk server can be run as unprivileged user, and /dev/ublkbN can
 101  * be accessed and managed by its owner represented by owner_uid/owner_gid.
 102  */
 103 #define UBLK_F_UNPRIVILEGED_DEV (1UL << 5)
 104
 105 /* device state */
 106 #define UBLK_S_DEV_DEAD 0
 107 #define UBLK_S_DEV_LIVE 1
 108 #define UBLK_S_DEV_QUIESCED     2
 109
 110 /* shipped via sqe->cmd of io_uring command */
 111 struct ublksrv_ctrl_cmd {
 112         /* sent to which device, must be valid */
 113         __u32   dev_id;
 114
 115         /* sent to which queue, must be -1 if the cmd isn't for queue */
 116         __u16   queue_id;
 117         /*
 118          * cmd specific buffer, can be IN or OUT.
 119          */
 120         __u16   len;
 121         __u64   addr;
 122
 123         /* inline data */
 124         __u64   data[1];
 125
 126         /*
 127          * Used for UBLK_F_UNPRIVILEGED_DEV and UBLK_CMD_GET_DEV_INFO2
 128          * only, include null char
 129          */
 130         __u16   dev_path_len;
 131         __u16   pad;
 132         __u32   reserved;
 133 };
 134
 135 struct ublksrv_ctrl_dev_info {
 136         __u16   nr_hw_queues;
 137         __u16   queue_depth;
 138         __u16   state;
 139         __u16   pad0;
 140
 141         __u32   max_io_buf_bytes;
 142         __u32   dev_id;
 143
 144         __s32   ublksrv_pid;
 145         __u32   pad1;
 146
 147         __u64   flags;
 148
 149         /* For ublksrv internal use, invisible to ublk driver */
 150         __u64   ublksrv_flags;
 151
 152         __u32   owner_uid;      /* store by kernel */
 153         __u32   owner_gid;      /* store by kernel */
 154         __u64   reserved1;
 155         __u64   reserved2;
 156 };
 157
 158 #define         UBLK_IO_OP_READ         0
 159 #define         UBLK_IO_OP_WRITE                1
 160 #define         UBLK_IO_OP_FLUSH                2
 161 #define         UBLK_IO_OP_DISCARD      3
 162 #define         UBLK_IO_OP_WRITE_SAME   4
 163 #define         UBLK_IO_OP_WRITE_ZEROES 5
 164
 165 #define         UBLK_IO_F_FAILFAST_DEV          (1U << 8)
 166 #define         UBLK_IO_F_FAILFAST_TRANSPORT    (1U << 9)
 167 #define         UBLK_IO_F_FAILFAST_DRIVER       (1U << 10)
 168 #define         UBLK_IO_F_META                  (1U << 11)
 169 #define         UBLK_IO_F_FUA                   (1U << 13)
 170 #define         UBLK_IO_F_NOUNMAP               (1U << 15)
 171 #define         UBLK_IO_F_SWAP                  (1U << 16)
 172
 173 /*
 174  * io cmd is described by this structure, and stored in share memory, indexed
 175  * by request tag.
 176  *
 177  * The data is stored by ublk driver, and read by ublksrv after one fetch command
 178  * returns.
 179  */
 180 struct ublksrv_io_desc {
 181         /* op: bit 0-7, flags: bit 8-31 */
 182         __u32           op_flags;
 183
 184         __u32           nr_sectors;
 185
 186         /* start sector for this io */
 187         __u64           start_sector;
 188
 189         /* buffer address in ublksrv daemon vm space, from ublk driver */
 190         __u64           addr;
 191 };
 192
 193 static inline __u8 ublksrv_get_op(const struct ublksrv_io_desc *iod)
 194 {
 195         return iod->op_flags & 0xff;
 196 }
 197
 198 static inline __u32 ublksrv_get_flags(const struct ublksrv_io_desc *iod)
 199 {
 200         return iod->op_flags >> 8;
 201 }
 202
 203 /* issued to ublk driver via /dev/ublkcN */
 204 struct ublksrv_io_cmd {
 205         __u16   q_id;
 206
 207         /* for fetch/commit which result */
 208         __u16   tag;
 209
 210         /* io result, it is valid for COMMIT* command only */
 211         __s32   result;
 212
 213         /*
 214          * userspace buffer address in ublksrv daemon process, valid for
 215          * FETCH* command only
 216          */
 217         __u64   addr;
 218 };
 219
 220 struct ublk_param_basic {
 221 #define UBLK_ATTR_READ_ONLY            (1 << 0)
 222 #define UBLK_ATTR_ROTATIONAL           (1 << 1)
 223 #define UBLK_ATTR_VOLATILE_CACHE       (1 << 2)
 224 #define UBLK_ATTR_FUA                  (1 << 3)
 225         __u32   attrs;
 226         __u8    logical_bs_shift;
 227         __u8    physical_bs_shift;
 228         __u8    io_opt_shift;
 229         __u8    io_min_shift;
 230
 231         __u32   max_sectors;
 232         __u32   chunk_sectors;
 233
 234         __u64   dev_sectors;
 235         __u64   virt_boundary_mask;
 236 };
 237
 238 struct ublk_param_discard {
 239         __u32   discard_alignment;
 240
 241         __u32   discard_granularity;
 242         __u32   max_discard_sectors;
 243
 244         __u32   max_write_zeroes_sectors;
 245         __u16   max_discard_segments;
 246         __u16   reserved0;
 247 };
 248
 249 /*
 250  * read-only, can't set via UBLK_CMD_SET_PARAMS, disk_devt is available
 251  * after device is started
 252  */
 253 struct ublk_param_devt {
 254         __u32   char_major;
 255         __u32   char_minor;
 256         __u32   disk_major;
 257         __u32   disk_minor;
 258 };
 259
 260 struct ublk_params {
 261         /*
 262          * Total length of parameters, userspace has to set 'len' for both
 263          * SET_PARAMS and GET_PARAMS command, and driver may update len
 264          * if two sides use different version of 'ublk_params', same with
 265          * 'types' fields.
 266          */
 267         __u32   len;
 268 #define UBLK_PARAM_TYPE_BASIC           (1 << 0)
 269 #define UBLK_PARAM_TYPE_DISCARD         (1 << 1)
 270 #define UBLK_PARAM_TYPE_DEVT            (1 << 2)
 271         __u32   types;                  /* types of parameter included */
 272
 273         struct ublk_param_basic         basic;
 274         struct ublk_param_discard       discard;
 275         struct ublk_param_devt          devt;
 276 };
 277
 278 #endif