@samitouri / QOSamiQemu / commits / 37b14d86d6

vhost-user.rst: clarify when rings are started

Jorge Moreira <jemoreira@google.com> pointed out that the ring state machine is underspecified. In the discussion that followed, we discovered that the spec says one thing and implementations do something else. This patch updates the spec to reflect how things are actually implemented across widely-used front-ends and back-ends including QEMU, crosvm, rust-vmm, and DPDK. Do this while taking care not to make any other existing implementations non-compliant by changing the spec. The spec says rings are started when a kick is received but the implementations actually start rings when VHOST_USER_SET_VRING_KICK is received. Reconcile this as follows: - Clarify that a ring can be stopped and then started again. The back-end must resume processing available requests when the ring is restarted. - Update the spec to say rings are started when VHOST_USER_SET_VRING_KICK is received. - Ensure compatibility by saying front-ends SHOULD inject a kick in case the back-end strictly implemented the old spec. - Avoid future back-end dependencies on injected kicks by saying that back-ends SHOULD NOT expect a kick to start rings. This way implementors have clarity on how things work while still allowing compatibility for existing implementations. Reported-by: Jorge Moreira <jemoreira@google.com> Cc: "Michael S . Tsirkin" <mst@redhat.com> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com> Reviewed-by: Stefano Garzarella <sgarzare@redhat.com> Reviewed-by: Michael S. Tsirkin <mst@redhat.com> Signed-off-by: Michael S. Tsirkin <mst@redhat.com> Message-ID: <20260604201029.250450-2-stefanha@redhat.com>

Stefan Hajnoczi committed Jun 4, 2026 at 16:10 UTC 37b14d86d65a29e94a1d50cb4b9593dffc612e76
1 file changed +20 -6
docs/interop/vhost-user.rst
+20 -6
@@ -518,12 +518,26 @@ Rings have two independent states: started/stopped, and enabled/disabled.
518 * started and enabled: The back-end must process the ring normally, i.e.
519 process all requests and execute them.
520
521 -Each ring is initialized in a stopped and disabled state. The back-end
522 -must start a ring upon receiving a kick (that is, detecting that file
523 -descriptor is readable) on the descriptor specified by
524 -``VHOST_USER_SET_VRING_KICK`` or receiving the in-band message
525 -``VHOST_USER_VRING_KICK`` if negotiated, and stop a ring upon receiving
526 -``VHOST_USER_GET_VRING_BASE``.
521 +Each ring is initialized in a stopped and disabled state. Rings are started
522 +with ``VHOST_USER_SET_VRING_KICK`` (or ``VHOST_USER_VRING_KICK`` if
523 +``VHOST_USER_PROTOCOL_F_INBAND_NOTIFICATIONS`` is negotiated) and stopped with
524 +``VHOST_USER_GET_VRING_BASE``. A stopped ring enters the started state again
525 +with ``VHOST_USER_SET_VRING_KICK`` (or ``VHOST_USER_VRING_KICK`` if
526 +``VHOST_USER_PROTOCOL_F_INBAND_NOTIFICATIONS`` is negotiated) and the back-end
527 +resumes processing requests.
528 +
529 +Note that previous versions of this specification stated that rings start when
530 +the back-end receives a kick (that is, detecting that file descriptor is
531 +readable) on the descriptor specified by ``VHOST_USER_SET_VRING_KICK`` or
532 +receiving the in-band message ``VHOST_USER_VRING_KICK`` if negotiated.
533 +Widely-used front-ends and back-ends did not implement this behavior and it
534 +complicates poll mode back-ends that do not rely on the kick file descriptor.
535 +
536 +For compatibility with back-ends that implemented the start on kick behavior,
537 +front-ends SHOULD inject a kick after ``VHOST_USER_SET_VRING_KICK``. This
538 +ensures that the back-end processes any available requests in the ring.
539 +Back-ends SHOULD NOT rely on receiving a kick after
540 +``VHOST_USER_SET_VRING_KICK``.
541
542 Rings can be enabled or disabled by ``VHOST_USER_SET_VRING_ENABLE``.
543