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

16 files changed, 614 insertions, 400 deletions

diff --git a/REVISION b/REVISION
index 376c82e..6a9f46a 100644
--- a/REVISION
+++ b/REVISION
@@ -1 +1 @@
-virtio-v1.0-cs03
+virtio-v1.0-cs04
diff --git a/REVISION-DATE b/REVISION-DATE
index 86ffb4e..d14a9a6 100644
--- a/REVISION-DATE
+++ b/REVISION-DATE
@@ -1 +1 @@
-02 August 2015
+03 March 2016
diff --git a/acknowledgements.tex b/acknowledgements.tex
index 6c86d12..53942b0 100644
--- a/acknowledgements.tex
+++ b/acknowledgements.tex
@@ -41,6 +41,7 @@ Gerd Hoffmann, Red Hat	\newline
 Jason Wang, Red Hat \newline
 Laura Novich, Red Hat	\newline
 Patrick Durusau,	Technical Advisory Board, OASIS	\newline
-Thomas Huth,	IBM	\newline
+Thomas Huth,	Red Hat	\newline
 Yan Vugenfirer, Red Hat / Daynix	\newline
+Kevin Lo,	MSI	\newline
 \end{oasistitlesection}
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
diff --git a/cl-os.tex b/cl-os.tex
index ab26d64..da78bf8 100644
--- a/cl-os.tex
+++ b/cl-os.tex
@@ -1,328 +1,134 @@
-478 & 15 Mar 2015 & Cornelia Huck & {VIRTIO-129: legacy:
-clean up virtqueue layout definitions
+540 & 11 Oct 2015 & Greg Kurz & {virtqueues: fix
+trivial typo
 
-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}.
- } \\
+See
+\ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Interrupt Suppression}.
+} \\
 \hline
-479 & 15 Mar 2015 & Cornelia Huck & {VIRTIO-118:
-ccw: clarify basic channel commands
+541 & 11 Oct 2015 & Paolo Bonzini & {virtio-blk: fix typo
+in legacy framing requirements section
 
-"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}.
+See
+\ref{sec:Device Types / Block Device / Legacy Interface: Framing Requirements}.
 } \\
 \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-ring.h}.
- } \\
-\hline
-486 & 15 Mar 2015 & Jason Wang & {VIRTIO-136:
-document idx field in virtqueue used ring
+545 & 18 Oct 2015 & Paolo Bonzini & {virtio-blk: restore VIRTIO_BLK_F_FLUSH and VIRTIO_BLK_F_CONFIG_WCE
 
-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
+VIRTIO_BLK_F_CONFIG_WCE is important in order to achieve good performance
+(up to 2x, though more realistically +30-40\%) in latency-bound workloads.
+However, it was removed by mistake together with VIRTIO_BLK_F_FLUSH.
 
-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.
+In addition, even removing VIRTIO_BLK_F_FLUSH was probably not a great
+idea, because it simplifies simple drivers (e.g. firmware) that are okay
+with a writethrough cache but still need data to persist after power loss.
+What really should have been removed is just the possibility that devices
+not propose VIRTIO_BLK_F_FLUSH, but even that only deserves a "SHOULD" in
+the new world of conformance statements.
 
-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
+Restore these, with the following changes:
 
-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
+* clarify and use conformance statements in order to define writeback
+and writethrough caching according to what is commonly done by high-end
+storage.
 
-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.
+* clarify (with conformance statements) the influence of the
+VIRTIO_BLK_F_FLUSH feature on caching and how to proceed if only one of
+VIRTIO_BLK_F_FLUSH and VIRTIO_BLK_F_CONFIG_WCE is negotiated.
 
-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.
+* strengthen the requirement for persisting writes to MUST after
+a VIRTIO_BLK_T_FLUSH request (and in other cases too involving the
+new features).
 
-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.
+The suggested behavior upon feature negotiation is okay for the Linux
+implementation of virtio1, even after the implementation is modified to
+support the two new features.
 
-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}.
+This fixes VIRTIO-144.
+
+See \ref{sec:Device Types / Block Device},
+\ref{sec:Conformance / Driver Conformance / Block Driver Conformance} and
+\ref{sec:Conformance / Device Conformance / Block Device Conformance}.
 } \\
 \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.
+546 & 18 Oct 2015 & Michael S. Tsirkin & {pci: clarify configuration access capability rules
 
-Let's make this an explicit requirement, and require
-devices to support this.
+The point of the configuration access capability is to enable
+access to other capabilities.  The intent never was to allow
+writes to a random place within device BARs.
+Limiting drivers simplifies devices - and devices can always
+add another capability if drivers ever want to access
+some other range.
 
-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".
+This resolves VIRTIO-145.
 
-See \ref{sec:Device Types / Memory Balloon Device / Feature
-bits}.
- } \\
+See \ref{drivernormative:Virtio Transport Options / Virtio Over
+PCI Bus / PCI Device Layout / PCI configuration access
+capability}.
+} \\
 \hline
