Documentation/block/ublk.rst

Source file repositories/reference/linux-study-clean/Documentation/block/ublk.rst

File Facts

System
Linux kernel
Corpus path
Documentation/block/ublk.rst
Extension
.rst
Size
26653 bytes
Lines
617
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

struct ublk_auto_buf_reg {
        __u16 index;      /* Buffer index for registration */
        __u8 flags;       /* Registration flags */
        __u8 reserved0;   /* Reserved for future use */
        __u32 reserved1;  /* Reserved for future use */
    };

   ublk_auto_buf_reg_to_sqe_addr() is for converting the above structure into
   ``sqe->addr``.

3. All reserved fields in ``ublk_auto_buf_reg`` must be zeroed.

4. Optional flags can be passed via ``ublk_auto_buf_reg.flags``.

Fallback Behavior
~~~~~~~~~~~~~~~~~

If auto buffer registration fails:

1. When ``UBLK_AUTO_BUF_REG_FALLBACK`` is enabled:

   - The uring_cmd is completed
   - ``UBLK_IO_F_NEED_REG_BUF`` is set in ``ublksrv_io_desc.op_flags``
   - The ublk server must manually deal with the failure, such as, register
     the buffer manually, or using user copy feature for retrieving the data
     for handling ublk IO

2. If fallback is not enabled:

   - The ublk I/O request fails silently
   - The uring_cmd won't be completed

Limitations
~~~~~~~~~~~

- Requires same ``io_ring_ctx`` for all operations
- May require manual buffer management in fallback cases
- io_ring_ctx buffer table has a max size of 16K, which may not be enough
  in case that too many ublk devices are handled by this single io_ring_ctx
  and each one has very large queue depth

Shared Memory Zero Copy (UBLK_F_SHMEM_ZC)
------------------------------------------

The ``UBLK_F_SHMEM_ZC`` feature provides an alternative zero-copy path
that works by sharing physical memory pages between the client application
and the ublk server. Unlike the io_uring fixed buffer approach above,
shared memory zero copy does not require io_uring buffer registration
per I/O — instead, it relies on the kernel matching physical pages
at I/O time. This allows the ublk server to access the shared
buffer directly, which is unlikely for the io_uring fixed buffer
approach.

Motivation
~~~~~~~~~~

Shared memory zero copy takes a different approach: if the client
application and the ublk server both map the same physical memory, there is
nothing to copy. The kernel detects the shared pages automatically and
tells the server where the data already lives.

``UBLK_F_SHMEM_ZC`` can be thought of as a supplement for optimized client
applications — when the client is willing to allocate I/O buffers from
shared memory, the entire data path becomes zero-copy.

Use Cases
~~~~~~~~~

This feature is useful when the client application can be configured to
use a specific shared memory region for its I/O buffers:

Annotation

Implementation Notes