On Thu, Jan 15, 2026 at 1:10 PM Alyssa Ross <[email protected]> wrote: > > Albert Esteve <[email protected]> writes: > > > Add SHMEM_MAP/_UNMAP request to the vhost-user > > spec documentation. > > > > Reviewed-by: Stefan Hajnoczi <[email protected]> > > Reviewed-by: Manos Pitsidianakis <[email protected]> > > Signed-off-by: Albert Esteve <[email protected]> > > --- > > docs/interop/vhost-user.rst | 59 +++++++++++++++++++++++++++++++++++++ > > 1 file changed, 59 insertions(+) > > > > diff --git a/docs/interop/vhost-user.rst b/docs/interop/vhost-user.rst > > index 17a68a62eb..6c1d66d7d3 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,42 @@ 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. > > Having now tried to implement this, I'm wondering whether replies should > be mandatory, even without VHOST_USER_PROTOCOL_F_REPLY_ACK, like they > are for some other messages. Without waiting for a reply, a backend > doesn't know when it can tell the driver to start using the mapped > memory, so I'm not sure there's ever a case in which a backend would not > want to wait for a reply after sending VHOST_USER_BACKEND_SHMEM_MAP, > even if it doesn't wait habitually wait for replies for other messages. > (crosvm is like this — its backends don't negotiate > VHOST_USER_PROTOCOL_F_REPLY_ACK, and their non-standard map/unmap > requests had mandatory replies.)
What you say makes sense to me. Every test I run for this, I used the flag, because it was required to work correctly. Nonetheless, I assumed giving flexibility may be better in case there are backends that will not be accessing the mapped memory right away and prefer to save the response. Also, previous implementation in QEMU always checked VHOST_USER_PROTOCOL_F_REPLY_ACK before sending a response. Which made me think this was the norm. I could relax that requirement in a v12, given this patch is still pending to merge (and update the implementation accordingly). > > > + 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. > > + A reply is generated indicating whether unmapping succeeded. > > + > > .. _reply_ack: > > > > VHOST_USER_PROTOCOL_F_REPLY_ACK > > -- > > 2.49.0
