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

["Cédric Le Goater" <clg@redhat.com>]

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.