RE: [PATCH v6] introduce vfio-user protocol specification

[Thanos Makatos]

> +Version Data Format
> +^^^^^^^^^^^^^^^^^^^
> +
> +The version data is an optional JSON byte array with the following format:
> +
> ++--------------+------------------+-------------------------------------------+
> +| Name         | Type             | Description                              
>  |
> ++==============+==================+======================
> =====================+
> +| capabilities | collection of    | Contains common capabilities that the    
>  |
> +|              | name/value pairs | sender supports. Optional.               
>  |
> ++--------------+------------------+-------------------------------------------+
> +
> +Capabilities:
> +
> ++---------------+------------------+------------------------------------------+
> +| Name          | Type             | Description                             
>  |
> ++===============+==================+=====================
> =====================+
> +| ``max_fds``   | number           | Maximum number of file descriptors that 
>  |
> +|               |                  | can be received by the sender. 
> Optional. |
> +|               |                  | If not specified then the receiver must 
>  |
> +|               |                  | assume ``max_fds=1``.                   
>  |
> ++---------------+------------------+------------------------------------------+
> +| ``migration`` | collection of    | Migration capability parameters. If     
>  |
> +|               | name/value pairs | missing then migration is not supported 
>  |
> +|               |                  | by the sender.                          
>  |
> ++---------------+------------------+------------------------------------------+

Can we introduce the following parameters that can help simplify the
server implementation?

* max_dma_regions: maximum number of DMA regions per VFIO_USER_DMA_MAP/UNMAP
                   message
                                   
* max_dirty_bitmaps: maximum number of dirty bitmaps requested per
                     VFIO_USER_DIRTY_PAGES message
                                         
If these parameters are missing then they can be unlimited. The vfio-user client
will have to break a single operation into multiple messages.


> +VFIO_USER_DEVICE_GET_REGION_INFO
> +--------------------------------
> +
> +Message format
> +^^^^^^^^^^^^^^
> +
> ++--------------+------------------------+
> +| Name         | Value                  |
> ++==============+========================+
> +| Message ID   | <ID>                   |
> ++--------------+------------------------+
> +| Command      | 5                      |
> ++--------------+------------------------+
> +| Message size | 48 + any caps          |
> ++--------------+------------------------+
> +| Flags        | Reply bit set in reply |
> ++--------------+------------------------+
> +| Error        | 0/errno                |
> ++--------------+------------------------+
> +| Region info  | VFIO region info       |
> ++--------------+------------------------+
> +
> +This command message is sent by the client to the server to query for
> +information about device memory regions. The VFIO region info structure is
> +defined in ``<linux/vfio.h>`` (``struct vfio_region_info``). Since the client
> +does not know the size of the capabilities, the size of the reply it should
> +expect is 48 plus any capabilities whose size is indicated in the size field 
> of
> +the reply header.
> +
> +VFIO region info format
> +^^^^^^^^^^^^^^^^^^^^^^^
> +
> ++------------+--------+------------------------------+
> +| Name       | Offset | Size                         |
> ++============+========+==============================+
> +| argsz      | 16     | 4                            |
> ++------------+--------+------------------------------+
> +| flags      | 20     | 4                            |
> ++------------+--------+------------------------------+
> +|            | +-----+-----------------------------+ |
> +|            | | Bit | Definition                  | |
> +|            | +=====+=============================+ |
> +|            | | 0   | VFIO_REGION_INFO_FLAG_READ  | |
> +|            | +-----+-----------------------------+ |
> +|            | | 1   | VFIO_REGION_INFO_FLAG_WRITE | |
> +|            | +-----+-----------------------------+ |
> +|            | | 2   | VFIO_REGION_INFO_FLAG_MMAP  | |
> +|            | +-----+-----------------------------+ |
> +|            | | 3   | VFIO_REGION_INFO_FLAG_CAPS  | |
> +|            | +-----+-----------------------------+ |
> ++------------+--------+------------------------------+
> +| index      | 24     | 4                            |
> ++------------+--------+------------------------------+
> +| cap_offset | 28     | 4                            |
> ++------------+--------+------------------------------+
> +| size       | 32     | 8                            |
> ++------------+--------+------------------------------+
> +| offset     | 40     | 8                            |
> ++------------+--------+------------------------------+
> +
> +* *argsz* is the size of the VFIO region info structure plus the
> +  size of any region capabilities returned.
> +* *flags* are attributes of the region:
> +
> +  * *VFIO_REGION_INFO_FLAG_READ* allows client read access to the
> region.
> +  * *VFIO_REGION_INFO_FLAG_WRITE* allows client write access to the
> region.
> +  * *VFIO_REGION_INFO_FLAG_MMAP* specifies the client can mmap()
> the region.
> +    When this flag is set, the reply will include a file descriptor in its
> +    meta-data. On AF_UNIX sockets, the file descriptors will be passed as
> +    SCM_RIGHTS type ancillary data.
> +  * *VFIO_REGION_INFO_FLAG_CAPS* indicates additional capabilities
> found in the
> +    reply.
> +
> +* *index* is the index of memory region being queried, it is the only field
> +  that is required to be set in the command message.
> +* *cap_offset* describes where additional region capabilities can be found.
> +  cap_offset is relative to the beginning of the VFIO region info structure.
> +  The data structure it points is a VFIO cap header defined in
> +  ``<linux/vfio.h>``.
> +* *size* is the size of the region.
> +* *offset* is the offset given to the mmap() system call for regions with the
> +  MMAP attribute. It is also used as the base offset when mapping a VFIO
> +  sparse mmap area, described below.

In the command message we only use vfio_region_info.index. VFIO passes the
entire struct since it gets filled in, however this doesn't make sense in
vfio-user. Shall we drop sending the entire struct vfio_region_info and only
send the region index?