[PATCH 06/10] PCI: minor clarifications after rearrangement

There's some mixup wrt device/driver in Rusty's
rearrangement of PCI devices, correct the
confirmance clauses to list requirement against
the correct entity.

Signed-off-by: Michael S. Tsirkin <>
---
 content.tex | 67 ++++++++++++++++++++++++++++++++++++++++++-------------------
 1 file changed, 46 insertions(+), 21 deletions(-)

diff --git a/content.tex b/content.tex
index bb28100..2da2d63 100644
--- a/content.tex
+++ b/content.tex
@@ -875,8 +875,12 @@ struct virtio_pci_cap {
 \end{lstlisting}
 
 This structure can be followed by extra data, depending on
-\field{cfg_type}, as documented below.  The device MAY append extra data
-or padding to any structure beyond that, the device MUST accept a \field{cap_len} value
+\field{cfg_type}, as documented below. In this case device MUST
+include this extra data (from the beginning of the \field{cap_vndr}
+through end of the extra data fields if any)
+in the capability length as specified by \field{cap_len}.
+The device MAY append extra data
+or padding to any structure beyond that; the driver MUST accept a \field{cap_len} value
 which is larger than specified here.
 
 The fields are interpreted as follows:
@@ -939,7 +943,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}]
@@ -956,8 +960,9 @@ The fields are interpreted as follows:
         For example, a future device might present a large structure size of several
         MBytes.
         As current devices never utilize structures larger than 4KBytes in size,
-        driver can limit the mapped structure size to e.g.
-        4KBytes to allow forward compatibility with such devices without loss of
+        driver may limit the mapped structure size to e.g.
+        4KBytes (thus ignoring parts of structure after the first
+        4KBytes) to allow forward compatibility with such devices without loss of
         functionality and without wasting resources.
 \end{description}
 
@@ -1006,10 +1011,13 @@ struct virtio_pci_common_cfg {
 \item[\field{driver_feature_select}]
         The driver uses this to select which feature bits \field{driver_feature} shows.
         Value 0x0 selects Feature Bits 0 to 31, 0x1 selects Feature Bits 32 to 63.
-        When set to any other value, the device MUST return 0 on reads from \field{driver_feature}
-        return 0, and ignore writing of 0 into \field{driver_feature}.  The driver
-        MUST not write any other value into \field{driver_feature} (a corollary of
+        When set to any other value:
+	\begin{itemize}
+	\item the device MUST return 0 on reads from the driver_feature field
+	\item the device MUST ignore writing of 0 into the driver_feature field
+	\item the driver MUST NOT write any non 0 value into driver_feature (a corollary of
         the rule that the driver can only write a subset of device features).
+	\end{itemize}
 
 \item[\field{driver_feature}]
         The driver writes this to accept feature bits offered by the device.
@@ -1081,11 +1089,8 @@ struct virtio_pci_notify_cap {
 };
 \end{lstlisting}
 
-The device MUST present an even \field{cap.length} of at least 2.
-
-The device MUST present \field{notify_off_multiplier} as an even power of 2,
-or 0.  The device MUST ignore a capability with \field{notify_off_multiplier}
-of 1.
+The device MUST either present notify_off_multiplier as an even power of 2,
+or present notify_off_multiplier as 0.
 
 \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:
@@ -1094,13 +1099,21 @@ derive the Queue Notify address within a BAR for a specific queue:
         cap.offset + queue_notify_off * notify_off_multiplier
 \end{lstlisting}
 
-The \field{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.
 
 For example, if \field{notifier_off_multiplier} is 0, all queues will use the same 
 Queue Notify address.
 
+The value \field{cap.length} presented by the device MUST be at least 2
+and MUST be large enough to support queue notification offsets
+for all supported queues in all possible configurations.
+For all queues, the value \field{cap.length} presented by the device MUST satisty:
+\begin{lstlisting}
+	cap.length >= queue_notify_off * notify_off_multiplier + 2
+\end{lstlisting}
+
 \subsubsection{ISR status capability}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / ISR status capability}
 
 The device MUST present at least one VIRTIO_PCI_CAP_ISR_CFG capability.  This
@@ -1136,6 +1149,9 @@ struct virtio_pci_cfg_cap {
 };
 \end{lstlisting}
 
+The fields \field{cap.bar}, \field{cap.legth}, \field{cap.offset} and
+\field{pci_cfg_data} are read-write (RW).
+
 To access a device region, the driver writes into the capability
 structure (ie. within the PCI configuration space) as follows:
 
@@ -1150,13 +1166,22 @@ structure (ie. within the PCI configuration space) as follows:
   a multiple of \field{cap.length} (ie. all accesses must be aligned).
 \end{itemize}
 
-At that point, the pci_cfg_data field will provide a window of size
-\field{cap.length} into the given \field{cap.bar} at offset \field{cap.offset}: writes will
-have the same effect as writes into the BAR, and reads will have the
-same effect and return the same value as reads from the BAR.
+At that point, \field{pci_cfg_data} will provide a window of size
+\field{cap.length} into the given \field{cap.bar} at offset
+\field{cap.offset} : writes into \field{pci_cfg_data} will
+have the same effect as writes into the BAR, and reads will have
+the same effect and return the same value as reads from the BAR.
+
+Upon detecting driver write access to \field{pci_cfg_data} field,
+device MUST execute a write access of length \field{cap.length}
+at offset \field{cap.offset} at BAR selected by \field{cap.bar}
+using the first \field{cap.length} bytes in pci_cfg_data.
 
-The driver MUST perform reads/writes from/to pci_cfg_data of the same
-width as given by \field{cap.length}.
+Upon detecting driver read access to \field{pci_cfg_data} field,
+device MUST execute a read access of length \field{cap.length} at
+offset \field{cap.offset} at BAR selected by \field{cap.bar} and
+store the result in the first \field{cap.length} bytes in
+pci_cfg_data.
 
 \subsubsection{Legacy Interfaces: A Note on PCI Device Layout}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Legacy Interfaces: A Note on PCI Device Layout}
 
@@ -1369,7 +1394,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}
-- 
MST