Add SHMEM_MAP/_UNMAP request to the vhost-user
spec documentation.
Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>
Reviewed-by: Manos Pitsidianakis <manos.pitsidianakis@linaro.org>
Signed-off-by: Albert Esteve <aesteve@redhat.com>
---
docs/interop/vhost-user.rst | 61 +++++++++++++++++++++++++++++++++++++
1 file changed, 61 insertions(+)
diff --git a/docs/interop/vhost-user.rst b/docs/interop/vhost-user.rst
index 17a68a62eb..ae4ad6f441 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;
@@ -1064,6 +1086,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
-----------------------
@@ -1872,6 +1895,44 @@ 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. Lastly, mappings are automatically unmapped by the front-end
+ across device reset operation.
+
+``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.
+ If ``VHOST_USER_PROTOCOL_F_REPLY_ACK`` is negotiated, and the back-end
+ sets the ``VHOST_USER_NEED_REPLY`` flag, the front-end must respond with
+ zero when operation is successfully completed, or non-zero otherwise.
+
.. _reply_ack:
VHOST_USER_PROTOCOL_F_REPLY_ACK
--
2.52.0On Thu, Feb 19, 2026 at 2:04 PM Albert Esteve <aesteve@redhat.com> wrote: > > Add SHMEM_MAP/_UNMAP request to the vhost-user > spec documentation. > > Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com> > Reviewed-by: Manos Pitsidianakis <manos.pitsidianakis@linaro.org> > Signed-off-by: Albert Esteve <aesteve@redhat.com> > --- > docs/interop/vhost-user.rst | 61 +++++++++++++++++++++++++++++++++++++ > 1 file changed, 61 insertions(+) > > diff --git a/docs/interop/vhost-user.rst b/docs/interop/vhost-user.rst > index 17a68a62eb..ae4ad6f441 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; > > @@ -1064,6 +1086,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 Commit cda83adc62b6108afc8a82d0f54d9a9a861e7aa8 got upstream first and took feature number 20, so this should be 21 now. @Michael Tsirkin Is it worth sending a new version or will you handle the change? > > Front-end message types > ----------------------- > @@ -1872,6 +1895,44 @@ 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. Lastly, mappings are automatically unmapped by the front-end > + across device reset operation. > + > +``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. > + If ``VHOST_USER_PROTOCOL_F_REPLY_ACK`` is negotiated, and the back-end > + sets the ``VHOST_USER_NEED_REPLY`` flag, the front-end must respond with > + zero when operation is successfully completed, or non-zero otherwise. > + > .. _reply_ack: > > VHOST_USER_PROTOCOL_F_REPLY_ACK > -- > 2.52.0 > >
On Wed, Mar 4, 2026 at 10:46 AM Albert Esteve <aesteve@redhat.com> wrote: > > On Thu, Feb 19, 2026 at 2:04 PM Albert Esteve <aesteve@redhat.com> wrote: > > > > Add SHMEM_MAP/_UNMAP request to the vhost-user > > spec documentation. > > > > Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com> > > Reviewed-by: Manos Pitsidianakis <manos.pitsidianakis@linaro.org> > > Signed-off-by: Albert Esteve <aesteve@redhat.com> > > --- > > docs/interop/vhost-user.rst | 61 +++++++++++++++++++++++++++++++++++++ > > 1 file changed, 61 insertions(+) > > > > diff --git a/docs/interop/vhost-user.rst b/docs/interop/vhost-user.rst > > index 17a68a62eb..ae4ad6f441 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; > > > > @@ -1064,6 +1086,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 > > Commit cda83adc62b6108afc8a82d0f54d9a9a861e7aa8 got upstream first and > took feature number 20, so this should be 21 now. > > @Michael Tsirkin Is it worth sending a new version or will you handle > the change? Sorry, I meant e0822e6085aecc15e2cfb2914d8cd827abae0249 (vhost-user: introduce protocol feature for skip drain on GET_VRING_BASE). But the question remains. > > > > > Front-end message types > > ----------------------- > > @@ -1872,6 +1895,44 @@ 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. Lastly, mappings are automatically unmapped by the front-end > > + across device reset operation. > > + > > +``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. > > + If ``VHOST_USER_PROTOCOL_F_REPLY_ACK`` is negotiated, and the back-end > > + sets the ``VHOST_USER_NEED_REPLY`` flag, the front-end must respond with > > + zero when operation is successfully completed, or non-zero otherwise. > > + > > .. _reply_ack: > > > > VHOST_USER_PROTOCOL_F_REPLY_ACK > > -- > > 2.52.0 > > > >
On Wed, Mar 04, 2026 at 11:23:42AM +0100, Albert Esteve wrote: >On Wed, Mar 4, 2026 at 10:46 AM Albert Esteve <aesteve@redhat.com> wrote: >> >> On Thu, Feb 19, 2026 at 2:04 PM Albert Esteve <aesteve@redhat.com> wrote: >> > >> > Add SHMEM_MAP/_UNMAP request to the vhost-user >> > spec documentation. >> > >> > Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com> >> > Reviewed-by: Manos Pitsidianakis <manos.pitsidianakis@linaro.org> >> > Signed-off-by: Albert Esteve <aesteve@redhat.com> >> > --- >> > docs/interop/vhost-user.rst | 61 +++++++++++++++++++++++++++++++++++++ >> > 1 file changed, 61 insertions(+) >> > >> > diff --git a/docs/interop/vhost-user.rst b/docs/interop/vhost-user.rst >> > index 17a68a62eb..ae4ad6f441 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; >> > >> > @@ -1064,6 +1086,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 >> >> Commit cda83adc62b6108afc8a82d0f54d9a9a861e7aa8 got upstream first and >> took feature number 20, so this should be 21 now. >> >> @Michael Tsirkin Is it worth sending a new version or will you handle >> the change? > >Sorry, I meant e0822e6085aecc15e2cfb2914d8cd827abae0249 (vhost-user: >introduce protocol feature for skip drain on GET_VRING_BASE). > >But the question remains. Maybe better to rebase to simplify Michael's life. BTW this pach LGTM: Reviewed-by: Stefano Garzarella <sgarzare@redhat.com>
Albert Esteve <aesteve@redhat.com> writes: > Add SHMEM_MAP/_UNMAP request to the vhost-user > spec documentation. > > Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com> > Reviewed-by: Manos Pitsidianakis <manos.pitsidianakis@linaro.org> > Signed-off-by: Albert Esteve <aesteve@redhat.com> > --- > docs/interop/vhost-user.rst | 61 +++++++++++++++++++++++++++++++++++++ > 1 file changed, 61 insertions(+) Reviewed-by: Alyssa Ross <hi@alyssa.is>
© 2016 - 2026 Red Hat, Inc.