[PATCH V4 8/8] Documentation: document ublk user recovery feature

From: ZiyangZhang
Date: Wed Sep 21 2022 - 06:01:57 EST


Add documentation for user recovery feature of ublk subsystem.

Signed-off-by: ZiyangZhang <ZiyangZhang@xxxxxxxxxxxxxxxxx>
---
Documentation/block/ublk.rst | 25 +++++++++++++++++++++++++
1 file changed, 25 insertions(+)

diff --git a/Documentation/block/ublk.rst b/Documentation/block/ublk.rst
index 2122d1a4a541..3f1bfd51898b 100644
--- a/Documentation/block/ublk.rst
+++ b/Documentation/block/ublk.rst
@@ -144,6 +144,31 @@ managing and controlling ublk devices with help of several control commands:
For retrieving device info via ``ublksrv_ctrl_dev_info``. It is the server's
responsibility to save IO target specific info in userspace.

+- ``UBLK_CMD_RESTART_DEV``
+
+ This command is valid if ``UBLK_F_USER_RECOVERY`` feature is enabled. The old
+ process has exited and ublk device is quiesced. Then, user should start a new
+ process which opens ``/dev/ublkc*`` and gets all ublk queues be ready. Finally
+ user should send this command. When this command returns, ublk device is
+ unquiesced and new I/O requests are passed to the new process.
+
+- user recovery feature description
+
+ Two new features are added for user recovery: ``UBLK_F_USER_RECOVERY`` and
+ ``UBLK_F_USER_RECOVERY_REISSUE``.
+
+ With ``UBLK_F_USER_RECOVERY`` set, after one ubq_daemon(ublksrv io handler) is
+ dying, ublk does not release ``/dev/ublkc*`` or ``/dev/ublkb*`` but requeues all
+ inflight requests which have not been issued to userspace. Requests which have
+ been issued to userspace are aborted.
+
+ With ``UBLK_F_USER_RECOVERY_REISSUE`` set, after one ubq_daemon(ublksrv io
+ handler) is dying, contrary to ``UBLK_F_USER_RECOVERY``, requests which have been
+ issued to userspace are requeued and will be re-issued to the new process after
+ handling ``UBLK_CMD_RESTART_DEV``. ``UBLK_F_USER_RECOVERY_REISSUE`` is designed
+ for backends who tolerate double-write since the driver may issue the same
+ I/O request twice. It might be useful to a read-only FS or a VM backend.
+
Data plane
----------

--
2.27.0