-510 & 22 Apr 2015 & Michael S. Tsirkin & {conformance:
-add VIRTIO-137 statement links
+547 & 18 Oct 2015 & Michael S. Tsirkin & {add advice on transition from legacy interfaces
 
-Add links to new conformance statements added to
-resolve VIRTIO-137 (describing used ring entry len usage).
+Reading legacy chapters gives a hint about what changed,
+let's help readers discover this useful shortcut.
 
-See \ref{sec:Conformance / Device Conformance}
-and \ref{sec:Conformance / Driver Conformance}.
- } \\
-\hline
-517 & 22 Apr 2015 & Michael S. Tsirkin & {acknowledgements:
-contributors+minor fixup
+This resolves VIRTIO-146.
 
-acknowledge feedback by Jason Wang, add Richard Sohn who
-joined the TC, sort acknowledged reviewers alphabetically.
-
-See \ref{chap:Acknowledgements}.
+See \ref{sec:Transition from earlier specification drafts}.
 } \\
 \hline
-520 & 30 Apr 2015 & James Bottomley & {VIRTIO-140:
-give explicit guidance on the use of 64 bit fields
+554 & 16 Feb 2016 & Thomas Huth & {virtio-net: fix inconsistent legacy header size
 
-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.
+    Current text says:
+    	The legacy driver only presented num_buffers in the struct
+    	virtio_net_hdr when VIRTIO_NET_F_MRG_RXBUF was not negotiated;
 
-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.
+    Should be:
+    	"\dots was negotiated \dots" instead of "\dots was not negotiated \dots"
 
-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
+    To be consistent with the following:
+    	without that feature the structure was 2 bytes shorter.
 
-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}.
+See \ref{sec:Device Types / Network Device / Device Operation / Legacy Interface: Device Operation}.
 } \\
 \hline
-523 & 30 Apr 2015 & Michael S. Tsirkin & {VIRTIO-142:
-entropy device: typo fix
+555 & 16 Feb 2016 & Michael S. Tsirkin & {virtio header: tweak
+change motivation
 
-Current text: "The driver MUST examine the length written by the
-driver" makes no sense. length is written by the device.
+    The changes are not just to remove Linux assumptions,
+    we have also renamed ring->queue.
+    Tweak the header description accordingly.
 
-See \ref{drivernormative:Device Types / Entropy Device / Device
-Operation}.
+See \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Helpers for Operating Virtqueues}.
 } \\
 \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.
+558 & 16 Feb 2016 & Michael S. Tsirkin & {rename virtio_ring.h to virtio_queue.h
 
-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}
+    Since vring* and VRING* have been replaced with virtq* and VIRTQ*
+    respectively, rename the header virtio_ring.h to virtio_queue.h.
 
-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}.
+See \ref{sec:virtio-queue.h}.
 } \\
 \hline
-527 & 18 May 2015 & Michael S. Tsirkin & {VIRTIO-126:
-document deflate on oom
+559 & 16 Feb 2016 & Michael S. Tsirkin & {init: sort status bits
 
-Document the new option, and also clarify behaviour
-without it.
+    Status bit order is inconsistent: they are neither in increasing
+    order nor in the order they are likely to be used.
 
-In particular, actual field is not the
-actual number of pages in the balloon as
-driver might do inflate followed by deflate.
+    The second approach seems more useful since there aren't
+    that many bits, so the numerical order does not help much.
 
-Also, device isn't always driven by interrupts,
-driver can inflate/deflate in response to e.g.
-memory compaction.
+    A typical order of use would be:
 
-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
+\begin{itemize}   
+\item    ACKNOWLEDGE
+\item    DRIVER
+\item    then either FAILED or FEATURES_OK
+\item    then either FAILED or DRIVER_OK
+\item    then DEVICE_NEEDS_RESET (if device detects an error)
 \end{itemize}
+    
+    Sort the bits accordingly.
 
-\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}.
+See \ref{sec:Basic Facilities of a Virtio Device / Device Status Field}.
 } \\
 \hline
diff --git a/conformance.tex b/conformance.tex
index 7b7df32..f59e360 100644
--- a/conformance.tex
+++ b/conformance.tex
@@ -105,6 +105,7 @@ A network driver MUST conform to the following normative statements:
 A block driver MUST conform to the following normative statements:
 
 \begin{itemize}
+\item \ref{drivernormative:Device Types / Block Device / Device Initialization}
 \item \ref{drivernormative:Device Types / Block Device / Device Operation}
 \end{itemize}
 
@@ -224,6 +225,7 @@ A network device MUST conform to the following normative statements:
 A block device MUST conform to the following normative statements:
 
 \begin{itemize}
+\item \ref{devicenormative:Device Types / Block Device / Device Initialization}
 \item \ref{devicenormative:Device Types / Block Device / Device Operation}
 \end{itemize}
 
diff --git a/content.tex b/content.tex
index d989d98..4b45678 100644
--- a/content.tex
+++ b/content.tex
@@ -22,7 +22,8 @@ The \field{device status} field provides a simple low-level
 indication of the completed steps of this sequence.
 It's most useful to imagine it hooked up to traffic
 lights on the console indicating the status of each device.  The
