diff options
| -rw-r--r-- | content.tex | 74 |
1 files changed, 40 insertions, 34 deletions
diff --git a/content.tex b/content.tex index 999ebbd..aa191a3 100644 --- a/content.tex +++ b/content.tex @@ -654,14 +654,14 @@ free descriptors before beginning the mappings. The descriptor chain head is the first d in the algorithm above, ie. the index of the descriptor table entry referring to the first -part of the buffer. A naive implementation would do the following (with the +part of the buffer. A naive driver implementation MAY do the following (with the appropriate conversion to-and-from little-endian assumed): \begin{lstlisting} avail->ring[avail->idx % qsz] = head; \end{lstlisting} -However, in general the driver can add many descriptor chains before it updates +However, in general the driver MAY add many descriptor chains before it updates \field{idx} (at which point they become visible to the device), so it is common to keep a counter of how many the driver has added: @@ -671,13 +671,13 @@ avail->ring[(avail->idx + added++) % qsz] = head; \subsubsection{Updating \field{idx}}\label{sec:General Initialization And Device Operation / Device Operation / Supplying Buffers to The Device / Updating idx} -Once \field{idx} is updated, the device will -be able to access the descriptor chains the driver created and the -memory they refer to. This is why a memory barrier is generally -used before the \field{idx} update, to ensure it sees the most up-to-date -copy. +Once available \field{idx} is updated by driver, the device MAY +access the descriptor chains the driver created and the +memory they refer to. This is why the driver SHOULD generally +use a memory barrier before the \field{idx} update, to ensure the +device sees the most up-to-date copy. -\field{idx} always increments, and the driver can let it wrap naturally at +\field{idx} always increments, and wraps naturally at 65536: \begin{lstlisting} @@ -718,7 +718,8 @@ similar to the algorithm used for the driver to send the device a buffer: \begin{enumerate} -\item Write the head descriptor number to the next entry in the used +\item Write the head descriptor number to the next free entry + (pointed to by the used ring \field{idx}) in the used ring. \item Update the used ring \field{idx}. @@ -946,7 +947,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}] @@ -1096,14 +1097,14 @@ struct virtio_pci_notify_cap { The device MUST either present \field{notify_off_multiplier} as an even power of 2, or present \field{notify_off_multiplier} as 0. -\field{notify_off_multiplier} field is combined with the \field{queue_notify_off} to +\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: \begin{lstlisting} cap.offset + queue_notify_off * notify_off_multiplier \end{lstlisting} -The 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. @@ -1123,10 +1124,12 @@ cap.length >= queue_notify_off * notify_off_multiplier + 2 The device MUST present at least one VIRTIO_PCI_CAP_ISR_CFG capability. This refers to at least a single byte, which contains the 8-bit ISR status field. -The \field{offset} for the ISR status field has no specific alignment requirements. +The \field{offset} for the \field{ISR status} has no specific alignment requirements. -The ISR status field is used for INT\#x interrupt handling. -The driver MUST NOT access the ISR field when MSI-X capability +\subsection{ISR status field}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / ISR status field} + +\field{ISR status} is used for INT\#x interrupt handling. +Driver MUST NOT access \field{ISR status} when MSI-X capability is enabled. \begin{tabular}{ |l||l|l|l| } @@ -1139,15 +1142,17 @@ Purpose & Device Configuration Interrupt & Queue Interrupt & Reserved \\ If MSI-X capability is disabled, device MUST set Interrupt Status bit in the PCI Status register in the PCI Configuration Header of -the device to the logical OR of all bits in ISR status field of +the device to the logical OR of all bits in \field{ISR status} of the device. Device then asserts/deasserts INT\#x interrupts unless masked according to standard PCI rules \hyperref[intro:PCI]{[PCI]}. -Device MUST reset the ISR status field to 0 on read. +Device MUST reset \field{ISR status} to 0 on read. -In this way, driver read of ISR status causes the device to de-assert +In this way, driver read of \field{ISR status} causes the device to de-assert an interrupt. +See sections \ref{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Virtqueue Interrupts From The Device} and \ref{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Notification of Device Configuration Changes} for how this is used. + \subsubsection{Device specific structure}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Device specific structure} The device MAY present at least one VIRTIO_PCI_CAP_DEVICE_CFG capability (some @@ -1170,10 +1175,10 @@ struct virtio_pci_cfg_cap { }; \end{lstlisting} -The fields \field{cap.bar}, \field{cap.length}, \field{cap.offset} and \field{pci_cfg_data} -are read-write (RW). +The fields \field{cap.bar}, \field{cap.legth}, \field{cap.offset} and +\field{pci_cfg_data} are read-write (RW). -To access to a device region, the driver writes into the capability +To access a device region, the driver writes into the capability structure (ie. within the PCI configuration space) as follows: \begin{itemize} @@ -1207,12 +1212,11 @@ Transitional devices should present part of configuration registers in a legacy configuration structure in BAR0 in the first I/O region of the PCI device, as documented below. -There may be different widths of accesses to the I/O region; the -“natural” access method for each field in the virtio common configuration structure must be -used (i.e. 32-bit accesses for 32-bit fields, etc), but -when accessed through the legacy interface the -device-specific region can be accessed using any width accesses, and -should obtain the same results. +When accessed through the legacy interface the driver MAY access +the device-specific region using any width accesses, and +a transitional device MUST present it with the same results as +when accessed using the “natural” access method (i.e. +32-bit accesses for 32-bit fields, etc). Note that this is possible because while the virtio common configuration structure is PCI (i.e. little) endian, when using the legacy interface the device-specific @@ -1334,7 +1338,7 @@ Writing a valid MSI-X Table entry number, 0 to 0x7FF, to \field{config_msix_vector}/\field{queue_msix_vector} maps interrupts triggered by the configuration change/selected queue events respectively to the corresponding MSI-X vector. To disable interrupts for a -specific event type, unmap it by writing a special NO_VECTOR +specific event type, unmap this event by writing a special NO_VECTOR value: \begin{lstlisting} @@ -1346,14 +1350,15 @@ Reading these registers returns vector mapped to a given event, or NO_VECTOR if unmapped. All queue and configuration change events are unmapped by default. -Note that mapping an event to vector might require allocating -internal device resources, and might fail. Devices MUST report such +Note that mapping an event to vector might require device to +allocate internal device resources, and MAY fail. Devices MUST report such failures by returning the NO_VECTOR value when the relevant Vector field is read. After mapping an event to vector, the driver MUST verify success by reading the Vector field value: on success, the previously written value is returned, and on failure, NO_VECTOR is returned. If a mapping failure is detected, -the driver can retry mapping with fewer vectors, or disable MSI-X. +the driver MAY retry mapping with fewer vectors, disable MSI-X +or report device failure. \paragraph{Virtqueue Configuration}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Device Initialization / Virtqueue Configuration} @@ -1415,7 +1420,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} @@ -1439,7 +1444,8 @@ The driver interrupt handler SHOULD: \subsubsection{Notification of Device Configuration Changes}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Notification of Device Configuration Changes} -Some devices can change the device configuration space. In this case: +Some virtio PCI devices can change the device configuration +state, as reflected in the device-specific region of the device. In this case: \begin{itemize} \item If MSI-X capability is disabled: an interrupt is delivered and @@ -3616,7 +3622,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 device 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} |