[PATCH] vhost-user.rst: clarify when FDs can be sent

[PATCH] vhost-user.rst: clarify when FDs can be sent

[Alyssa Ross]

Previously the spec did not say where in a message the FDs should be
sent.  As I understand it, FDs transferred in ancilliary data will
always be received along with the first byte of the data they were
sent with, so we should define which byte that is.  Going by both
libvhost-user in QEMU and the rust-vmm crate, that byte is the first
byte of the message header.  This is important to specify because it
would make back-end implementation significantly more complicated if
receiving file descriptors in the middle of a message had to be
handled.

Signed-off-by: Alyssa Ross <hi@alyssa.is>
---
 docs/interop/vhost-user.rst | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/docs/interop/vhost-user.rst b/docs/interop/vhost-user.rst
index 2e50f2ddfa..93a9c8df2b 100644
--- a/docs/interop/vhost-user.rst
+++ b/docs/interop/vhost-user.rst
@@ -411,6 +411,13 @@ in the ancillary data:
 * ``VHOST_USER_SET_INFLIGHT_FD`` (if ``VHOST_USER_PROTOCOL_F_INFLIGHT_SHMFD``)
 * ``VHOST_USER_SET_DEVICE_STATE_FD``
 
+When sending file descriptors in ancilliary data, *front-end* should
+associate the ancilliary data with a ``sendmsg`` operation (or
+equivalent) that sends bytes starting with the first byte of the
+message header.  *back-end* can therefore expect that file descriptors
+will only be received in the first ``recvmsg`` operation for a message
+header.
+
 If *front-end* is unable to send the full message or receives a wrong
 reply it will close the connection. An optional reconnection mechanism
 can be implemented.

base-commit: 917ac07f9aef579b9538a81d45f45850aba42906
-- 
2.51.0

Re: [PATCH] vhost-user.rst: clarify when FDs can be sent

[Michael S. Tsirkin]

On Thu, Nov 06, 2025 at 08:21:05PM +0100, Alyssa Ross wrote:
> Previously the spec did not say where in a message the FDs should be
> sent.  As I understand it, FDs transferred in ancilliary data will

ancillary, actually

> always be received along with the first byte of the data they were
> sent with, so we should define which byte that is.  Going by both
> libvhost-user in QEMU and the rust-vmm crate, that byte is the first
> byte of the message header.  This is important to specify because it
> would make back-end implementation significantly more complicated if
> receiving file descriptors in the middle of a message had to be
> handled.
> 
> Signed-off-by: Alyssa Ross <hi@alyssa.is>
> ---
>  docs/interop/vhost-user.rst | 7 +++++++
>  1 file changed, 7 insertions(+)
> 
> diff --git a/docs/interop/vhost-user.rst b/docs/interop/vhost-user.rst
> index 2e50f2ddfa..93a9c8df2b 100644
> --- a/docs/interop/vhost-user.rst
> +++ b/docs/interop/vhost-user.rst
> @@ -411,6 +411,13 @@ in the ancillary data:
>  * ``VHOST_USER_SET_INFLIGHT_FD`` (if ``VHOST_USER_PROTOCOL_F_INFLIGHT_SHMFD``)
>  * ``VHOST_USER_SET_DEVICE_STATE_FD``
>  
> +When sending file descriptors in ancilliary data, *front-end* should

ancillary, here too

> +associate the ancilliary data with a ``sendmsg`` operation (or
> +equivalent) that sends bytes starting with the first byte of the
> +message header.  *back-end* can therefore expect that file descriptors
> +will only be received in the first ``recvmsg`` operation for a message
> +header.
> +
>  If *front-end* is unable to send the full message or receives a wrong
>  reply it will close the connection. An optional reconnection mechanism
>  can be implemented.
> 
> base-commit: 917ac07f9aef579b9538a81d45f45850aba42906
> -- 
> 2.51.0