Commit | Line | Data |
---|---|---|
7a3d2225 ML |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | ||
3 | =========================================== | |
4 | Userspace block device driver (ublk driver) | |
5 | =========================================== | |
6 | ||
7 | Overview | |
8 | ======== | |
9 | ||
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). | |
15 | ||
16 | Userspace block devices are attractive because: | |
17 | ||
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 | |
23 | code. | |
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 | |
27 | ||
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]_. | |
36 | ||
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. | |
41 | ||
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*``. | |
45 | ||
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 | |
52 | based approach too. | |
53 | ||
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. | |
60 | ||
61 | Using ublk | |
62 | ========== | |
63 | ||
64 | ublk requires userspace ublk server to handle real block device logic. | |
65 | ||
66 | Below is example of using ``ublksrv`` to provide ublk-based loop device. | |
67 | ||
68 | - add a device:: | |
69 | ||
70 | ublk add -t loop -f ublk-loop.img | |
71 | ||
72 | - format with xfs, then use it:: | |
73 | ||
74 | mkfs.xfs /dev/ublkb0 | |
75 | mount /dev/ublkb0 /mnt | |
76 | # do anything. all IOs are handled by io_uring | |
77 | ... | |
78 | umount /mnt | |
79 | ||
80 | - list the devices with their info:: | |
81 | ||
82 | ublk list | |
83 | ||
84 | - delete the device:: | |
85 | ||
86 | ublk del -a | |
87 | ublk del -n $ublk_dev_id | |
88 | ||
89 | See usage details in README of ``ublksrv`` [#userspace_readme]_. | |
90 | ||
91 | Design | |
92 | ====== | |
93 | ||
94 | Control plane | |
95 | ------------- | |
96 | ||
97 | ublk driver provides global misc device node (``/dev/ublk-control``) for | |
98 | managing and controlling ublk devices with help of several control commands: | |
99 | ||
100 | - ``UBLK_CMD_ADD_DEV`` | |
101 | ||
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. | |
108 | ||
109 | - ``UBLK_CMD_SET_PARAMS`` / ``UBLK_CMD_GET_PARAMS`` | |
110 | ||
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``. | |
115 | ||
116 | - ``UBLK_CMD_START_DEV`` | |
117 | ||
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. | |
122 | ||
123 | - ``UBLK_CMD_STOP_DEV`` | |
124 | ||
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 & | |
127 | io_uring). | |
128 | ||
129 | - ``UBLK_CMD_DEL_DEV`` | |
130 | ||
131 | Remove ``/dev/ublkc*``. When this command returns, the allocated ublk device | |
132 | number can be reused. | |
133 | ||
134 | - ``UBLK_CMD_GET_QUEUE_AFFINITY`` | |
135 | ||
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. | |
141 | ||
142 | - ``UBLK_CMD_GET_DEV_INFO`` | |
143 | ||
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. | |
146 | ||
147 | Data plane | |
148 | ---------- | |
149 | ||
150 | ublk server needs to create per-queue IO pthread & io_uring for handling IO | |
151 | commands via io_uring passthrough. The per-queue IO pthread | |
152 | focuses on IO handling and shouldn't handle any control & management | |
153 | tasks. | |
154 | ||
155 | The's IO is assigned by a unique tag, which is 1:1 mapping with IO | |
156 | request of ``/dev/ublkb*``. | |
157 | ||
158 | UAPI structure of ``ublksrv_io_desc`` is defined for describing each IO from | |
159 | the driver. A fixed mmaped area (array) on ``/dev/ublkc*`` is provided for | |
160 | exporting IO info to the server; such as IO offset, length, OP/flags and | |
161 | buffer address. Each ``ublksrv_io_desc`` instance can be indexed via queue id | |
162 | and IO tag directly. | |
163 | ||
164 | The following IO commands are communicated via io_uring passthrough command, | |
165 | and each command is only for forwarding the IO and committing the result | |
166 | with specified IO tag in the command data: | |
167 | ||
168 | - ``UBLK_IO_FETCH_REQ`` | |
169 | ||
170 | Sent from the server IO pthread for fetching future incoming IO requests | |
171 | destined to ``/dev/ublkb*``. This command is sent only once from the server | |
172 | IO pthread for ublk driver to setup IO forward environment. | |
173 | ||
174 | - ``UBLK_IO_COMMIT_AND_FETCH_REQ`` | |
175 | ||
176 | When an IO request is destined to ``/dev/ublkb*``, the driver stores | |
177 | the IO's ``ublksrv_io_desc`` to the specified mapped area; then the | |
178 | previous received IO command of this IO tag (either ``UBLK_IO_FETCH_REQ`` | |
179 | or ``UBLK_IO_COMMIT_AND_FETCH_REQ)`` is completed, so the server gets | |
180 | the IO notification via io_uring. | |
181 | ||
182 | After the server handles the IO, its result is committed back to the | |
183 | driver by sending ``UBLK_IO_COMMIT_AND_FETCH_REQ`` back. Once ublkdrv | |
184 | received this command, it parses the result and complete the request to | |
185 | ``/dev/ublkb*``. In the meantime setup environment for fetching future | |
186 | requests with the same IO tag. That is, ``UBLK_IO_COMMIT_AND_FETCH_REQ`` | |
187 | is reused for both fetching request and committing back IO result. | |
188 | ||
189 | - ``UBLK_IO_NEED_GET_DATA`` | |
190 | ||
191 | With ``UBLK_F_NEED_GET_DATA`` enabled, the WRITE request will be firstly | |
192 | issued to ublk server without data copy. Then, IO backend of ublk server | |
193 | receives the request and it can allocate data buffer and embed its addr | |
194 | inside this new io command. After the kernel driver gets the command, | |
195 | data copy is done from request pages to this backend's buffer. Finally, | |
196 | backend receives the request again with data to be written and it can | |
197 | truly handle the request. | |
198 | ||
199 | ``UBLK_IO_NEED_GET_DATA`` adds one additional round-trip and one | |
200 | io_uring_enter() syscall. Any user thinks that it may lower performance | |
201 | should not enable UBLK_F_NEED_GET_DATA. ublk server pre-allocates IO | |
202 | buffer for each IO by default. Any new project should try to use this | |
203 | buffer to communicate with ublk driver. However, existing project may | |
204 | break or not able to consume the new buffer interface; that's why this | |
205 | command is added for backwards compatibility so that existing projects | |
206 | can still consume existing buffers. | |
207 | ||
208 | - data copy between ublk server IO buffer and ublk block IO request | |
209 | ||
210 | The driver needs to copy the block IO request pages into the server buffer | |
211 | (pages) first for WRITE before notifying the server of the coming IO, so | |
212 | that the server can handle WRITE request. | |
213 | ||
214 | When the server handles READ request and sends | |
215 | ``UBLK_IO_COMMIT_AND_FETCH_REQ`` to the server, ublkdrv needs to copy | |
216 | the server buffer (pages) read to the IO request pages. | |
217 | ||
218 | Future development | |
219 | ================== | |
220 | ||
221 | Container-aware ublk deivice | |
222 | ---------------------------- | |
223 | ||
224 | ublk driver doesn't handle any IO logic. Its function is well defined | |
225 | for now and very limited userspace interfaces are needed, which is also | |
226 | well defined too. It is possible to make ublk devices container-aware block | |
227 | devices in future as Stefan Hajnoczi suggested [#stefan]_, by removing | |
228 | ADMIN privilege. | |
229 | ||
230 | Zero copy | |
231 | --------- | |
232 | ||
233 | Zero copy is a generic requirement for nbd, fuse or similar drivers. A | |
234 | problem [#xiaoguang]_ Xiaoguang mentioned is that pages mapped to userspace | |
235 | can't be remapped any more in kernel with existing mm interfaces. This can | |
236 | occurs when destining direct IO to ``/dev/ublkb*``. Also, he reported that | |
237 | big requests (IO size >= 256 KB) may benefit a lot from zero copy. | |
238 | ||
239 | ||
240 | References | |
241 | ========== | |
242 | ||
243 | .. [#userspace] https://github.com/ming1/ubdsrv | |
244 | ||
245 | .. [#userspace_lib] https://github.com/ming1/ubdsrv/tree/master/lib | |
246 | ||
247 | .. [#userspace_nbdublk] https://gitlab.com/rwmjones/libnbd/-/tree/nbdublk | |
248 | ||
249 | .. [#userspace_readme] https://github.com/ming1/ubdsrv/blob/master/README | |
250 | ||
251 | .. [#stefan] https://lore.kernel.org/linux-block/YoOr6jBfgVm8GvWg@stefanha-x1.localdomain/ | |
252 | ||
253 | .. [#xiaoguang] https://lore.kernel.org/linux-block/YoOr6jBfgVm8GvWg@stefanha-x1.localdomain/ |