* [PATCH] vfio-user.rst: clarify handling of VFIO_USER_VERSION capabilities
@ 2026-11-16 11:48 Mark Cave-Ayland
2026-11-16 13:51 ` Philippe Mathieu-Daudé
0 siblings, 1 reply; 4+ messages in thread
From: Mark Cave-Ayland @ 2026-11-16 11:48 UTC (permalink / raw)
To: john.levon, thanos.makatos, clg, qemu-devel
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") 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
+sent by the client, the server should assume the default values specified in
+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. |
++--------------------+---------+--------------------------+-----------------------------------------------+
+| 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. |
++--------------------+---------+--------------------------+-----------------------------------------------+
+| 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:
--
2.43.0
^ permalink raw reply related [flat|nested] 4+ messages in thread
* Re: [PATCH] vfio-user.rst: clarify handling of VFIO_USER_VERSION capabilities
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é
2026-11-17 10:25 ` Mark Cave-Ayland
0 siblings, 1 reply; 4+ messages in thread
From: Philippe Mathieu-Daudé @ 2026-11-16 13:51 UTC (permalink / raw)
To: Mark Cave-Ayland, john.levon, thanos.makatos, clg, qemu-devel
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:
>
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [PATCH] vfio-user.rst: clarify handling of VFIO_USER_VERSION capabilities
2026-11-16 13:51 ` Philippe Mathieu-Daudé
@ 2026-11-17 10:25 ` Mark Cave-Ayland
2026-11-17 11:29 ` John Levon
0 siblings, 1 reply; 4+ messages in thread
From: Mark Cave-Ayland @ 2026-11-17 10:25 UTC (permalink / raw)
To: Philippe Mathieu-Daudé, john.levon, thanos.makatos, clg,
qemu-devel
On 16/11/2026 13:51, Philippe Mathieu-Daudé wrote:
Hi Phil,
> 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?
It means that no capabilities have been provided. The existing
documentation at
https://www.qemu.org/docs/master/interop/vfio-user.html#request is
fairly clear that both these fields are optional.
However...
>> 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
... I added this extra paragraph to emphasise this behaviour if
capabilities are not provided.
> Typo "capabilities".
Ooops, will fix in v2.
>> +sent by the client, the server should assume the default values
>> specified in
>
> The "must" -> "should" change should be justified.
I'm not sure what you mean - this paragraph is completely new? Or are
you saying I should use "must" instead?
>> +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.
Okay I'll change from 64-1 to 64 KiB - 1.
> Previous was optional, now default is always present. Can we clarify?
I'm fairly sure "Optional, with a value of 65535 (64k-1)" is intending
to express the default value if none is supplied. John/Thanos - please
confirm that I've got this correct.
But indeed, you've spotted some of the ambiguities that this patch is
intended to resolve :)
>> ++--------------------+---------+--------------------------
>> +-----------------------------------------------+
>> +| 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:
ATB,
Mark.
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [PATCH] vfio-user.rst: clarify handling of VFIO_USER_VERSION capabilities
2026-11-17 10:25 ` Mark Cave-Ayland
@ 2026-11-17 11:29 ` John Levon
0 siblings, 0 replies; 4+ messages in thread
From: John Levon @ 2026-11-17 11:29 UTC (permalink / raw)
To: Mark Cave-Ayland
Cc: Philippe Mathieu-Daudé, thanos.makatos, clg, qemu-devel
On Tue, Nov 17, 2026 at 10:25:42AM +0000, Mark Cave-Ayland wrote:
> > Previous was optional, now default is always present. Can we clarify?
>
> I'm fairly sure "Optional, with a value of 65535 (64k-1)" is intending to
> express the default value if none is supplied. John/Thanos - please confirm
> that I've got this correct.
Yes
regards
john
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2026-11-17 11:30 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
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é
2026-11-17 10:25 ` Mark Cave-Ayland
2026-11-17 11:29 ` John Levon
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.