Re: [virtio-dev] [PATCH 1/5] introduction: tweak text as suggested by pbonzini

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

"Michael S. Tsirkin" <mst@redhat.com> writes:
> Seems slightly more straight-forward.
>
> Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
> ---
>  introduction.tex | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/introduction.tex b/introduction.tex
> index cf2fdac..7c79921 100644
> --- a/introduction.tex
> +++ b/introduction.tex
> @@ -20,14 +20,14 @@ inter-guest communication) requires copying.
>  
>    Standard: Virtio makes no assumptions about the environment in which
>    it operates, beyond supporting the bus to which the device is
> -  attached.  Virtio
> +  attached.  In this specification, Virtio
>    devices are implemented over MMIO, Channel I/O and PCI bus
>    transports
>  \footnote{The Linux implementation further separates the virtio
>  transport code from the specific virtio drivers: these drivers are shared
>  between different transports.
>  }, earlier drafts
> -  have been implemented on other buses not included in this specification.
> +  have been implemented on other buses not included here.

Hmm, I would normally just apply this as trivial, but it intersects
with other feedback which hasn't been applied yet.

Instead I appended it to feedback/5.txt, which appears as shown below.

Thanks,
Rusty.

Document: virtio-v1.0-csprd01
Number: 5
Date: Tue, 28 Jan 2014 09:44:50 -0500
Link to Mail: https://lists.oasis-open.org/archives/virtio-comment/201401/msg00046.html
Commenter name: Laura Novich <lnovich@redhat.com>
Decision:

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.
3. The purpose of ...
4. replace rather than using boutique to  rather than using vendor-specific,
per-environment, or per-OS mechanisms. 

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]
6. Efficient: ADD to input and output (I/O),
7. effects from both guest and (not sure but i think you should ADD host)
device writing to the same cache
  lines.
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]

Proposal:

diff --git a/abstract.tex b/abstract.tex
index b42a0b6..186fb81 100644
--- a/abstract.tex
+++ b/abstract.tex
@@ -1,7 +1,7 @@
 This document describes the specifications of the “virtio” family of
 devices. These devices are found in virtual environments, yet by
 design they are not all that different from physical devices, and this
-document treats them as such. This allows the guest to use standard
+document treats them as such. This similarity allows the guest to use standard
 drivers and discovery mechanisms.
 
 The purpose of virtio and this specification is that virtual
diff --git a/introduction.tex b/introduction.tex
index 5d57f78..275ad98 100644
--- a/introduction.tex
+++ b/introduction.tex
@@ -13,14 +13,15 @@ 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
+  it operates, beyond supporting the bus to which device is attached.
+  In this specification, 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 here.
 \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).