Re: [PATCH] virtio-net: Improve control vq introductory description

[Cornelia Huck <cohuck@redhat.com>]

On Mon, Jan 23 2023, Parav Pandit <parav@nvidia.com> wrote:

> The control VQ of the virtio network device is used for controlling
> multiple features, not just advanced steering control. The control VQ
> dynamically changes multiple features of the initialized device.
>
> Hence, update this area of control VQ introductory description.
>
> This patch is on top of [1].
>
> [1] https://lists.oasis-open.org/archives/virtio-dev/202301/msg00272.html

[Side note: better put notes like that beneath the "---" delimiter, so
that they don't end up in the changelog, where they won't be of much
interest anymore.]

>
> Fixes: https://github.com/oasis-tcs/virtio-spec/issues/156
> Signed-off-by: Parav Pandit <parav@nvidia.com>
> ---
>  device-types/net/description.tex | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/device-types/net/description.tex b/device-types/net/description.tex
> index 41ae7f5..56bd672 100644
> --- a/device-types/net/description.tex
> +++ b/device-types/net/description.tex
> @@ -8,7 +8,7 @@ \section{Network Device}\label{sec:Device Types / Network Device}
>  device. Empty buffers are placed in one virtqueue for receiving
>  packets, and outgoing packets are enqueued into another for
>  transmission in that order. A third command queue is used to
> -control advanced filtering features.
> +dynamically manipulate various features of the initialized device.

I think that whole paragraph needs some editing; apart from your
card/device terminology change, it hasn't seem updates in ages.

- the "most complex device supported so far" half sentence, while not
  untrue, doesn't really add much to the understanding of what the net
  device does
- same for the "It has enhanced rapidly..." statement
- more importantly, it still talks about single receive/transmit queues,
  while multiqueue has been specified for ages; this also makes the "A
  third command queue" statement a bit confusing

What about generalizing this change to a "virtio-net: Improve
introductory description" update to something like the following,
copying the purpose of the control queue from the description further
below:

"The virtio network device is a virtual ethernet device with a complex
and configurable set of features. One or more pairs of virtqueues are
used for receiving and transmitting packets: Empty buffers are placed
in the first virtqueue of the pair for receiving packets, and outgoing
packets are enqueued into the other for transmission. An optional
command queue is used to dynamically manipulate various features of the
initialized device which would not easily map into the configuration
space."