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
ublksrv_get_op(const struct ublksrv_io_desc * iod)496 static inline __u8 ublksrv_get_op(const struct ublksrv_io_desc *iod)
497 {
498 return iod->op_flags & 0xff;
499 }
500
ublksrv_get_flags(const struct ublksrv_io_desc * iod)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 */
ublk_sqe_addr_to_auto_buf_reg(__u64 sqe_addr)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
ublk_auto_buf_reg_to_sqe_addr(const struct ublk_auto_buf_reg * buf)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