Re: [PATCH v4 25/25] docs: fuse: add io-uring bufring and zero-copy documentation

[Bernd Schubert <bernd@bsbernd.com>]

On 1/17/26 00:30, Joanne Koong wrote:
> Add documentation for fuse over io-uring usage of kernel-managed
> bufrings and zero-copy.
> 
> Signed-off-by: Joanne Koong <joannelkoong@gmail.com>
> ---
>  .../filesystems/fuse/fuse-io-uring.rst        | 59 ++++++++++++++++++-
>  1 file changed, 58 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/filesystems/fuse/fuse-io-uring.rst b/Documentation/filesystems/fuse/fuse-io-uring.rst
> index d73dd0dbd238..11c244b63d25 100644
> --- a/Documentation/filesystems/fuse/fuse-io-uring.rst
> +++ b/Documentation/filesystems/fuse/fuse-io-uring.rst
> @@ -95,5 +95,62 @@ Sending requests with CQEs
>   |    <fuse_unlink()                         |
>   |  <sys_unlink()                            |
>  
> +Kernel-managed buffer rings
> +===========================
>  
> -
> +Kernel-managed buffer rings have two main advantages:
> +
> +* eliminates the overhead of pinning/unpinning user pages and translating
> +  virtual addresses for every server-kernel interaction
> +* reduces buffer memory allocation requirements
> +
> +In order to use buffer rings, the server must preregister the following:
> +
> +* a fixed buffer at index 0. This is where the headers will reside
> +* a kernel-managed buffer ring. This is where the payload will reside

Would you mind to add the actual liburing call for this? I think it
would be helpful for anyone who wants to implement it.

> +
> +At a high-level, this is how fuse uses buffer rings:
> +
> +* The server registers a kernel-managed buffer ring. In the kernel this
> +  allocates the pages needed for the buffers and vmaps them. The server
> +  obtains the virtual address for the buffers through an mmap call on the ring
> +  fd.
> +* When there is a request from a client, fuse will select a buffer from the
> +  ring if there is any payload that needs to be copied, copy over the payload
> +  to the selected buffer, and copy over the headers to the fixed buffer at
> +  index 0, at the buffer id that corresponds to the server (which the server
> +  needs to specify through sqe->buf_index).
> +* The server obtains a cqe representing the request. The cqe flag will have
> +  IORING_CQE_F_BUFFER set if a selected buffer was used for the payload. The
> +  buffer id is stashed in cqe->flags (through IORING_CQE_BUFFER_SHIFT). The
> +  server can directly access the payload by using that buffer id to calculate
> +  the offset into the virtual address obtained for the buffers.
> +* The server processes the request and then sends a
> +  FUSE_URING_CMD_COMMIT_AND_FETCH sqe with the reply.
> +* When the kernel handles the sqe, it will process the reply and if there is a
> +  next request, it will reuse the same selected buffer for the request. If
> +  there is no next request, it will recycle the buffer back to the ring.
> +
> +Zero-copy
> +=========
> +
> +Fuse io-uring zero-copy allows the server to directly read from / write to the
> +client's pages and bypass any intermediary buffer copies. This is only allowed
> +on privileged servers.
> +
> +In order to use zero-copy, the server must pregister the following:
> +
> +* a sparse buffer for every entry in the queue. This is where the client's
> +  pages will reside
> +* a fixed buffer at index queue_depth (tailing the sparse buffer).
> +  This is where the headers will reside
> +* a kernel-managed buffer ring. This is where any non-zero-copied payload (eg
> +  out headers) will reside
> +
> +When the client issues a read/write, fuse stores the client's underlying pages
> +in the sparse buffer entry corresponding to the ent in the queue. The server
> +can then issue reads/writes on these pages through io_uring rw operations.
> +Please note that the server is not able to directly access these pages, it
> +must go through the io-uring interface to read/write to them. The pages are
> +unregistered once the server replies to the request. Non-zero-copyable
> +payload (if needed) is placed in a buffer from the kernel-managed buffer ring.