Merge remote-tracking branch 'origin/v1.0'

git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/trunk@572 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652

1 files changed, 328 insertions, 0 deletions

diff --git a/cl-cs03.tex b/cl-cs03.tex
new file mode 100644
index 0000000..72925ca
--- /dev/null
+++ b/cl-cs03.tex
@@ -0,0 +1,328 @@
+478 & 15 Mar 2015 & Cornelia Huck & {VIRTIO-129: legacy:
+clean up virtqueue layout definitions
+
+Generalize "Legacy Interfaces: A Note on Virtqueue Layout" to allow
+for different alignment requirements. Have pci and ccw refer to that
+section for legacy devices. Remove the double definition of virtqueue
+alignment (which referred to legacy, but was not tagged as such) from
+the ccw section.
+See \ref{sec:Basic Facilities of a Virtio Device / Virtqueues /
+Legacy Interfaces: A Note on Virtqueue Layout}, \ref{sec:Virtio
+Transport Options / Virtio Over PCI Bus / PCI-specific
+Initialization And Device Operation / Device Initialization /
+Virtqueue Configuration / Legacy Interface: A Note on Virtqueue
+Configuration} and \ref{sec:Virtio Transport Options / Virtio
+over channel I/O / Device Initialization / Configuring a
+Virtqueue / Legacy Interface: A Note on Configuring a Virtqueue}.
+ } \\
+\hline
+479 & 15 Mar 2015 & Cornelia Huck & {VIRTIO-118:
+ccw: clarify basic channel commands
+
+"Basic channel commands" seems to be not as clear as it
+could, so let's spell out which channel commands we refer to.
+See \ref{sec:Virtio Transport Options / Virtio over channel I/O /
+Basic Concepts}.
+} \\
+\hline
+479 & 15 Mar 2015 & Cornelia Huck & {VIRTIO-116:
+ccw: allow WRITE_STATUS to fail
+    
+We want to be able to fail setting a status on the device
+(e.g.  FEATURES_OK if the device can't work with the features
+negotiated).
+The easiest way to do that is to allow the device to fail the
+WRITE_STATUS command by posting a command reject.
+See \ref{sec:Virtio Transport Options / Virtio over channel I/O /
+Device Initialization / Communicating Status Information}.
+ } \\
+\hline
+485 & 15 Mar 2015 & Jason Wang & {VIRTIO-135:
+virtio-ring: comment fixup
+    
+virtio_ring.h included with spec has this text:
+/* Support for avail_idx and used_idx fields */
+it should really refer to avail_event and used_event.
+See Appendix \ref{sec:virtio-queue.h}.
+ } \\
+\hline
+486 & 15 Mar 2015 & Jason Wang & {VIRTIO-136:
+document idx field in virtqueue used ring
+
+Section \ref{sec:Basic Facilities of a Virtio Device / Virtqueues
+/ The Virtqueue Used Ring} The Virtqueue Used Ring
+listed the idx field, but never documented it.
+See \ref{sec:Basic Facilities of a Virtio Device / Virtqueues /
+The Virtqueue Used Ring}.
+ } \\
+\hline
+487 & 15 Mar 2015 & Rusty Russell & {VIRTIO-130:
+ISR status: Fix incorrect diagram
+
+ISR status capability diagram has the "Device Configuration
+Interrupt " as bit 0, and the "Queue Interrupt" as bit 1. This is
+the wrong way around: it disagrees with the legacy
+implementations, as well as the spec elsewhere.
+
+All current guests correctly follow the text, fix
+up the diagram to match.
+See \ref{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI
+Device Layout / ISR status capability}.
+ } \\
+\hline
+488 & 15 Mar 2015 & Rusty Russell & {VIRTIO-133:
+Change 4.1.5.1.2.1 to device requirement
+
+4.1.5.1.2.1 is incorrectly labelled as a driver requirement; it's
+self-evidently referring to the device.
+See \ref{sec:Conformance / Driver Conformance / PCI Driver
+Conformance}, \ref{sec:Conformance / Device Conformance / PCI
+Device Conformance} and \ref{devicenormative:Virtio
+Transport Options / Virtio Over PCI Bus / PCI-specific
+Initialization And Device Operation / Device Initialization /
+Non-transitional Device With Legacy Driver}.
+ } \\
+\hline
+504 & 22 Apr 2015 & Rusty Russell & {VIRTIO-137:
+define the meaning and requirements of the len field.
+    
+We said what it was for, and noted why.  We didn't place any
+requirements on it, nor clearly spell out the implications of its use.
+    
+This clarification comes particularly from noticing that QEMU
+didn't set len correctly, and philosophising over the correct value
+when an error has occurred.
+See \ref{sec:Basic Facilities of a Virtio Device / Virtqueues /
+The Virtqueue Used Ring}, \ref{devicenormative:Basic Facilities
+of a Virtio Device / Virtqueues / The Virtqueue Used Ring} and
+\ref{sec:Basic Facilities of a Virtio Device / Virtqueues / The
+Virtqueue Used Ring}.
+ } \\
+\hline
+506 & 22 Apr 2015 & Michael S. Tsirkin & {VIRTIO-138:
+multiple errors: Non-transitional With Legacy
+
+virtio 1.0 has two sections titled "Non-transitional Device With
+Legacy Driver" the first says devices SHOULD fail, the second
+says devices MUST fail.  Clearly a mistake.
+
+Other issues: devices don't really fail - they cause drivers to
+fail. second section seems to be in the wrong place, and also
+have a section followed by subsection with no explanatory text in
+between, which is ugly.
+Finally, this text was originally ritten to handle buggy windows
+drivers gracefully, but later we changed device IDs so it's not
+really required there. Might be handy for some other buggy legacy
+drivers, though no such drivers are known.
+
+To fix, drop the duplicate section variant, add some explanatory
+text, clarify what does "same ID" mean here, and clarify
+that the work-around is only needed if a buggy driver
+is known to bind to a transitional device.
+
+See \ref{sec:Virtio Transport Options / Virtio
+Over PCI Bus / PCI Device Layout / Non-transitional Device With
+Legacy Driver: A Note on PCI Device Layout},
+\ref{devicenormative:Virtio Transport Options / Virtio Over PCI
+Bus / PCI-specific Initialization And Device Operation / Device
+Initialization / Non-transitional Device With Legacy Driver} and
+\ref{sec:Virtio Transport Options / Virtio Over PCI Bus /
+PCI-specific Initialization And Device Operation / Device
+Initialization}.
+} \\
+\hline
+508 & 22 Apr 2015 & Michael S. Tsirkin & {VIRTIO-139:
+pci: missing documentation for dealing with 64 bit config fields
+    
+pci spec says what width access to use for 32, 16 and 8
+bit fields, but does not explicitly say what to do for
+32 bit fields. As we have text that says driver must
+treat 64 bit accesses as non-atomic, this seems
+to imply driver should always do two 32 bit wide accesses.
+
+Let's make this an explicit requirement, and require
+devices to support this.
+
+See \ref{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI
+Device Layout}, \ref{drivernormative:Virtio Transport Options /
+Virtio Over PCI Bus / PCI Device Layout},
+\ref{devicenormative:Virtio Transport Options / Virtio Over PCI
+Bus / PCI Device Layout} and \ref{sec:Conformance / Driver
+Conformance / PCI Driver Conformance}.
+ } \\
+\hline
+509 & 22 Apr 2015 & Michael S. Tsirkin & {balloon:
+MUST -> has to
+
+MUST shouldn't be used outside normative statements,
+that's confusing. Replace with "has to".
+
+See \ref{sec:Device Types / Memory Balloon Device / Feature
+bits}.
+ } \\
+\hline
+510 & 22 Apr 2015 & Michael S. Tsirkin & {conformance:
+add VIRTIO-137 statement links
+
+Add links to new conformance statements added to
+resolve VIRTIO-137 (describing used ring entry len usage).
+
+See \ref{sec:Conformance / Device Conformance}
+and \ref{sec:Conformance / Driver Conformance}.
+ } \\
+\hline
+517 & 22 Apr 2015 & Michael S. Tsirkin & {acknowledgements:
+contributors+minor fixup
+
+acknowledge feedback by Jason Wang, add Richard Sohn who
+joined the TC, sort acknowledged reviewers alphabetically.
+
+See \ref{chap:Acknowledgements}.
+} \\
+\hline
+520 & 30 Apr 2015 & James Bottomley & {VIRTIO-140:
+give explicit guidance on the use of 64 bit fields
+
+Just saying 64 bit fields may not be atomic is true, but less
+helpful than it might be.  Add explicit guidance about what the
+consequences of non-atomicity are.
+
+See \ref{sec:Creating New Device Types / What Device
+Configuration Space Layout?}
+} \\
+\hline
+521 & 30 Apr 2015 & Rusty Russell & {VIRTIO-134:
+Spell out details of indirect elements in chains
+    
+1) It's implied that a chain terminates with an indirect descriptor (since
+VIRTIO-15) but we didn't spell out that a device MUST NOT
+continue it.
+    
+2) We allow [direct]->[direct]->[indirect], and qemu and
+bhyve both accept it.  Make it clear that this is valid, thus devices MUST
+handle it.
+
+See \ref{drivernormative:Basic Facilities of a Virtio Device /
+Virtqueues / The Virtqueue Descriptor Table / Indirect
+Descriptors} and \ref{devicenormative:Basic Facilities of a
+Virtio Device / Virtqueues / The Virtqueue Descriptor Table /
+Indirect Descriptors}
+} \\
+\hline
+522 & 30 Apr 2015 & Michael S. Tsirkin & {VIRTIO-141:
+used ring: specify legacy behaviour for len field
+
+many hypervisors implemented len field incorrectly.
+Document existing bugs in the legacy sections.
+
+See \ref{sec:Basic Facilities of a Virtio Device / Virtqueues
+/ The Virtqueue Used Ring/ Legacy Interface: The Virtqueue Used
+Ring}, \ref{sec:Device Types / Network Device / Device Operation
+/ Legacy Interface: Device Operation}, \ref{sec:Device Types /
+Block Device / Device Operation / Legacy Interface: Device
+Operation}, \ref{sec:Device Types / Console Device / Device
+Operation / Legacy Interface: Device Operation}, \ref{sec:Device
+Types / Memory Balloon Device / Device Operation / Legacy
+Interface: Device Operation}, \ref{sec:Device
+Types / SCSI Host Device / Device Operation / Legacy
+Interface: Device Operation} and \ref{sec:Conformance / Legacy
+Interface: Transitional Device and Transitional Driver
+Conformance}.
+} \\
+\hline
+523 & 30 Apr 2015 & Michael S. Tsirkin & {VIRTIO-142:
+entropy device: typo fix
+
+Current text: "The driver MUST examine the length written by the
+driver" makes no sense. length is written by the device.
+
+See \ref{drivernormative:Device Types / Entropy Device / Device
+Operation}.
+} \\
+\hline
+526 & 18 May 2015 & Michael S. Tsirkin & {VIRTIO-143:
+balloon: transitional device support
+
+Support a transitional balloon device: this has the advantage of supporting
+existing drivers, transparently, as well as transports that don't allow mixing
+virtio 0 and virtio 1 devices. And balloon is an easy device to test, so it's
+also useful for people to test virtio core handling of transitional devices.
+
+Three issues with legacy hypervisors have been identified:
+\begin{enumerate}
+\item
+Actual value is actually used, and is necessary for management
+to work. Luckily 4 byte config space writes are now atomic.
+When using old guests, hypervisors can detect access to the last byte.
+When using old hypervisors, drivers can use atomic 4-byte accesses.
+\item Hypervisors actually didn't ignore the stats from the first
+buffer supplied. This means the values there would be
+incorrect until hypervisor resends the request.
+Add a note suggesting hypervisors ignore the 1st buffer.
+\item QEMU simply over-writes stats from each buffer it gets.
+Thus if driver supplies a different subset of stats
+on each request, stale values will be there.
+Require drivers to supply the same subset on each
+request. This also gives us a simple way to figure out
+which stats are supported.
+\end{enumerate}
+
+See
+\ref{sec:Device Types / Memory Balloon Device},
+\ref{devicenormative:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Discovery},
+\ref{sec:Conformance / Driver Conformance / Traditional Memory Balloon Driver Conformance},
+\ref{sec:Conformance / Device Conformance / Traditional Memory Balloon Device Conformance},
+\ref{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance},
+\ref{sec:Conformance / Device Conformance} and \ref{sec:Conformance / Driver Conformance}.
+} \\
+\hline
+527 & 18 May 2015 & Michael S. Tsirkin & {VIRTIO-126:
+document deflate on oom
+
+Document the new option, and also clarify behaviour
+without it.
+
+In particular, actual field is not the
+actual number of pages in the balloon as
+driver might do inflate followed by deflate.
+
+Also, device isn't always driven by interrupts,
+driver can inflate/deflate in response to e.g.
+memory compaction.
+
+See \ref{sec:Device Types / Memory Balloon Device / Feature bits},
+\ref{sec:Device Types / Memory Balloon Device / Device Operation} and
+\ref{drivernormative:Device Types / Memory Balloon Device / Device Operation}.
+} \\
+\hline
+528 & 18 May 2015 & Michael S. Tsirkin & {VIRTIO-123:
+network device: xmit/receive cleanup
+
+Fix up multiple issues in xmit/receive sections:
+\begin{itemize}
+   \item drop MAY/MUST/SHOULD outside normative statements
+   \item spell out conformance requirements for both drivers and
+      devices, for xmit and receive paths
+   \item document the missing VIRTIO_NET_HDR_F_DATA_VALID
+   \item document handling of unrecognized flag bits so we can extend
+      flags in the future, similar to VIRTIO_NET_HDR_F_DATA_VALID
+\end{itemize}
+
+\ref{sec:Device Types / Network Device / Device Initialization},
+\ref{drivernormative:Device Types / Network Device / Device Operation / Packet Transmission},
+\ref{devicenormative:Device Types / Network Device / Device Operation / Packet Transmission},
+\ref{sec:Device Types / Network Device / Device Operation / Processing of Incoming Packets},
+\ref{sec:Conformance / Driver Conformance / Network Driver Conformance} and
+\ref{sec:Conformance / Device Conformance / Network Device Conformance}.
+} \\
+\hline
+529 & 18 May 2015 & Michael S. Tsirkin & {VIRTIO-124:
+network device: document VIRTIO_NET_F_CTRL_RX_EXTRA
+
+See
+\ref{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Packet Receive Filtering},
+\ref{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Setting MAC Address Filtering},
+\ref{sec:Conformance / Driver Conformance / Network Driver Conformance} and
+\ref{sec:Conformance / Device Conformance / Network Device Conformance}.
+} \\
+\hline