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.) > + 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
signature.asc
Description: PGP signature
