summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authormstsirkin <mstsirkin@0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652>2014-02-12 11:21:49 +0000
committermstsirkin <mstsirkin@0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652>2014-02-12 11:21:49 +0000
commitb06c313ed4125825518e0f5275ab0818c31ab259 (patch)
treeeca26fe9a23b7d100398bd3c9e28deb798ece049
parentaf89066fe41159d4c1db8dfc27bc60358b9f7146 (diff)
content: more strict confirmance language
Correct new language to explicitly use MAY/SHOULD/MUST in more places or simply drop the somewhat vague "can" where we are describing the only way to operate the device. Most of the changes are in the PCI section. Signed-off-by: Michael S. Tsirkin <mst@redhat.com> git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio@247 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652
-rw-r--r--content.tex74
1 files changed, 40 insertions, 34 deletions
diff --git a/content.tex b/content.tex
index 999ebbd..aa191a3 100644
--- a/content.tex
+++ b/content.tex
@@ -654,14 +654,14 @@ free descriptors before beginning the mappings.
The descriptor chain head is the first d in the algorithm
above, ie. the index of the descriptor table entry referring to the first
-part of the buffer. A naive implementation would do the following (with the
+part of the buffer. A naive driver implementation MAY do the following (with the
appropriate conversion to-and-from little-endian assumed):
\begin{lstlisting}
avail->ring[avail->idx % qsz] = head;
\end{lstlisting}
-However, in general the driver can add many descriptor chains before it updates
+However, in general the driver MAY add many descriptor chains before it updates
\field{idx} (at which point they become visible to the
device), so it is common to keep a counter of how many the driver has added:
@@ -671,13 +671,13 @@ avail->ring[(avail->idx + added++) % qsz] = head;
\subsubsection{Updating \field{idx}}\label{sec:General Initialization And Device Operation / Device Operation / Supplying Buffers to The Device / Updating idx}
-Once \field{idx} is updated, the device will
-be able to access the descriptor chains the driver created and the
-memory they refer to. This is why a memory barrier is generally
-used before the \field{idx} update, to ensure it sees the most up-to-date
-copy.
+Once available \field{idx} is updated by driver, the device MAY
+access the descriptor chains the driver created and the
+memory they refer to. This is why the driver SHOULD generally
+use a memory barrier before the \field{idx} update, to ensure the
+device sees the most up-to-date copy.
-\field{idx} always increments, and the driver can let it wrap naturally at
+\field{idx} always increments, and wraps naturally at
65536:
\begin{lstlisting}
@@ -718,7 +718,8 @@ similar to the algorithm used for the driver to send the device a
buffer:
\begin{enumerate}
-\item Write the head descriptor number to the next entry in the used
+\item Write the head descriptor number to the next free entry
+ (pointed to by the used ring \field{idx}) in the used
ring.
\item Update the used ring \field{idx}.
@@ -946,7 +947,7 @@ The fields are interpreted as follows:
\item[\field{offset}]
indicates where the structure begins relative to the base address associated
- with the BAR. The alignment requirement of \field{offset} are indicated
+ with the BAR. The alignment requirements of \field{offset} are indicated
in each structure-specific section below.
\item[\field{length}]
@@ -1096,14 +1097,14 @@ struct virtio_pci_notify_cap {
The device MUST either present \field{notify_off_multiplier} as an even power of 2,
or present \field{notify_off_multiplier} as 0.
-\field{notify_off_multiplier} field is combined with the \field{queue_notify_off} to
+\field{notify_off_multiplier} is combined with the \field{queue_notify_off} to
derive the Queue Notify address within a BAR for a specific queue:
\begin{lstlisting}
cap.offset + queue_notify_off * notify_off_multiplier
\end{lstlisting}
-The BAR, \field{offset} and \field{notify_off_multiplier} are taken from the
+The \field{cap.offset} and \field{notify_off_multiplier} are taken from the
notification capability structure above, and the \field{queue_notify_off} is
taken from the common configuration structure.
@@ -1123,10 +1124,12 @@ cap.length >= queue_notify_off * notify_off_multiplier + 2
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.
-The \field{offset} for the ISR status field has no specific alignment requirements.
+The \field{offset} for the \field{ISR status} has no specific alignment requirements.
-The ISR status field is used for INT\#x interrupt handling.
-The driver MUST NOT access the ISR field when MSI-X capability
+\subsection{ISR status field}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / ISR status field}
+
+\field{ISR status} is used for INT\#x interrupt handling.
+Driver MUST NOT access \field{ISR status} when MSI-X capability
is enabled.
\begin{tabular}{ |l||l|l|l| }
@@ -1139,15 +1142,17 @@ Purpose & Device Configuration Interrupt & Queue Interrupt & Reserved \\
If MSI-X capability is disabled, device MUST set Interrupt Status
bit in the PCI Status register in the PCI Configuration Header of
-the device to the logical OR of all bits in ISR status field of
+the device to the logical OR of all bits in \field{ISR status} of
the device. Device then asserts/deasserts INT\#x interrupts unless masked
according to standard PCI rules \hyperref[intro:PCI]{[PCI]}.
-Device MUST reset the ISR status field to 0 on read.
+Device MUST reset \field{ISR status} to 0 on read.
-In this way, driver read of ISR status causes the device to de-assert
+In this way, driver read of \field{ISR status} causes the device to de-assert
an interrupt.
+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.
+
\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
@@ -1170,10 +1175,10 @@ struct virtio_pci_cfg_cap {
};
\end{lstlisting}
-The fields \field{cap.bar}, \field{cap.length}, \field{cap.offset} and \field{pci_cfg_data}
-are read-write (RW).
+The fields \field{cap.bar}, \field{cap.legth}, \field{cap.offset} and
+\field{pci_cfg_data} are read-write (RW).
-To access to a device region, the driver writes into the capability
+To access a device region, the driver writes into the capability
structure (ie. within the PCI configuration space) as follows:
\begin{itemize}
@@ -1207,12 +1212,11 @@ Transitional devices should present part of configuration
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 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.
+When accessed through the legacy interface the driver MAY access
+the device-specific region using any width accesses, and
+a transitional device MUST present it with the same results as
+when accessed using the “natural” access method (i.e.
+32-bit accesses for 32-bit fields, etc).
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
@@ -1334,7 +1338,7 @@ Writing a valid MSI-X Table entry number, 0 to 0x7FF, to
\field{config_msix_vector}/\field{queue_msix_vector} maps interrupts triggered
by the configuration change/selected queue events respectively to
the corresponding MSI-X vector. To disable interrupts for a
-specific event type, unmap it by writing a special NO_VECTOR
+specific event type, unmap this event by writing a special NO_VECTOR
value:
\begin{lstlisting}
@@ -1346,14 +1350,15 @@ Reading these registers returns vector mapped to a given event,
or NO_VECTOR if unmapped. All queue and configuration change
events are unmapped by default.
-Note that mapping an event to vector might require allocating
-internal device resources, and might fail. Devices MUST report such
+Note that mapping an event to vector might require device to
+allocate internal device resources, and MAY fail. Devices MUST report such
failures by returning the NO_VECTOR value when the relevant
Vector field is read. After mapping an event to vector, the
driver MUST verify success by reading the Vector field value: on
success, the previously written value is returned, and on
failure, NO_VECTOR is returned. If a mapping failure is detected,
-the driver can retry mapping with fewer vectors, or disable MSI-X.
+the driver MAY retry mapping with fewer vectors, disable MSI-X
+or report device failure.
\paragraph{Virtqueue Configuration}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Device Initialization / Virtqueue Configuration}
@@ -1415,7 +1420,7 @@ If an interrupt is necessary for a virtqueue, the device SHOULD:
device, \field{queue_msix_vector} sets the MSI-X Table entry
number.
- \item If the vector field value is NO_VECTOR, no interrupt
+ \item If the vector value is NO_VECTOR, no interrupt
message is requested for this event, so the device MUST NOT
deliver an interrupt.
\end{enumerate}
@@ -1439,7 +1444,8 @@ 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 devices can change the device configuration space. In this case:
+Some virtio PCI devices can change the device configuration
+state, as reflected in the device-specific region of the device. In this case:
\begin{itemize}
\item If MSI-X capability is disabled: an interrupt is delivered and
@@ -3616,7 +3622,7 @@ configuration change interrupt.
\item In either case, once the device has completed the inflation or
deflation, \field{actual} should be
- updated to reflect the new number of pages in the balloon.\footnote{As updates to device configuration space are not atomic, this field
+ updated to reflect the new number of pages in the balloon.\footnote{As updates to device-specific configuration space are not atomic, this field
isn't particularly reliable, but can be used to diagnose buggy guests.
}
\end{enumerate}