Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
Documentation: ublk: document UBLK_F_USER_RECOVERY_FAIL_IO
Signed-off-by: Uday Shankar <ushankar@purestorage.com>
Reviewed-by: Ming Lei <ming.lei@redhat.com>
Link: https://lore.kernel.org/r/20241007182419.3263186-6-ushankar@purestorage.com
Signed-off-by: Jens Axboe <axboe@kernel.dk>
authored by
Uday Shankar
and committed by
Jens Axboe
69f407ee
59eaa01c
+17
-5
+17
-5
Documentation/block/ublk.rst
+17
-5
Documentation/block/ublk.rst
···
199
199
200
200
- user recovery feature description
201
201
202
-
Two new features are added for user recovery: ``UBLK_F_USER_RECOVERY`` and
203
-
``UBLK_F_USER_RECOVERY_REISSUE``.
202
+
Three new features are added for user recovery: ``UBLK_F_USER_RECOVERY``,
203
+
``UBLK_F_USER_RECOVERY_REISSUE``, and ``UBLK_F_USER_RECOVERY_FAIL_IO``. To
204
+
enable recovery of ublk devices after the ublk server exits, the ublk server
205
+
should specify the ``UBLK_F_USER_RECOVERY`` flag when creating the device. The
206
+
ublk server may additionally specify at most one of
207
+
``UBLK_F_USER_RECOVERY_REISSUE`` and ``UBLK_F_USER_RECOVERY_FAIL_IO`` to
208
+
modify how I/O is handled while the ublk server is dying/dead (this is called
209
+
the ``nosrv`` case in the driver code).
204
210
205
-
With ``UBLK_F_USER_RECOVERY`` set, after one ubq_daemon(ublk server's io
211
+
With just ``UBLK_F_USER_RECOVERY`` set, after one ubq_daemon(ublk server's io
206
212
handler) is dying, ublk does not delete ``/dev/ublkb*`` during the whole
207
213
recovery stage and ublk device ID is kept. It is ublk server's
208
214
responsibility to recover the device context by its own knowledge.
209
215
Requests which have not been issued to userspace are requeued. Requests
210
216
which have been issued to userspace are aborted.
211
217
212
-
With ``UBLK_F_USER_RECOVERY_REISSUE`` set, after one ubq_daemon(ublk
213
-
server's io handler) is dying, contrary to ``UBLK_F_USER_RECOVERY``,
218
+
With ``UBLK_F_USER_RECOVERY_REISSUE`` additionally set, after one ubq_daemon
219
+
(ublk server's io handler) is dying, contrary to ``UBLK_F_USER_RECOVERY``,
214
220
requests which have been issued to userspace are requeued and will be
215
221
re-issued to the new process after handling ``UBLK_CMD_END_USER_RECOVERY``.
216
222
``UBLK_F_USER_RECOVERY_REISSUE`` is designed for backends who tolerate
217
223
double-write since the driver may issue the same I/O request twice. It
218
224
might be useful to a read-only FS or a VM backend.
225
+
226
+
With ``UBLK_F_USER_RECOVERY_FAIL_IO`` additionally set, after the ublk server
227
+
exits, requests which have issued to userspace are failed, as are any
228
+
subsequently issued requests. Applications continuously issuing I/O against
229
+
devices with this flag set will see a stream of I/O errors until a new ublk
230
+
server recovers the device.
219
231
220
232
Unprivileged ublk device is supported by passing ``UBLK_F_UNPRIVILEGED_DEV``.
221
233
Once the flag is set, all control commands can be sent by unprivileged