Re: [virtio-comment] comments for the virtio spec - Introduction section

[Rusty Russell <rusty@au1.ibm.com>]

Hi Laura,

Thanks for the feedback!

Laura Novich <lnovich@redhat.com> writes:
> If you can't open the document here are my comments

Hmm, attachment got stripped?

> INTRODUCTION
> ===============
> 1. Remove The entire first paragraph with the exveption of the first sentence.
> 2. Replace with - A virtual device in its truest sense is not any different from a physical device. The virtual machine sees a virtual device just as a physical machine would see a physical one. As such, this document will treat virtual devices as physical devices.

This isn't quite correct.  Consider:

        This document describes the specifications of the “virtio”
        family of devices. These devices are found in virtual
        environments

vs:
        This document describes the specifications of the “virtio”
        family of devices. A virtual device in its truest sense is not
        any different from a physical device.

We need to say that virtio devices are found in virtual environments.

Secondly, you are missing historical context: Xen and HyperV treat
virtual devices as very different beasts than physical devices.  It is
not a fundamental feature of these devices that they are no different
from a physical device, but rather a conscious decision by the spec
authors.

> 3. The purpose of ...
> 4. replace rather than using boutique to  rather than using vendor-specific, per-environment, or per-OS mechanisms. 

Is "boutique" too obscure?  I like it because it casts an image of the
alternatives being niche.  That may be wishful thinking, but it was a
deliberate choice :)

> 5. ADD -The categories described above are further defined as follows:
>   Straightforward: Revise last sentence to read - There aren’t any exotic page-flipping or COW mechanisms and it functions as a  normal device.[1]

The end of this sentence is not meaningful.  Compare:

        There is no exotic page-flipping or COW mechanism: it's just
        a normal device.

The ": it's just..." emphasizes the former.  With your variant:


        There aren’t any exotic page-flipping or COW mechanisms and it
        functions as a normal device.

It's not clear what "functions as a normal device" means.

> 6. Efficient: ADD to input and output (I/O),

Again, I disagree.  I/O conflates input and output, whereas I wish to
call them both out separately.  Perhaps we should add the word "both",
ie:

        descriptors for both input and output...

> 7. effects from both guest and (not sure but i think you should ADD host) device writing to the same cache
>   lines.

Throughout the document, we explicitly refer to "device" and "driver"
rather than host and guest.  This reinforces the design decision that
they should appear "normal", as well as being more specific.

> 8. Standard: CHANGE TO READ: Virtio makes no assumptions about the environment in which
>   it operates, beyond what is required in order to allow the bus to  attach the host device to the driver on the guest.  Virtio
>   devices are implemented over PCI and other buses, and earlier drafts that
>   have been implemented on other buses not included in this specification.[2]

You suggest replacing "beyond supporting the bus attaching the device."
with "beyond what is required in order to allow the bus to attach the
host device to the driver on the guest."

What do these extra words add?

There is a missing word "have", but it doesn't need "that".

        ...and earlier drafts been implemented on other buses not included
        in this spec.

And I'll accept changing "spec" to "specification".

So this is the difference I have so far from your feedback:

diff --git a/introduction.tex b/introduction.tex
index 5d57f78..98e1e0d 100644
--- a/introduction.tex
+++ b/introduction.tex
@@ -13,14 +13,14 @@ inter-guest communication) requires copying.
 }
 
   Efficient: Virtio devices consist of rings of descriptors
-  for input and output, which are neatly separated to avoid cache
+  for both input and output, which are neatly separated to avoid cache
   effects from both driver and device writing to the same cache
   lines.
 
   Standard: Virtio makes no assumptions about the environment in which
   it operates, beyond supporting the bus attaching the device.  Virtio
   devices are implemented over PCI and other buses, and earlier drafts
-  been implemented on other buses not included in this spec.
+  have been implemented on other buses not included in this specification.
 \footnote{The Linux implementation further separates the PCI virtio code
 from the specific virtio drivers: these drivers are shared with
 the non-PCI implementations (currently lguest and S/390).

Cheers,
Rusty.