This way contributors can avoid resending it multiple times.
Cc: Viresh Kumar viresh.kumar@linaro.org; Vincent Guittot
vincent.guittot@linaro.org; Alex Bennée alex.bennee@linaro.org;
stratos- dev@op-lists.linaro.org; Manos Pitsidianakis
manos.pitsidianakis@linaro.org; Cornelia Huck cohuck@redhat.com;
Michael S. Tsirkin mst@redhat.com
Subject: [PATCH V3 Resend] virtio-transport: Clarify requirements
The virtio documentation currently doesn't define any generic
requirements that are applicable to all transports. They can be
useful while adding support for a new transport.
This commit tries to define the same.
Reviewed-by: Alex Bennée alex.bennee@linaro.org
Signed-off-by: Viresh Kumar viresh.kumar@linaro.org
V2->V3:
- Minor fixes.
- Added Reviewed by from Alex.
V1->V2:
- Lot of changes after discussions with Alex and Cornelia.
- Almost a rewrite of the first commit.
- Add Transport normative sections.
commands.tex | 3 +-
conformance.tex | 14 +++++++++
content.tex | 78
+++++++++++++++++++++++++++++++++++++++++++++++--
3 files changed, 92 insertions(+), 3 deletions(-)
diff --git a/commands.tex b/commands.tex index
25ea8ee3bc78..b64b14424bd2 100644
--- a/commands.tex
+++ b/commands.tex
@@ -7,7 +7,8 @@
% How we format a field name
\newcommand{\field}[1]{\emph{#1}}
-% Mark a normative section (driver or device)
+% Mark a normative section (driver or device, or transport)
+\newcommand{\transportnormative}[3]{#1{Transport Requirements:
+#2}\label{transportnormative:#3}}
\newcommand{\drivernormative}[3]{#1{Driver Requirements:
#2}\label{drivernormative:#3}}
\newcommand{\devicenormative}[3]{#1{Device Requirements:
#2}\label{devicenormative:#3}} \newcounter{clausecounter} diff
--git a/conformance.tex b/conformance.tex index
dc00e84e75ae..4a873169ce63
100644
--- a/conformance.tex
+++ b/conformance.tex
@@ -11,6 +11,10 @@ \section{Conformance
Targets}\label{sec:Conformance / Conformance Targets}
Conformance targets:
\begin{description}
+\item[Transport] A transport MUST conform to one conformance clauses:
- \begin{itemize}
- \item Clause \ref{sec:Conformance / Transport Conformance}.
- \end{itemize}
\item[Driver] A driver MUST conform to four conformance clauses:
\begin{itemize}
\item Clause \ref{sec:Conformance / Driver Conformance}.
@@ -66,6 +70,14 @@ \section{Conformance
Targets}\label{sec:Conformance / Conformance Targets}
\end{itemize}
\end{description}
+\conformance{\section}{Transport Conformance}\label{sec:Conformance
+/ Transport Conformance}
+A transport MUST conform to the following normative statements:
+\begin{itemize}
+\item \ref{transportnormative:Virtio Transport Options / Virtio
+Transport Requirements} \end{itemize}
\conformance{\section}{Driver Conformance}\label{sec:Conformance /
Driver Conformance}
A driver MUST conform to the following normative statements:
@@ -93,6 +105,7 @@ \section{Conformance
Targets}\label{sec:Conformance / Conformance Targets} \item
\ref{drivernormative:Basic Facilities of a Virtio Device / Packed
Virtqueues / Supplying Buffers to The Device / Sending Available
Buffer Notifications} \item \ref{drivernormative:General
Initialization And Device Operation / Device Initialization} \item
\ref{drivernormative:General Initialization And Device Operation /
Device Cleanup}
+\item \ref{drivernormative:Virtio Transport Options / Virtio
+Transport Requirements}
\item \ref{drivernormative:Reserved Feature Bits} \end{itemize}
@@ -172,6 +185,7 @@ \section{Conformance
Targets}\label{sec:Conformance / Conformance Targets} \item
\ref{devicenormative:Basic Facilities of a Virtio Device / Packed
Virtqueues / The Virtqueue Descriptor Table} \item
\ref{devicenormative:Basic Facilities of a Virtio Device / Packed
Virtqueues / Scatter-Gather Support} \item
\ref{devicenormative:Basic Facilities of a Virtio Device / Shared
Memory Regions}
+\item \ref{devicenormative:Virtio Transport Options / Virtio
+Transport Requirements}
\item \ref{devicenormative:Reserved Feature Bits} \end{itemize}
diff --git a/content.tex b/content.tex index
0a62dce5f65f..a79993b5ed69 100644
--- a/content.tex
+++ b/content.tex
@@ -631,8 +631,82 @@ \section{Device Cleanup}\label{sec:General
Initialization And Device Operation /
\chapter{Virtio Transport Options}\label{sec:Virtio Transport
Options}
-Virtio can use various different buses, thus the standard is split
-into virtio general and bus-specific sections.
+Devices and drivers can use different transport methods to enable
+interaction, for example PCI, MMIO, or Channel I/O. The transport
+methods define various aspects of the communication between the
+device and the driver, like device discovery, exchanging
+capabilities, interrupt handling, data transfer, etc. For example,
+in a host/guest architecture, the host might expose a device to the
+guest on a PCI bus, and the guest will use a PCI-specific driver to interact