summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorrusty <rusty@0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652>2014-02-12 03:16:51 +0000
committerrusty <rusty@0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652>2014-02-12 03:16:51 +0000
commit86e2b45812fea4fbf34f6e1ee45d06d4ae886d8e (patch)
tree4adc29090354ba9c7780caf7a64a1764ad2becfa
parent69678f44cb86d3c162d845541f28f67c091500fc (diff)
Feedback #8: Applied.
[ Includes fixup! removing MSI-X ] As per minutes: https://lists.oasis-open.org/archives/virtio/201402/msg00121.html Signed-off-by: Rusty Russell <rusty@au1.ibm.com> git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio@239 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652
-rw-r--r--content.tex65
-rw-r--r--feedback/8.txt2
-rw-r--r--introduction.tex8
3 files changed, 56 insertions, 19 deletions
diff --git a/content.tex b/content.tex
index 568a90b..4e60565 100644
--- a/content.tex
+++ b/content.tex
@@ -760,6 +760,8 @@ for (;;) {
if (vq->last_seen_used != le16_to_cpu(vring->used.idx))
break;
+
+ vring_disable_interrupts(vq);
}
struct vring_used_elem *e = vring.used->ring[vq->last_seen_used%vsz];
@@ -797,6 +799,17 @@ into virtio general and bus-specific sections.
Virtio devices are commonly implemented as PCI devices.
+A Virtio device can be implemented as any kind of PCI device:
+a Conventional PCI device or a PCI Express
+device. A Virtio device using Virtio Over PCI Bus MUST expose to
+guest an interface that meets the specification requirements of
+the appropriate PCI specification: \hyperref[intro:PCI]{[PCI]}
+and \hyperref[intro:PCIe]{[PCIe]}
+respectively. To assure designs meet the latest level
+requirements, designers of Virtio Over PCI devices must refer to
+the PCI-SIG home page at \url{http://www.pcisig.com} for any
+approved changes.
+
\subsection{PCI Device Discovery}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Discovery}
Any PCI device with Vendor ID 0x1AF4, and Device ID 0x1000 through
@@ -835,8 +848,13 @@ MUST access each field using the “natural” access method (i.e. 32-bit access
\subsection{Virtio Structure PCI Capabilities}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / Virtio Structure PCI Capabilities}
-The virtio device configuration layout includes a common configuration header, notification area, ISR status area
-and a device-specific configuration area.
+The virtio device configuration layout includes several structures:
+\begin{itemize}
+\item Common configuration
+\item Notifications
+\item ISR Status
+\item Device-specific configuration (optional)
+\end{itemize}
Each structure can be mapped by a Base Address register (BAR) belonging to
the function, or accessed via the special VIRTIO_PCI_CAP_PCI_CFG field in the PCI configuration space.
@@ -875,7 +893,7 @@ The fields are interpreted as follows:
0x09; Identifies a vendor-specific capability.
\item[\field{cap_next}]
- Link to next capability in the capability list in the configuration space.
+ Link to next capability in the capability list in the PCI configuration space.
\item[\field{cap_len}]
Length of this capability structure, including the whole of
@@ -917,7 +935,7 @@ The fields are interpreted as follows:
\item[\field{bar}]
values 0x0 to 0x5 specify a Base Address register (BAR) belonging to
- the function located beginning at 10h in Configuration Space
+ the function located beginning at 10h in PCI Configuration Space
and used to map the structure into Memory or I/O Space.
The BAR is permitted to be either 32-bit or 64-bit, it can map Memory Space
or I/O Space.
@@ -928,7 +946,8 @@ The fields are interpreted as follows:
\item[\field{offset}]
indicates where the structure begins relative to the base address associated
- with the BAR.
+ with the BAR. The alignment requirement of \field{offset} are indicated
+ in each structure-specific section below.
\item[\field{length}]
indicates the length of the structure.
@@ -953,6 +972,7 @@ The fields are interpreted as follows:
\subsubsection{Common configuration structure layout}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Common configuration structure layout}
The common configuration structure is found at the \field{bar} and \field{offset} within the VIRTIO_PCI_CAP_COMMON_CFG capability; its layout is below.
+\field{offset} must be 4-byte aligned.
The device MUST present at least one common configuration capability.
@@ -1049,13 +1069,13 @@ struct virtio_pci_common_cfg {
See \ref{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Notification capability} below.
\item[\field{queue_desc}]
- The driver writes the physical address of Descriptor Table here.
+ The driver writes the physical address of Descriptor Table here. See section \ref{sec:Basic Facilities of a Virtio Device / Virtqueues}.
\item[\field{queue_avail}]
- The driver writes the physical address of Available Ring here.
+ The driver writes the physical address of Available Ring here. See section \ref{sec:Basic Facilities of a Virtio Device / Virtqueues}.
\item[\field{queue_used}]
- The driver writes the physical address of Used Ring here.
+ The driver writes the physical address of Used Ring here. See section \ref{sec:Basic Facilities of a Virtio Device / Virtqueues}.
\end{description}
\subsubsection{Notification structure layout}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Notification capability}
@@ -1063,7 +1083,7 @@ struct virtio_pci_common_cfg {
The device MUST present at least one notification capability.
The notification location is found using the VIRTIO_PCI_CAP_NOTIFY_CFG
-capability. This capability is immediately followed by an additional
+capability. The \field{offset} must be 2-byte aligned. This capability is immediately followed by an additional
field, like so:
\begin{lstlisting}
@@ -1101,13 +1121,23 @@ cap.length >= queue_notify_off * notify_off_multiplier + 2
\subsubsection{ISR status capability}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / ISR status capability}
The device MUST present at least one VIRTIO_PCI_CAP_ISR_CFG capability. This
-refers to at least a single byte, which contains the 8-bit ISR status field.
+refers to at least a single byte, which contains the 8-bit ISR status field:
+\begin{lstlisting}
+#define VIRTIO_PCI_ISR_VQ 0x1
+#define VIRTIO_PCI_ISR_CONFIG 0x2
+\end{lstlisting}
+
+See sections \ref{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Virtqueue Interrupts From The Device} and \ref{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Notification of Device Configuration Changes} for how this is used.
+
+The \field{offset} for the ISR status has no specific alignment requirements.
\subsubsection{Device specific structure}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Device specific structure}
The device MAY present at least one VIRTIO_PCI_CAP_DEVICE_CFG capability (some
devices may not have any device specific structure).
+The \field{offset} for the device specific structure must be 4-byte aligned.
+
\subsubsection{PCI configuration access capability}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / PCI configuration access capability}
The device MUST present at least one VIRTIO_PCI_CAP_PCI_CFG. This
@@ -1161,18 +1191,18 @@ registers in a legacy configuration structure in BAR0 in the first I/O
region of the PCI device, as documented below.
There may be different widths of accesses to the I/O region; the
-“natural” access method for each field in the virtio header must be
+“natural” access method for each field in the virtio common configuration structure must be
used (i.e. 32-bit accesses for 32-bit fields, etc), but
when accessed through the legacy interface the
device-specific region can be accessed using any width accesses, and
should obtain the same results.
-Note that this is possible because while the virtio header is PCI
+Note that this is possible because while the virtio common configuration structure is PCI
(i.e. little) endian, when using the legacy interface the device-specific
region is encoded in the native endian of the guest (where such distinction is
applicable).
-When used through the legacy interface, the virtio header looks as follows:
+When used through the legacy interface, the virtio common configuration structure looks as follows:
\begin{tabularx}{\textwidth}{ |X||X|X|X|X|X|X|X|X| }
\hline
@@ -1200,7 +1230,7 @@ Purpose (MSI-X) & \field{config_msix_vector} & \field{queue_msix_vector} \\
\end{tabular}
Note: When MSI-X capability is enabled, device specific configuration starts at
-byte offset 24 in virtio header structure. When MSI-X capability is not
+byte offset 24 in virtio common configuration structure structure. When MSI-X capability is not
enabled, device specific configuration starts at byte offset 20 in virtio
header. ie. once you enable MSI-X on the device, the other fields move.
If you turn it off again, they move back!
@@ -1232,7 +1262,7 @@ see \ref{sec:Basic Facilities of a Virtio Device / Configuration Space / Legacy
This documents PCI-specific steps executed during Device Initialization.
As the first step, driver must detect device configuration layout
-to locate configuration fields in memory, I/O or configuration space of the
+to locate configuration fields in memory, I/O or PCI configuration space of the
device.
\paragraph{Virtio Device Configuration Layout Detection}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Device Initialization / Virtio Device Configuration Layout Detection}
@@ -1244,7 +1274,7 @@ Structure PCI capabilities.
\subparagraph{Legacy Interface: A Note on Device Layout Detection}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Device Initialization / Virtio Device Configuration Layout Detection / Legacy Interface: A Note on Device Layout Detection}
Legacy drivers skipped the Device Layout Detection step, assuming legacy
-configuration space in BAR0 in I/O space unconditionally.
+device registers in BAR0 in I/O space unconditionally.
Legacy devices did not have the Virtio PCI Capability in their
capability list.
@@ -1390,8 +1420,7 @@ The driver interrupt handler SHOULD:
\subsubsection{Notification of Device Configuration Changes}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Notification of Device Configuration Changes}
-Some virtio PCI devices can change the device configuration
-state, as reflected in the device-specific region of the device. In this case:
+Some devices can change the device configuration space. In this case:
\begin{itemize}
\item If MSI-X capability is disabled: an interrupt is delivered and
diff --git a/feedback/8.txt b/feedback/8.txt
index 9d132da..988ebf0 100644
--- a/feedback/8.txt
+++ b/feedback/8.txt
@@ -3,7 +3,7 @@ Number: 8
Date: Wed, 29 Jan 2014 17:05:06 -0800
Link to Mail: https://lists.oasis-open.org/archives/virtio-comment/201401/msg00058.html
Commenter name: Arun Subbarao <asubbarao@lnxw.com>
-Decision:
+Decision: 2014-02-11 minutes: Applied
1) 3.2.1.4 Notifying The Device:
"We" is confusing and ambiguous. Please use either "device" or "driver" instead of "we" everywhere.
diff --git a/introduction.tex b/introduction.tex
index 8e08d02..649e64c 100644
--- a/introduction.tex
+++ b/introduction.tex
@@ -43,6 +43,14 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S
\phantomsection\label{intro:rfc2119}\textbf{[RFC2119]} & S. Bradner, Key words for use in RFCs to Indicate Requirement Levels, \newline\url{http://www.ietf.org/rfc/rfc2119.txt}, March 1997\\
\phantomsection\label{intro:S390 PoP}\textbf{[S390 PoP]} & z/Architecture Principles of Operation, \newline IBM Publication SA22-7832\\
\phantomsection\label{intro:S390 Common I/O}\textbf{[S390 Common I/O]} & ESA/390 Common I/O-Device and Self-Description, \newline IBM Publication SA22-7204\\
+ \phantomsection\label{intro:PCI}\textbf{[PCI]} &
+ Conventional PCI Specifications,
+ \newline\url{http://www.pcisig.com/specifications/conventional/},
+ PCI-SIG\\
+ \phantomsection\label{intro:PCIe}\textbf{[PCIe]} &
+ PCI Express Specifications
+ \newline\url{http://www.pcisig.com/specifications/pciexpress/},
+ PCI-SIG\\
\end{longtable}
\section{Structure Specifications}