virtio — archive

[Michael S. Tsirkin <mst@redhat.com>]

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: + egin{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: +egin{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