logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

ublk_cmd.h (12046B)


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