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>
---
 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
+  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

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
>