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

Previously the spec did not say where in a message the FDs should be
sent.  As I understand it, FDs transferred in ancillary 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>
Reviewed-by: Michael S. Tsirkin <mst@redhat.com>
Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
Message-Id: <20251106192105.3456755-1-hi@alyssa.is>

diff --git a/docs/interop/vhost-user.rst b/docs/interop/vhost-user.rst
index 2e50f2ddfad2b996f57a28438bc1a919d6c1164c..93a9c8df2bee6468b61f2a9527ca13500cde0689 100644 (file)
--- 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.