1. Patchew
  2. QEMU
  3. View series

[PATCH] docs: Update vfio-user spec to describe DMA access mode bits

Mattias Nissler posted 1 patch 1 month, 2 weeks ago
Patches applied successfully (tree, apply log)
git fetch https://github.com/patchew-project/qemu tags/patchew/20260602133829.305842-1-mnissler@meta.com
Maintainers: John Levon <john.levon@nutanix.com>, Thanos Makatos <thanos.makatos@nutanix.com>, "Cédric Le Goater" <clg@redhat.com>, Pierrick Bouvier <pierrick.bouvier@oss.qualcomm.com>
docs/interop/vfio-user.rst | 82 ++++++++++++++++++++++++--------------
1 file changed, 51 insertions(+), 31 deletions(-)
[PATCH] docs: Update vfio-user spec to describe DMA access mode bits
Posted by Mattias Nissler 1 month, 2 weeks ago 
This makes the intended access mode explicit when registering DMA
regions with the server. A new "file I/O" access mode is defined, which
can be used if the file descriptor provided by the client doesn't
support `mmap()`.

Signed-off-by: Mattias Nissler <mnissler@meta.com>
---
 docs/interop/vfio-user.rst | 82 ++++++++++++++++++++++++--------------
 1 file changed, 51 insertions(+), 31 deletions(-)

diff --git a/docs/interop/vfio-user.rst b/docs/interop/vfio-user.rst
index 12deb25102..1c92f442d2 100644
--- a/docs/interop/vfio-user.rst
+++ b/docs/interop/vfio-user.rst
@@ -604,27 +604,31 @@ Request
 
 The request payload for this message is a structure of the following format:
 
-+-------------+--------+-------------+
-| Name        | Offset | Size        |
-+=============+========+=============+
-| argsz       | 0      | 4           |
-+-------------+--------+-------------+
-| flags       | 4      | 4           |
-+-------------+--------+-------------+
-|             | +-----+------------+ |
-|             | | Bit | Definition | |
-|             | +=====+============+ |
-|             | | 0   | readable   | |
-|             | +-----+------------+ |
-|             | | 1   | writeable  | |
-|             | +-----+------------+ |
-+-------------+--------+-------------+
-| offset      | 8      | 8           |
-+-------------+--------+-------------+
-| address     | 16     | 8           |
-+-------------+--------+-------------+
-| size        | 24     | 8           |
-+-------------+--------+-------------+
++-------------+--------+------------------------+
+| Name        | Offset | Size                   |
++=============+========+========================+
+| argsz       | 0      | 4                      |
++-------------+--------+------------------------+
+| flags       | 4      | 4                      |
++-------------+--------+------------------------+
+|             | +-----+-----------------------+ |
+|             | | Bit | Definition            | |
+|             | +=====+=======================+ |
+|             | | 0   | readable              | |
+|             | +-----+-----------------------+ |
+|             | | 1   | writeable             | |
+|             | +-----+-----------------------+ |
+|             | | 2   | access mode: mmap     | |
+|             | +-----+-----------------------+ |
+|             | | 3   | access mode: file I/O | |
+|             | +-----+-----------------------+ |
++-------------+--------+------------------------+
+| offset      | 8      | 8                      |
++-------------+--------+------------------------+
+| address     | 16     | 8                      |
++-------------+--------+------------------------+
+| size        | 24     | 8                      |
++-------------+--------+------------------------+
 
 * *argsz* is the size of the above structure. Note there is no reply payload,
   so this field differs from other message types.
@@ -634,6 +638,8 @@ The request payload for this message is a structure of the following format:
 
   * *writeable* indicates that the region can be written to.
 
+  * *access mode* bits indicate how the region is to be accessed by the server.
+
 * *offset* is the file offset of the region with respect to the associated file
   descriptor, or zero if the region is not mappable
 * *address* is the base DMA address of the region.
@@ -641,16 +647,30 @@ The request payload for this message is a structure of the following format:
 
 This structure is 32 bytes in size, so the message size is 16 + 32 bytes.
 
