summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--content.tex57
1 files changed, 29 insertions, 28 deletions
diff --git a/content.tex b/content.tex
index 4e60565..d43decd 100644
--- a/content.tex
+++ b/content.tex
@@ -8,7 +8,7 @@ device consists of the following parts:
\begin{itemize}
\item Device status field
\item Feature bits
-\item Configuration space
+\item Device Configuration space
\item One or more virtqueues
\end{itemize}
@@ -138,19 +138,19 @@ To make them easier to locate, specification sections documenting
these transitional features are explicitly marked with 'Legacy
Interface' in the section title.
-\section{Configuration Space}\label{sec:Basic Facilities of a Virtio Device / Configuration Space}
+\section{Device Configuration Space}\label{sec:Basic Facilities of a Virtio Device / Device Configuration Space}
-Configuration space is generally used for rarely-changing or
+Device configuration space is generally used for rarely-changing or
initialization-time parameters. Drivers MUST NOT assume reads from
fields greater than 32 bits wide are atomic, nor reads from
multiple fields.
-Each transport provides a generation count for the configuration
+Each transport provides a generation count for the device configuration
space, which must change whenever there is a possibility that two
-accesses to the configuration space can see different versions of that
+accesses to the device configuration space can see different versions of that
space.
-Thus drivers SHOULD read configuration space fields like so:
+Thus drivers SHOULD read device configuration space fields like so:
\begin{lstlisting}
u32 before, after;
@@ -161,30 +161,30 @@ do {
} while (after != before);
\end{lstlisting}
-Note that configuration space uses the little-endian format
+Note that device configuration space uses the little-endian format
for multi-byte fields.
Note that future versions of this specification will likely
-extend the configuration space for devices by adding extra fields
-at the tail end of some structures in configuration space.
+extend the device configuration space for devices by adding extra fields
+at the tail end of some structures in device configuration space.
To allow forward compatibility with such extensions, drivers MUST
-NOT limit structure size and configuration space size. Instead,
-drivers SHOULD only check that configuration space is *large enough* to
+NOT limit structure size and device configuration space size. Instead,
+drivers SHOULD only check that device configuration space is *large enough* to
contain the fields required for device operation.
-For example, if the specification states that configuration
+For example, if the specification states that device configuration
space 'includes a single 8-bit field' drivers should understand this to mean that
-the configuration space might also include an arbitrary amount of
-tail padding, and accept any configuration space size equal to or
+the device configuration space might also include an arbitrary amount of
+tail padding, and accept any device configuration space size equal to or
greater than the specified 8-bit size.
-\subsection{Legacy Interface: A Note on Configuration Space endian-ness}\label{sec:Basic Facilities of a Virtio Device / Configuration Space / Legacy Interface: A Note on Configuration Space endian-ness}
+\subsection{Legacy Interface: A Note on Device Configuration Space endian-ness}\label{sec:Basic Facilities of a Virtio Device / Device Configuration Space / Legacy Interface: A Note on Configuration Space endian-ness}
-Note that for legacy interfaces, configuration space is generally the
+Note that for legacy interfaces, device configuration space is generally the
guest's native endian, rather than PCI's little-endian.
-\subsection{Legacy Interface: Configuration Space}\label{sec:Basic Facilities of a Virtio Device / Configuration Space / Legacy Interface: Configuration Space}
+\subsection{Legacy Interface: Device Configuration Space}\label{sec:Basic Facilities of a Virtio Device / Device Configuration Space / Legacy Interface: Device Configuration Space}
Legacy devices did not have a configuration generation field, thus are
susceptible to race conditions if configuration is updated. This
@@ -772,8 +772,8 @@ for (;;) {
\subsection{Notification of Device Configuration Changes}\label{sec:General Initialization And Device Operation / Device Operation / Notification of Device Configuration Changes}
-For devices where the configuration information can be changed, an
-interrupt is delivered when a configuration change occurs.
+For devices where the device-specific configuration information can be changed, an
+interrupt is delivered when a device-specific configuration change occurs.
\section{Device Cleanup}\label{sec:General Initialization And Device Operation / Device Cleanup}
@@ -1254,7 +1254,9 @@ Transitional Devices must assume that Feature Bits 32 to 63
are not acknowledged by Driver.
As legacy devices had no \field{config_generation} field,
-see \ref{sec:Basic Facilities of a Virtio Device / Configuration Space / Legacy Interface: Configuration Space}~\nameref{sec:Basic Facilities of a Virtio Device / Configuration Space / Legacy Interface: Configuration Space} for workarounds.
+see \ref{sec:Basic Facilities of a Virtio Device / Device
+Configuration Space / Legacy Interface: Device Configuration
+Space}~\nameref{sec:Basic Facilities of a Virtio Device / Device Configuration Space / Legacy Interface: Device Configuration Space} for workarounds.
\subsection{PCI-specific Initialization And Device Operation}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation}
@@ -1274,7 +1276,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
-device registers in BAR0 in I/O space unconditionally.
+device configuration space in BAR0 in I/O space unconditionally.
Legacy devices did not have the Virtio PCI Capability in their
capability list.
@@ -2180,8 +2182,7 @@ combination.
\subsubsection{Device Configuration}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Initialization / Device Configuration}
-The device's configuration space is located in host memory. It is
-the same size as the standard PCI configuration space.
+The device's configuration space is located in host memory.
To obtain information from the configuration space, the driver
uses CCW_CMD_READ_CONF, specifying the guest memory for the device
@@ -3596,7 +3597,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 configuration space are not atomic, this field
+ updated to reflect the new number of pages in the balloon.\footnote{As updates to device configuration space are not atomic, this field
isn't particularly reliable, but can be used to diagnose buggy guests.
}
\end{enumerate}
@@ -4316,16 +4317,16 @@ type.
\section{How Many Virtqueues?}\label{sec:Creating New Device Types / How Many Virtqueues?}
It is possible that a very simple device will operate entirely
-through its configuration space, but most will need at least one
+through its device configuration space, but most will need at least one
virtqueue in which it will place requests. A device with both
input and output (eg. console and network devices described here)
need two queues: one which the driver fills with buffers to
receive input, and one which the driver places buffers to
transmit output.
-\section{What Configuration Space Layout?}\label{sec:Creating New Device Types / What Configuration Space Layout?}
+\section{What Device Configuration Space Layout?}\label{sec:Creating New Device Types / What Device Configuration Space Layout?}
-Configuration space should only be used for initialization-time
+Device configuration space should only be used for initialization-time
parameters. It is a limited resource with no synchronization between
field written by the driver, so for most uses it is better to use a virtqueue to update
configuration information (the network device does this for filtering,
@@ -4362,7 +4363,7 @@ altogether.
\section{Device Improvements}\label{sec:Creating New Device Types / Device Improvements}
-Any change to configuration space, or new virtqueues, or
+Any change to device configuration space, or new virtqueues, or
behavioural changes, should be indicated by negotiation of a new
feature bit. This establishes clarity\footnote{Even if it does mean documenting design or implementation
mistakes!