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-ring.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