From fa9972662ce5b6d50fe7190efeb48a5a9fecca91 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alex=20Benn=C3=A9e?= Date: Mon, 21 Mar 2022 15:30:31 +0000 Subject: [PATCH] vhost-user.rst: add clarifying language about protocol negotiation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Make the language about feature negotiation explicitly clear about the handling of the VHOST_USER_F_PROTOCOL_FEATURES feature bit. Try and avoid the sort of bug introduced in vhost.rs REPLY_ACK processing: https://github.com/rust-vmm/vhost/pull/24 Signed-off-by: Alex Bennée Cc: Jiang Liu Message-Id: <20210226111619.21178-1-alex.bennee@linaro.org> Message-Id: <20220321153037.3622127-8-alex.bennee@linaro.org> Reviewed-by: Michael S. Tsirkin Signed-off-by: Michael S. Tsirkin --- docs/interop/vhost-user.rst | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/docs/interop/vhost-user.rst b/docs/interop/vhost-user.rst index 9159476678..73e710fe32 100644 --- a/docs/interop/vhost-user.rst +++ b/docs/interop/vhost-user.rst @@ -332,6 +332,18 @@ bit was dedicated for this purpose:: #define VHOST_USER_F_PROTOCOL_FEATURES 30 +Note that VHOST_USER_F_PROTOCOL_FEATURES is the UNUSED (30) feature +bit defined in `VIRTIO 1.1 6.3 Legacy Interface: Reserved Feature Bits +`_. +VIRTIO devices do not advertise this feature bit and therefore VIRTIO +drivers cannot negotiate it. + +This reserved feature bit was reused by the vhost-user protocol to add +vhost-user protocol feature negotiation in a backwards compatible +fashion. Old vhost-user master and slave implementations continue to +work even though they are not aware of vhost-user protocol feature +negotiation. + Ring states ----------- @@ -890,7 +902,8 @@ Front-end message types Get the protocol feature bitmask from the underlying vhost implementation. Only legal if feature bit ``VHOST_USER_F_PROTOCOL_FEATURES`` is present in - ``VHOST_USER_GET_FEATURES``. + ``VHOST_USER_GET_FEATURES``. It does not need to be acknowledged by + ``VHOST_USER_SET_FEATURES``. .. Note:: Back-ends that report ``VHOST_USER_F_PROTOCOL_FEATURES`` must @@ -906,7 +919,8 @@ Front-end message types Enable protocol features in the underlying vhost implementation. Only legal if feature bit ``VHOST_USER_F_PROTOCOL_FEATURES`` is present in - ``VHOST_USER_GET_FEATURES``. + ``VHOST_USER_GET_FEATURES``. It does not need to be acknowledged by + ``VHOST_USER_SET_FEATURES``. .. Note:: Back-ends that report ``VHOST_USER_F_PROTOCOL_FEATURES`` must support