Re: [PATCH v9 3/7] vhost_user.rst: Add SHMEM_MAP/_UNMAP to spec

[Manos Pitsidianakis <manos.pitsidianakis@linaro.org>]

On Wed, 15 Oct 2025 11:59, Albert Esteve <aesteve@redhat.com> wrote:
>Add SHMEM_MAP/_UNMAP request to the vhost-user
>spec documentation.
>
>Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>
>Signed-off-by: Albert Esteve <aesteve@redhat.com>
>---

I found a minor typo (response inline) but otherwise LGTM

Reviewed-by: Manos Pitsidianakis <manos.pitsidianakis@linaro.org>

> docs/interop/vhost-user.rst | 58 +++++++++++++++++++++++++++++++++++++
> 1 file changed, 58 insertions(+)
>
>diff --git a/docs/interop/vhost-user.rst b/docs/interop/vhost-user.rst
>index 436a94c0ee..dab9f3af42 100644
>--- a/docs/interop/vhost-user.rst
>+++ b/docs/interop/vhost-user.rst
>@@ -350,6 +350,27 @@ Device state transfer parameters
>   In the future, additional phases might be added e.g. to allow
>   iterative migration while the device is running.
> 
>+MMAP request
>+^^^^^^^^^^^^
>+
>++-------+---------+-----------+------------+-----+-------+
>+| shmid | padding | fd_offset | shm_offset | len | flags |
>++-------+---------+-----------+------------+-----+-------+
>+
>+:shmid: a 8-bit shared memory region identifier
>+
>+:fd_offset: a 64-bit offset of this area from the start
>+            of the supplied file descriptor
>+
>+:shm_offset: a 64-bit offset from the start of the
>+             pointed shared memory region
>+
>+:len: a 64-bit size of the memory to map
>+
>+:flags: a 64-bit value:
>+  - 0: Pages are mapped read-only
>+  - 1: Pages are mapped read-write
>+
> C structure
> -----------
> 
>@@ -375,6 +396,7 @@ In QEMU the vhost-user message is implemented with the following struct:
>           VhostUserInflight inflight;
>           VhostUserShared object;
>           VhostUserTransferDeviceState transfer_state;
>+          VhostUserMMap mmap;
>       };
>   } QEMU_PACKED VhostUserMsg;
> 
>@@ -1057,6 +1079,7 @@ Protocol features
>   #define VHOST_USER_PROTOCOL_F_XEN_MMAP             17
>   #define VHOST_USER_PROTOCOL_F_SHARED_OBJECT        18
>   #define VHOST_USER_PROTOCOL_F_DEVICE_STATE         19
>+  #define VHOST_USER_PROTOCOL_F_SHMEM                20
> 
> Front-end message types
> -----------------------
>@@ -1865,6 +1888,41 @@ is sent by the front-end.
>   when the operation is successful, or non-zero otherwise. Note that if the
>   operation fails, no fd is sent to the backend.
> 
>+``VHOST_USER_BACKEND_SHMEM_MAP``
>+  :id: 9
>+  :equivalent ioctl: N/A
>+  :request payload: fd and ``struct VhostUserMMap``
>+  :reply payload: N/A
>+
>+  When the ``VHOST_USER_PROTOCOL_F_SHMEM`` protocol feature has been
>+  successfully negotiated, this message can be submitted by the backends to
>+  advertise a new mapping to be made in a given VIRTIO Shared Memory Region.
>+  Upon receiving the message, the front-end will mmap the given fd into the
>+  VIRTIO Shared Memory Region with the requested ``shmid``.
>+  If``VHOST_USER_PROTOCOL_F_REPLY_ACK`` is negotiated, and

Space missing after initial "If"

>+  back-end set the ``VHOST_USER_NEED_REPLY`` flag, the front-end
>+  must respond with zero when operation is successfully completed,
>+  or non-zero otherwise.
>+
>+  Mapping over an already existing map is not allowed and requests shall fail.
>+  Therefore, the memory range in the request must correspond with a valid,
>+  free region of the VIRTIO Shared Memory Region. Also, note that mappings
>+  consume resources and that the request can fail when there are no 
>resources
>+  available.
>+
>+``VHOST_USER_BACKEND_SHMEM_UNMAP``
>+  :id: 10
>+  :equivalent ioctl: N/A
>+  :request payload: ``struct VhostUserMMap``
>+  :reply payload: N/A
>+
>+  When the ``VHOST_USER_PROTOCOL_F_SHMEM`` protocol feature has been
>+  successfully negotiated, this message can be submitted by the backends so
>+  that the front-end un-mmaps a given range (``shm_offset``, ``len``) in the
>+  VIRTIO Shared Memory Region with the requested ``shmid``. Note that the
>+  given range shall correspond to the entirety of a valid mapped region.
>+  A reply is generated indicating whether unmapping succeeded.
>+
> .. _reply_ack:
> 
> VHOST_USER_PROTOCOL_F_REPLY_ACK
>-- 
>2.49.0
>