-following bits are defined:
+following bits are defined (listed below in the order in which
+they would be typically set):
 \begin{description}
 \item[ACKNOWLEDGE (1)] Indicates that the guest OS has found the
   device and recognized it as a valid virtio device.
@@ -34,6 +35,11 @@ following bits are defined:
     this bit.  For example, under Linux, drivers can be loadable modules.
   \end{note}
 
+\item[FAILED (128)] Indicates that something went wrong in the guest,
+  and it has given up on the device. This could be an internal
+  error, or the driver didn't like the device for some reason, or
+  even a fatal error during device operation.
+
 \item[FEATURES_OK (8)] Indicates that the driver has acknowledged all the
   features it understands, and feature negotiation is complete.
 
@@ -42,11 +48,6 @@ following bits are defined:
 
 \item[DEVICE_NEEDS_RESET (64)] Indicates that the device has experienced
   an error from which it can't recover.
-
-\item[FAILED (128)] Indicates that something went wrong in the guest,
-  and it has given up on the device. This could be an internal
-  error, or the driver didn't like the device for some reason, or
-  even a fatal error during device operation.
 \end{description}
 
 \drivernormative{\subsection}{Device Status Field}{Basic Facilities of a Virtio Device / Device Status Field}
@@ -442,7 +443,7 @@ this implies that loops in the descriptor chain are forbidden!
 \subsubsection{Indirect Descriptors}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table / Indirect Descriptors}
 
 Some devices benefit by concurrently dispatching a large number
-of large requests. The VIRTIO_F_INDIRECT_DESC feature allows this (see \ref{sec:virtio-ring.h}~\nameref{sec:virtio-ring.h}). To increase
+of large requests. The VIRTIO_F_INDIRECT_DESC feature allows this (see \ref{sec:virtio-queue.h}~\nameref{sec:virtio-queue.h}). To increase
 ring capacity the driver can store a table of indirect
 descriptors anywhere in memory, and insert a descriptor in main
 virtqueue (with \field{flags}\&VIRTQ_DESC_F_INDIRECT on) that refers to memory buffer
@@ -522,7 +523,7 @@ VRING_AVAIL_F_NO_INTERRUPT, but the layout and value were identical.
 If the VIRTIO_F_EVENT_IDX feature bit is not negotiated,
 the \field{flags} field in the available ring offers a crude mechanism for the driver to inform
 the device that it doesn't want interrupts when buffers are used.  Otherwise
-\field{used_event} is a more performant alterative where the driver
+\field{used_event} is a more performant alternative where the driver
 specifies how far the device can progress before interrupting.
 
 Neither of these interrupt suppression methods are reliable, as they
@@ -717,7 +718,7 @@ helper routines in a more usable form, in
 include/uapi/linux/virtio_ring.h. This was explicitly licensed by IBM
 and Red Hat under the (3-clause) BSD license so that it can be
 freely used by all other projects, and is reproduced (with slight
-variation to remove Linux assumptions) in \ref{sec:virtio-ring.h}~\nameref{sec:virtio-ring.h}.
+variation) in \ref{sec:virtio-queue.h}~\nameref{sec:virtio-queue.h}.
 
 \chapter{General Initialization And Device Operation}\label{sec:General Initialization And Device Operation}
 
@@ -1132,6 +1133,7 @@ The virtio device configuration layout includes several structures:
 \item Notifications
 \item ISR Status
 \item Device-specific configuration (optional)
+\item PCI configuration access
 \end{itemize}
 
 Each structure can be mapped by a Base Address register (BAR) belonging to
@@ -1578,6 +1580,12 @@ at BAR selected by \field{cap.bar} and store the first \field{cap.length} bytes
 The driver MUST NOT write a \field{cap.offset} which is not
 a multiple of \field{cap.length} (ie. all accesses MUST be aligned).
 
+The driver MUST NOT read or write \field{pci_cfg_data}
+unless \field{cap.bar}, \field{cap.length} and \field{cap.offset}
+address \field{cap.length} bytes within a BAR range
+specified by some other Virtio Structure PCI Capability
+of type other than \field{VIRTIO_PCI_CAP_PCI_CFG}.
+
 \subsubsection{Legacy Interfaces: A Note on PCI Device Layout}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Legacy Interfaces: A Note on PCI Device Layout}
 
 Transitional devices MUST present part of configuration
@@ -3261,7 +3269,7 @@ according to the native endian of the guest rather than
 (necessarily when not using the legacy interface) little-endian.
 
 The legacy driver only presented \field{num_buffers} in the struct virtio_net_hdr
-when VIRTIO_NET_F_MRG_RXBUF was not negotiated; without that feature the
+when VIRTIO_NET_F_MRG_RXBUF was negotiated; without that feature the
 structure was 2 bytes shorter.
 
 When using the legacy interface, the driver SHOULD ignore the
@@ -4041,8 +4049,13 @@ device except where noted.
 
 \item[VIRTIO_BLK_F_BLK_SIZE (6)] Block size of disk is in \field{blk_size}.
 
