summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--REVISION2
-rw-r--r--REVISION-DATE2
-rw-r--r--acknowledgements.tex3
-rw-r--r--cl-cs03.tex328
-rw-r--r--cl-os.tex370
-rw-r--r--conformance.tex2
-rw-r--r--content.tex175
-rw-r--r--diffpreamble.tex11
-rw-r--r--fixupdiff.pl82
-rw-r--r--headerfile.tex6
-rw-r--r--introduction.tex10
-rwxr-xr-xmakediff.sh9
-rwxr-xr-xmakezip.sh4
-rw-r--r--specvars.tex2
-rw-r--r--title.tex8
-rw-r--r--virtio-queue.h (renamed from virtio-ring.h)0
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