Re: [virtio-dev] [PATCH 1/2] virtio-net: rephrase devconf fields description

["Michael S. Tsirkin" <mst@redhat.com>]

On Wed, Aug 12, 2015 at 06:37:18PM +0300, Victor Kaplansky wrote:
> Clarify general description of the mac, status and
> max_virtqueue_pairs fields. Specifically, the old description is
> vague about configuration layout and fields offsets when some of
> the fields are non valid.
> 
> Also mac was described as driver-read-only, while actually it can
> be modified through legacy interface.

legacy interfaces have their only sections, there we do explain
that mac is writeable for legacy.
I would put that read-only term back - We have to say somewhere that
it's read only for modern devices, right?

> 
> Signed-off-by: Victor Kaplansky <victork@redhat.com>
> ---
>  content.tex | 33 ++++++++++++++++++++++-----------
>  1 file changed, 22 insertions(+), 11 deletions(-)
> 
> diff --git a/content.tex b/content.tex
> index d989d98..37e6a18 100644
> --- a/content.tex
> +++ b/content.tex
> @@ -3115,23 +3115,14 @@ were needed.
>  \subsection{Device configuration layout}\label{sec:Device Types / Network Device / Device configuration layout}
>  \label{sec:Device Types / Block Device / Feature bits / Device configuration layout}
>  
> -Three driver-read-only configuration fields are currently defined. The \field{mac} address field
> -always exists (though is only valid if VIRTIO_NET_F_MAC is set), and
> -\field{status} only exists if VIRTIO_NET_F_STATUS is set. Two
> -read-only bits (for the driver) are currently defined for the status field:
> -VIRTIO_NET_S_LINK_UP and VIRTIO_NET_S_ANNOUNCE.
> +
> +The following configuration fields are currently defined:
>  
>  \begin{lstlisting}
>  #define VIRTIO_NET_S_LINK_UP     1
>  #define VIRTIO_NET_S_ANNOUNCE    2
>  \end{lstlisting}
>  
> -The following driver-read-only field, \field{max_virtqueue_pairs} only exists if
> -VIRTIO_NET_F_MQ is set. This field specifies the maximum number
> -of each of transmit and receive virtqueues (receiveq1\ldots receiveqN
> -and transmitq1\ldots transmitqN respectively) that can be configured once VIRTIO_NET_F_MQ
> -is negotiated.
> -
>  \begin{lstlisting}
>  struct virtio_net_config {
>          u8 mac[6];
> @@ -3140,6 +3131,26 @@ struct virtio_net_config {
>  };
>  \end{lstlisting}
>  
> +\begin{description}
> +
> +\item [\field{mac}] is MAC address assigned by the device and is valid
> +    only if VIRTIO_NET_F_MAC is set.
> +
> +\item [\field{status}] consists of two driver-read-only status
> +    bits: VIRTIO_NET_S_LINK_UP and VIRTIO_NET_S_ANNOUNCE and is valid only
> +    if VIRTIO_NET_F_STATUS is set.

Actually no. VIRTIO_NET_F_STATUS means VIRTIO_NET_S_LINK_UP is valid.
GUEST_ANNOUNCE bit means VIRTIO_NET_S_ANNOUNCE is valid.

> +
> +
> +\item [\field{max_virtqueue_pairs}] tells the driver the maximum
> +    number of each of virtqueues (receiveq1\ldots receiveqN and
> +    transmitq1\ldots transmitqN respectively) that can be configured
> +    on the device once VIRTIO_NET_F_MQ is negotiated.
> +    \field{max_virtqueue_pairs} is valid only if VIRTIO_NET_F_MQ is
> +    set and should not be modified by the driver.
> +
> +\end{description}
> +
> +

so all these are driver-read-only.

>  \devicenormative{\subsubsection}{Device configuration layout}{Device Types / Network Device / Device configuration layout}
>  
>  The device MUST set \field{max_virtqueue_pairs} to between 1 and 0x8000 inclusive,
> -- 
> --Victor
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org