From: "Philippe Mathieu-Daudé" <philmd@oss.qualcomm.com>
To: Mark Cave-Ayland <mark.caveayland@nutanix.com>,
john.levon@nutanix.com, thanos.makatos@nutanix.com,
clg@redhat.com, qemu-devel@nongnu.org
Subject: Re: [PATCH] vfio-user.rst: clarify handling of VFIO_USER_VERSION capabilities
Date: Mon, 16 Nov 2026 14:51:46 +0100 [thread overview]
Message-ID: <d6dd9ec4-d3b6-41c7-a79d-e72161aeaf37@oss.qualcomm.com> (raw)
In-Reply-To: <20261116114947.3365480-1-mark.caveayland@nutanix.com>
Hi Mark,
On 16/11/26 12:48, Mark Cave-Ayland wrote:
> The vfio-user protocol specification currently lists each individual capability
> as being optional and provides an indication of the default value within the
> description text.
>
> Clarify that all VFIO_USER_VERSION capabilities are optional (including if no
> capabilities are provided in "version data")
What happens in if "version data" is empty?
> and move the default values to
> their own separate column within the capabilities table to make them more
> visible.
>
> Signed-off-by: Mark Cave-Ayland <mark.caveayland@nutanix.com>
> ---
> docs/interop/vfio-user.rst | 61 +++++++++++++++++++-------------------
> 1 file changed, 30 insertions(+), 31 deletions(-)
>
> diff --git a/docs/interop/vfio-user.rst b/docs/interop/vfio-user.rst
> index b49781a755..4a5cfbb704 100644
> --- a/docs/interop/vfio-user.rst
> +++ b/docs/interop/vfio-user.rst
> @@ -515,37 +515,36 @@ format:
>
> Capabilities:
>
> -+--------------------+---------+-----------------------------------------------+
> -| Name | Type | Description |
> -+====================+=========+===============================================+
> -| max_msg_fds | number | Maximum number of file descriptors that can |
> -| | | be received by the sender in one message. |
> -| | | Optional. If not specified then the receiver |
> -| | | must assume a value of ``1``. |
> -+--------------------+---------+-----------------------------------------------+
> -| max_data_xfer_size | number | Maximum ``count`` for data transfer messages; |
> -| | | see `Read and Write Operations`_. Optional, |
> -| | | with a default value of 1048576 bytes. |
> -+--------------------+---------+-----------------------------------------------+
> -| max_dma_maps | number | Maximum number DMA map windows that can be |
> -| | | valid simultaneously. Optional, with a |
> -| | | value of 65535 (64k-1). |
> -+--------------------+---------+-----------------------------------------------+
> -| pgsizes | number | Page sizes supported in DMA map operations |
> -| | | or'ed together. Optional, with a default |
> -| | | value of supporting only 4k pages. |
> -+--------------------+---------+-----------------------------------------------+
> -| twin_socket | object | Parameters for twin-socket mode, which |
> -| | | handles server-to-client commands and their |
> -| | | replies on a separate socket. Optional. |
> -+--------------------+---------+-----------------------------------------------+
> -| write_multiple | boolean | ``VFIO_USER_REGION_WRITE_MULTI`` messages |
> -| | | are supported if the value is ``true``. |
> -+--------------------+---------+-----------------------------------------------+
> -| sparse_mmap_fds | boolean | ``VFIO_REGION_INFO_CAP_SPARSE_MMAP_FDS`` |
> -| | | capability is supported if the value is |
> -| | | ``true``. |
> -+--------------------+---------+-----------------------------------------------+
> +All capabilties are optional. If a capability is not included in the request
Typo "capabilities".
> +sent by the client, the server should assume the default values specified in
The "must" -> "should" change should be justified.
> +the table below:
> +
> ++--------------------+---------+--------------------------+-----------------------------------------------+
> +| Name | Type | Default (if unspecified) | Description |
> ++====================+=========+==========================+===============================================+
> +| max_msg_fds | number | ``1`` | Maximum number of file descriptors that can |
> +| | | | be received by the sender in one message. |
> ++--------------------+---------+--------------------------+-----------------------------------------------+
> +| max_data_xfer_size | number | ``1048576`` | Maximum ``count`` in bytes for data transfer |
> +| | | | messages; see `Read and Write Operations`_. |
> ++--------------------+---------+--------------------------+-----------------------------------------------+
> +| max_dma_maps | number | ``65535`` (64k-1) | Maximum number DMA map windows that can be |
> +| | | | valid simultaneously. |
Pre-exiting, "64 KiB - 1" is more accurate.
Previous was optional, now default is always present. Can we clarify?
> ++--------------------+---------+--------------------------+-----------------------------------------------+
> +| pgsizes | number | ``4096`` (4k pages only) | Page sizes supported in DMA map operations |
> +| | | | or'ed together. |
> ++--------------------+---------+--------------------------+-----------------------------------------------+
> +| twin_socket | object | (empty) | Parameters for twin-socket mode, which |
> +| | | | handles server-to-client commands and their |
> +| | | | replies on a separate socket. |
"empty" is not clear; maybe "absent" (unless requested)?
> ++--------------------+---------+--------------------------+-----------------------------------------------+
> +| write_multiple | boolean | ``false`` | ``VFIO_USER_REGION_WRITE_MULTI`` messages |
> +| | | | are supported if the value is ``true``. |
> ++--------------------+---------+--------------------------+-----------------------------------------------+
> +| sparse_mmap_fds | boolean | ``false`` | ``VFIO_REGION_INFO_CAP_SPARSE_MMAP_FDS`` |
> +| | | | capability is supported if the value is |
> +| | | | ``true``. |
> ++--------------------+---------+--------------------------+-----------------------------------------------+
>
> The ``twin_socket`` capability object holds these name/value pairs:
>
next prev parent reply other threads:[~2026-11-16 13:52 UTC|newest]
Thread overview: 4+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-11-16 11:48 [PATCH] vfio-user.rst: clarify handling of VFIO_USER_VERSION capabilities Mark Cave-Ayland
2026-11-16 13:51 ` Philippe Mathieu-Daudé [this message]
2026-11-17 10:25 ` Mark Cave-Ayland
2026-11-17 11:29 ` John Levon
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=d6dd9ec4-d3b6-41c7-a79d-e72161aeaf37@oss.qualcomm.com \
--to=philmd@oss.qualcomm.com \
--cc=clg@redhat.com \
--cc=john.levon@nutanix.com \
--cc=mark.caveayland@nutanix.com \
--cc=qemu-devel@nongnu.org \
--cc=thanos.makatos@nutanix.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.