[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: [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 <mst@redhat.com> --- 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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]