Re: [virtio-comment] VIRTIO Spec feedback

[Cornelia Huck <cornelia.huck@de.ibm.com>]

On Fri, 07 Feb 2014 17:25:33 +1030
Rusty Russell <rusty@au1.ibm.com> wrote:

> Arun Subbarao <asubbarao@lnxw.com> writes:
> > Please consider our feedback on the Virtio spec.
> 
> Hi Arun,
> 
>         Thanks for the feedback, you will have already seen fixed fly
> past addressing some of them.
> 
> I particularly want to address the inconsistent use of field/register
> names.  This was a big job, but I agree.  The patch which cleans then up
> is below.  I chose italics in the end, which is a bit less jarring than
> typewriter.
> 
> Thanks,
> Rusty.
> ===
> Use \field{} for all register and field names.
> 
> This currently just makes it italic.  Generally this means changing
> phrases of form "the XXX field" to "\field{XXX}", but other minor
> consistency and formatting changes were made along the way:
> 
> 1) Device Status became "device status" to match other fields.
> 
> 2) PCI: The legacy PCI fields now have the same name as modern ones (where
>    appropriate) so the general text still stands.
> 
> 3) PCI: the msix_config field is renamed config_msix_vector to match the
>    queue equivalent.
> 
> 4) MMIO: use italics for field names in table instead of bold (to match
>    the rest of the document)
> 
> 5) MMIO: extra spacing in "QueueDescLow/ QueueDescHigh" and "QueueUsedLow/
>    QueueUsedHigh" removed.
> 
> 6) NET: CAN changed to MAY (was: 'a transitional device CAN defer MAC
>    update, or CAN defer')
> 
> 7) SCSI: control commands are now an item list, for better formatting.
> 
> 8) SCSI: events now an item list.  reason fields now a description list.
> 
> 9) VIRTIO_F_RING_EVENT_IDX is now a coherent sentence instead of just
>    ending "; the flags field is used". 
> 
> Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
> 

I like that the fields are more obvious now.

My only minor nit is that you missed some fields for ccw :)

---

commit 3433b9a2f1096fa6eaf027d22c44ed2bf3c1acef
Author: Cornelia Huck <cornelia.huck@de.ibm.com>
Date:   Fri Feb 7 13:38:23 2014 +0100

    ccw: missed field conversions
    
    Signed-off-by: Cornelia Huck <cornelia.huck@de.ibm.com>

diff --git a/content.tex b/content.tex
index f7a8604..3fb44c5 100644
--- a/content.tex
+++ b/content.tex
@@ -2011,7 +2011,7 @@ struct vq_config_block {
 } __attribute__ ((packed));
 \end{lstlisting}
 
-The requested number of buffers for queue index is returned in
+The requested number of buffers for queue \field{index} is returned in
 \field{max_num}.
 
 Afterwards, CCW_CMD_SET_VQ is issued by the driver to inform the
@@ -2030,7 +2030,7 @@ struct vq_info_block {
 \end{lstlisting}
 
 \field{desc}, \field{avail} and \field{used} contain the guest addresses for the descriptor table,
-available ring and used ring for queue index, respectively. The actual
+available ring and used ring for queue \field{index}, respectively. The actual
 virtqueue size (number of allocated buffers) is transmitted in \field{num}.
 \field{res0} is reserved and MUST be ignored by the device.
 
@@ -2048,7 +2048,7 @@ struct vq_info_block_legacy {
 } __attribute__ ((packed));
 \end{lstlisting}
 
-\field{queue} contains the guest address for queue index, \field{num} the number of buffers
+\field{queue} contains the guest address for queue \field{index}, \field{num} the number of buffers
 and \field{align} the alignment.
 
 \subsubsection{Virtqueue Layout}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Initialization / Virtqueue Layout}