OASIS Virtual I/O Device (VIRTIO) TC

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 53 +++++++++++++++++++++++++++-------------------------- 1 file changed, 27 insertions(+), 26 deletions(-) diff --git a/content.tex b/content.tex index 0be7ae2..e70473e 100644 --- a/content.tex +++ b/content.tex @@ -8,7 +8,7 @@ device consists of the following parts: egin{itemize} item Device Status field item Feature bits -item Configuration space +item Device Configuration space item One or more virtqueues end{itemize} @@ -141,19 +141,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 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: egin{lstlisting} u32 before, after; @@ -164,30 +164,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 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 @@ -886,7 +886,7 @@ The fields are interpreted as follows: 0x09; Identifies a vendor-specific capability. item[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[cap_len] Length of this capability structure, including the whole of @@ -928,7 +928,7 @@ The fields are interpreted as follows: item[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. @@ -1249,7 +1249,9 @@ Transitional Devices must assume that Feature Bits 32 to 63 are not acknowledged by Driver. As legacy devices had no configuration generation field, -see
ef{sec:Basic Facilities of a Virtio Device / Configuration Space / Legacy Interface: Configuration Space}~
ameref{sec:Basic Facilities of a Virtio Device / Configuration Space / Legacy Interface: Configuration Space} for workarounds. +see
ef{sec:Basic Facilities of a Virtio Device / Device +Configuration Space / Legacy Interface: Device Configuration +Space}~
ameref{sec:Basic Facilities of a Virtio Device / Device Configuration Space / Legacy Interface: Device Configuration Space} for workarounds. subsection{PCI-specific Initialization And Device Operation}label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation} @@ -1269,7 +1271,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 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 +2181,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 @@ -3555,7 +3556,7 @@ configuration change interrupt. item In either case, once the device has completed the inflation or deflation, the “actual” field of the configuration 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 configuration space are not atomic, this field isn't particularly reliable, but can be used to diagnose buggy guests. } end{enumerate} @@ -4268,16 +4269,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 writable fields, so for most uses it is better to use a virtqueue to update configuration information (the network device does this for filtering, @@ -4314,7 +4315,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 clarityfootnote{Even if it does mean documenting design or implementation mistakes! -- MST

Feedback on ISR status register: It would be helpful if this section provided the meaning of each bit in the register. ISR use is scattered all around the place. Add a section describing the format and semantics. Cc: Arun Subbarao <asubbarao@lnxw.com> Signed-off-by: Michael S. Tsirkin <mst@redhat.com> --- content.tex 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/content.tex b/content.tex index e70473e..199fb1e 100644 --- a/content.tex +++ b/content.tex @@ -1115,6 +1115,31 @@ For all queues, the value cap.length presented by the device MUST satisty: 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. +subsection{ISR status field}label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / ISR status field} + +ISR status field is used for INT#x interrupt handling. +Driver MUST NOT access ISR field when MSI-X capability +is enabled. + +egin{tabular}{ l l l } +hline +Bits & 0 & 1 & 2 to 31 \ +hline +Purpose & Device Configuration Interrupt & Queue Interrupt & Reserved \ +hline +end{tabular} + +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. 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. + +In this way, driver read of ISR status causes the device to de-assert +an interrupt. + 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 -- MST

I didn't really give any thought to PCI-X so let's not promise what we are not sure what we can deliver. Fix up soe cross-references. --- content.tex 6 +++--- introduction.tex 6 +----- 2 files changed, 4 insertions(+), 8 deletions(-) diff --git a/content.tex b/content.tex index 199fb1e..a786832 100644 --- a/content.tex +++ b/content.tex @@ -798,11 +798,11 @@ into virtio general and bus-specific sections. Virtio devices are commonly implemented as PCI devices. A Virtio device can be implemented as any kind of PCI device: -a Conventional PCI device, a PCI-X device or a PCI Express +a Conventional PCI device or a PCI Express device. A Virtio device using Virtio Over PCI Bus MUST expose to guest an interface that meets the specification requirements of -the appropriate PCI specification: hyperref[intro:PCI]{[PCI]}, -hyperref[intro:PCI-X]{[PCI-X]} and hyperref[intro:PCIe]{[PCIe]} +the appropriate PCI specification: hyperref[intro:PCI]{[PCI]} +and hyperref[intro:PCIe]{[PCIe]} respectively. To assure designs meet the latest level requirements, designers of Virtio Over PCI devices must refer to the PCI-SIG home page at url{ http://www.pcisig.com} for any diff --git a/introduction.tex b/introduction.tex index fbe69f6..e5c9e7f 100644 --- a/introduction.tex +++ b/introduction.tex @@ -50,11 +50,7 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S Conventional PCI Specifications,
ewlineurl{ http://www.pcisig.com/specifications/conventional/} , PCI-SIG\ - phantomsectionlabel{intro:PCI-X} extbf{[PCI-X]} & - PCI-X Specifications, -
ewlineurl{ http://www.pcisig.com/specifications/pcix_20/} , - PCI-SIG\ - phantomsectionlabel{intro:PCI-X} extbf{[PCIe]} & + phantomsectionlabel{intro:PCIe} extbf{[PCIe]} & PCI Express Specifications
ewlineurl{ http://www.pcisig.com/specifications/pciexpress/} , PCI-SIG\ -- MST

--- content.tex 1 - 1 file changed, 1 deletion(-) diff --git a/content.tex b/content.tex index a786832..262a5c7 100644 --- a/content.tex +++ b/content.tex @@ -1105,7 +1105,6 @@ The value 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 cap.length presented by the device MUST satisty: - egin{lstlisting} cap.length >= queue_notify_off * notify_off_multiplier + 2 end{lstlisting} -- MST