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 #define UBLK_U_CMD_GET_FEATURES \
  51         _IOR('u', 0x13, struct ublksrv_ctrl_cmd)
  52 #define UBLK_U_CMD_DEL_DEV_ASYNC        \
  53         _IOR('u', 0x14, struct ublksrv_ctrl_cmd)
  54
  55 /*
  56  * 64bits are enough now, and it should be easy to extend in case of
  57  * running out of feature flags
  58  */
  59 #define UBLK_FEATURES_LEN  8
  60
  61 /*
  62  * IO commands, issued by ublk server, and handled by ublk driver.
  63  *
  64  * FETCH_REQ: issued via sqe(URING_CMD) beforehand for fetching IO request
  65  *      from ublk driver, should be issued only when starting device. After
  66  *      the associated cqe is returned, request's tag can be retrieved via
  67  *      cqe->userdata.
  68  *
  69  * COMMIT_AND_FETCH_REQ: issued via sqe(URING_CMD) after ublkserver handled
  70  *      this IO request, request's handling result is committed to ublk
  71  *      driver, meantime FETCH_REQ is piggyback, and FETCH_REQ has to be
  72  *      handled before completing io request.
  73  *
  74  * NEED_GET_DATA: only used for write requests to set io addr and copy data
  75  *      When NEED_GET_DATA is set, ublksrv has to issue UBLK_IO_NEED_GET_DATA
  76  *      command after ublk driver returns UBLK_IO_RES_NEED_GET_DATA.
  77  *
  78  *      It is only used if ublksrv set UBLK_F_NEED_GET_DATA flag
  79  *      while starting a ublk device.
  80  */
  81
  82 /*
  83  * Legacy IO command definition, don't use in new application, and don't
  84  * add new such definition any more
  85  */
  86 #define UBLK_IO_FETCH_REQ               0x20
  87 #define UBLK_IO_COMMIT_AND_FETCH_REQ    0x21
  88 #define UBLK_IO_NEED_GET_DATA   0x22
  89
  90 /* Any new IO command should encode by __IOWR() */
  91 #define UBLK_U_IO_FETCH_REQ             \
  92         _IOWR('u', UBLK_IO_FETCH_REQ, struct ublksrv_io_cmd)
  93 #define UBLK_U_IO_COMMIT_AND_FETCH_REQ  \
  94         _IOWR('u', UBLK_IO_COMMIT_AND_FETCH_REQ, struct ublksrv_io_cmd)
  95 #define UBLK_U_IO_NEED_GET_DATA         \
  96         _IOWR('u', UBLK_IO_NEED_GET_DATA, struct ublksrv_io_cmd)
  97
  98 /* only ABORT means that no re-fetch */
  99 #define UBLK_IO_RES_OK                  0
 100 #define UBLK_IO_RES_NEED_GET_DATA       1
 101 #define UBLK_IO_RES_ABORT               (-ENODEV)
 102
 103 #define UBLKSRV_CMD_BUF_OFFSET  0
 104 #define UBLKSRV_IO_BUF_OFFSET   0x80000000
 105
 106 /* tag bit is 16bit, so far limit at most 4096 IOs for each queue */
 107 #define UBLK_MAX_QUEUE_DEPTH    4096
 108
 109 /* single IO buffer max size is 32MB */
 110 #define UBLK_IO_BUF_OFF         0
 111 #define UBLK_IO_BUF_BITS        25
 112 #define UBLK_IO_BUF_BITS_MASK   ((1ULL << UBLK_IO_BUF_BITS) - 1)
 113
 114 /* so at most 64K IOs for each queue */
 115 #define UBLK_TAG_OFF            UBLK_IO_BUF_BITS
 116 #define UBLK_TAG_BITS           16
 117 #define UBLK_TAG_BITS_MASK      ((1ULL << UBLK_TAG_BITS) - 1)
 118
 119 /* max 4096 queues */
 120 #define UBLK_QID_OFF            (UBLK_TAG_OFF + UBLK_TAG_BITS)
 121 #define UBLK_QID_BITS           12
 122 #define UBLK_QID_BITS_MASK      ((1ULL << UBLK_QID_BITS) - 1)
 123
 124 #define UBLK_MAX_NR_QUEUES      (1U << UBLK_QID_BITS)
 125
 126 #define UBLKSRV_IO_BUF_TOTAL_BITS       (UBLK_QID_OFF + UBLK_QID_BITS)
 127 #define UBLKSRV_IO_BUF_TOTAL_SIZE       (1ULL << UBLKSRV_IO_BUF_TOTAL_BITS)
 128
 129 /*
 130  * zero copy requires 4k block size, and can remap ublk driver's io
 131  * request into ublksrv's vm space
 132  */
 133 #define UBLK_F_SUPPORT_ZERO_COPY        (1ULL << 0)
 134
 135 /*
 136  * Force to complete io cmd via io_uring_cmd_complete_in_task so that
 137  * performance comparison is done easily with using task_work_add
 138  */
 139 #define UBLK_F_URING_CMD_COMP_IN_TASK   (1ULL << 1)
 140
 141 /*
 142  * User should issue io cmd again for write requests to
 143  * set io buffer address and copy data from bio vectors
 144  * to the userspace io buffer.
 145  *
 146  * In this mode, task_work is not used.
 147  */
 148 #define UBLK_F_NEED_GET_DATA (1UL << 2)
 149
 150 #define UBLK_F_USER_RECOVERY    (1UL << 3)
 151
 152 #define UBLK_F_USER_RECOVERY_REISSUE    (1UL << 4)
 153
 154 /*
 155  * Unprivileged user can create /dev/ublkcN and /dev/ublkbN.
 156  *
 157  * /dev/ublk-control needs to be available for unprivileged user, and it
 158  * can be done via udev rule to make all control commands available to
 159  * unprivileged user. Except for the command of UBLK_CMD_ADD_DEV, all
 160  * other commands are only allowed for the owner of the specified device.
 161  *
 162  * When userspace sends UBLK_CMD_ADD_DEV, the device pair's owner_uid and
 163  * owner_gid are stored to ublksrv_ctrl_dev_info by kernel, so far only
 164  * the current user's uid/gid is stored, that said owner of the created
 165  * device is always the current user.
 166  *
 167  * We still need udev rule to apply OWNER/GROUP with the stored owner_uid
 168  * and owner_gid.
 169  *
 170  * Then ublk server can be run as unprivileged user, and /dev/ublkbN can
 171  * be accessed and managed by its owner represented by owner_uid/owner_gid.
 172  */
 173 #define UBLK_F_UNPRIVILEGED_DEV (1UL << 5)
 174
 175 /* use ioctl encoding for uring command */
 176 #define UBLK_F_CMD_IOCTL_ENCODE (1UL << 6)
 177
 178 /* Copy between request and user buffer by pread()/pwrite() */
 179 #define UBLK_F_USER_COPY        (1UL << 7)
 180
 181 /*
 182  * User space sets this flag when setting up the device to request zoned storage support. Kernel may
 183  * deny the request by returning an error.
 184  */
 185 #define UBLK_F_ZONED (1ULL << 8)
 186
 187 /* device state */
 188 #define UBLK_S_DEV_DEAD 0
 189 #define UBLK_S_DEV_LIVE 1
 190 #define UBLK_S_DEV_QUIESCED     2
 191
 192 /* shipped via sqe->cmd of io_uring command */
 193 struct ublksrv_ctrl_cmd {
 194         /* sent to which device, must be valid */
 195         __u32   dev_id;
 196
 197         /* sent to which queue, must be -1 if the cmd isn't for queue */
 198         __u16   queue_id;
 199         /*
 200          * cmd specific buffer, can be IN or OUT.
 201          */
 202         __u16   len;
 203         __u64   addr;
 204
 205         /* inline data */
 206         __u64   data[1];
 207
 208         /*
 209          * Used for UBLK_F_UNPRIVILEGED_DEV and UBLK_CMD_GET_DEV_INFO2
 210          * only, include null char
 211          */
 212         __u16   dev_path_len;
 213         __u16   pad;
 214         __u32   reserved;
 215 };
 216
 217 struct ublksrv_ctrl_dev_info {
 218         __u16   nr_hw_queues;
 219         __u16   queue_depth;
 220         __u16   state;
 221         __u16   pad0;
 222
 223         __u32   max_io_buf_bytes;
 224         __u32   dev_id;
 225
 226         __s32   ublksrv_pid;
 227         __u32   pad1;
 228
 229         __u64   flags;
 230
 231         /* For ublksrv internal use, invisible to ublk driver */
 232         __u64   ublksrv_flags;
 233
 234         __u32   owner_uid;      /* store by kernel */
 235         __u32   owner_gid;      /* store by kernel */
 236         __u64   reserved1;
 237         __u64   reserved2;
 238 };
 239
 240 #define         UBLK_IO_OP_READ         0
 241 #define         UBLK_IO_OP_WRITE                1
 242 #define         UBLK_IO_OP_FLUSH                2
 243 #define         UBLK_IO_OP_DISCARD              3
 244 #define         UBLK_IO_OP_WRITE_SAME           4
 245 #define         UBLK_IO_OP_WRITE_ZEROES         5
 246 #define         UBLK_IO_OP_ZONE_OPEN            10
 247 #define         UBLK_IO_OP_ZONE_CLOSE           11
 248 #define         UBLK_IO_OP_ZONE_FINISH          12
 249 #define         UBLK_IO_OP_ZONE_APPEND          13
 250 #define         UBLK_IO_OP_ZONE_RESET_ALL       14
 251 #define         UBLK_IO_OP_ZONE_RESET           15
 252 /*
 253  * Construct a zone report. The report request is carried in `struct
 254  * ublksrv_io_desc`. The `start_sector` field must be the first sector of a zone
 255  * and shall indicate the first zone of the report. The `nr_zones` shall
 256  * indicate how many zones should be reported at most. The report shall be
 257  * delivered as a `struct blk_zone` array. To report fewer zones than requested,
 258  * zero the last entry of the returned array.
 259  *
 260  * Related definitions(blk_zone, blk_zone_cond, blk_zone_type, ...) in
 261  * include/uapi/linux/blkzoned.h are part of ublk UAPI.
 262  */
 263 #define         UBLK_IO_OP_REPORT_ZONES         18
 264
 265 #define         UBLK_IO_F_FAILFAST_DEV          (1U << 8)
 266 #define         UBLK_IO_F_FAILFAST_TRANSPORT    (1U << 9)
 267 #define         UBLK_IO_F_FAILFAST_DRIVER       (1U << 10)
 268 #define         UBLK_IO_F_META                  (1U << 11)
 269 #define         UBLK_IO_F_FUA                   (1U << 13)
 270 #define         UBLK_IO_F_NOUNMAP               (1U << 15)
 271 #define         UBLK_IO_F_SWAP                  (1U << 16)
 272
 273 /*
 274  * io cmd is described by this structure, and stored in share memory, indexed
 275  * by request tag.
 276  *
 277  * The data is stored by ublk driver, and read by ublksrv after one fetch command
 278  * returns.
 279  */
 280 struct ublksrv_io_desc {
 281         /* op: bit 0-7, flags: bit 8-31 */
 282         __u32           op_flags;
 283
 284         union {
 285                 __u32           nr_sectors;
 286                 __u32           nr_zones; /* for UBLK_IO_OP_REPORT_ZONES */
 287         };
 288
 289         /* start sector for this io */
 290         __u64           start_sector;
 291
 292         /* buffer address in ublksrv daemon vm space, from ublk driver */
 293         __u64           addr;
 294 };
 295
 296 static inline __u8 ublksrv_get_op(const struct ublksrv_io_desc *iod)
 297 {
 298         return iod->op_flags & 0xff;
 299 }
 300
 301 static inline __u32 ublksrv_get_flags(const struct ublksrv_io_desc *iod)
 302 {
 303         return iod->op_flags >> 8;
 304 }
 305
 306 /* issued to ublk driver via /dev/ublkcN */
 307 struct ublksrv_io_cmd {
 308         __u16   q_id;
 309
 310         /* for fetch/commit which result */
 311         __u16   tag;
 312
 313         /* io result, it is valid for COMMIT* command only */
 314         __s32   result;
 315
 316         union {
 317                 /*
 318                  * userspace buffer address in ublksrv daemon process, valid for
 319                  * FETCH* command only
 320                  *
 321                  * `addr` should not be used when UBLK_F_USER_COPY is enabled,
 322                  * because userspace handles data copy by pread()/pwrite() over
 323                  * /dev/ublkcN. But in case of UBLK_F_ZONED, this union is
 324                  * re-used to pass back the allocated LBA for
 325                  * UBLK_IO_OP_ZONE_APPEND which actually depends on
 326                  * UBLK_F_USER_COPY
 327                  */
 328                 __u64   addr;
 329                 __u64   zone_append_lba;
 330         };
 331 };
 332
 333 struct ublk_param_basic {
 334 #define UBLK_ATTR_READ_ONLY            (1 << 0)
 335 #define UBLK_ATTR_ROTATIONAL           (1 << 1)
 336 #define UBLK_ATTR_VOLATILE_CACHE       (1 << 2)
 337 #define UBLK_ATTR_FUA                  (1 << 3)
 338         __u32   attrs;
 339         __u8    logical_bs_shift;
 340         __u8    physical_bs_shift;
 341         __u8    io_opt_shift;
 342         __u8    io_min_shift;
 343
 344         __u32   max_sectors;
 345         __u32   chunk_sectors;
 346
 347         __u64   dev_sectors;
 348         __u64   virt_boundary_mask;
 349 };
 350
 351 struct ublk_param_discard {
 352         __u32   discard_alignment;
 353
 354         __u32   discard_granularity;
 355         __u32   max_discard_sectors;
 356
 357         __u32   max_write_zeroes_sectors;
 358         __u16   max_discard_segments;
 359         __u16   reserved0;
 360 };
 361
 362 /*
 363  * read-only, can't set via UBLK_CMD_SET_PARAMS, disk_devt is available
 364  * after device is started
 365  */
 366 struct ublk_param_devt {
 367         __u32   char_major;
 368         __u32   char_minor;
 369         __u32   disk_major;
 370         __u32   disk_minor;
 371 };
 372
 373 struct ublk_param_zoned {
 374         __u32   max_open_zones;
 375         __u32   max_active_zones;
 376         __u32   max_zone_append_sectors;
 377         __u8    reserved[20];
 378 };
 379
 380 struct ublk_params {
 381         /*
 382          * Total length of parameters, userspace has to set 'len' for both
 383          * SET_PARAMS and GET_PARAMS command, and driver may update len
 384          * if two sides use different version of 'ublk_params', same with
 385          * 'types' fields.
 386          */
 387         __u32   len;
 388 #define UBLK_PARAM_TYPE_BASIC           (1 << 0)
 389 #define UBLK_PARAM_TYPE_DISCARD         (1 << 1)
 390 #define UBLK_PARAM_TYPE_DEVT            (1 << 2)
 391 #define UBLK_PARAM_TYPE_ZONED           (1 << 3)
 392         __u32   types;                  /* types of parameter included */
 393
 394         struct ublk_param_basic         basic;
 395         struct ublk_param_discard       discard;
 396         struct ublk_param_devt          devt;
 397         struct ublk_param_zoned zoned;
 398 };
 399
 400 #endif