docs: clarify multiqueue vs multiple virtqueues

The vhost-user specification does not explain when
VHOST_USER_PROTOCOL_F_MQ must be implemented.  This may lead
implementors of vhost-user masters to believe that this protocol feature
is required for any device that has multiple virtqueues.  That would be
a mistake since existing vhost-user slaves offer multiple virtqueues but
do not advertise VHOST_USER_PROTOCOL_F_MQ.

For example, a vhost-net device with one rx/tx queue pair is not
multiqueue.  The slave does not need to advertise
VHOST_USER_PROTOCOL_F_MQ.  Therefore the master must assume it has these
virtqueues and cannot rely on askingt the slave how many virtqueues
exist.

Extend the specification to explain the different between true
multiqueue and regular devices with a fixed virtqueue layout.

Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
Message-Id: <20190624091304.666-1-stefanha@redhat.com>
Reviewed-by: Michael S. Tsirkin <mst@redhat.com>
Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
This commit is contained in:
Stefan Hajnoczi 2019-06-24 10:13:04 +01:00 committed by Michael S. Tsirkin
parent bf8b024372
commit df98d7ccc2
1 changed files with 17 additions and 0 deletions

View File

@ -324,6 +324,15 @@ must support changing some configuration aspects on the fly.
Multiple queue support
----------------------
Many devices have a fixed number of virtqueues. In this case the master
already knows the number of available virtqueues without communicating with the
slave.
Some devices do not have a fixed number of virtqueues. Instead the maximum
number of virtqueues is chosen by the slave. The number can depend on host
resource availability or slave implementation details. Such devices are called
multiple queue devices.
Multiple queue support allows the slave to advertise the maximum number of
queues. This is treated as a protocol extension, hence the slave has to
implement protocol features first. The multiple queues feature is supported
@ -339,6 +348,14 @@ queue in the sent message to identify a specified queue.
The master enables queues by sending message ``VHOST_USER_SET_VRING_ENABLE``.
vhost-user-net has historically automatically enabled the first queue pair.
Slaves should always implement the ``VHOST_USER_PROTOCOL_F_MQ`` protocol
feature, even for devices with a fixed number of virtqueues, since it is simple
to implement and offers a degree of introspection.
Masters must not rely on the ``VHOST_USER_PROTOCOL_F_MQ`` protocol feature for
devices with a fixed number of virtqueues. Only true multiqueue devices
require this protocol feature.
Migration
---------