+\item[VIRTIO_BLK_F_FLUSH (9)] Cache flush command support.
+
 \item[VIRTIO_BLK_F_TOPOLOGY (10)] Device exports information on optimal I/O
     alignment.
+
+\item[VIRTIO_BLK_F_CONFIG_WCE (11)] Device can toggle its cache between writeback
+    and writethrough modes.
 \end{description}
 
 \subsubsection{Legacy Interface: Feature bits}\label{sec:Device Types / Block Device / Feature bits / Legacy Interface: Feature bits}
@@ -4051,16 +4064,12 @@ device except where noted.
 \item[VIRTIO_BLK_F_BARRIER (0)] Device supports request barriers.
 
 \item[VIRTIO_BLK_F_SCSI (7)] Device supports scsi packet commands.
-
-\item[VIRTIO_BLK_F_FLUSH (9)] Cache flush command support.
-
-\item[VIRTIO_BLK_F_CONFIG_WCE (11)] Device can toggle its cache between writeback
-    and writethrough modes.
 \end{description}
 
-VIRTIO_BLK_F_FLUSH was also called VIRTIO_BLK_F_WCE: Legacy drivers
-MUST only negotiate this feature if they are capable of sending
-VIRTIO_BLK_T_FLUSH commands.
+\begin{note}
+  In the legacy interface, VIRTIO_BLK_F_FLUSH was also
+  called VIRTIO_BLK_F_WCE.
+\end{note}
 
 \subsection{Device configuration layout}\label{sec:Device Types / Block Device / Device configuration layout}
 
@@ -4089,7 +4098,7 @@ struct virtio_blk_config {
                 // optimal (suggested maximum) I/O size in blocks
                 le32 opt_io_size;
         } topology;
-        u8 reserved;
+        u8 writeback;
 };
 \end{lstlisting}
 
@@ -4119,21 +4128,63 @@ according to the native endian of the guest rather than
   \field{topology} struct can be read to determine the physical block size and optimal
   I/O lengths for the driver to use. This also does not affect the units
   in the protocol, only performance.
+
+\item If the VIRTIO_BLK_F_CONFIG_WCE feature is negotiated, the cache
+  mode can be read or set through the \field{writeback} field.  0 corresponds
+  to a writethrough cache, 1 to a writeback cache\footnote{Consistent with
+    \ref{devicenormative:Device Types / Block Device / Device Operation},
+    a writethrough cache can be defined broadly as a cache that commits
+    writes to persistent device backend storage before reporting their
+    completion. For example, a battery-backed writeback cache actually
+    counts as writethrough according to this definition.}.  The cache mode
+  after reset can be either writeback or writethrough.  The actual
+  mode can be determined by reading \field{writeback} after feature
+  negotiation.
 \end{enumerate}
 
+\drivernormative{\subsubsection}{Device Initialization}{Device Types / Block Device / Device Initialization}
+
+Drivers SHOULD NOT negotiate VIRTIO_BLK_F_FLUSH if they are incapable of
+sending VIRTIO_BLK_T_FLUSH commands.
+
+If neither VIRTIO_BLK_F_CONFIG_WCE nor VIRTIO_BLK_F_FLUSH are
+negotiated, the driver MAY deduce the presence of a writethrough cache.
+If VIRTIO_BLK_F_CONFIG_WCE was not negotiated but VIRTIO_BLK_F_FLUSH was,
+the driver SHOULD assume presence of a writeback cache.
+
+The driver MUST NOT read \field{writeback} before setting
+the FEATURES_OK \field{status} bit.
+
+\devicenormative{\subsubsection}{Device Initialization}{Device Types / Block Device / Device Initialization}
+
+Devices SHOULD always offer VIRTIO_BLK_F_FLUSH, and MUST offer it
+if they offer VIRTIO_BLK_F_CONFIG_WCE.
+
+If VIRTIO_BLK_F_CONFIG_WCE is negotiated but VIRTIO_BLK_F_FLUSH
+is not, the device MUST initialize \field{writeback} to 0.
+
 \subsubsection{Legacy Interface: Device Initialization}\label{sec:Device Types / Block Device / Device Initialization / Legacy Interface: Device Initialization}
 
-The \field{reserved} field used to be called \field{writeback}.  If the
-VIRTIO_BLK_F_CONFIG_WCE feature is offered, the cache mode can be
-read from \field{writeback}; the
-driver can also write to the field in order to toggle the cache
-between writethrough (0) and writeback (1) mode.  If the feature is
-not available, the driver can instead look at the result of
-negotiating VIRTIO_BLK_F_FLUSH: the cache will be in writeback mode
-after reset if and only if VIRTIO_BLK_F_FLUSH is negotiated.
+Because legacy devices do not have FEATURES_OK, transitional devices
+MUST implement slightly different behavior around feature negotiation
+when used through the legacy interface.  In particular, when using the
+legacy interface:
+
+\begin{itemize}
+\item the driver MAY read or write \field{writeback} before setting
+  the DRIVER or DRIVER_OK \field{status} bit
+
+\item the device MUST NOT modify the cache mode (and \field{writeback})
+  as a result of a driver setting a status bit, unless
+  the DRIVER_OK bit is being set and the driver has not set the
+  VIRTIO_BLK_F_CONFIG_WCE driver feature bit.
+
+\item the device MUST NOT modify the cache mode (and \field{writeback})
+  as a result of a driver modifying the driver feature bits, for example
+  if the driver sets the VIRTIO_BLK_F_CONFIG_WCE driver feature bit but
+  does not set the VIRTIO_BLK_F_FLUSH bit.
+\end{itemize}
 
