Migration of back-end state happens while the device is suspended (i.e
all vrings are stopped). To resume normal operation on the destination,
the vrings need to be started again with a kick (either a write on the
FD or the VHOST_USER_VRING_KICK in-band message if negotiated). While
these notifications are typically sent by the driver, it has no reason
to send them in the destination if it already sent them in the source as
the driver is unaware that a migration took place. Therefore it should
be the responsibility of the vhost-user front-end to ensure these vrings
are started. This is particularly necessary for queues where data only
flows from device to driver, such as those used by the vsock and input
devices.
This behavior is already used by some qemu vhost-user front-ends (e.g
vhost-user-blk) and by front-ends implemented on other VMMs(e.g CrosVm).
Adding it to the vhost-user documentation makes it explicit that this
strategy is permitted and suggest it to vhost-user front-end authors.
Explicitly documenting it is necessary because vring kicks appear
designed to originate in the driver, so having some originate in the
front-end can be counterintuitive and cause developers to waste time
looking for other alternatives or face pushback during code review.
Signed-off-by: Jorge E. Moreira <jemoreira@google.com>
---
docs/interop/vhost-user.rst | 5 ++++-
1 file changed, 4 insertions(+), 1 deletion(-)
diff --git a/docs/interop/vhost-user.rst b/docs/interop/vhost-user.rst
index 137c9f3669..ad5aba3430 100644
--- a/docs/interop/vhost-user.rst
+++ b/docs/interop/vhost-user.rst
@@ -656,7 +656,10 @@ destination, following the usual protocol for establishing a connection
to a vhost-user back-end: This includes, for example, setting up memory
mappings and kick and call FDs as necessary, negotiating protocol
features, or setting the initial vring base indices (to the same value
-as on the source side, so that operation can resume).
+as on the source side, so that operation can resume). The vhost-user front-end
+may also write to the kick FDs of vrings containing unused buffers or send
+``VHOST_USER_VRING_KICK`` if negotiated to start those vrings in the destination
+since the driver likely already kicked them in the source and won't do it again.
Both on the source and on the destination side, after the respective
front-end has seen all data transferred (when the transfer FD has been
--
2.53.0.1213.gd9a14994de-goog