legacy interface: move to terminology

Change accepted on VIRTIO TC Meeting, 3 December 2013

VIRTIO-64

Cc: Patrick Durusau <patrick@durusau.net

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

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

1 files changed, 55 insertions, 31 deletions

diff --git a/introduction.tex b/introduction.tex
index 1091911..9b84b5b 100644
--- a/introduction.tex
+++ b/introduction.tex
@@ -34,37 +34,6 @@ between different transports.
   acknowledges those it understands and wishes to use.
 \end{description}
 
-\section{Terminology}\label{Terminology}
-
-The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in \hyperref[intro:rfc2119]{[RFC2119]}.
-
-An older specification (see \hyperref[intro:Virtio PCI Draft]{[Virtio PCI Draft]}) defined a
-similar, but different interface between the hypervisor and the guest.
-To simplify transition and note differences, the following terms are used:
-
-\begin{description}
-\item[Legacy Interface]
-        An interface specified by \hyperref[intro:Virtio PCI Draft]{[Virtio PCI Draft]}.
-\item[Legacy Device]
-        A device which implements \hyperref[intro:Virtio PCI Draft]{[Virtio PCI Draft]}, but not this specification.
-\item[Legacy Driver]
-        A driver which implements \hyperref[intro:Virtio PCI Draft]{[Virtio PCI Draft]}, but not this specification. 
-\item[Transitional Device]
-        A device which implements both this specification and the older
-        \hyperref[intro:Virtio PCI Draft]{[Virtio PCI Draft]}
-        specification, thus allowing legacy drivers.
-\item[Transitional Driver]
-        A driver which implements both this specification and the older
-        \hyperref[intro:Virtio PCI Draft]{[Virtio PCI Draft]}
-        specification, thus allowing legacy devices.
-\item[Non-Transitional Device]
-        A device which does not implement the
-        \hyperref[intro:Virtio PCI Draft]{[Virtio PCI Draft]} specification.
-\item[Non-Transitional Driver]
-        A driver which does not implement the
-        \hyperref[intro:Virtio PCI Draft]{[Virtio PCI Draft]} specification.
-\end{description}
-
 \section{Normative References}
 
 \begin{longtable}{l p{5in}}
@@ -100,6 +69,61 @@ To simplify transition and note differences, the following terms are used:
 	\newline\url{http://ozlabs.org/~rusty/virtio-spec/virtio-0.9.5.pdf}\\
 \end{longtable}
 
+\section{Terminology}\label{Terminology}
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in \hyperref[intro:rfc2119]{[RFC2119]}.
+
+\subsection{Legacy Interface: Terminology}\label{intro:Legacy
+Interface: Terminology}
+
+Earlier drafts of this specification (i.e. revisions before 1.0,
+see e.g. \hyperref[intro:Virtio PCI Draft]{[Virtio PCI Draft]})
+defined a similar, but different
+interface between the driver and the device.
+Since these are widely deployed, this specification
+accommodates OPTIONAL features to simplify transition
+from these earlier draft interfaces.
+
+Specifically devices and drivers MAY support:
+\begin{description}
+\item[Legacy Interface]
+        is an interface specified by an earlier draft of this specification
+        (before 1.0)
+\item[Legacy Device]
+        is a device implemented before this specification was released,
+        and implementing a legacy interface on the host side
+\item[Legacy Driver]
+        is a driver implemented before this specification was released,
+        and implementing a legacy interface on the guest side
+\end{description}
+
+Legacy devices and legacy drivers are not compliant with this
+specification.
+
+To simplify transition from these earlier draft interfaces,
+a device MAY implement:
+
+\begin{description}
+\item[Transitional Device]
+        a device supporting both drivers conforming to this
+        specification, and allowing legacy drivers.
+\end{description}
+
+Similarly, a driver MAY implement:
+\begin{description}
+\item[Transitional Driver]
+        a driver supporting both devices conforming to this
+        specification, and legacy devices.
+\end{description}
+
+\begin{note}
+  No legacy interfaces are required; ie. don't implement them unless you
+  have a need for backwards compatibility!
+\end{note}
+
+Devices or drivers with no legacy compatibility are referred to as
+non-transitional devices and drivers, respectively.
+
 \section{Structure Specifications}
 
 Many device and driver in-memory structure layouts are documented using