From e0c73f5462c8fe1fd7adae5620828c42042370af Mon Sep 17 00:00:00 2001
From: mstsirkin <mstsirkin@0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652>
Date: Sun, 2 Mar 2014 21:34:05 +0000
Subject: content: explain that legacy support is optional

Change accepted on VIRTIO TC Meeting, 3 December 2013

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

git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio@288 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652
---
 content.tex | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 58 insertions(+), 6 deletions(-)

(limited to 'content.tex')

diff --git a/content.tex b/content.tex
index 16ea610..7eb08d0 100644
--- a/content.tex
+++ b/content.tex
@@ -100,22 +100,74 @@ FEATURES_OK \field{device status} bit when the driver writes it.
 
 \subsection{Legacy Interface: A Note on transitions from earlier drafts}\label{sec:Basic Facilities of a Virtio Device / Feature Bits / Legacy Interface: A Note on transitions from earlier drafts}
 
-Careful consideration has been given on the transition from the older
-\hyperref[intro:Virtio PCI Draft]{[Virtio PCI Draft]} specification to
-this one.  Advice pertaining to transitional devices and drivers
-is contained in sections named 'Legacy Interface' like this one.
+%TODO: split out conformance sections
+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.
 
 \begin{note}
   No legacy interfaces are required; ie. don't implement them unless you
   have a need for backwards compatibility!
 \end{note}
 
-Transitional Drivers can detect Legacy Devices by detecting that
+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}
+
+Devices or drivers with no legacy compatibility are referred to as
+non-transitional devices and drivers, respectively.
+
+Transitional Drivers MUST detect Legacy Devices by detecting that
 the feature bit VIRTIO_F_VERSION_1 is not offered.
-Transitional devices can detect Legacy drivers by detecting that
+Transitional devices MUST detect Legacy drivers by detecting that
 VIRTIO_F_VERSION_1 has not been acknowledged by the driver.
 In this case device is used through the legacy interface.
 
+Legacy interface support is OPTIONAL.
+Thus, both transitional and non-transitional devices and
+drivers are compliant with this specification.
+
+Requirements pertaining to transitional devices and drivers
+is contained in sections named 'Legacy Interface' like this one.
+
+When device is used through the legacy interface, transitional
+devices and transitional drivers MUST operate according to the
+requirements documented within these legacy interface sections.
+Specification text within these sections generally does not apply
+to non-transitional devices.
+
 \section{Device Configuration Space}\label{sec:Basic Facilities of a Virtio Device / Device Configuration Space}
 
 Device configuration space is generally used for rarely-changing or
-- 
cgit v1.2.3

