In practice the protocol negotiation between vhost master and slave occurs before the final feature negotiation between backend and frontend. This has lead to an inconsistency between the rust-vmm vhost implementation and the libvhost-user library in their approaches to checking if all the requirements for REPLY_ACK processing were met. As this is purely a function of the protocol negotiation and not of interest to the frontend lets make the language clearer about the requirements for a successfully negotiated protocol feature. Signed-off-by: Alex Bennée <alex.bennee@linaro.org> Cc: Jiang Liu <gerry@linux.alibaba.com> --- docs/interop/vhost-user.rst | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/interop/vhost-user.rst b/docs/interop/vhost-user.rst index XXXXXXX..XXXXXXX 100644 --- a/docs/interop/vhost-user.rst +++ b/docs/interop/vhost-user.rst @@ -XXX,XX +XXX,XX @@ If *slave* detects some error such as incompatible features, it may also close the connection. This should only happen in exceptional circumstances. Any protocol extensions are gated by protocol feature bits, which -allows full backwards compatibility on both master and slave. As -older slaves don't support negotiating protocol features, a feature +allows full backwards compatibility on both master and slave. As older +slaves don't support negotiating protocol features, a device feature bit was dedicated for this purpose:: #define VHOST_USER_F_PROTOCOL_FEATURES 30 +However as the protocol negotiation something that only occurs between +parts of the backend implementation it is permissible to for the master +to mask the feature bit from the guest. As noted for the +``VHOST_USER_GET_PROTOCOL_FEATURES`` and +``VHOST_USER_SET_PROTOCOL_FEATURES`` messages this occurs before a +final ``VHOST_USER_SET_FEATURES`` comes from the guest. So the +enabling of protocol features need only require the advertising of the +feature by the slave and the successful get/set protocol features +sequence. + Starting and stopping rings --------------------------- -- 2.20.1 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 <alex.bennee@linaro.org> Cc: Jiang Liu <gerry@linux.alibaba.com> Message-Id: <20210226111619.21178-1-alex.bennee@linaro.org> --- v2 - use Stefan's suggested wording - Be super explicit in the message descriptions --- 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 XXXXXXX..XXXXXXX 100644 --- a/docs/interop/vhost-user.rst +++ b/docs/interop/vhost-user.rst @@ -XXX,XX +XXX,XX @@ 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 +<https://docs.oasis-open.org/virtio/virtio/v1.1/cs01/virtio-v1.1-cs01.html#x1-4130003>`_. +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 ----------- @@ -XXX,XX +XXX,XX @@ 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 @@ -XXX,XX +XXX,XX @@ 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 -- 2.20.1