-Some older legacy devices did not operate in writethrough mode even
-after a driver announced lack of support for VIRTIO_BLK_F_FLUSH.
 
 \subsection{Device Operation}\label{sec:Device Types / Block Device / Device Operation}
 
@@ -4183,14 +4234,66 @@ A driver SHOULD accept the VIRTIO_BLK_F_RO feature if offered.
 A driver MUST set \field{sector} to 0 for a VIRTIO_BLK_T_FLUSH request.
 A driver SHOULD NOT include any data in a VIRTIO_BLK_T_FLUSH request.
 
+If the VIRTIO_BLK_F_CONFIG_WCE feature is negotiated, the driver MAY
+switch to writethrough or writeback mode by writing respectively 0 and
+1 to the \field{writeback} field.  After writing a 0 to \field{writeback},
+the driver MUST NOT assume that any volatile writes have been committed
+to persistent device backend storage.
+
 \devicenormative{\subsubsection}{Device Operation}{Device Types / Block Device / Device Operation}
 
 A device MUST set the \field{status} byte to VIRTIO_BLK_S_IOERR
 for a write request if the VIRTIO_BLK_F_RO feature if offered, and MUST NOT
 write any data.
 
-Upon receipt of a VIRTIO_BLK_T_FLUSH request, the driver SHOULD ensure
-that any writes which were completed are committed to non-volatile storage.
+A write is considered volatile when it is submitted; the contents of
+sectors covered by a volatile write are undefined in persistent device
+backend storage until the write becomes stable.  A write becomes stable
+once it is completed and one or more of the following conditions is true:
+
+\begin{enumerate}
+\item\label{item:flush1} neither VIRTIO_BLK_F_CONFIG_WCE nor
+  VIRTIO_BLK_F_FLUSH feature were negotiated, but VIRTIO_BLK_F_FLUSH was
+  offered by the device;
+
+\item\label{item:flush2} the VIRTIO_BLK_F_CONFIG_WCE feature was negotiated and the
+  \field{writeback} field in configuration space was 0 \textbf{all the time between
+  the submission of the write and its completion};
+
+\item\label{item:flush3} a VIRTIO_BLK_T_FLUSH request is sent \textbf{after the write is
+  completed} and is completed itself.
+\end{enumerate}
+
+If the device is backed by persistent storage, the device MUST ensure that
+stable writes are committed to it, before reporting completion of the write
+(cases~\ref{item:flush1} and~\ref{item:flush2}) or the flush
+(case~\ref{item:flush3}).  Failure to do so can cause data loss
+in case of a crash.
+
+If the driver changes \field{writeback} between the submission of the write
+and its completion, the write could be either volatile or stable when
+its completion is reported; in other words, the exact behavior is undefined.
+
+% According to the device requirements for device initialization:
+%   Offer(CONFIG_WCE) => Offer(FLUSH).
+%
+% After reversing the implication:
+%   not Offer(FLUSH) => not Offer(CONFIG_WCE).
+
+If VIRTIO_BLK_F_FLUSH was not offered by the
+  device\footnote{Note that in this case, according to
+  \ref{devicenormative:Device Types / Block Device / Device Initialization},
+  the device will not have offered VIRTIO_BLK_F_CONFIG_WCE either.}, the
+device MAY also commit writes to persistent device backend storage before
+reporting their completion.  Unlike case~\ref{item:flush1}, however, this
+is not an absolute requirement of the specification.
+
+\begin{note}
+  An implementation that does not offer VIRTIO_BLK_F_FLUSH and does not commit
+  completed writes will not be resilient to data loss in case of crashes.
+  Not offering VIRTIO_BLK_F_FLUSH is an absolute requirement
+  for implementations that do not wish to be safe against such data losses.
+\end{note}
 
 \subsubsection{Legacy Interface: Device Operation}\label{sec:Device Types / Block Device / Device Operation / Legacy Interface: Device Operation}
 When using the legacy interface, transitional devices and drivers
@@ -4233,6 +4336,12 @@ serve as data consistency guarantee.  Only a VIRTIO_BLK_T_FLUSH request
 does that.
 \end{note}
 
+Some older legacy devices did not commit completed writes to persistent
+device backend storage when VIRTIO_BLK_F_FLUSH was offered but not
+negotiated.  In order to work around this, the driver MAY set the
+\field{writeback} to 0 (if available) or it MAY send an explicit flush
+request after every completed write.
+
 If the device has VIRTIO_BLK_F_SCSI feature, it can also support
 scsi packet command requests, each of these requests is of form:
 
