From b76aef36e43b5444e87de5a4ce273f6af346a8e1 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Sun, 11 Oct 2015 15:13:22 +0000 Subject: cl: clear it out for cs03 Signed-off-by: Michael S. Tsirkin git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@543 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- cl-cs03.tex | 328 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 328 insertions(+) create mode 100644 cl-cs03.tex (limited to 'cl-cs03.tex') diff --git a/cl-cs03.tex b/cl-cs03.tex new file mode 100644 index 0000000..ab26d64 --- /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-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 -- cgit v1.2.3 From 4331df88a9c1db818c600d93e44b9cabab04e525 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Tue, 16 Feb 2016 17:10:51 +0000 Subject: virtio-ring.h -> virtio-queue.h Since vring* and VRING* have been replaced with virtq* and VIRTQ* respectively, rename the header virtio_ring.h to virtio_queue.h. Suggested-by: Kevin Lo Signed-off-by: Michael S. Tsirkin Acked-by: Cornelia Huck git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@558 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- cl-cs03.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'cl-cs03.tex') diff --git a/cl-cs03.tex b/cl-cs03.tex index ab26d64..72925ca 100644 --- a/cl-cs03.tex +++ b/cl-cs03.tex @@ -43,7 +43,7 @@ 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}. +See Appendix \ref{sec:virtio-queue.h}. } \\ \hline 486 & 15 Mar 2015 & Jason Wang & {VIRTIO-136: -- cgit v1.2.3