From ad88ffd9acdf4deec83cb3f5fdae4fd62ec30efe Mon Sep 17 00:00:00 2001 From: Thanos Makatos Date: Fri, 28 May 2021 15:43:33 +0100 Subject: restore argsz for DMA map/unmap (#523) use DMA map/unmap format similar to VFIO's Using a DMA map/unmap format similar to VFIO's (vfio_iommu_type1_dma_map / vfio_iommu_type1_dma_unmap) makes it easier to adapt to future changes. Consequently we also honor the passed argsz. Signed-off-by: Thanos Makatos Reviewed-by: John Levon --- docs/vfio-user.rst | 145 +++++++++++++++++++++++++++-------------------------- 1 file changed, 75 insertions(+), 70 deletions(-) (limited to 'docs/vfio-user.rst') diff --git a/docs/vfio-user.rst b/docs/vfio-user.rst index b5825d8..57d689b 100644 --- a/docs/vfio-user.rst +++ b/docs/vfio-user.rst @@ -531,40 +531,49 @@ or if the client uses a vIOMMU. Request ^^^^^^^ -The request payload for this message is an entry of the following format: +The request payload for this message is a structure of the following format: +-------------+--------+-------------+ | Name | Offset | Size | +=============+========+=============+ -| Address | 0 | 8 | +| argsz | 0 | 4 | +-------------+--------+-------------+ -| Size | 8 | 8 | -+-------------+--------+-------------+ -| Offset | 16 | 8 | -+-------------+--------+-------------+ -| Protections | 24 | 4 | -+-------------+--------+-------------+ -| Flags | 28 | 4 | +| flags | 4 | 4 | +-------------+--------+-------------+ | | +-----+------------+ | | | | Bit | Definition | | | | +=====+============+ | -| | | 0 | Mappable | | +| | | 0 | readable | | | | +-----+------------+ | +| | | 1 | writeable | | +| | +-----+------------+ | +| | | 2 | mappable | | +| | +-----+------------+ | ++-------------+--------+-------------+ +| offset | 8 | 8 | ++-------------+--------+-------------+ +| address | 16 | 8 | ++-------------+--------+-------------+ +| size | 24 | 8 | +-------------+--------+-------------+ -* *Address* is the base DMA address of the region. -* *Size* is the size of the region. -* *Offset* is the file offset of the region with respect to the associated file - descriptor, or zero if the region is not mappable -* *Protections* are the region's protection attributes as encoded in - ````; only ``PROT_READ`` and ``PROT_WRITE`` are supported -* *Flags* contains the following region attributes: +* *argsz* is the size of the above structure. Note there is no reply payload, + so this field differs from other message types. +* *flags* contains the following region attributes: - * *Mappable* indicates that the region can be mapped via the mmap() system + * *readable* indicates that the region can be read from. + + * *writeable* indicates that the region can be written to. + + * *mappable* indicates that the region can be mapped via the mmap() system call using the file descriptor provided in the message meta-data. -This structure is 32 bytes in size, so the message size is 16 + 32 == 48 bytes. +* *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. +* *size* is the size of the region. + +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. On ``AF_UNIX`` @@ -592,44 +601,45 @@ described by the following structure: Request ^^^^^^^ -The request payload for this message is an entry of the following format: - -+--------------+--------+---------------------------------------+ -| Name | Offset | Size | -+==============+========+=======================================+ -| Address | 0 | 8 | -+--------------+--------+---------------------------------------+ -| Size | 8 | 8 | -+--------------+--------+---------------------------------------+ -| Offset | 16 | 8 | -+--------------+--------+---------------------------------------+ -| Protections | 24 | 4 | -+--------------+--------+---------------------------------------+ -| Flags | 28 | 4 | -+--------------+--------+---------------------------------------+ -| | +-----+--------------------------------------+ | -| | | Bit | Definition | | -| | +=====+======================================+ | -| | | 0 | VFIO_DMA_UNMAP_FLAG_GET_DIRTY_BITMAP | | -| | +-----+--------------------------------------+ | -+--------------+--------+---------------------------------------+ - -* *Address* is the base DMA address of the DMA region. -* *Size* is the size of the DMA region. -* *Offset* must be zero (ignored) -* *Protections* must be zero (ignored) -* *Flags* contains the following DMA region attributes: - - * ``VFIO_DMA_UNMAP_FLAG_GET_DIRTY_BITMAP`` indicates that a dirty page bitmap - must be populated before unmapping the DMA region. The client must provide - a ``struct vfio_user_bitmap`` immediately following this table entry. - -If ``VFIO_DMA_UNMAP_FLAG_GET_DIRTY_BITMAP`` is set in Flags, the size of the -total request message is: 16 + 32 + 16. -Otherwise, if ``VFIO_DMA_UNMAP_FLAG_GET_DIRTY_BITMAP`` is not set in Flags, the -size of the total request message is: 16 + 32. - -.. _VFIO bitmap format: +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 | get dirty page bitmap | | +| | +-----+-----------------------+ | ++--------------+--------+------------------------+ +| address | 8 | 8 | ++--------------+--------+------------------------+ +| size | 16 | 8 | ++--------------+--------+------------------------+ + +* *argsz* is the maximum size of the reply payload. +* *flags* contains the following DMA region attributes: + + * *get dirty page bitmap* indicates that a dirty page bitmap must be + populated before unmapping the DMA region. The client must provide a + `VFIO bitmap`_ structure, explained below, immediately following this + entry. + +* *address* is the base DMA address of the DMA region. +* *size* is the size of the DMA region. + +The size of request message depends on whether or not the +*get dirty page bitmap* bit is set in Flags: + +* If not set, the size of the total request message is: 16 + 24. + +* If set, the size of the total request message is: 16 + 24 + 16. + +.. _VFIO bitmap: VFIO bitmap format """""""""""""""""" @@ -653,18 +663,14 @@ mapped then the server must release all references to that DMA region before replying, which potentially includes in-flight DMA transactions. Removing a portion of a DMA region is possible. -The payload depends on whether or not ``VFIO_DMA_UNMAP_FLAG_GET_DIRTY_BITMAP`` -is set in Flags in the request: - -* ``VFIO_DMA_UNMAP_FLAG_GET_DIRTY_BITMAP`` is set in Flags in the request: - The server responds with a payload that contains the original - ``struct vfio_user_bitmap`` sent in the request, followed by the - corresponding dirty page bitmap, where each bit represents one page of size - ``struct vfio_user_bitmap.pgsize``. The size of the total reply message is: - 16 + 16 + size of dirty page bitmap. +The server responds with the original DMA entry in the request. If the +*get dirty page bitmap* bit is set in flags in the request, then +the server also includes the `VFIO bitmap`_ structure sent in the request, +followed by the corresponding dirty page bitmap, where each bit represents +one page of size *pgsize* in `VFIO bitmap`_ . -* ``VFIO_DMA_UNMAP_FLAG_GET_DIRTY_BITMAP`` is not set in Flags in the request: - There is no payload. The size of the reply message is: 16. +The total size of the total reply message is: +16 + 24 + (16 + *size* in `VFIO bitmap`_ if *get dirty page bitmap* is set). ``VFIO_USER_DEVICE_GET_INFO`` ----------------------------- @@ -1542,8 +1548,7 @@ VFIO Dirty Bitmap Get Format * *size* is the size of the IOVA region -* *bitmap* is the VFIO bitmap (``struct vfio_bitmap``). This field is explained - in `VFIO bitmap format`_. +* *bitmap* is the VFIO bitmap explained in `VFIO bitmap`_. Reply ^^^^^ -- cgit v1.1