@@ -4296,7 +4405,7 @@ negotiated VIRTIO_F_ANY_LAYOUT:
 
 \begin{itemize}
 \item MUST use a single 8-byte descriptor containing \field{type},
-  \field{reseved} and \field{sector}, followed by descriptors
+  \field{reserved} and \field{sector}, followed by descriptors
   for \field{data}, then finally a separate 1-byte descriptor
   for \field{status}.
 
@@ -5577,7 +5686,7 @@ contents of \field{event}. The following events are defined:
 \end{lstlisting}
 
   By sending this event, the device signals a change in the configuration parameters
-  of a logical unit, for example the capacity or caching mode.
+  of a logical unit, for example the capacity or cache mode.
   \field{event} is set to VIRTIO_SCSI_T_PARAM_CHANGE.
   \field{lun} addresses a logical unit in the SCSI host.
 
diff --git a/diffpreamble.tex b/diffpreamble.tex
index 9b5b7e5..f7b5cec 100644
--- a/diffpreamble.tex
+++ b/diffpreamble.tex
@@ -8,10 +8,13 @@
 
 %DIF COLOR PREAMBLE
 \RequirePackage{color}
-\providecommand{\DIFaddbegin}{\begingroup\color{green}\hypersetup{linkcolor=green,urlcolor=green}}
-\providecommand{\DIFaddend}{\hypersetup{linkcolor=blue,urlcolor=blue}\endgroup}
-\providecommand{\DIFdelbegin}{\begingroup\color{red}\hypersetup{linkcolor=red,urlcolor=red}}
-\providecommand{\DIFdelend}{\hypersetup{linkcolor=blue,urlcolor=blue}\endgroup}
+\providecommand{\DIFaddbegin}{\protect\color{green}\hypersetup{linkcolor=green,urlcolor=green}}
+\providecommand{\DIFaddend}{\protect\color{black}\hypersetup{linkcolor=blue,urlcolor=blue}}
+\providecommand{\DIFdelbegin}{\protect\color{red}\hypersetup{linkcolor=red,urlcolor=red}}
+\providecommand{\DIFdelend}{\protect\color{black}\hypersetup{linkcolor=blue,urlcolor=blue}}
+\providecommand{\DIFaddtext}[1]{\textcolor{blue}{\sf #1}}
+\providecommand{\DIFdeltext}[1]{\textcolor{red}{\footnotesize \sout{#1}}}
+
 %DIF END COLOR PREAMBLE
 \providecommand{\DIFaddtext}[1]{\textcolor{green}{\sf #1}}
 \providecommand{\DIFdeltext}[1]{\textcolor{red}{\footnotesize \sout{#1}}}
diff --git a/fixupdiff.pl b/fixupdiff.pl
index e557e2b..f66eaa3 100644
--- a/fixupdiff.pl
+++ b/fixupdiff.pl
@@ -1,76 +1,36 @@
-my $bufferdiff="";
-my $diff="";
-my $buffer="";
+use strict;
+
+my $lstlisting=0;
+
 while (<>) {
 	my $line = $_;
-	if (m/%DIFDELCMD\s+<\s+\\begin{lstlisting}/) {
+	if (m/%DIFDELCMD\s+<\s+\\begin\{lstlisting\}/) {
 		$lstlisting=1;
 		$line =~s/%DIFDELCMD\s+</{\\lstset{escapechar=\\\$} /;
 	}
 	if ($lstlisting) {
 		$line =~ s/%DIFDELCMD\s+< //;
-		if (not $line =~ m/\\(?:begin|end){lstlisting}/) {
+		if (not $line =~ m/\\(?:begin|end)\{lstlisting\}/) {
 			$line =~ s/([#&{} ])/\\$1/g;
-			$line =~ s/(.*)/\$\\DIFdel{$1}\$/;
+			$line =~ s/(.*)/\$\\DIFdel\{$1\}\$/;
 		}
 		#print "%FIXED BY RULE 1\n";
 	}
-	#In section headings, replace begin/end with begin/endFL,
-	#but be careful in case some tag spills over to the next
-	#line
-	if (m/\\(section|subsection|subsubsection|paragraph)/ and m/DIF/) {
-		my @list = split(/(\\DIF(?:add|del)(?:begin|end)(?:FL)?)/, $line, -1);
-		#if there's only one tag, don't touch it:
-		#matching one is on the other line
-		if ($#list >= 5) {
-			#if first tag is end, don't touch it - matching
-			#begin is on the previous line
-			if ($list[1] =~ m/begin$/) {
-				$list[1] .= "FL";
-			}
-			#if last tag is begin, don't touch it - matching
-			#end is on the next line
-			if ($list[$#list - 1] =~ m/end$/) {
-				$list[$#list - 1] .= "FL";
-			}
-		}
-		for (my $i = 3; $i <= $#list - 3; $i += 2) {
-			if (not $list[$i] =~ m/FL$/) {
-				$list[$i] .= "FL";
-			}
-		}
-		$line = join("", @list);
-		#print "%FIXED BY RULE 2\n";
-	}
-	#detect where we have DIFbegin/end cross
-	#enumerate/itemize environments and fix up
-	if (m/\\DIF(?:add|del)(?:begin|end)/) {
-		my @list = split(/(\\DIF(?:add|del)(?:begin|end)(?:FL)?)/, $line, -1);
-		$diff = $list[$#list - 1];
-		if ($diff =~ m/begin/) {
-			$diff =~ s/begin/end/;
-		} else {
-			$diff = "";
-		}
-	}
-	if ($diff ne "" and m/\\(?:begin|end){(?:enumerate|itemize)}$/ and not m/\\DIF/) {
-		$buffer = $line;
-		$bufferdiff = $diff;
-		$line = "";
-		#print "%BUFFERED BY RULE 3: $bufferdiff\n";
-	}
-	if ($buffer ne "" and $line ne "") {
-		if (m/^(\\DIF(?:add|del)end(?:FL)?)/ and $bufferdiff ne $1) {
-			$line =~ s/^(\\DIF(?:add|del)end(?:FL)?)//;
-			$buffer =~ s/(\\(?:begin|end){(?:enumerate|itemize)})$/$bufferdiff$1/;
-			#print "%FIXED BY RULE 3: $bufferdiff\n";
-		}
-		print $buffer;
-		$buffer = "";
-		$bufferdiff = "";
-	}
+
+	# Too many \color directives (generated by DIFdel/addbegin/end)
+	# confuse xetex, producing errors:
+	# WARNING ** Color stack overflow. Just ignore.
+	# and resulting in corrupted color in output.
+	# As a work-around, detect cases where it's safe, and replace \color with
+	# \textcolor.
+	# As a result, number of \color directives goes does sufficiently
+	# enough to avoid the overflow error.
+
+	$line =~ s/\\DIFdelbegin \\DIFdel\{([^}]*)\}\\DIFdelend/\\DIFdeltext{$1}/;
+	$line =~ s/\\DIFaddbegin \\DIFadd\{([^}]*)\}\\DIFaddend/\\DIFaddtext{$1}/;
+
 	print $line;
-	if (m/%DIFDELCMD\s+<\s+\\end{lstlisting}/) {
+	if (m/%DIFDELCMD\s+<\s+\\end\{lstlisting\}/) {
 		print "}\n";
 		$lstlisting=0;
 	}
diff --git a/headerfile.tex b/headerfile.tex
index b1a92c2..767005c 100644
--- a/headerfile.tex
+++ b/headerfile.tex
@@ -1,8 +1,8 @@
-\chapter{virtio_ring.h}\label{sec:virtio-ring.h}
-
+\chapter[virtio_queue.h]{virtio_queue.h}\label{sec:virtio-queue.h}
+\label{sec:virtio-ring.h}
 This file is also available at the link
 \virtiourlh.
 All definitions in this section are for non-normative reference
 only.
 
-\lstinputlisting{virtio-ring.h}
+\lstinputlisting{virtio-queue.h}
diff --git a/introduction.tex b/introduction.tex
index ac7eefa..979881e 100644
--- a/introduction.tex
+++ b/introduction.tex
@@ -126,6 +126,16 @@ Similarly, a driver MAY implement:
 Devices or drivers with no legacy compatibility are referred to as
 non-transitional devices and drivers, respectively.
 
+\subsection{Transition from earlier specification drafts}\label{sec:Transition from earlier specification drafts}
+
+For devices and drivers already implementing the legacy
+interface, some changes will have to be made to support this
+specification.
+
+In this case, it might be beneficial for the reader to focus on
+sections tagged "Legacy Interface" in the section title.
+These highlight the changes made since the earlier drafts.
+
 \section{Structure Specifications}
 
 Many device and driver in-memory structure layouts are documented using
diff --git a/makediff.sh b/makediff.sh
index 7d64c93..1dd75d4 100755
--- a/makediff.sh
+++ b/makediff.sh
@@ -9,7 +9,7 @@ export DATESTR=${DATESTR:-`cat REVISION-DATE`}
 MAIN=$1
 PATH=.:${PATH}
 cur="$PWD"
-oldrev=`git rev-list -1 origin/tags/v1.0-cs02`
+oldrev=`git rev-list -1 origin/tags/v1.0-cs03`
 newrev=`git rev-list -1 HEAD`
 rm -fr old new
 git clone $PWD old
@@ -19,11 +19,7 @@ while read -r rev; do
 	echo "Applying $rev"
 	git cherry-pick `git rev-list -1 -F --grep "$rev" $newrev` || exit 1
 done << 'EOF'
-Revert: formatting: mark change manually as changed in cs02
-cl: move out cs02 changelog
-cl: drop contents temporarily
-changelog: comment out header
-changelog: disable markup
+headerfile: rename virtio_ring to virtio queue
 EOF
 
 #mv specvars.tex specvars-orig.tex
@@ -56,6 +52,7 @@ sed 's/\\footnote{/\\footnote {/' new/flat.tex > new/flat-fixed.tex
 latexdiff-fast --config \
 "FLOATENV=(?:figure|longtable|table|tabular|plate|lstlisting|note|enumerate|itemize)[\w\d*@]*,PICTUREENV=(?:picture|DIFdeltextcstwo|DIFnomarkup|lstlisting)[\w\d*@]*" \
  --append-safecmd=field --append-textcmd=mmioreg \
+ --exclude-textcmd=chapter \
 --ignore-warnings -p diffpreamble.tex old/flat-fixed.tex \
 new/flat-fixed.tex > virtio-diff-tofix.tex
 perl fixupdiff.pl virtio-diff-tofix.tex > virtio-diff.tex
diff --git a/makezip.sh b/makezip.sh
index de52abf..3c94f8e 100755
--- a/makezip.sh
+++ b/makezip.sh
@@ -17,8 +17,8 @@ fi
 zip -d $SPECDOC.zip tex/.gitattributes
 rm -fr listings
 mkdir -p listings
-cp virtio-ring.h listings/virtio_ring.h
-zip $SPECDOC.zip listings/virtio_ring.h
+cp virtio-queue.h listings/virtio_queue.h
+zip $SPECDOC.zip listings/virtio_queue.h
 rm -fr tmpfilesforzip
 mkdir -p tmpfilesforzip/tex
 echo "$SPECDOC" > tmpfilesforzip/tex/REVISION
diff --git a/specvars.tex b/specvars.tex
index 1f7cd9f..84f8bae 100644
--- a/specvars.tex
+++ b/specvars.tex
@@ -7,7 +7,7 @@
 \urldef \virtiourltex\url{\virtiourlbase/tex/}
 \urldef \virtiourlpdf\url{\virtiourlbase/\virtiospecfile.pdf}
 \urldef \virtiourlhtml\url{\virtiourlbase/\virtiospecfile.html}
-\urldef \virtiourlh\url{\virtiourlbase/listings/virtio_ring.h}
+\urldef \virtiourlh\url{\virtiourlbase/listings/virtio_queue.h}
 \urldef \virtiourllatestpdf\url{http://docs.oasis-open.org/virtio/virtio/v\virtiorev/virtio-v\virtiorev.pdf}
 \urldef \virtiourllatesthtml\url{http://docs.oasis-open.org/virtio/virtio/v\virtiorev/virtio-v\virtiorev.html}
 \newcommand{\virtioworkproduct}{Standards Track Work Product}
diff --git a/title.tex b/title.tex
index 00eea75..8138417 100644
--- a/title.tex
+++ b/title.tex
@@ -20,10 +20,10 @@
 \end{oasistitlesection}
 
 \begin{oasistitlesection}{Previous version}
-\url{http://docs.oasis-open.org/virtio/virtio/v1.0/cs02/tex/}
+\url{http://docs.oasis-open.org/virtio/virtio/v1.0/cs03/tex/}
 {}(Authoritative)\newline
-\url{http://docs.oasis-open.org/virtio/virtio/v1.0/cs02/virtio-v1.0-cs02.pdf}\newline
-\url{http://docs.oasis-open.org/virtio/virtio/v1.0/cs02/virtio-v1.0-cs02.html}
+\url{http://docs.oasis-open.org/virtio/virtio/v1.0/cs03/virtio-v1.0-cs03.pdf}\newline
+\url{http://docs.oasis-open.org/virtio/virtio/v1.0/cs03/virtio-v1.0-cs03.html}
 \end{oasistitlesection}
 
 \begin{oasistitlesection}{Latest version}
@@ -36,12 +36,10 @@
 \end{oasistitlesection}
 
 \begin{oasistitlesection}{Chairs}
-Rusty Russell (\href{mailto:rusty@au.ibm.com}{rusty@au.ibm.com}), \href{http://www.ibm.com/}{IBM}\newline
 Michael S. Tsirkin (\href{mailto:mst@redhat.com}{mst@redhat.com}), \href{http://www.redhat.com/}{Red Hat}\newline
 \end{oasistitlesection}
 
 \begin{oasistitlesection}{Editors}
-Rusty Russell (\href{mailto:rusty@au.ibm.com}{rusty@au.ibm.com}), \href{http://www.ibm.com/}{IBM}\newline
 Michael S. Tsirkin (\href{mailto:mst@redhat.com}{mst@redhat.com}), \href{http://www.redhat.com/}{Red Hat}\newline
 Cornelia Huck (\href{mailto:cornelia.huck@de.ibm.com}{cornelia.huck@de.ibm.com}), \href{http://www.ibm.com/}{IBM}\newline
 Pawel Moll (\href{mailto:pawel.moll@arm.com}{pawel.moll@arm.com}), \href{http://www.arm.com/}{ARM}
diff --git a/virtio-ring.h b/virtio-queue.h
index 5a1e87d..5a1e87d 100644
--- a/virtio-ring.h
+++ b/virtio-queue.h