[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: [PATCH 07/10] 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. Cc: Arun Subbarao <asubbarao@lnxw.com> Signed-off-by: Michael S. Tsirkin <mst@redhat.com> --- content.tex | 59 +++++++++++++++++++++++++++++------------------------------ 1 file changed, 29 insertions(+), 30 deletions(-) diff --git a/content.tex b/content.tex index 2da2d63..ca69623 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 @@ -773,8 +773,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} @@ -890,7 +890,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 @@ -932,7 +932,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. @@ -1260,7 +1260,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} @@ -1272,7 +1272,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 configuration space in BAR0 in I/O space unconditionally. Legacy devices did not have the Virtio PCI Capability in their capability list. @@ -2179,8 +2179,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 @@ -3595,7 +3594,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-specific configuration space are not atomic, this field isn't particularly reliable, but can be used to diagnose buggy guests. } \end{enumerate} @@ -4315,16 +4314,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, @@ -4361,7 +4360,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! -- MST
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]