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 #define UBLK_U_CMD_UPDATE_SIZE \ 55 _IOWR('u', 0x15, struct ublksrv_ctrl_cmd) 56 #define UBLK_U_CMD_QUIESCE_DEV \ 57 _IOWR('u', 0x16, struct ublksrv_ctrl_cmd) 58 #define UBLK_U_CMD_TRY_STOP_DEV \ 59 _IOWR('u', 0x17, struct ublksrv_ctrl_cmd) 60 /* 61 * 64bits are enough now, and it should be easy to extend in case of 62 * running out of feature flags 63 */ 64 #define UBLK_FEATURES_LEN 8 65 66 /* 67 * IO commands, issued by ublk server, and handled by ublk driver. 68 * 69 * FETCH_REQ: issued via sqe(URING_CMD) beforehand for fetching IO request 70 * from ublk driver, should be issued only when starting device. After 71 * the associated cqe is returned, request's tag can be retrieved via 72 * cqe->userdata. 73 * 74 * COMMIT_AND_FETCH_REQ: issued via sqe(URING_CMD) after ublkserver handled 75 * this IO request, request's handling result is committed to ublk 76 * driver, meantime FETCH_REQ is piggyback, and FETCH_REQ has to be 77 * handled before completing io request. 78 * 79 * NEED_GET_DATA: only used for write requests to set io addr and copy data 80 * When NEED_GET_DATA is set, ublksrv has to issue UBLK_IO_NEED_GET_DATA 81 * command after ublk driver returns UBLK_IO_RES_NEED_GET_DATA. 82 * 83 * It is only used if ublksrv set UBLK_F_NEED_GET_DATA flag 84 * while starting a ublk device. 85 */ 86 87 /* 88 * Legacy IO command definition, don't use in new application, and don't 89 * add new such definition any more 90 */ 91 #define UBLK_IO_FETCH_REQ 0x20 92 #define UBLK_IO_COMMIT_AND_FETCH_REQ 0x21 93 #define UBLK_IO_NEED_GET_DATA 0x22 94 95 /* Any new IO command should encode by __IOWR() */ 96 #define UBLK_U_IO_FETCH_REQ \ 97 _IOWR('u', UBLK_IO_FETCH_REQ, struct ublksrv_io_cmd) 98 #define UBLK_U_IO_COMMIT_AND_FETCH_REQ \ 99 _IOWR('u', UBLK_IO_COMMIT_AND_FETCH_REQ, struct ublksrv_io_cmd) 100 #define UBLK_U_IO_NEED_GET_DATA \ 101 _IOWR('u', UBLK_IO_NEED_GET_DATA, struct ublksrv_io_cmd) 102 #define UBLK_U_IO_REGISTER_IO_BUF \ 103 _IOWR('u', 0x23, struct ublksrv_io_cmd) 104 #define UBLK_U_IO_UNREGISTER_IO_BUF \ 105 _IOWR('u', 0x24, struct ublksrv_io_cmd) 106 107 /* 108 * return 0 if the command is run successfully, otherwise failure code 109 * is returned 110 */ 111 #define UBLK_U_IO_PREP_IO_CMDS \ 112 _IOWR('u', 0x25, struct ublk_batch_io) 113 /* 114 * If failure code is returned, nothing in the command buffer is handled. 115 * Otherwise, the returned value means how many bytes in command buffer 116 * are handled actually, then number of handled IOs can be calculated with 117 * `elem_bytes` for each IO. IOs in the remained bytes are not committed, 118 * userspace has to check return value for dealing with partial committing 119 * correctly. 120 */ 121 #define UBLK_U_IO_COMMIT_IO_CMDS \ 122 _IOWR('u', 0x26, struct ublk_batch_io) 123 124 /* 125 * Fetch io commands to provided buffer in multishot style, 126 * `IORING_URING_CMD_MULTISHOT` is required for this command. 127 */ 128 #define UBLK_U_IO_FETCH_IO_CMDS \ 129 _IOWR('u', 0x27, struct ublk_batch_io) 130 131 /* only ABORT means that no re-fetch */ 132 #define UBLK_IO_RES_OK 0 133 #define UBLK_IO_RES_NEED_GET_DATA 1 134 #define UBLK_IO_RES_ABORT (-ENODEV) 135 136 #define UBLKSRV_CMD_BUF_OFFSET 0 137 #define UBLKSRV_IO_BUF_OFFSET 0x80000000 138 139 /* tag bit is 16bit, so far limit at most 4096 IOs for each queue */ 140 #define UBLK_MAX_QUEUE_DEPTH 4096 141 142 /* single IO buffer max size is 32MB */ 143 #define UBLK_IO_BUF_OFF 0 144 #define UBLK_IO_BUF_BITS 25 145 #define UBLK_IO_BUF_BITS_MASK ((1ULL << UBLK_IO_BUF_BITS) - 1) 146 147 /* so at most 64K IOs for each queue */ 148 #define UBLK_TAG_OFF UBLK_IO_BUF_BITS 149 #define UBLK_TAG_BITS 16 150 #define UBLK_TAG_BITS_MASK ((1ULL << UBLK_TAG_BITS) - 1) 151 152 /* max 4096 queues */ 153 #define UBLK_QID_OFF (UBLK_TAG_OFF + UBLK_TAG_BITS) 154 #define UBLK_QID_BITS 12 155 #define UBLK_QID_BITS_MASK ((1ULL << UBLK_QID_BITS) - 1) 156 157 #define UBLK_MAX_NR_QUEUES (1U << UBLK_QID_BITS) 158 159 #define UBLKSRV_IO_BUF_TOTAL_BITS (UBLK_QID_OFF + UBLK_QID_BITS) 160 #define UBLKSRV_IO_BUF_TOTAL_SIZE (1ULL << UBLKSRV_IO_BUF_TOTAL_BITS) 161 162 /* Copy to/from request integrity buffer instead of data buffer */ 163 #define UBLK_INTEGRITY_FLAG_OFF 62 164 #define UBLKSRV_IO_INTEGRITY_FLAG (1ULL << UBLK_INTEGRITY_FLAG_OFF) 165 166 /* 167 * ublk server can register data buffers for incoming I/O requests with a sparse 168 * io_uring buffer table. The request buffer can then be used as the data buffer 169 * for io_uring operations via the fixed buffer index. 170 * Note that the ublk server can never directly access the request data memory. 171 * 172 * To use this feature, the ublk server must first register a sparse buffer 173 * table on an io_uring instance. 174 * When an incoming ublk request is received, the ublk server submits a 175 * UBLK_U_IO_REGISTER_IO_BUF command to that io_uring instance. The 176 * ublksrv_io_cmd's q_id and tag specify the request whose buffer to register 177 * and addr is the index in the io_uring's buffer table to install the buffer. 178 * SQEs can now be submitted to the io_uring to read/write the request's buffer 179 * by enabling fixed buffers (e.g. using IORING_OP_{READ,WRITE}_FIXED or 180 * IORING_URING_CMD_FIXED) and passing the registered buffer index in buf_index. 181 * Once the last io_uring operation using the request's buffer has completed, 182 * the ublk server submits a UBLK_U_IO_UNREGISTER_IO_BUF command with q_id, tag, 183 * and addr again specifying the request buffer to unregister. 184 * The ublk request is completed when its buffer is unregistered from all 185 * io_uring instances and the ublk server issues UBLK_U_IO_COMMIT_AND_FETCH_REQ. 186 * 187 * Not available for UBLK_F_UNPRIVILEGED_DEV, as a ublk server can leak 188 * uninitialized kernel memory by not reading into the full request buffer. 189 */ 190 #define UBLK_F_SUPPORT_ZERO_COPY (1ULL << 0) 191 192 /* 193 * Force to complete io cmd via io_uring_cmd_complete_in_task so that 194 * performance comparison is done easily with using task_work_add 195 */ 196 #define UBLK_F_URING_CMD_COMP_IN_TASK (1ULL << 1) 197 198 /* 199 * User should issue io cmd again for write requests to 200 * set io buffer address and copy data from bio vectors 201 * to the userspace io buffer. 202 * 203 * In this mode, task_work is not used. 204 */ 205 #define UBLK_F_NEED_GET_DATA (1UL << 2) 206 207 /* 208 * - Block devices are recoverable if ublk server exits and restarts 209 * - Outstanding I/O when ublk server exits is met with errors 210 * - I/O issued while there is no ublk server queues 211 */ 212 #define UBLK_F_USER_RECOVERY (1UL << 3) 213 214 /* 215 * - Block devices are recoverable if ublk server exits and restarts 216 * - Outstanding I/O when ublk server exits is reissued 217 * - I/O issued while there is no ublk server queues 218 */ 219 #define UBLK_F_USER_RECOVERY_REISSUE (1UL << 4) 220 221 /* 222 * Unprivileged user can create /dev/ublkcN and /dev/ublkbN. 223 * 224 * /dev/ublk-control needs to be available for unprivileged user, and it 225 * can be done via udev rule to make all control commands available to 226 * unprivileged user. Except for the command of UBLK_CMD_ADD_DEV, all 227 * other commands are only allowed for the owner of the specified device. 228 * 229 * When userspace sends UBLK_CMD_ADD_DEV, the device pair's owner_uid and 230 * owner_gid are stored to ublksrv_ctrl_dev_info by kernel, so far only 231 * the current user's uid/gid is stored, that said owner of the created 232 * device is always the current user. 233 * 234 * We still need udev rule to apply OWNER/GROUP with the stored owner_uid 235 * and owner_gid. 236 * 237 * Then ublk server can be run as unprivileged user, and /dev/ublkbN can 238 * be accessed and managed by its owner represented by owner_uid/owner_gid. 239 */ 240 #define UBLK_F_UNPRIVILEGED_DEV (1UL << 5) 241 242 /* use ioctl encoding for uring command */ 243 #define UBLK_F_CMD_IOCTL_ENCODE (1UL << 6) 244 245 /* 246 * Copy between request and user buffer by pread()/pwrite() 247 * 248 * Not available for UBLK_F_UNPRIVILEGED_DEV, otherwise userspace may 249 * deceive us by not filling request buffer, then kernel uninitialized 250 * data may be leaked. 251 */ 252 #define UBLK_F_USER_COPY (1UL << 7) 253 254 /* 255 * User space sets this flag when setting up the device to request zoned storage support. Kernel may 256 * deny the request by returning an error. 257 */ 258 #define UBLK_F_ZONED (1ULL << 8) 259 260 /* 261 * - Block devices are recoverable if ublk server exits and restarts 262 * - Outstanding I/O when ublk server exits is met with errors 263 * - I/O issued while there is no ublk server is met with errors 264 */ 265 #define UBLK_F_USER_RECOVERY_FAIL_IO (1ULL << 9) 266 267 /* 268 * Resizing a block device is possible with UBLK_U_CMD_UPDATE_SIZE 269 * New size is passed in cmd->data[0] and is in units of sectors 270 */ 271 #define UBLK_F_UPDATE_SIZE (1ULL << 10) 272 273 /* 274 * request buffer is registered automatically to uring_cmd's io_uring 275 * context before delivering this io command to ublk server, meantime 276 * it is un-registered automatically when completing this io command. 277 * 278 * For using this feature: 279 * 280 * - ublk server has to create sparse buffer table on the same `io_ring_ctx` 281 * for issuing `UBLK_IO_FETCH_REQ` and `UBLK_IO_COMMIT_AND_FETCH_REQ`. 282 * If uring_cmd isn't issued on same `io_ring_ctx`, it is ublk server's 283 * responsibility to unregister the buffer by issuing `IO_UNREGISTER_IO_BUF` 284 * manually, otherwise this ublk request won't complete. 285 * 286 * - ublk server passes auto buf register data via uring_cmd's sqe->addr, 287 * `struct ublk_auto_buf_reg` is populated from sqe->addr, please see 288 * the definition of ublk_sqe_addr_to_auto_buf_reg() 289 * 290 * - pass buffer index from `ublk_auto_buf_reg.index` 291 * 292 * - all reserved fields in `ublk_auto_buf_reg` need to be zeroed 293 * 294 * - pass flags from `ublk_auto_buf_reg.flags` if needed 295 * 296 * This way avoids extra cost from two uring_cmd, but also simplifies backend 297 * implementation, such as, the dependency on IO_REGISTER_IO_BUF and 298 * IO_UNREGISTER_IO_BUF becomes not necessary. 299 * 300 * If wrong data or flags are provided, both IO_FETCH_REQ and 301 * IO_COMMIT_AND_FETCH_REQ are failed, for the latter, the ublk IO request 302 * won't be completed until new IO_COMMIT_AND_FETCH_REQ command is issued 303 * successfully 304 */ 305 #define UBLK_F_AUTO_BUF_REG (1ULL << 11) 306 307 /* 308 * Control command `UBLK_U_CMD_QUIESCE_DEV` is added for quiescing device, 309 * which state can be transitioned to `UBLK_S_DEV_QUIESCED` or 310 * `UBLK_S_DEV_FAIL_IO` finally, and it needs ublk server cooperation for 311 * handling `UBLK_IO_RES_ABORT` correctly. 312 * 313 * Typical use case is for supporting to upgrade ublk server application, 314 * meantime keep ublk block device persistent during the period. 315 * 316 * This feature is only available when UBLK_F_USER_RECOVERY is enabled. 317 * 318 * Note, this command returns -EBUSY in case that all IO commands are being 319 * handled by ublk server and not completed in specified time period which 320 * is passed from the control command parameter. 321 */ 322 #define UBLK_F_QUIESCE (1ULL << 12) 323 324 /* 325 * If this feature is set, ublk_drv supports each (qid,tag) pair having 326 * its own independent daemon task that is responsible for handling it. 327 * If it is not set, daemons are per-queue instead, so for two pairs 328 * (qid1,tag1) and (qid2,tag2), if qid1 == qid2, then the same task must 329 * be responsible for handling (qid1,tag1) and (qid2,tag2). 330 */ 331 #define UBLK_F_PER_IO_DAEMON (1ULL << 13) 332 333 /* 334 * If this feature is set, UBLK_U_IO_REGISTER_IO_BUF/UBLK_U_IO_UNREGISTER_IO_BUF 335 * can be issued for an I/O on any task. q_id and tag are also ignored in 336 * UBLK_U_IO_UNREGISTER_IO_BUF's ublksrv_io_cmd. 337 * If it is unset, zero-copy buffers can only be registered and unregistered by 338 * the I/O's daemon task. The q_id and tag of the registered buffer are required 339 * in UBLK_U_IO_UNREGISTER_IO_BUF's ublksrv_io_cmd. 340 */ 341 #define UBLK_F_BUF_REG_OFF_DAEMON (1ULL << 14) 342 343 /* 344 * Support the following commands for delivering & committing io command 345 * in batch. 346 * 347 * - UBLK_U_IO_PREP_IO_CMDS 348 * - UBLK_U_IO_COMMIT_IO_CMDS 349 * - UBLK_U_IO_FETCH_IO_CMDS 350 * - UBLK_U_IO_REGISTER_IO_BUF 351 * - UBLK_U_IO_UNREGISTER_IO_BUF 352 * 353 * The existing UBLK_U_IO_FETCH_REQ, UBLK_U_IO_COMMIT_AND_FETCH_REQ and 354 * UBLK_U_IO_NEED_GET_DATA uring_cmd are not supported for this feature. 355 */ 356 #define UBLK_F_BATCH_IO (1ULL << 15) 357 358 /* 359 * ublk device supports requests with integrity/metadata buffer. 360 * Requires UBLK_F_USER_COPY. 361 */ 362 #define UBLK_F_INTEGRITY (1ULL << 16) 363 364 /* 365 * The device supports the UBLK_CMD_TRY_STOP_DEV command, which 366 * allows stopping the device only if there are no openers. 367 */ 368 #define UBLK_F_SAFE_STOP_DEV (1ULL << 17) 369 370 /* Disable automatic partition scanning when device is started */ 371 #define UBLK_F_NO_AUTO_PART_SCAN (1ULL << 18) 372 373 /* device state */ 374 #define UBLK_S_DEV_DEAD 0 375 #define UBLK_S_DEV_LIVE 1 376 #define UBLK_S_DEV_QUIESCED 2 377 #define UBLK_S_DEV_FAIL_IO 3 378 379 /* shipped via sqe->cmd of io_uring command */ 380 struct ublksrv_ctrl_cmd { 381 /* sent to which device, must be valid */ 382 __u32 dev_id; 383 384 /* sent to which queue, must be -1 if the cmd isn't for queue */ 385 __u16 queue_id; 386 /* 387 * cmd specific buffer, can be IN or OUT. 388 */ 389 __u16 len; 390 __u64 addr; 391 392 /* inline data */ 393 __u64 data[1]; 394 395 /* 396 * Used for UBLK_F_UNPRIVILEGED_DEV and UBLK_CMD_GET_DEV_INFO2 397 * only, include null char 398 */ 399 __u16 dev_path_len; 400 __u16 pad; 401 __u32 reserved; 402 }; 403 404 struct ublksrv_ctrl_dev_info { 405 __u16 nr_hw_queues; 406 __u16 queue_depth; 407 __u16 state; 408 __u16 pad0; 409 410 __u32 max_io_buf_bytes; 411 __u32 dev_id; 412 413 __s32 ublksrv_pid; 414 __u32 pad1; 415 416 __u64 flags; 417 418 /* For ublksrv internal use, invisible to ublk driver */ 419 __u64 ublksrv_flags; 420 421 __u32 owner_uid; /* store by kernel */ 422 __u32 owner_gid; /* store by kernel */ 423 __u64 reserved1; 424 __u64 reserved2; 425 }; 426 427 #define UBLK_IO_OP_READ 0 428 #define UBLK_IO_OP_WRITE 1 429 #define UBLK_IO_OP_FLUSH 2 430 #define UBLK_IO_OP_DISCARD 3 431 #define UBLK_IO_OP_WRITE_SAME 4 432 #define UBLK_IO_OP_WRITE_ZEROES 5 433 #define UBLK_IO_OP_ZONE_OPEN 10 434 #define UBLK_IO_OP_ZONE_CLOSE 11 435 #define UBLK_IO_OP_ZONE_FINISH 12 436 #define UBLK_IO_OP_ZONE_APPEND 13 437 #define UBLK_IO_OP_ZONE_RESET_ALL 14 438 #define UBLK_IO_OP_ZONE_RESET 15 439 /* 440 * Construct a zone report. The report request is carried in `struct 441 * ublksrv_io_desc`. The `start_sector` field must be the first sector of a zone 442 * and shall indicate the first zone of the report. The `nr_zones` shall 443 * indicate how many zones should be reported at most. The report shall be 444 * delivered as a `struct blk_zone` array. To report fewer zones than requested, 445 * zero the last entry of the returned array. 446 * 447 * Related definitions(blk_zone, blk_zone_cond, blk_zone_type, ...) in 448 * include/uapi/linux/blkzoned.h are part of ublk UAPI. 449 */ 450 #define UBLK_IO_OP_REPORT_ZONES 18 451 452 #define UBLK_IO_F_FAILFAST_DEV (1U << 8) 453 #define UBLK_IO_F_FAILFAST_TRANSPORT (1U << 9) 454 #define UBLK_IO_F_FAILFAST_DRIVER (1U << 10) 455 #define UBLK_IO_F_META (1U << 11) 456 #define UBLK_IO_F_FUA (1U << 13) 457 #define UBLK_IO_F_NOUNMAP (1U << 15) 458 #define UBLK_IO_F_SWAP (1U << 16) 459 /* 460 * For UBLK_F_AUTO_BUF_REG & UBLK_AUTO_BUF_REG_FALLBACK only. 461 * 462 * This flag is set if auto buffer register is failed & ublk server passes 463 * UBLK_AUTO_BUF_REG_FALLBACK, and ublk server need to register buffer 464 * manually for handling the delivered IO command if this flag is observed 465 * 466 * ublk server has to check this flag if UBLK_AUTO_BUF_REG_FALLBACK is 467 * passed in. 468 */ 469 #define UBLK_IO_F_NEED_REG_BUF (1U << 17) 470 /* Request has an integrity data buffer */ 471 #define UBLK_IO_F_INTEGRITY (1UL << 18) 472 473 /* 474 * io cmd is described by this structure, and stored in share memory, indexed 475 * by request tag. 476 * 477 * The data is stored by ublk driver, and read by ublksrv after one fetch command 478 * returns. 479 */ 480 struct ublksrv_io_desc { 481 /* op: bit 0-7, flags: bit 8-31 */ 482 __u32 op_flags; 483 484 union { 485 __u32 nr_sectors; 486 __u32 nr_zones; /* for UBLK_IO_OP_REPORT_ZONES */ 487 }; 488 489 /* start sector for this io */ 490 __u64 start_sector; 491 492 /* buffer address in ublksrv daemon vm space, from ublk driver */ 493 __u64 addr; 494 }; 495 496 static inline __u8 ublksrv_get_op(const struct ublksrv_io_desc *iod) 497 { 498 return iod->op_flags & 0xff; 499 } 500 501 static inline __u32 ublksrv_get_flags(const struct ublksrv_io_desc *iod) 502 { 503 return iod->op_flags >> 8; 504 } 505 506 /* 507 * If this flag is set, fallback by completing the uring_cmd and setting 508 * `UBLK_IO_F_NEED_REG_BUF` in case of auto-buf-register failure; 509 * otherwise the client ublk request is failed silently 510 * 511 * If ublk server passes this flag, it has to check if UBLK_IO_F_NEED_REG_BUF 512 * is set in `ublksrv_io_desc.op_flags`. If UBLK_IO_F_NEED_REG_BUF is set, 513 * ublk server needs to register io buffer manually for handling IO command. 514 */ 515 #define UBLK_AUTO_BUF_REG_FALLBACK (1 << 0) 516 #define UBLK_AUTO_BUF_REG_F_MASK UBLK_AUTO_BUF_REG_FALLBACK 517 518 struct ublk_auto_buf_reg { 519 /* index for registering the delivered request buffer */ 520 __u16 index; 521 __u8 flags; 522 __u8 reserved0; 523 524 /* 525 * io_ring FD can be passed via the reserve field in future for 526 * supporting to register io buffer to external io_uring 527 */ 528 __u32 reserved1; 529 }; 530 531 /* 532 * For UBLK_F_AUTO_BUF_REG, auto buffer register data is carried via 533 * uring_cmd's sqe->addr: 534 * 535 * - bit0 ~ bit15: buffer index 536 * - bit16 ~ bit23: flags 537 * - bit24 ~ bit31: reserved0 538 * - bit32 ~ bit63: reserved1 539 */ 540 static inline struct ublk_auto_buf_reg ublk_sqe_addr_to_auto_buf_reg( 541 __u64 sqe_addr) 542 { 543 struct ublk_auto_buf_reg reg = { 544 .index = (__u16)sqe_addr, 545 .flags = (__u8)(sqe_addr >> 16), 546 .reserved0 = (__u8)(sqe_addr >> 24), 547 .reserved1 = (__u32)(sqe_addr >> 32), 548 }; 549 550 return reg; 551 } 552 553 static inline __u64 554 ublk_auto_buf_reg_to_sqe_addr(const struct ublk_auto_buf_reg *buf) 555 { 556 __u64 addr = buf->index | (__u64)buf->flags << 16 | (__u64)buf->reserved0 << 24 | 557 (__u64)buf->reserved1 << 32; 558 559 return addr; 560 } 561 562 /* issued to ublk driver via /dev/ublkcN */ 563 struct ublksrv_io_cmd { 564 __u16 q_id; 565 566 /* for fetch/commit which result */ 567 __u16 tag; 568 569 /* io result, it is valid for COMMIT* command only */ 570 __s32 result; 571 572 union { 573 /* 574 * userspace buffer address in ublksrv daemon process, valid for 575 * FETCH* command only 576 * 577 * `addr` should not be used when UBLK_F_USER_COPY is enabled, 578 * because userspace handles data copy by pread()/pwrite() over 579 * /dev/ublkcN. But in case of UBLK_F_ZONED, this union is 580 * re-used to pass back the allocated LBA for 581 * UBLK_IO_OP_ZONE_APPEND which actually depends on 582 * UBLK_F_USER_COPY 583 */ 584 __u64 addr; 585 __u64 zone_append_lba; 586 }; 587 }; 588 589 struct ublk_elem_header { 590 __u16 tag; /* IO tag */ 591 592 /* 593 * Buffer index for incoming io command, only valid iff 594 * UBLK_F_AUTO_BUF_REG is set 595 */ 596 __u16 buf_index; 597 __s32 result; /* I/O completion result (commit only) */ 598 }; 599 600 /* 601 * uring_cmd buffer structure for batch commands 602 * 603 * buffer includes multiple elements, which number is specified by 604 * `nr_elem`. Each element buffer is organized in the following order: 605 * 606 * struct ublk_elem_buffer { 607 * // Mandatory fields (8 bytes) 608 * struct ublk_elem_header header; 609 * 610 * // Optional fields (8 bytes each, included based on flags) 611 * 612 * // Buffer address (if UBLK_BATCH_F_HAS_BUF_ADDR) for copying data 613 * // between ublk request and ublk server buffer 614 * __u64 buf_addr; 615 * 616 * // returned Zone append LBA (if UBLK_BATCH_F_HAS_ZONE_LBA) 617 * __u64 zone_lba; 618 * } 619 * 620 * Used for `UBLK_U_IO_PREP_IO_CMDS` and `UBLK_U_IO_COMMIT_IO_CMDS` 621 */ 622 struct ublk_batch_io { 623 __u16 q_id; 624 #define UBLK_BATCH_F_HAS_ZONE_LBA (1 << 0) 625 #define UBLK_BATCH_F_HAS_BUF_ADDR (1 << 1) 626 #define UBLK_BATCH_F_AUTO_BUF_REG_FALLBACK (1 << 2) 627 __u16 flags; 628 __u16 nr_elem; 629 __u8 elem_bytes; 630 __u8 reserved; 631 __u64 reserved2; 632 }; 633 634 struct ublk_param_basic { 635 #define UBLK_ATTR_READ_ONLY (1 << 0) 636 #define UBLK_ATTR_ROTATIONAL (1 << 1) 637 #define UBLK_ATTR_VOLATILE_CACHE (1 << 2) 638 #define UBLK_ATTR_FUA (1 << 3) 639 __u32 attrs; 640 __u8 logical_bs_shift; 641 __u8 physical_bs_shift; 642 __u8 io_opt_shift; 643 __u8 io_min_shift; 644 645 __u32 max_sectors; 646 __u32 chunk_sectors; 647 648 __u64 dev_sectors; 649 __u64 virt_boundary_mask; 650 }; 651 652 struct ublk_param_discard { 653 __u32 discard_alignment; 654 655 __u32 discard_granularity; 656 __u32 max_discard_sectors; 657 658 __u32 max_write_zeroes_sectors; 659 __u16 max_discard_segments; 660 __u16 reserved0; 661 }; 662 663 /* 664 * read-only, can't set via UBLK_CMD_SET_PARAMS, disk_devt is available 665 * after device is started 666 */ 667 struct ublk_param_devt { 668 __u32 char_major; 669 __u32 char_minor; 670 __u32 disk_major; 671 __u32 disk_minor; 672 }; 673 674 struct ublk_param_zoned { 675 __u32 max_open_zones; 676 __u32 max_active_zones; 677 __u32 max_zone_append_sectors; 678 __u8 reserved[20]; 679 }; 680 681 struct ublk_param_dma_align { 682 __u32 alignment; 683 __u8 pad[4]; 684 }; 685 686 #define UBLK_MIN_SEGMENT_SIZE 4096 687 /* 688 * If any one of the three segment parameter is set as 0, the behavior is 689 * undefined. 690 */ 691 struct ublk_param_segment { 692 /* 693 * seg_boundary_mask + 1 needs to be power_of_2(), and the sum has 694 * to be >= UBLK_MIN_SEGMENT_SIZE(4096) 695 */ 696 __u64 seg_boundary_mask; 697 698 /* 699 * max_segment_size could be override by virt_boundary_mask, so be 700 * careful when setting both. 701 * 702 * max_segment_size has to be >= UBLK_MIN_SEGMENT_SIZE(4096) 703 */ 704 __u32 max_segment_size; 705 __u16 max_segments; 706 __u8 pad[2]; 707 }; 708 709 struct ublk_param_integrity { 710 __u32 flags; /* LBMD_PI_CAP_* from linux/fs.h */ 711 __u16 max_integrity_segments; /* 0 means no limit */ 712 __u8 interval_exp; 713 __u8 metadata_size; /* UBLK_PARAM_TYPE_INTEGRITY requires nonzero */ 714 __u8 pi_offset; 715 __u8 csum_type; /* LBMD_PI_CSUM_* from linux/fs.h */ 716 __u8 tag_size; 717 __u8 pad[5]; 718 }; 719 720 struct ublk_params { 721 /* 722 * Total length of parameters, userspace has to set 'len' for both 723 * SET_PARAMS and GET_PARAMS command, and driver may update len 724 * if two sides use different version of 'ublk_params', same with 725 * 'types' fields. 726 */ 727 __u32 len; 728 #define UBLK_PARAM_TYPE_BASIC (1 << 0) 729 #define UBLK_PARAM_TYPE_DISCARD (1 << 1) 730 #define UBLK_PARAM_TYPE_DEVT (1 << 2) 731 #define UBLK_PARAM_TYPE_ZONED (1 << 3) 732 #define UBLK_PARAM_TYPE_DMA_ALIGN (1 << 4) 733 #define UBLK_PARAM_TYPE_SEGMENT (1 << 5) 734 #define UBLK_PARAM_TYPE_INTEGRITY (1 << 6) /* requires UBLK_F_INTEGRITY */ 735 __u32 types; /* types of parameter included */ 736 737 struct ublk_param_basic basic; 738 struct ublk_param_discard discard; 739 struct ublk_param_devt devt; 740 struct ublk_param_zoned zoned; 741 struct ublk_param_dma_align dma; 742 struct ublk_param_segment seg; 743 struct ublk_param_integrity integrity; 744 }; 745 746 #endif 747