From: Ming Lei Date: Thu, 9 Apr 2026 13:30:18 +0000 (+0800) Subject: Documentation: ublk: address review comments for SHMEM_ZC docs X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=289653bb76c46149f88939c3cfef55cdb236ace2;p=thirdparty%2Flinux.git Documentation: ublk: address review comments for SHMEM_ZC docs - Use "physical pages" instead of "page frame numbers (PFNs)" for clarity - Remove "without any per-I/O overhead" claim from zero-copy description - Add scatter/gather limitation: each I/O's data must be contiguous within a single registered buffer Suggested-by: Caleb Sander Mateos Signed-off-by: Ming Lei Link: https://patch.msgid.link/20260409133020.3780098-7-tom.leiming@gmail.com Signed-off-by: Jens Axboe --- diff --git a/Documentation/block/ublk.rst b/Documentation/block/ublk.rst index e80cc415a7396..0413dcd9ef69d 100644 --- a/Documentation/block/ublk.rst +++ b/Documentation/block/ublk.rst @@ -492,8 +492,8 @@ 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 page frame numbers -(PFNs) at I/O time. This allows the ublk server to access the shared +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. @@ -507,8 +507,7 @@ 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 without any per-I/O -overhead. +shared memory, the entire data path becomes zero-copy. Use Cases ~~~~~~~~~ @@ -584,6 +583,9 @@ Limitations the page cache, which allocates its own pages. These kernel-allocated pages will never match the registered shared buffer. Only ``O_DIRECT`` puts the client's buffer pages directly into the block I/O. +- **Contiguous data only**: each I/O request's data must be contiguous + within a single registered buffer. Scatter/gather I/O that spans + multiple non-adjacent registered buffers cannot use the zero-copy path. Control Commands ~~~~~~~~~~~~~~~~