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