All of lore.kernel.org
 help / color / mirror / Atom feed
* [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.