-If the DMA region being added can be directly mapped by the server, a file
-descriptor must be sent as part of the message meta-data. The region can be
-mapped via the mmap() system call. On ``AF_UNIX`` sockets, the file descriptor
-must be passed as ``SCM_RIGHTS`` type ancillary data.  Otherwise, if the DMA
-region cannot be directly mapped by the server, no file descriptor must be sent
-as part of the message meta-data and the DMA region can be accessed by the
-server using ``VFIO_USER_DMA_READ`` and ``VFIO_USER_DMA_WRITE`` messages,
-explained in `Read and Write Operations`_. A command to map over an existing
-region must be failed by the server with ``EEXIST`` set in error field in the
-reply.
+There are several alternative access modes for the server to use when accessing
+the region:
+
+* ``VFIO_USER_DMA_READ`` and ``VFIO_USER_DMA_WRITE`` messages, explained in
+  `Read and Write Operations`_.
+
+* ``mmap()`` a client-provided file descriptor, then perform direct accesses to
+  the underlying memory.
+
+* File I/O system calls (such as ``pread()`` / ``pwrite()``) against a
+  client-provided file descriptor.
+
+The access mode bits in the flags field indicate which access mode to use. If
+an access mode requiring a file descriptor is specified, but the client does
+not provide a file descriptor, the server must fail the request with
+``EINVAL``. If no access mode flag bit is set, the server should use ``mmap()``
+based access if the client provided a file descriptor and message-based access
+otherwise.
+
+On ``AF_UNIX`` sockets, the file descriptor must be passed as ``SCM_RIGHTS``
+type ancillary data.
+
+A command to map over an existing region must be failed by the server with
+``EEXIST`` set in the error field in the reply.
 
 Reply
 ^^^^^
