OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

virtio message

[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]