1 .. SPDX-License-Identifier: GPL-2.0
3 ===========================================
4 Userspace block device driver (ublk driver)
5 ===========================================
10 ublk is a generic framework for implementing block device logic from userspace.
11 The motivation behind it is that moving virtual block drivers into userspace,
12 such as loop, nbd and similar can be very helpful. It can help to implement
13 new virtual block device such as ublk-qcow2 (there are several attempts of
14 implementing qcow2 driver in kernel).
16 Userspace block devices are attractive because:
18 - They can be written many programming languages.
19 - They can use libraries that are not available in the kernel.
20 - They can be debugged with tools familiar to application developers.
21 - Crashes do not kernel panic the machine.
22 - Bugs are likely to have a lower security impact than bugs in kernel
24 - They can be installed and updated independently of the kernel.
25 - They can be used to simulate block device easily with user specified
26 parameters/setting for test/debug purpose
28 ublk block device (``/dev/ublkb*``) is added by ublk driver. Any IO request
29 on the device will be forwarded to ublk userspace program. For convenience,
30 in this document, ``ublk server`` refers to generic ublk userspace
31 program. ``ublksrv`` [#userspace]_ is one of such implementation. It
32 provides ``libublksrv`` [#userspace_lib]_ library for developing specific
33 user block device conveniently, while also generic type block device is
34 included, such as loop and null. Richard W.M. Jones wrote userspace nbd device
35 ``nbdublk`` [#userspace_nbdublk]_ based on ``libublksrv`` [#userspace_lib]_.
37 After the IO is handled by userspace, the result is committed back to the
38 driver, thus completing the request cycle. This way, any specific IO handling
39 logic is totally done by userspace, such as loop's IO handling, NBD's IO
40 communication, or qcow2's IO mapping.
42 ``/dev/ublkb*`` is driven by blk-mq request-based driver. Each request is
43 assigned by one queue wide unique tag. ublk server assigns unique tag to each
44 IO too, which is 1:1 mapped with IO of ``/dev/ublkb*``.
46 Both the IO request forward and IO handling result committing are done via
47 ``io_uring`` passthrough command; that is why ublk is also one io_uring based
48 block driver. It has been observed that using io_uring passthrough command can
49 give better IOPS than block IO; which is why ublk is one of high performance
50 implementation of userspace block device: not only IO request communication is
51 done by io_uring, but also the preferred IO handling in ublk server is io_uring
54 ublk provides control interface to set/get ublk block device parameters.
55 The interface is extendable and kabi compatible: basically any ublk request
56 queue's parameter or ublk generic feature parameters can be set/get via the
57 interface. Thus, ublk is generic userspace block device framework.
58 For example, it is easy to setup a ublk device with specified block
59 parameters from userspace.
64 ublk requires userspace ublk server to handle real block device logic.
66 Below is example of using ``ublksrv`` to provide ublk-based loop device.
70 ublk add -t loop -f ublk-loop.img
72 - format with xfs, then use it::
75 mount /dev/ublkb0 /mnt
76 # do anything. all IOs are handled by io_uring
80 - list the devices with their info::
87 ublk del -n $ublk_dev_id
89 See usage details in README of ``ublksrv`` [#userspace_readme]_.
97 ublk driver provides global misc device node (``/dev/ublk-control``) for
98 managing and controlling ublk devices with help of several control commands:
100 - ``UBLK_CMD_ADD_DEV``
102 Add a ublk char device (``/dev/ublkc*``) which is talked with ublk server
103 WRT IO command communication. Basic device info is sent together with this
104 command. It sets UAPI structure of ``ublksrv_ctrl_dev_info``,
105 such as ``nr_hw_queues``, ``queue_depth``, and max IO request buffer size,
106 for which the info is negotiated with the driver and sent back to the server.
107 When this command is completed, the basic device info is immutable.
109 - ``UBLK_CMD_SET_PARAMS`` / ``UBLK_CMD_GET_PARAMS``
111 Set or get parameters of the device, which can be either generic feature
112 related, or request queue limit related, but can't be IO logic specific,
113 because the driver does not handle any IO logic. This command has to be
114 sent before sending ``UBLK_CMD_START_DEV``.
116 - ``UBLK_CMD_START_DEV``
118 After the server prepares userspace resources (such as creating per-queue
119 pthread & io_uring for handling ublk IO), this command is sent to the
120 driver for allocating & exposing ``/dev/ublkb*``. Parameters set via
121 ``UBLK_CMD_SET_PARAMS`` are applied for creating the device.
123 - ``UBLK_CMD_STOP_DEV``
125 Halt IO on ``/dev/ublkb*`` and remove the device. When this command returns,
126 ublk server will release resources (such as destroying per-queue pthread &
129 - ``UBLK_CMD_DEL_DEV``
131 Remove ``/dev/ublkc*``. When this command returns, the allocated ublk device
132 number can be reused.
134 - ``UBLK_CMD_GET_QUEUE_AFFINITY``
136 When ``/dev/ublkc`` is added, the driver creates block layer tagset, so
137 that each queue's affinity info is available. The server sends
138 ``UBLK_CMD_GET_QUEUE_AFFINITY`` to retrieve queue affinity info. It can
139 set up the per-queue context efficiently, such as bind affine CPUs with IO
140 pthread and try to allocate buffers in IO thread context.
142 - ``UBLK_CMD_GET_DEV_INFO``
144 For retrieving device info via ``ublksrv_ctrl_dev_info``. It is the server's
145 responsibility to save IO target specific info in userspace.
147 - ``UBLK_CMD_START_USER_RECOVERY``
149 This command is valid if ``UBLK_F_USER_RECOVERY`` feature is enabled. This
150 command is accepted after the old process has exited, ublk device is quiesced
151 and ``/dev/ublkc*`` is released. User should send this command before he starts
152 a new process which re-opens ``/dev/ublkc*``. When this command returns, the
153 ublk device is ready for the new process.
155 - ``UBLK_CMD_END_USER_RECOVERY``
157 This command is valid if ``UBLK_F_USER_RECOVERY`` feature is enabled. This
158 command is accepted after ublk device is quiesced and a new process has
159 opened ``/dev/ublkc*`` and get all ublk queues be ready. When this command
160 returns, ublk device is unquiesced and new I/O requests are passed to the
163 - user recovery feature description
165 Two new features are added for user recovery: ``UBLK_F_USER_RECOVERY`` and
166 ``UBLK_F_USER_RECOVERY_REISSUE``.
168 With ``UBLK_F_USER_RECOVERY`` set, after one ubq_daemon(ublk server's io
169 handler) is dying, ublk does not delete ``/dev/ublkb*`` during the whole
170 recovery stage and ublk device ID is kept. It is ublk server's
171 responsibility to recover the device context by its own knowledge.
172 Requests which have not been issued to userspace are requeued. Requests
173 which have been issued to userspace are aborted.
175 With ``UBLK_F_USER_RECOVERY_REISSUE`` set, after one ubq_daemon(ublk
176 server's io handler) is dying, contrary to ``UBLK_F_USER_RECOVERY``,
177 requests which have been issued to userspace are requeued and will be
178 re-issued to the new process after handling ``UBLK_CMD_END_USER_RECOVERY``.
179 ``UBLK_F_USER_RECOVERY_REISSUE`` is designed for backends who tolerate
180 double-write since the driver may issue the same I/O request twice. It
181 might be useful to a read-only FS or a VM backend.
186 ublk server needs to create per-queue IO pthread & io_uring for handling IO
187 commands via io_uring passthrough. The per-queue IO pthread
188 focuses on IO handling and shouldn't handle any control & management
191 The's IO is assigned by a unique tag, which is 1:1 mapping with IO
192 request of ``/dev/ublkb*``.
194 UAPI structure of ``ublksrv_io_desc`` is defined for describing each IO from
195 the driver. A fixed mmaped area (array) on ``/dev/ublkc*`` is provided for
196 exporting IO info to the server; such as IO offset, length, OP/flags and
197 buffer address. Each ``ublksrv_io_desc`` instance can be indexed via queue id
200 The following IO commands are communicated via io_uring passthrough command,
201 and each command is only for forwarding the IO and committing the result
202 with specified IO tag in the command data:
204 - ``UBLK_IO_FETCH_REQ``
206 Sent from the server IO pthread for fetching future incoming IO requests
207 destined to ``/dev/ublkb*``. This command is sent only once from the server
208 IO pthread for ublk driver to setup IO forward environment.
210 - ``UBLK_IO_COMMIT_AND_FETCH_REQ``
212 When an IO request is destined to ``/dev/ublkb*``, the driver stores
213 the IO's ``ublksrv_io_desc`` to the specified mapped area; then the
214 previous received IO command of this IO tag (either ``UBLK_IO_FETCH_REQ``
215 or ``UBLK_IO_COMMIT_AND_FETCH_REQ)`` is completed, so the server gets
216 the IO notification via io_uring.
218 After the server handles the IO, its result is committed back to the
219 driver by sending ``UBLK_IO_COMMIT_AND_FETCH_REQ`` back. Once ublkdrv
220 received this command, it parses the result and complete the request to
221 ``/dev/ublkb*``. In the meantime setup environment for fetching future
222 requests with the same IO tag. That is, ``UBLK_IO_COMMIT_AND_FETCH_REQ``
223 is reused for both fetching request and committing back IO result.
225 - ``UBLK_IO_NEED_GET_DATA``
227 With ``UBLK_F_NEED_GET_DATA`` enabled, the WRITE request will be firstly
228 issued to ublk server without data copy. Then, IO backend of ublk server
229 receives the request and it can allocate data buffer and embed its addr
230 inside this new io command. After the kernel driver gets the command,
231 data copy is done from request pages to this backend's buffer. Finally,
232 backend receives the request again with data to be written and it can
233 truly handle the request.
235 ``UBLK_IO_NEED_GET_DATA`` adds one additional round-trip and one
236 io_uring_enter() syscall. Any user thinks that it may lower performance
237 should not enable UBLK_F_NEED_GET_DATA. ublk server pre-allocates IO
238 buffer for each IO by default. Any new project should try to use this
239 buffer to communicate with ublk driver. However, existing project may
240 break or not able to consume the new buffer interface; that's why this
241 command is added for backwards compatibility so that existing projects
242 can still consume existing buffers.
244 - data copy between ublk server IO buffer and ublk block IO request
246 The driver needs to copy the block IO request pages into the server buffer
247 (pages) first for WRITE before notifying the server of the coming IO, so
248 that the server can handle WRITE request.
250 When the server handles READ request and sends
251 ``UBLK_IO_COMMIT_AND_FETCH_REQ`` to the server, ublkdrv needs to copy
252 the server buffer (pages) read to the IO request pages.
257 Container-aware ublk deivice
258 ----------------------------
260 ublk driver doesn't handle any IO logic. Its function is well defined
261 for now and very limited userspace interfaces are needed, which is also
262 well defined too. It is possible to make ublk devices container-aware block
263 devices in future as Stefan Hajnoczi suggested [#stefan]_, by removing
269 Zero copy is a generic requirement for nbd, fuse or similar drivers. A
270 problem [#xiaoguang]_ Xiaoguang mentioned is that pages mapped to userspace
271 can't be remapped any more in kernel with existing mm interfaces. This can
272 occurs when destining direct IO to ``/dev/ublkb*``. Also, he reported that
273 big requests (IO size >= 256 KB) may benefit a lot from zero copy.
279 .. [#userspace] https://github.com/ming1/ubdsrv
281 .. [#userspace_lib] https://github.com/ming1/ubdsrv/tree/master/lib
283 .. [#userspace_nbdublk] https://gitlab.com/rwmjones/libnbd/-/tree/nbdublk
285 .. [#userspace_readme] https://github.com/ming1/ubdsrv/blob/master/README
287 .. [#stefan] https://lore.kernel.org/linux-block/YoOr6jBfgVm8GvWg@stefanha-x1.localdomain/
289 .. [#xiaoguang] https://lore.kernel.org/linux-block/YoOr6jBfgVm8GvWg@stefanha-x1.localdomain/