-- 
2.52.0
Re: [PATCH] docs: Update vfio-user spec to describe DMA access mode bits
Posted by Cédric Le Goater 3 weeks, 1 day ago 
On 6/2/26 15:38, Mattias Nissler wrote:
> This makes the intended access mode explicit when registering DMA
> regions with the server. A new "file I/O" access mode is defined, which
> can be used if the file descriptor provided by the client doesn't
> support `mmap()`.
> 
> Signed-off-by: Mattias Nissler <mnissler@meta.com>
> ---
>   docs/interop/vfio-user.rst | 82 ++++++++++++++++++++++++--------------
>   1 file changed, 51 insertions(+), 31 deletions(-)
> 
> diff --git a/docs/interop/vfio-user.rst b/docs/interop/vfio-user.rst
> index 12deb25102..1c92f442d2 100644
> --- a/docs/interop/vfio-user.rst
> +++ b/docs/interop/vfio-user.rst
> @@ -604,27 +604,31 @@ Request
>   
>   The request payload for this message is a structure of the following format:
>   
> -+-------------+--------+-------------+
> -| Name        | Offset | Size        |
> -+=============+========+=============+
> -| argsz       | 0      | 4           |
> -+-------------+--------+-------------+
> -| flags       | 4      | 4           |
> -+-------------+--------+-------------+
> -|             | +-----+------------+ |
> -|             | | Bit | Definition | |
> -|             | +=====+============+ |
> -|             | | 0   | readable   | |
> -|             | +-----+------------+ |
> -|             | | 1   | writeable  | |
> -|             | +-----+------------+ |
> -+-------------+--------+-------------+
> -| offset      | 8      | 8           |
> -+-------------+--------+-------------+
> -| address     | 16     | 8           |
> -+-------------+--------+-------------+
> -| size        | 24     | 8           |
> -+-------------+--------+-------------+
> ++-------------+--------+------------------------+
> +| Name        | Offset | Size                   |
> ++=============+========+========================+
> +| argsz       | 0      | 4                      |
> ++-------------+--------+------------------------+
> +| flags       | 4      | 4                      |
> ++-------------+--------+------------------------+
> +|             | +-----+-----------------------+ |
> +|             | | Bit | Definition            | |
> +|             | +=====+=======================+ |
> +|             | | 0   | readable              | |
> +|             | +-----+-----------------------+ |
> +|             | | 1   | writeable             | |
> +|             | +-----+-----------------------+ |
> +|             | | 2   | access mode: mmap     | |
> +|             | +-----+-----------------------+ |
> +|             | | 3   | access mode: file I/O | |
> +|             | +-----+-----------------------+ |
> ++-------------+--------+------------------------+
> +| offset      | 8      | 8                      |
> ++-------------+--------+------------------------+
> +| address     | 16     | 8                      |
> ++-------------+--------+------------------------+
> +| size        | 24     | 8                      |
> ++-------------+--------+------------------------+
>   
>   * *argsz* is the size of the above structure. Note there is no reply payload,
>     so this field differs from other message types.
> @@ -634,6 +638,8 @@ The request payload for this message is a structure of the following format:
>   
>     * *writeable* indicates that the region can be written to.
>   
> +  * *access mode* bits indicate how the region is to be accessed by the server.
> +
>   * *offset* is the file offset of the region with respect to the associated file
>     descriptor, or zero if the region is not mappable
>   * *address* is the base DMA address of the region.
> @@ -641,16 +647,30 @@ The request payload for this message is a structure of the following format:
>   
>   This structure is 32 bytes in size, so the message size is 16 + 32 bytes.
>   
> -If the DMA region being added can be directly mapped by the server, a file
> -descriptor must be sent as part of the message meta-data. The region can be
> -mapped via the mmap() system call. On ``AF_UNIX`` sockets, the file descriptor
> -must be passed as ``SCM_RIGHTS`` type ancillary data.  Otherwise, if the DMA
> -region cannot be directly mapped by the server, no file descriptor must be sent
> -as part of the message meta-data and the DMA region can be accessed by the
> -server using ``VFIO_USER_DMA_READ`` and ``VFIO_USER_DMA_WRITE`` messages,
> -explained in `Read and Write Operations`_. A command to map over an existing
> -region must be failed by the server with ``EEXIST`` set in error field in the
> -reply.
> +There are several alternative access modes for the server to use when accessing
> +the region:
> +
> +* ``VFIO_USER_DMA_READ`` and ``VFIO_USER_DMA_WRITE`` messages, explained in
> +  `Read and Write Operations`_.
> +
> +* ``mmap()`` a client-provided file descriptor, then perform direct accesses to
> +  the underlying memory.
> +
> +* File I/O system calls (such as ``pread()`` / ``pwrite()``) against a
> +  client-provided file descriptor.
> +
> +The access mode bits in the flags field indicate which access mode to use. If
> +an access mode requiring a file descriptor is specified, but the client does
> +not provide a file descriptor, the server must fail the request with
> +``EINVAL``. If no access mode flag bit is set, the server should use ``mmap()``
> +based access if the client provided a file descriptor and message-based access
> +otherwise.
> +
> +On ``AF_UNIX`` sockets, the file descriptor must be passed as ``SCM_RIGHTS``
> +type ancillary data.
> +
> +A command to map over an existing region must be failed by the server with
> +``EEXIST`` set in the error field in the reply.
>   
>   Reply
>   ^^^^^

Applied to

     https://github.com/legoater/qemu vfio-next

Thanks,

C.
Re: [PATCH] docs: Update vfio-user spec to describe DMA access mode bits
Posted by John Levon 1 month, 1 week ago 
On Tue, Jun 02, 2026 at 06:38:29AM -0700, Mattias Nissler wrote:

> This makes the intended access mode explicit when registering DMA
> regions with the server. A new "file I/O" access mode is defined, which
> can be used if the file descriptor provided by the client doesn't
> support `mmap()`.
> 
> Signed-off-by: Mattias Nissler <mnissler@meta.com>

Reviewed-by: John Levon <john.levon@nutanix.com>

regards
john

Patchew 2.1-devel-ea86937

© 2016 - 2026 Red Hat, Inc.