From 7232c520616404bdccb084c9058551b0ef4b82f1 Mon Sep 17 00:00:00 2001 From: mstsirkin Date: Sun, 2 Mar 2014 21:36:54 +0000 Subject: legacy interface: move to terminology Change accepted on VIRTIO TC Meeting, 3 December 2013 VIRTIO-64 Cc: Patrick Durusau git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio@303 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- conformance.tex | 8 +++--- content.tex | 54 +++-------------------------------- introduction.tex | 86 ++++++++++++++++++++++++++++++++++++-------------------- 3 files changed, 63 insertions(+), 85 deletions(-) diff --git a/conformance.tex b/conformance.tex index d72c3e2..0ea012a 100644 --- a/conformance.tex +++ b/conformance.tex @@ -236,9 +236,8 @@ Transitional Driver Conformance}\label{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance} A conformant implementation MUST be either transitional or -non-transitional, see \ref{sec:Basic Facilities of a Virtio -Device / Feature Bits / Legacy Interface: A Note on transitions -from earlier drafts}. +non-transitional, see \ref{intro:Legacy +Interface: Terminology}. A non-transitional implementation conforms to this specification if it satisfies all of the MUST or REQUIRED level requirements @@ -253,7 +252,8 @@ for the transitional devices and drivers. The requirements for the legacy interface for transitional implementations are located in sections named "Legacy Interface" listed below: \begin{itemize} -\item Section \ref{sec:Basic Facilities of a Virtio Device / Feature Bits / Legacy Interface: A Note on transitions from earlier drafts} +\item Section \ref{sec:Basic Facilities of a Virtio Device / +Feature Bits / Legacy Interface: A Note on Feature Bits} \item Section \ref{sec:Basic Facilities of a Virtio Device / Device Configuration Space / Legacy Interface: A Note on Configuration Space endian-ness} \item Section \ref{sec:Basic Facilities of a Virtio Device / Device Configuration Space / Legacy Interface: Device Configuration Space} \item Section \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Legacy Interfaces: A Note on Virtqueue Layout} diff --git a/content.tex b/content.tex index cb0d648..c9a566a 100644 --- a/content.tex +++ b/content.tex @@ -98,61 +98,15 @@ which was not offered. The device SHOULD accept any valid subset of features the driver accepts, otherwise it MUST fail to set the 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} - -%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} - -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. +\subsection{Legacy Interface: A Note on Feature +Bits}\label{sec:Basic Facilities of a Virtio Device / Feature +Bits / Legacy Interface: A Note on Feature Bits} Transitional Drivers MUST detect Legacy Devices by detecting that the feature bit VIRTIO_F_VERSION_1 is not offered. 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. 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 -- cgit v1.2.3