From e0c73f5462c8fe1fd7adae5620828c42042370af Mon Sep 17 00:00:00 2001 From: mstsirkin 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 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