docs: Update vfio-user spec to describe DMA access mode bits
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> Link: https://lore.kernel.org/qemu-devel/20260602133829.305842-1-mnissler@meta.com Signed-off-by: Cédric Le Goater <clg@redhat.com>
Mattias Nissler committed
Jun 2, 2026 at 06:38 UTC
e7625ee53fe21a0c5bbef7be9acf7d0c7fbd9ade
1 file changed
+51
-31
docs/interop/vfio-user.rst
+51
-31
@@ -604,27 +604,31 @@ Request
604
605
The request payload for this message is a structure of the following format:
606
607
-+-------------+--------+-------------+
608
-| Name | Offset | Size |
609
-+=============+========+=============+
610
-| argsz | 0 | 4 |
611
-+-------------+--------+-------------+
612
-| flags | 4 | 4 |
613
-+-------------+--------+-------------+
614
-| | +-----+------------+ |
615
-| | | Bit | Definition | |
616
-| | +=====+============+ |
617
-| | | 0 | readable | |
618
-| | +-----+------------+ |
619
-| | | 1 | writeable | |
620
-| | +-----+------------+ |
621
-+-------------+--------+-------------+
622
-| offset | 8 | 8 |
623
-+-------------+--------+-------------+
624
-| address | 16 | 8 |
625
-+-------------+--------+-------------+
626
-| size | 24 | 8 |
627
-+-------------+--------+-------------+
607
++-------------+--------+------------------------+
608
+| Name | Offset | Size |
609
++=============+========+========================+
610
+| argsz | 0 | 4 |
611
++-------------+--------+------------------------+
612
+| flags | 4 | 4 |
613
++-------------+--------+------------------------+
614
+| | +-----+-----------------------+ |
615
+| | | Bit | Definition | |
616
+| | +=====+=======================+ |
617
+| | | 0 | readable | |
618
+| | +-----+-----------------------+ |
619
+| | | 1 | writeable | |
620
+| | +-----+-----------------------+ |
621
+| | | 2 | access mode: mmap | |
622
+| | +-----+-----------------------+ |
623
+| | | 3 | access mode: file I/O | |
624
+| | +-----+-----------------------+ |
625
++-------------+--------+------------------------+
626
+| offset | 8 | 8 |
627
++-------------+--------+------------------------+
628
+| address | 16 | 8 |
629
++-------------+--------+------------------------+
630
+| size | 24 | 8 |
631
++-------------+--------+------------------------+
632
633
* *argsz* is the size of the above structure. Note there is no reply payload,
634
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:
638
639
* *writeable* indicates that the region can be written to.
640
641
+ * *access mode* bits indicate how the region is to be accessed by the server.
642
+
643
* *offset* is the file offset of the region with respect to the associated file
644
descriptor, or zero if the region is not mappable
645
* *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:
647
648
This structure is 32 bytes in size, so the message size is 16 + 32 bytes.
649
644
-If the DMA region being added can be directly mapped by the server, a file
645
-descriptor must be sent as part of the message meta-data. The region can be
646
-mapped via the mmap() system call. On ``AF_UNIX`` sockets, the file descriptor
647
-must be passed as ``SCM_RIGHTS`` type ancillary data. Otherwise, if the DMA
648
-region cannot be directly mapped by the server, no file descriptor must be sent
649
-as part of the message meta-data and the DMA region can be accessed by the
650
-server using ``VFIO_USER_DMA_READ`` and ``VFIO_USER_DMA_WRITE`` messages,
651
-explained in `Read and Write Operations`_. A command to map over an existing
652
-region must be failed by the server with ``EEXIST`` set in error field in the
653
-reply.
650
+There are several alternative access modes for the server to use when accessing
651
+the region:
652
+
653
+* ``VFIO_USER_DMA_READ`` and ``VFIO_USER_DMA_WRITE`` messages, explained in
654
+ `Read and Write Operations`_.
655
+
656
+* ``mmap()`` a client-provided file descriptor, then perform direct accesses to
657
+ the underlying memory.
658
+
659
+* File I/O system calls (such as ``pread()`` / ``pwrite()``) against a
660
+ client-provided file descriptor.
661
+
662
+The access mode bits in the flags field indicate which access mode to use. If
663
+an access mode requiring a file descriptor is specified, but the client does
664
+not provide a file descriptor, the server must fail the request with
665
+``EINVAL``. If no access mode flag bit is set, the server should use ``mmap()``
666
+based access if the client provided a file descriptor and message-based access
667
+otherwise.
668
+
669
+On ``AF_UNIX`` sockets, the file descriptor must be passed as ``SCM_RIGHTS``
670
+type ancillary data.
671
+
672
+A command to map over an existing region must be failed by the server with
673
+``EEXIST`` set in the error field in the reply.
674
675
Reply
676
^^^^^