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.

VIRTIO-138

Signed-off-by: Michael S. Tsirkin <mst@redhat.com>

git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio/branches/v1.0@506 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652

1 files changed, 18 insertions, 19 deletions

diff --git a/content.tex b/content.tex
index 9120730..5a1a989 100644
--- a/content.tex
+++ b/content.tex
@@ -1636,10 +1636,25 @@ on PCI Device Layout}\label{sec:Virtio Transport Options / Virtio
 Over PCI Bus / PCI Device Layout / Non-transitional Device With
 Legacy Driver: A Note on PCI Device Layout}
 
+All known legacy drivers check either the PCI Revision or the
+Device and Vendor IDs, and thus won't attempt to drive a
+non-transitional device.
+
+A buggy legacy driver might mistakenly attempt to drive a
+non-transitional device. If support for such drivers is required
+(as opposed to fixing the bug), the following would be the
+recommended way to detect and handle them.
+\begin{note}
+Such buggy drivers are not currently known to be used in
+production.
+\end{note}
+
+\devicenormative{\paragraph}{Non-transitional Device With Legacy Driver}{Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Device Initialization / Non-transitional Device With Legacy Driver}
 Non-transitional devices, on a platform where a legacy driver for
-a legacy device with the same ID might have previously existed,
-SHOULD take the following steps to fail gracefully when a legacy
-driver attempts to drive them:
+a legacy device with the same ID (including PCI Revision, Device
+and Vendor IDs) is known to have previously existed,
+SHOULD take the following steps to cause the legacy driver to
+fail gracefully when it attempts to drive them:
 
 \begin{enumerate}
 \item Present an I/O BAR in BAR0, and
@@ -1660,22 +1675,6 @@ As a prerequisite to device initialization, the driver scans the
 PCI capability list, detecting virtio configuration layout using Virtio
 Structure PCI capabilities as detailed in \ref{sec:Virtio Transport Options / Virtio Over PCI Bus / Virtio Structure PCI Capabilities}
 
-\paragraph{Non-transitional Device With Legacy Driver}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Device Initialization / Non-transitional Device With Legacy Driver}
-
-\devicenormative{\subparagraph}{Non-transitional Device With Legacy Driver}{Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Device Initialization / Non-transitional Device With Legacy Driver}
-
-Non-transitional devices, on a platform where a legacy driver for
-a legacy device with the same ID might have previously existed,
-MUST take the following steps to fail gracefully when a legacy
-driver attempts to drive them:
-
-\begin{enumerate}
-\item Present an I/O BAR in BAR0, and
-\item Respond to a single-byte zero write to offset 18
-   (corresponding to Device Status register in the legacy layout)
-   of BAR0 by presenting zeroes on every BAR and ignoring writes.
-\end{enumerate}
-
 \subparagraph{Legacy Interface: A Note on Device Layout Detection}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Device Initialization / Virtio Device Configuration Layout Detection / Legacy Interface: A Note on Device Layout Detection}
 
 Legacy drivers skipped the Device Layout Detection step, assuming legacy