diff options
| -rw-r--r-- | REVISION | 2 | ||||
| -rw-r--r-- | REVISION-DATE | 2 | ||||
| -rw-r--r-- | acknowledgements.tex | 3 | ||||
| -rw-r--r-- | cl-cs03.tex | 328 | ||||
| -rw-r--r-- | cl-os.tex | 370 | ||||
| -rw-r--r-- | conformance.tex | 2 | ||||
| -rw-r--r-- | content.tex | 175 | ||||
| -rw-r--r-- | diffpreamble.tex | 11 | ||||
| -rw-r--r-- | fixupdiff.pl | 82 | ||||
| -rw-r--r-- | headerfile.tex | 6 | ||||
| -rw-r--r-- | introduction.tex | 10 | ||||
| -rwxr-xr-x | makediff.sh | 9 | ||||
| -rwxr-xr-x | makezip.sh | 4 | ||||
| -rw-r--r-- | specvars.tex | 2 | ||||
| -rw-r--r-- | title.tex | 8 | ||||
| -rw-r--r-- | virtio-queue.h (renamed from virtio-ring.h) | 0 |
16 files changed, 614 insertions, 400 deletions
@@ -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 @@ -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 @@ -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} @@ -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 |