From ad640ee757d06e7f2e6b6bfb75e2087639419424 Mon Sep 17 00:00:00 2001 From: rusty Date: Wed, 12 Feb 2014 03:17:11 +0000 Subject: PCI: consistent device/PCI configuration space Re section: 4.1.3.4 Notification of Device Configuration Changes Feedback: Please use "PCI configuration space" and "device configuration state" consistently, without abbreviation. For example, from the first sentence it looks like "device configuration state" can be changed, but the first bullet claims it's "configuration space". So, which one? Does "configuration space" mean "PCI configuration space" or is it a synonym for "device configuration state"? Because those are two different things; the driver needs to know what exactly to rescan. As per minutes: https://lists.oasis-open.org/archives/virtio/201402/msg00121.html Cc: Arun Subbarao Signed-off-by: Michael S. Tsirkin Signed-off-by: Rusty Russell git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio@240 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652 --- content.tex | 57 +++++++++++++++++++++++++++++---------------------------- 1 file 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! -- cgit v1.2.3