vhost_user.rst: Add SHMEM_MAP/_UNMAP to spec
Add SHMEM_MAP/_UNMAP request to the vhost-user spec documentation. Reviewed-by: Stefano Garzarella <sgarzare@redhat.com> Reviewed-by: Alyssa Ross <hi@alyssa.is> Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com> Reviewed-by: Manos Pitsidianakis <manos.pitsidianakis@linaro.org> Signed-off-by: Albert Esteve <aesteve@redhat.com> Reviewed-by: Michael S. Tsirkin <mst@redhat.com> Signed-off-by: Michael S. Tsirkin <mst@redhat.com> Message-Id: <20260304165223.2166175-4-aesteve@redhat.com>
Albert Esteve committed
Mar 4, 2026 at 17:52 UTC
588acb45c29f8c30f98b5cbafb9fd09cb932bd88
1 file changed
+64
docs/interop/vhost-user.rst
+64
@@ -362,6 +362,28 @@ Device state transfer parameters
362
In the future, additional phases might be added e.g. to allow
363
iterative migration while the device is running.
364
365
+MMAP request
366
+^^^^^^^^^^^^
367
+
368
++-------+---------+-----------+------------+-----+-------+
369
+| shmid | padding | fd_offset | shm_offset | len | flags |
370
++-------+---------+-----------+------------+-----+-------+
371
+
372
+:shmid: a 8-bit shared memory region identifier
373
+
374
+:fd_offset: a 64-bit offset of this area from the start
375
+ of the supplied file descriptor
376
+
377
+:shm_offset: a 64-bit offset from the start of the
378
+ pointed shared memory region
379
+
380
+:len: a 64-bit size of the memory to map
381
+
382
+:flags: a 64-bit value:
383
+
384
+ - 0: Pages are mapped read-only
385
+ - 1: Pages are mapped read-write
386
+
387
C structure
388
-----------
389
@@ -387,6 +409,7 @@ In QEMU the vhost-user message is implemented with the following struct:
409
VhostUserInflight inflight;
410
VhostUserShared object;
411
VhostUserTransferDeviceState transfer_state;
412
+ VhostUserMMap mmap;
413
};
414
} QEMU_PACKED VhostUserMsg;
415
@@ -1083,6 +1106,7 @@ Protocol features
1106
#define VHOST_USER_PROTOCOL_F_DEVICE_STATE 19
1107
#define VHOST_USER_PROTOCOL_F_GET_VRING_BASE_INFLIGHT 20
1108
#define VHOST_USER_PROTOCOL_F_GPA_ADDRESSES 21
1109
+ #define VHOST_USER_PROTOCOL_F_SHMEM_MAP 22
1110
1111
Front-end message types
1112
-----------------------
@@ -1904,6 +1928,46 @@ is sent by the front-end.
1928
when the operation is successful, or non-zero otherwise. Note that if the
1929
operation fails, no fd is sent to the backend.
1930
1931
+``VHOST_USER_BACKEND_SHMEM_MAP``
1932
+ :id: 9
1933
+ :equivalent ioctl: N/A
1934
+ :request payload: fd and ``struct VhostUserMMap``
1935
+ :reply payload: N/A
1936
+
1937
+ When the ``VHOST_USER_PROTOCOL_F_SHMEM`` protocol feature has been
1938
+ successfully negotiated, this message can be submitted by the backends to
1939
+ advertise a new mapping to be made in a given VIRTIO Shared Memory Region.
1940
+ Upon receiving the message, the front-end will mmap the given fd into the
1941
+ VIRTIO Shared Memory Region with the requested ``shmid``.
1942
+
1943
+ If ``VHOST_USER_PROTOCOL_F_REPLY_ACK`` is negotiated, and
1944
+ back-end set the ``VHOST_USER_NEED_REPLY`` flag, the front-end
1945
+ must respond with zero when operation is successfully completed,
1946
+ or non-zero otherwise.
1947
+
1948
+ Mapping over an already existing map is not allowed and requests shall fail.
1949
+ Therefore, the memory range in the request must correspond with a valid,
1950
+ free region of the VIRTIO Shared Memory Region. Also, note that mappings
1951
+ consume resources and that the request can fail when there are no resources
1952
+ available. Lastly, mappings are automatically unmapped by the front-end
1953
+ across device reset operation.
1954
+
1955
+``VHOST_USER_BACKEND_SHMEM_UNMAP``
1956
+ :id: 10
1957
+ :equivalent ioctl: N/A
1958
+ :request payload: ``struct VhostUserMMap``
1959
+ :reply payload: N/A
1960
+
1961
+ When the ``VHOST_USER_PROTOCOL_F_SHMEM`` protocol feature has been
1962
+ successfully negotiated, this message can be submitted by the backends so
1963
+ that the front-end un-mmaps a given range (``shm_offset``, ``len``) in the
1964
+ VIRTIO Shared Memory Region with the requested ``shmid``. Note that the
1965
+ given range shall correspond to the entirety of a valid mapped region.
1966
+
1967
+ If ``VHOST_USER_PROTOCOL_F_REPLY_ACK`` is negotiated, and the back-end
1968
+ sets the ``VHOST_USER_NEED_REPLY`` flag, the front-end must respond with
1969
+ zero when operation is successfully completed, or non-zero otherwise.
1970
+
1971
.. _reply_ack:
1972
1973
VHOST_USER_PROTOCOL_F_REPLY_ACK