@@ -352,6 +352,83 @@ For reaching best IO performance, ublk server should align its segment
352352parameter of `struct ublk_param_segment ` with backend for avoiding
353353unnecessary IO split, which usually hurts io_uring performance.
354354
355+ Auto Buffer Registration
356+ ------------------------
357+
358+ The ``UBLK_F_AUTO_BUF_REG `` feature automatically handles buffer registration
359+ and unregistration for I/O requests, which simplifies the buffer management
360+ process and reduces overhead in the ublk server implementation.
361+
362+ This is another feature flag for using zero copy, and it is compatible with
363+ ``UBLK_F_SUPPORT_ZERO_COPY ``.
364+
365+ Feature Overview
366+ ~~~~~~~~~~~~~~~~
367+
368+ This feature automatically registers request buffers to the io_uring context
369+ before delivering I/O commands to the ublk server and unregisters them when
370+ completing I/O commands. This eliminates the need for manual buffer
371+ registration/unregistration via ``UBLK_IO_REGISTER_IO_BUF `` and
372+ ``UBLK_IO_UNREGISTER_IO_BUF `` commands, then IO handling in ublk server
373+ can avoid dependency on the two uring_cmd operations.
374+
375+ IOs can't be issued concurrently to io_uring if there is any dependency
376+ among these IOs. So this way not only simplifies ublk server implementation,
377+ but also makes concurrent IO handling becomes possible by removing the
378+ dependency on buffer registration & unregistration commands.
379+
380+ Usage Requirements
381+ ~~~~~~~~~~~~~~~~~~
382+
383+ 1. The ublk server must create a sparse buffer table on the same ``io_ring_ctx ``
384+ used for ``UBLK_IO_FETCH_REQ `` and ``UBLK_IO_COMMIT_AND_FETCH_REQ ``. If
385+ uring_cmd is issued on a different ``io_ring_ctx ``, manual buffer
386+ unregistration is required.
387+
388+ 2. Buffer registration data must be passed via uring_cmd's ``sqe->addr `` with the
389+ following structure::
390+
391+ struct ublk_auto_buf_reg {
392+ __u16 index; /* Buffer index for registration */
393+ __u8 flags; /* Registration flags */
394+ __u8 reserved0; /* Reserved for future use */
395+ __u32 reserved1; /* Reserved for future use */
396+ };
397+
398+ ublk_auto_buf_reg_to_sqe_addr() is for converting the above structure into
399+ ``sqe->addr ``.
400+
401+ 3. All reserved fields in ``ublk_auto_buf_reg `` must be zeroed.
402+
403+ 4. Optional flags can be passed via ``ublk_auto_buf_reg.flags ``.
404+
405+ Fallback Behavior
406+ ~~~~~~~~~~~~~~~~~
407+
408+ If auto buffer registration fails:
409+
410+ 1. When ``UBLK_AUTO_BUF_REG_FALLBACK `` is enabled:
411+
412+ - The uring_cmd is completed
413+ - ``UBLK_IO_F_NEED_REG_BUF `` is set in ``ublksrv_io_desc.op_flags ``
414+ - The ublk server must manually deal with the failure, such as, register
415+ the buffer manually, or using user copy feature for retrieving the data
416+ for handling ublk IO
417+
418+ 2. If fallback is not enabled:
419+
420+ - The ublk I/O request fails silently
421+ - The uring_cmd won't be completed
422+
423+ Limitations
424+ ~~~~~~~~~~~
425+
426+ - Requires same ``io_ring_ctx `` for all operations
427+ - May require manual buffer management in fallback cases
428+ - io_ring_ctx buffer table has a max size of 16K, which may not be enough
429+ in case that too many ublk devices are handled by this single io_ring_ctx
430+ and each one has very large queue depth
431+
355432References
356433==========
357434
0 commit comments