On Mon, Dec 02, 2013 at 04:56:16PM +1030, Rusty Russell wrote:
> This change:
> - Turns formatted lists into real lists (itemize, etc).
> - Turns ascii tables into real tables.
> - Use \ldots for ...
> - Moves \footnote to immediately after what it refers to, otherwise we
> get awkward whitespace before the superscript.
> - List of stats for balloon contains values in () to match other lists.
> - Puts lstlisting around CCW code example
>
> No actual contents changed, but I haven't committed it yet to avoid
> stepping on MST's toes if he has outstanding commits.
>
> Signed-off-by: Rusty Russell <>
I don't have outstanding commits so please go ahead.
Did you use some script for converting these?
> diff --git a/content.tex b/content.tex
> index 259dea1..8db13c4 100644
> --- a/content.tex
> +++ b/content.tex
> @@ -5,10 +5,12 @@ A virtio device is discovered and identified by a bus-specific method
> \ref{sec:Virtio Transport Options / Virtio Over MMIO}~\nameref{sec:Virtio Transport Options / Virtio Over MMIO} and \ref{sec:Virtio Transport Options / Virtio Over Channel I/O}~\nameref{sec:Virtio Transport Options / Virtio Over Channel I/O}). Each
> device consists of the following parts:
>
> -o Device Status field
> -o Feature bits
> -o Configuration space
> -o One or more virtqueues
> +\begin{itemize}
> +\item Device Status field
> +\item Feature bits
> +\item Configuration space
> +\item One or more virtqueues
> +\end{itemize}
>
> Unless explicitly specified otherwise, all multi-byte fields are little-endian.
> To reinforce this the examples use typenames like "le16" instead of "uint16_t".
> @@ -23,25 +25,27 @@ clear a device status bit.
>
> This field is 0 upon reset, otherwise at least one bit should be set:
>
> - ACKNOWLEDGE (1) Indicates that the guest OS has found the
> +\begin{description}
> +\item[ACKNOWLEDGE (1)] Indicates that the guest OS has found the
> device and recognized it as a valid virtio device.
>
> - DRIVER (2) Indicates that the guest OS knows how to drive the
> +\item[DRIVER (2)] Indicates that the guest OS knows how to drive the
> device. Under Linux, drivers can be loadable modules so there
> may be a significant (or infinite) delay before setting this
> bit.
>
> - FEATURES_OK (8) Indicates that the driver has acknowledged all the
> +\item[FEATURES_OK (8)] Indicates that the driver has acknowledged all the
> features it understands, and feature negotiation is complete.
>
> - DRIVER_OK (4) Indicates that the driver is set up and ready to
> +\item[DRIVER_OK (4)] Indicates that the driver is set up and ready to
> drive the device.
>
> - FAILED (128) Indicates that something went wrong in the guest,
> +\item[FAILED (128)] Indicates that something went wrong in the guest,
> and it has given up on the device. This could be an internal
> error, or the driver didn't like the device for some reason, or
> even a fatal error during device operation. The driver MUST
> reset the device before attempting to re-initialize.
> +\end{description}
>
> \section{Feature Bits}\label{sec:Basic Facilities of a Virtio Device / Feature Bits}
>
> @@ -67,12 +71,14 @@ which was not offered.
>
> Feature bits are allocated as follows:
>
> - 0 to 23: Feature bits for the specific device type
> +\begin{description}
> +\item[0 to 23] Feature bits for the specific device type
>
> - 24 to 32: Feature bits reserved for extensions to the queue and
> +\item[24 to 32] Feature bits reserved for extensions to the queue and
> feature negotiation mechanisms
>
> - 33 and above: Feature bits reserved for future extensions.
> +\item[33 and above] Feature bits reserved for future extensions.
> +\end{description}
>
> For example, feature bit 0 for a network device (i.e. Subsystem
> Device ID 1) indicates that the device supports checksumming of
> @@ -91,15 +97,17 @@ Since these are widely deployed, this specification
> accommodates optional features to simplify transition
> from these earlier draft interfaces. Specifically:
>
> -Legacy Interface
> +\begin{description}
> +\item[Legacy Interface]
> is an interface specified by an earlier draft of this specification
> (up to 0.9.X)
> -Legacy Device
> +\item[Legacy Device]
> is a device implemented before this specification was released,
> and implementing a legacy interface on the host side
> -Legacy Driver
> +\item[Legacy Driver]
> is a driver implemented before this specification was released,
> and implementing a legacy interface on the guest side
> +\end{description}
>
> Legacy devices and legacy drivers are not compliant with this
> specification.
> @@ -107,13 +115,15 @@ specification.
> To simplify transition from these earlier draft interfaces,
> it is possible to implement:
>
> -Transitional Device
> +\begin{description}
> +\item[Transitional Device]
> a device supporting both drivers conforming to this
> specification, and allowing legacy drivers.
>
> -Transitional Driver
> +\item[Transitional Driver]
> a driver supporting both devices conforming to this
> specification, and legacy devices.
> +\end{description}
>
> Transitional devices and transitional drivers can be compliant with
> this specification (ie. when not operating in legacy mode).
> @@ -196,11 +206,11 @@ of the queue.
>
> Each virtqueue consists of three parts:
>
> - Descriptor Table
> -
> - Available Ring
> -
> - Used Ring
> +\begin{itemize}
> +\item Descriptor Table
> +\item Available Ring
> +\item Used Ring
> +\end{itemize}
>
> where each part is physically-contiguous in guest memory,
> and has different alignment requirements.
> @@ -208,18 +218,17 @@ and has different alignment requirements.
> The memory aligment and size requirements, in bytes, of each part of the
> virtqueue are summarized in the following table:
>
> -\begin{verbatim}
> -+------------+-----------------------------------------+
> -| Virtqueue Part | Alignment | Size |
> -+------------+-----------------------------------------+
> -+------------+-----------------------------------------+
> -| Descriptor Table | 16 | 16 * (Queue Size) |
> -+------------+-----------------------------------------+
> -| Available Ring | 2 | 6 + 2 * (Queue Size) |
> -+------------+-----------------------------------------+
> -| Used Ring | 4 | 6 + 4 * (Queue Size) |
> -+------------+-----------------------------------------+
> -\end{verbatim}
> +\begin{tabular}{|l|l|l|}
> +\hline
> +Virtqueue Part & Alignment & Size \\
> +\hline \hline
> +Descriptor Table & 16 & $16 * $(Queue Size) \\
> +\hline
> +Available Ring & 2 & $6 + 2 * $(Queue Size) \\
> + \hline
> +Used Ring & 4 & $6 + 4 * $(Queue Size) \\
> + \hline
> +\end{tabular}
>
> The Alignment column gives the miminum alignment: for each part
> of the virtqueue, the physical address of the first byte
> @@ -250,11 +259,11 @@ Each virtqueue occupies two or more physically-contiguous pages
> (usually defined as 4096 bytes, but depending on the transport)
> and consists of three parts:
>
> -\begin{verbatim}
> -+-------------------+-----------------------------------+-----------+
> -| Descriptor Table | Available Ring (padding) | Used Ring |
> -+-------------------+-----------------------------------+-----------+
> -\end{verbatim}
> +\begin{tabular}{|l|l|l|}
> +\hline
> +Descriptor Table & Available Ring (\ldots padding\ldots) & Used Ring \\
> +\hline
> +\end{tabular}
>
> The bus-specific Queue Size field controls the total number of bytes
> required for the virtqueue according to the following formula:
> @@ -503,28 +512,30 @@ how to communicate with the specific device.
>
> The driver MUST follow this sequence to initialize a device:
>
> -1. Reset the device.
> +\begin{enumerate}
> +\item Reset the device.
>
> -2. Set the ACKNOWLEDGE status bit: we have noticed the device.
> +\item Set the ACKNOWLEDGE status bit: we have noticed the device.
>
> -3. Set the DRIVER status bit: we know how to drive the device.
> +\item Set the DRIVER status bit: we know how to drive the device.
>
> -4. Read device feature bits, and write the subset of feature bits
> +\item Read device feature bits, and write the subset of feature bits
> understood by the OS and driver to the device.
>
> -5. Set the FEATURES_OK status bit. The driver MUST not accept
> +\item Set the FEATURES_OK status bit. The driver MUST not accept
> new feature bits after this step.
>
> -6. Re-read the status byte to ensure the FEATURES_OK bit is still
> +\item Re-read the status byte to ensure the FEATURES_OK bit is still
> set: otherwise, the device does not support our subset of features
> and the device is unusable.
>
> -7. Perform device-specific setup, including discovery of virtqueues for the
> +\item Perform device-specific setup, including discovery of virtqueues for the
> device, optional per-bus setup, reading and possibly writing the
> device's virtio configuration space, and population of virtqueues.
>
> -8. Set the DRIVER_OK status bit. At this point the device is
> +\item Set the DRIVER_OK status bit. At this point the device is
> "live".
> +\end{enumerate}
>
> If any of these steps go irrecoverably wrong, the driver SHOULD
> set the FAILED status bit to indicate that it has given up on the
> @@ -568,27 +579,29 @@ they are used.
>
> The driver offers buffers to one of the device's virtqueues as follows:
>
> -1. The driver places the buffer into free descriptor(s) in the
> +\begin{enumerate}
> +\item The driver places the buffer into free descriptor(s) in the
> descriptor table, chaining as necessary (see \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table}~\nameref{sec:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table}).
>
> -2. The driver places the index of the head of the descriptor chain
> +\item The driver places the index of the head of the descriptor chain
> into the next ring entry of the available ring.
>
> -3. Steps (1) and (2) may be performed repeatedly if batching
> +\item Steps (1) and (2) may be performed repeatedly if batching
> is possible.
>
> -4. The driver MUST perform suitable a memory barrier to ensure the device sees
> +\item The driver MUST perform suitable a memory barrier to ensure the device sees
> the updated descriptor table and available ring before the next
> step.
>
> -5. The available “idx” field is increased by the number of
> +\item The available “idx” field is increased by the number of
> descriptor chain heads added to the available ring.
>
> -6. The driver MUST perform a suitable memory barrier to ensure that it updates
> +\item The driver MUST perform a suitable memory barrier to ensure that it updates
> the "idx" field before checking for notification suppression.
>
> -7. If notifications are not suppressed, the driver MUST notify the device
> +\item If notifications are not suppressed, the driver MUST notify the device
> of the new available buffers.
> +\end{enumerate}
>
> Note that the above code does not take precautions against the
> available ring buffer wrapping around: this is not possible since
> @@ -611,21 +624,19 @@ chain:
>
> for each buffer element, b:
>
> - (a) Get the next free descriptor table entry, d
> -
> - (b) Set d.addr to the physical address of the start of b
> -
> - (c) Set d.len to the length of b.
> -
> - (d) If b is write-only, set d.flags to VRING_DESC_F_WRITE,
> +\begin{enumerate}
> +\item Get the next free descriptor table entry, d
> +\item Set d.addr to the physical address of the start of b
> +\item Set d.len to the length of b.
> +\item If b is write-only, set d.flags to VRING_DESC_F_WRITE,
> otherwise 0.
> -
> - (e) If there is a buffer element after this:
> -
> - i. Set d.next to the index of the next free descriptor
> +\item If there is a buffer element after this:
> + \begin{enumerate}
> + \item Set d.next to the index of the next free descriptor
> element.
> -
> - ii. Set the VRING_DESC_F_NEXT bit in d.flags.
> + \item Set the VRING_DESC_F_NEXT bit in d.flags.
> + \end{enumerate}
> +\end{enumerate}
>
> In practice, the d.next fields are usually used to chain free
> descriptors, and a separate count kept to check there are enough
> @@ -698,24 +709,28 @@ device), it sends an interrupt, following an algorithm very
> similar to the algorithm used for the driver to send the device a
> buffer:
>
> -1. Write the head descriptor number to the next field in the used
> +\begin{enumerate}
> +\item Write the head descriptor number to the next field in the used
> ring.
>
> -2. Update the used ring index.
> +\item Update the used ring index.
>
> -3. Deliver an interrupt if necessary:
> +\item Deliver an interrupt if necessary:
>
> - (a) If the VIRTIO_F_RING_EVENT_IDX feature is not negotiated:
> + \begin{enumerate}
> + \item If the VIRTIO_F_RING_EVENT_IDX feature is not negotiated:
> check if the VRING_AVAIL_F_NO_INTERRUPT flag is not set in
> avail->flags.
>
> - (b) If the VIRTIO_F_RING_EVENT_IDX feature is negotiated: check
> + \item If the VIRTIO_F_RING_EVENT_IDX feature is negotiated: check
> whether the used index crossed the used_event field value
> since the last update. The used_event field wraps naturally
> at 65536 as well:
> \begin{lstlisting}
> (u16)(new_idx - used_event - 1) < (u16)(new_idx - old_idx)
> \end{lstlisting}
> + \end{enumerate}
> +\end{enumerate}
>
> For each ring, the driver should then disable interrupts by writing
> VRING_AVAIL_F_NO_INTERRUPT flag in avail structure, if required.
> @@ -764,8 +779,7 @@ Virtio devices are commonly implemented as PCI devices.
> \subsection{PCI Device Discovery}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Discovery}
>
> Any PCI device with Vendor ID 0x1AF4, and Device ID 0x1000 through
> -0x103F inclusive is a virtio device
> -\footnote{The actual value within this range is ignored
> +0x103F inclusive is a virtio device\footnote{The actual value within this range is ignored
> }.
>
> The Subsystem Device ID indicates which virtio device is
> @@ -830,20 +844,18 @@ Common configuration structure layout is documented below:
> };
> \end{lstlisting}
>
> -device_feature_select
> -
> +\begin{description}
> +\item[device_feature_select]
> The driver uses this to select which Feature Bits the device_feature field shows.
> Value 0x0 selects Feature Bits 0 to 31
> Value 0x1 selects Feature Bits 32 to 63
> The device MUST present 0 on device_feature for any other value.
>
> -device_feature
> -
> +\item[device_feature]
> The device uses this to report Feature Bits to the driver.
> Device Feature Bits selected by device_feature_select.
>
> -driver_feature_select
> -
> +\item[driver_feature_select]
> The driver uses this to select which Feature Bits the driver_feature field shows.
> Value 0x0 selects Feature Bits 0 to 31
> Value 0x1 selects Feature Bits 32 to 63
> @@ -852,72 +864,60 @@ driver_feature_select
> MUST not write any other value into driver_feature (a corollary of
> the rule that the driver can only write a subset of device features).
>
> -driver_feature
> -
> +\item[driver_feature]
> The driver writes this to accept feature bits offered by the device.
> Driver Feature Bits selected by driver_feature_select.
>
> -msix_config
> -
> +\item[msix_config]
> The driver sets the Configuration Vector for MSI-X.
>
> -num_queues
> -
> +\item[num_queues]
> The device specifies the maximum number of virtqueues supported here.
>
> -device_status
> -
> +\item[device_status]
> The driver writes the Device Status here. Writing 0 into this
> field resets the device.
>
> -config_generation
> -
> +\item[config_generation]
> Configuration atomicity value. The device changes this every time the
> configuration noticeably changes. This means the device may
> only change the value after a configuration read operation,
> but MUST change it if there is any risk of a driver seeing an
> inconsistent configuration state.
>
> -queue_select
> -
> +\item[queue_select]
> Queue Select. The driver selects which virtqueue the following
> fields refer to.
>
> -queue_size
> -
> +\item[queue_size]
> Queue Size. On reset, specifies the maximum queue size supported by
> the hypervisor. This can be modified by driver to reduce memory requirements.
> The device MUST set this to 0 if this virtqueue is unavailable.
>
> -queue_msix_vector
> -
> +\item[queue_msix_vector]
> The driver uses this to specify the Queue Vector for MSI-X.
>
> -queue_enable
> -
> +\item[queue_enable]
> The driver uses this to selectively prevent the device from executing requests from this virtqueue.
> 1 - enabled; 0 - disabled
>
> The driver MUST configure the other virtqueue fields before enabling
> the virtqueue.
>
> -queue_notify_off
> -
> +\item[queue_notify_off]
> The driver reads this to calculate the offset from start of Notification structure at
> which this virtqueue is located.
> Note: this is *not* an offset in bytes. See notify_off_multiplier below.
>
> -queue_desc
> -
> +\item[queue_desc]
> The driver writes the physical address of Descriptor Table here.
>
> -queue_avail
> -
> +\item[queue_avail]
> The driver writes the physical address of Available Ring here.
>
> -queue_used
> -
> +\item[queue_used]
> The driver writes the physical address of Used Ring here.
> +\end{description}
>
> \subsubsection{ISR status structure layout}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / ISR status structure layout}
> ISR status structure includes a single 8-bit ISR status field.
> @@ -967,17 +967,15 @@ When used through the legacy interface, the virtio header looks as follows:
> If MSI-X is enabled for the device, two additional fields
> immediately follow this header:
>
> -
> -\begin{verbatim}
> -+------------++----------------+--------+
> -| Bits || 16 | 16 |
> -+------------++----------------+--------+
> -| Read/Write || R+W | R+W |
> -+------------++----------------+--------+
> -| Purpose || Configuration | Queue |
> -| (MSI-X) || Vector | Vector |
> -+------------++----------------+--------+
> -\end{verbatim}
> +\begin{tabular}{ |l||l|l| }
> +\hline
> +Bits & 16 & 16 \\
> +\hline
> +Read/Write & R+W & R+W \\
> +\hline
> +Purpose (MSI-X) & Configuration Vector & Queue Vector \\
> +\hline
> +\end{tabular}
>
> Note: When MSI-X capability is enabled, device specific configuration starts at
> byte offset 24 in virtio header structure. When MSI-X capability is not
> @@ -988,16 +986,15 @@ If you turn it off again, they move back!
> Immediately following these general headers, there may be
> device-specific headers:
>
> -\begin{verbatim}
> -+------------++--------------------+
> -| Bits || Device Specific |
> -+------------++--------------------+
> -| Read/Write || Device Specific |
> -+------------++--------------------+
> -| Purpose || Device Specific... |
> -| || |
> -+------------++--------------------+
> -\end{verbatim}
> +\begin{tabular}{ |l||l| }
> +\hline
> +Bits & Device Specific \\
> +\hline
> +Read/Write & Device Specific \\
> +\hline
> +Purpose & Device Specific... \\
> +\hline
> +\end{tabular}
>
> Note that only Feature Bits 0 to 31 are accessible through the
> Legacy Interface. When used through the Legacy Interface,
> @@ -1013,7 +1010,7 @@ see \ref{sec:Basic Facilities of a Virtio Device / Configuration Space / Legacy
>
> This documents PCI-specific steps executed during Device Initialization.
> As the first step, driver must detect device configuration layout
> -to locate configuration fields in memory,I/O or configuration space of the
> +to locate configuration fields in memory, I/O or configuration space of the
> device.
>
> \paragraph{Virtio Device Configuration Layout Detection}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Device Initialization / Virtio Device Configuration Layout Detection}
> @@ -1065,18 +1062,19 @@ specified 8-bit size.
>
> The fields are interpreted as follows:
>
> -cap_vndr
> +\begin{description}
> +\item[cap_vndr]
> 0x09; Identifies a vendor-specific capability.
>
> -cap_next
> +\item[cap_next]
> Link to next capability in the capability list in the configuration space.
>
> -cap_len
> +\item[cap_len]
> Length of the capability structure, including the whole of
> struct virtio_pci_cap, and extra data if any.
> This length might include padding, or fields unused by the driver.
>
> -cfg_type
> +\item[cfg_type]
> identifies the structure, according to the following table.
>
> \begin{lstlisting}
> @@ -1107,7 +1105,7 @@ cfg_type
> Driver will use the I/O BAR if I/O resources are available, and fall back on
> memory BAR when I/O resources are unavailable.
>
> -bar
> +\item[bar]
> values 0x0 to 0x5 specify a Base Address register (BAR) belonging to
> the function located beginning at 10h in Configuration Space
> and used to map the structure into Memory or I/O Space.
> @@ -1118,11 +1116,11 @@ bar
> ignore any vendor-specific capability structure which has
> a reserved bar value.
>
> -offset
> +\item[offset]
> indicates where the structure begins relative to the base address associated
> with the BAR.
>
> -length
> +\item[length]
> indicates the length of the structure.
> This size might include padding, or fields unused by the driver.
> Drivers SHOULD only map part of configuration structure
> @@ -1133,7 +1131,7 @@ length
> driver can limit the mapped structure size to e.g.
> 4KBytes to allow forward compatibility with such devices without loss of
> functionality and without wasting resources.
> -
> +\end{description}
>
> If cfg_type is VIRTIO_PCI_CAP_NOTIFY_CFG this structure is immediately followed
> by additional fields:
> @@ -1145,7 +1143,8 @@ by additional fields:
> };
> \end{lstlisting}
>
> -notify_off_multiplier
> +\begin{description}
> +\item[notify_off_multiplier]
>
> Virtqueue offset multiplier, in bytes. Must be even and either a power of two, or 0.
> Value 0x1 is reserved.
> @@ -1155,6 +1154,7 @@ notify_off_multiplier
>
> If notify_off_multiplier is 0, all virtqueues use the same address in
> the Notifications structure!
> +\end{description}
>
> If cfg_type is VIRTIO_PCI_CAP_PCI_CFG the fields bar, offset and length are RW
> and this structure is immediately followed by an additional field:
> @@ -1165,7 +1165,8 @@ and this structure is immediately followed by an additional field:
> };
> \end{lstlisting}
>
> -pci_cfg_data
> +\begin{description}
> +\item[pci_cfg_data]
>
> This RW field allows an indirect access to any BAR on the
> device using PCI configuration accesses.
> @@ -1182,6 +1183,7 @@ pci_cfg_data
>
> When this field is read by driver, length bytes at the
> selected offset in the selected BAR are read into pci_cfg_data.
> +\end{description}
>
> \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}
>
> @@ -1210,10 +1212,12 @@ a legacy device with the same ID might have previously existed,
> must take the following steps to fail gracefully when a legacy
> driver attempts to drive them:
>
> -1) Present an I/O BAR in BAR0, and
> -2) Respond to a single-byte zero write to offset 18
> +\begin{enumerate}
> +\item Present an I/O BAR in BAR0, and
> +\item Respond to a single-byte zero write to offset 18
> (corresponding to Device Status register in the legacy layout)
> of BAR0 by presenting zeroes on every BAR and ignoring writes.
> +\end{enumerate}
>
> \paragraph{Queue Vector Configuration}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Device Initialization / Queue Vector Configuration}
>
> @@ -1256,31 +1260,32 @@ configuration.
>
> The driver does this as follows, for each virtqueue a device has:
>
> -1. Write the virtqueue index (first queue is 0) to the Queue
> +\begin{enumerate}
> +\item Write the virtqueue index (first queue is 0) to the Queue
> Select field.
>
> -2. Read the virtqueue size from the Queue Size field, which MUST
> +\item Read the virtqueue size from the Queue Size field, which MUST
> be a power of 2. This controls how big the virtqueue is
> (see \ref{sec:Basic Facilities of a Virtio Device / Virtqueues}~\nameref{sec:Basic Facilities of a Virtio Device / Virtqueues}). If this field is 0, the virtqueue does not exist.
>
> -3. Optionally, select a smaller virtqueue size and write it in the Queue Size
> +\item Optionally, select a smaller virtqueue size and write it in the Queue Size
> field.
>
> -4. Allocate and zero Descriptor Table, Available and Used rings for the
> +\item Allocate and zero Descriptor Table, Available and Used rings for the
> virtqueue in contiguous physical memory.
>
> -5. Optionally, if MSI-X capability is present and enabled on the
> +\item Optionally, if MSI-X capability is present and enabled on the
> device, select a vector to use to request interrupts triggered
> by virtqueue events. Write the MSI-X Table entry number
> corresponding to this vector in Queue Vector field. Read the
> Queue Vector field: on success, previously written value is
> returned; on failure, NO_VECTOR value is returned.
> +\end{enumerate}
>
> \subparagraph{Legacy Interface: A Note on Virtqueue Configuration}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Device Initialization / Virtqueue Configuration / Legacy Interface: A Note on Virtqueue Configuration}
> When using the legacy interface, the page size for a virtqueue on a PCI virtio
> device is defined as 4096 bytes. Driver writes the physical address, divided
> -by 4096 to the Queue Address field
> -\footnote{The 4096 is based on the x86 page size, but it's also large
> +by 4096 to the Queue Address field\footnote{The 4096 is based on the x86 page size, but it's also large
> enough to ensure that the separate parts of the virtqueue are on
> separate cache lines.
> }.
> @@ -1294,34 +1299,40 @@ of this virtqueue to the Queue Notify field.
>
> If an interrupt is necessary:
>
> - (a) If MSI-X capability is disabled:
> -
> - i. Set the lower bit of the ISR Status field for the device.
> +\begin{itemize}
> + \item If MSI-X capability is disabled:
> + \begin{enumerate}
> + \item Set the lower bit of the ISR Status field for the device.
>
> - ii. Send the appropriate PCI interrupt for the device.
> + \item Send the appropriate PCI interrupt for the device.
> + \end{enumerate}
>
> - (b) If MSI-X capability is enabled:
> -
> - i. Request the appropriate MSI-X interrupt message for the
> + \item If MSI-X capability is enabled:
> + \begin{enumerate}
> + \item Request the appropriate MSI-X interrupt message for the
> device, Queue Vector field sets the MSI-X Table entry
> number.
>
> - ii. If Queue Vector field value is NO_VECTOR, no interrupt
> + \item If Queue Vector field value is NO_VECTOR, no interrupt
> message is requested for this event.
> + \end{enumerate}
> +\end{itemize}
>
> The driver interrupt handler should:
>
> -1. If MSI-X capability is disabled: read the ISR Status field,
> +\begin{itemize}
> + \item If MSI-X capability is disabled: read the ISR Status field,
> which will reset it to zero. If the lower bit is zero, the
> interrupt was not for this device. Otherwise, the driver
> should look through the used rings of each virtqueue for the
> device, to see if any progress has been made by the device
> which requires servicing.
>
> -2. If MSI-X capability is enabled: look through the used rings of
> + \item If MSI-X capability is enabled: look through the used rings of
> each virtqueue mapped to the specific MSI-X vector for the
> device, to see if any progress has been made by the device
> which requires servicing.
> +\end{itemize}
>
> \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}
>
> @@ -1329,7 +1340,8 @@ Some virtio PCI devices can change the device configuration
> state, as reflected in the virtio header in the PCI configuration
> space. In this case:
>
> -1. If MSI-X capability is disabled: an interrupt is delivered and
> +\begin{itemize}
> + \item If MSI-X capability is disabled: an interrupt is delivered and
> the second lowest bit is set in the ISR Status field to
> indicate that the driver should re-examine the configuration
> space. Note that a single interrupt can indicate both that one
> @@ -1337,10 +1349,11 @@ space. In this case:
> space has changed: even if the config bit is set, virtqueues
> must be scanned.
>
> -2. If MSI-X capability is enabled: an interrupt message is
> + \item If MSI-X capability is enabled: an interrupt message is
> requested. The Configuration Vector field sets the MSI-X Table
> entry number to use. If Configuration Vector field value is
> NO_VECTOR, no interrupt message is requested for this event.
> +\end{itemize}
>
> \section{Virtio Over MMIO}\label{sec:Virtio Transport Options / Virtio Over MMIO}
>
> @@ -1371,29 +1384,25 @@ systems using Flattened Device Trees the suggested format is:
>
> MMIO virtio devices provides a set of memory mapped control
> registers, all 32 bits wide, followed by device-specific
> -configuration space. The following list presents their layout:
> -
> -* Offset from the device base address | Direction | Name
> - Description
> +configuration space. The following table presents their names,
> +offset from the base address, and whether they are read-only (R) or write-only (W) from the driver's perspective:
>
> -* 0x000 | R | MagicValue
> +\begin{description}
> +\item[MagicValue (0x000) - R]
> Magic value. Must be 0x74726976 (a Little Endian equivalent
> of a "virt" string).
> -
> -* 0x004 | R | Version
> +\item[Version (0x004) - R]
> Device version number. Devices compliant with this specification
> must return value 0x2.
> -
> -* 0x008 | R | DeviceID
> +\item[DeviceID (0x008) - R]
> Virtio Subsystem Device ID.
> See \ref{sec:Device Types}~\nameref{sec:Device Types} for possible values. Value zero (0x0)
> is invalid and devices returning this ID must be ignored
> by the guest.
> -
> -* 0x00c | R | VendorID
> +\item[VendorID (0x00c) - R]
> Virtio Subsystem Vendor ID.
>
> -* 0x010 | R | DeviceFeatures
> +\item[DeviceFeatures (0x010) - R]
> Flags representing features the device supports.
> Reading from this register returns 32 consecutive flag bits,
> first bit depending on the last value written to the
> @@ -1403,14 +1412,14 @@ configuration space. The following list presents their layout:
> features bits 32 to 63 if DeviceFeaturesSel is set to 1.
> Also see \ref{sec:Basic Facilities of a Virtio Device / Feature Bits}~\nameref{sec:Basic Facilities of a Virtio Device / Feature Bits}.
>
> -* 0x014 | W | DeviceFeaturesSel
> +\item[DeviceFeaturesSel (0x014) - W]
> Device (host) features word selection.
> Writing to this register selects a set of 32 device feature bits
> accessible by reading from the DeviceFeatures register. Device driver
> must write a value to the DeviceFeaturesSel register before
> reading from the DeviceFeatures register.
>
> -* 0x020 | W | DriverFeatures
> +\item[DriverFeatures (0x020) - W]
> Flags representing device features understood and activated by
> the driver.
> Writing to this register sets 32 consecutive flag bits, first
> @@ -1420,21 +1429,21 @@ configuration space. The following list presents their layout:
> DriverFeaturesSel is set to 0 and features bits 32 to 63 if
> DriverFeaturesSel is set to 1. Also see \ref{sec:Basic Facilities of a Virtio Device / Feature Bits}~\nameref{sec:Basic Facilities of a Virtio Device / Feature Bits}.
>
> -* 0x024 | W | DriverFeaturesSel
> +\item[DriverFeaturesSel (0x024) - W]
> Activated (guest) features word selection.
> Writing to this register selects a set of 32 activated feature
> bits accessible by writing to the DriverFeatures register.
> Device driver must write a value to the DriverFeaturesSel
> register before writing to the DriverFeatures register.
>
> -* 0x030 | W | QueueSel
> +\item[QueueSel (0x030) - W]
> Virtual queue index (first queue is 0).
> Writing to this register selects the virtual queue that the
> following operations on the QueueNumMax, QueueNum, QueueReady,
> QueueDescLow, QueueDescHigh, QueueAvailLow, QueueAvailHigh,
> QueueUsedLow and QueueUsedHigh registers apply to.
>
> -* 0x034 | R | QueueNumMax
> +\item[QueueNumMax (0x034) - R]
> Maximum virtual queue size.
> Reading from the register returns the maximum size of the queue
> the device is ready to process or zero (0x0) if the queue is not
> @@ -1442,7 +1451,7 @@ configuration space. The following list presents their layout:
> QueueSel and is allowed only when QueueReady is set to zero
> (0x0), so when the queue is not in use.
>
> -* 0x038 | W | QueueNum
> +\item[QueueNum (0x038) - W]
> Virtual queue size.
> Queue size is the number of elements in the queue, therefore size
> of the Descriptor Table and both Available and Used rings.
> @@ -1451,7 +1460,7 @@ configuration space. The following list presents their layout:
> writing to QueueSel and is allowed only when QueueReady is set
> to zero (0x0), so when the queue is not in use.
>
> -* 0x03c | RW | QueueReady
> +\item[QueueReady (0x03c) - RW]
> Virtual queue ready bit.
> Writing one (0x1) to this register notifies the device that the
> virtual queue is ready to be used. Reading from this register
> @@ -1461,12 +1470,12 @@ configuration space. The following list presents their layout:
> zero (0x0) to this register and read the value back to
> ensure synchronisation.
>
> -* 0x050 | W | QueueNotify
> +\item[QueueNotify (0x050) - W]
> Queue notifier.
> Writing a queue index to this register notifies the device that
> there are new buffers to process in the queue.
>
> -* 0x60 | R | InterruptStatus
> +\item[InterruptStatus (0x60) - R]
> Interrupt status.
> Reading from this register returns a bit mask of interrupts
> asserted by the device. An interrupt is asserted if the
> @@ -1480,13 +1489,13 @@ configuration space. The following list presents their layout:
> This interrupt is asserted when configuration of the device has
> changed.
>
> -* 0x064 | W | InterruptACK
> +\item[InterruptACK (0x064) - W]
> Interrupt acknowledge.
> Writing to this register notifies the device that the Driver
> finished handling interrupts. Set bits in the value clear
> the corresponding bits of the InterruptStatus register.
>
> -* 0x070 | RW | Status
> +\item[Status (0x070) - RW]
> Device status.
> Reading from this register returns the current device status
> flags.
> @@ -1497,8 +1506,8 @@ configuration space. The following list presents their layout:
> QueueReady register for all queues in the device.
> See also p. \ref{sec:Virtio Transport Options / Virtio Over MMIO / MMIO-specific Initialization And Device Operation / Device Initialization}~\nameref{sec:Virtio Transport Options / Virtio Over MMIO / MMIO-specific Initialization And Device Operation / Device Initialization}.
>
> -* 0x080 | W | QueueDescLow
> - 0x084 | W | QueueDescHigh
> +\item[QueueDescLow (0x080) - W]
> +\item[QueueDescHigh (0x084) - W]
> Virtual queue's Descriptor Table 64 bit long physical address.
> Writing to these two registers (lower 32 bits of the address
> to QueueDescLow, higher 32 bits to QueueDescHigh) notifies
> @@ -1507,8 +1516,8 @@ configuration space. The following list presents their layout:
> only when QueueReady is set to zero (0x0), so when the queue
> is not in use.
>
> -* 0x090 | W | QueueAvailLow
> - 0x094 | W | QueueAvailHigh
> +\item[QueueAvailLow (0x090) - W]
> +\item[QueueAvailHigh (0x094) - W]
> Virtual queue's Available Ring 64 bit long physical address.
> Writing to these two registers (lower 32 bits of the address
> to QueueAvailLow, higher 32 bits to QueueAvailHigh) notifies
> @@ -1517,8 +1526,8 @@ configuration space. The following list presents their layout:
> only when QueueReady is set to zero (0x0), so when the queue
> is not in use.
>
> -* 0x0a0 | W | QueueUsedLow
> - 0x0a4 | W | QueueUsedHigh
> +\item[QueueUsedLow (0x0a0) - W]
> +\item[QueueUsedHigh (0x0a4) - W]
> Virtual queue's Used Ring 64 bit long physical address.
> Writing to these two registers (lower 32 bits of the address
> to QueueUsedLow, higher 32 bits to QueueUsedHigh) notifies
> @@ -1527,17 +1536,18 @@ configuration space. The following list presents their layout:
> only when QueueReady is set to zero (0x0), so when the queue
> is not in use.
>
> -* 0x0fc | R | ConfigGeneration
> +\item[ConfigGeneration (0x0fc) - R]
> Configuration atomicity value.
> Changes every time the configuration noticeably changes. This
> means the device may only change the value after a configuration
> read operation, but it must change if there is any risk of a
> device seeing an inconsistent configuration state.
>
> -* 0x100+ | RW | Config
> +\item[Config (0x100) - RW]
> Device-specific configuration space starts at an offset 0x100
> and is accessed with byte alignment. Its meaning and size
> depends on the device and the driver.
> +\end{description}
>
> All register values are organized as Little Endian.
>
> @@ -1558,35 +1568,37 @@ and if its value is zero (0x0) must abort initialization and
> must not access any other register.
>
> Further initialization must follow the procedure described in
> -p. \ref{sec:General Initialization And Device Operation / Device Initialization}~\nameref{sec:General Initialization And Device Operation / Device Initialization}.
> +\ref{sec:General Initialization And Device Operation / Device Initialization}~\nameref{sec:General Initialization And Device Operation / Device Initialization}.
>
> \subsubsection{Virtqueue Configuration}\label{sec:Virtio Transport Options / Virtio Over MMIO / MMIO-specific Initialization And Device Operation / Virtqueue Configuration}
>
> -1. Select the queue writing its index (first queue is 0) to the
> +\begin{enumerate}
> +\item Select the queue writing its index (first queue is 0) to the
> QueueSel register.
>
> -2. Check if the queue is not already in use: read the QueueReady
> +\item Check if the queue is not already in use: read the QueueReady
> register, returned value should be zero (0x0).
>
> -3. Read maximum queue size (number of elements) from the
> +\item Read maximum queue size (number of elements) from the
> QueueNumMax register. If the returned value is zero (0x0) the
> queue is not available.
>
> -4. Allocate and zero the queue pages, making sure the memory
> +\item Allocate and zero the queue pages, making sure the memory
> is physically contiguous. It is recommended to align the
> Used Ring to an optimal boundary (usually page size).
> Size of the allocated queue may be smaller than or equal to
> the maximum size returned by the device.
>
> -5. Notify the device about the queue size by writing the size to
> +\item Notify the device about the queue size by writing the size to
> the QueueNum register.
>
> -6. Write physical addresses of the queue's Descriptor Table,
> +\item Write physical addresses of the queue's Descriptor Table,
> Available Ring and Used Ring to (respectively) the QueueDescLow/
> QueueDescHigh, QueueAvailLow/QueueAvailHigh and QueueUsedLow/
> QueueUsedHigh register pairs.
>
> -7. Write 0x1 to the QueueReady register.
> +\item Write 0x1 to the QueueReady register.
> +\end{enumerate}
>
> \subsubsection{Notifying The Device}\label{sec:Virtio Transport Options / Virtio Over MMIO / MMIO-specific Initialization And Device Operation / Notifying The Device}
>
> @@ -1718,30 +1730,31 @@ p. \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Legacy Interfaces
> with the alignment defined in the QueueAlign register.
>
> The virtual queue is configured as follows:
> -
> -1. Select the queue writing its index (first queue is 0) to the
> +\begin{enumerate}
> +\item Select the queue writing its index (first queue is 0) to the
> QueueSel register.
>
> -2. Check if the queue is not already in use: read the QueuePFN
> +\item Check if the queue is not already in use: read the QueuePFN
> register, returned value should be zero (0x0).
>
> -3. Read maximum queue size (number of elements) from the
> +\item Read maximum queue size (number of elements) from the
> QueueNumMax register. If the returned value is zero (0x0) the
> queue is not available.
>
> -4. Allocate and zero the queue pages in contiguous virtual
> +\item Allocate and zero the queue pages in contiguous virtual
> memory, aligning the Used Ring to an optimal boundary (usually
> page size). Size of the allocated queue may be smaller than or
> equal to the maximum size returned by the device.
>
> -5. Notify the device about the queue size by writing the size to
> +\item Notify the device about the queue size by writing the size to
> the QueueNum register.
>
> -6. Notify the device about the used alignment by writing its value
> +\item Notify the device about the used alignment by writing its value
> in bytes to the QueueAlign register.
>
> -7. Write the physical number of the first page of the queue to
> +\item Write the physical number of the first page of the queue to
> the QueuePFN register.
> +\end{enumerate}
>
> Notification mechanisms did not change.
>
> @@ -1778,23 +1791,23 @@ importantly SENSE ID.
> For a virtio-ccw proxy device, SENSE ID will return the following
> information:
>
> -\begin{verbatim}
> -+-------+--------------------------------------------+
> -| Bytes | Contents |
> -|-------|--------------------------------------------|
> -| 0 | reserved | 0xff |
> -|-------|-----------------------|--------------------|
> -| 1-2 | control unit type | 0x3832 |
> -|-------|-----------------------|--------------------|
> -| 3 | control unit model | <virtio device id> |
> -|-------|-----------------------|--------------------|
> -| 4-5 | device type | zeroes (unset) |
> -|-------|-----------------------|--------------------|
> -| 6 | device model | zeroes (unset) |
> -|-------|-----------------------|--------------------|
> -| 7-255 | extended SenseId data | zeroes (unset) |
> -+-------+--------------------------------------------+
> -\end{verbatim}
> +\begin{tabular}{ |l|l|l| }
> +\hline
> +Bytes & Description & Contents \\
> +\hline \hline
> +0 & reserved & 0xff \\
> +\hline
> +1-2 & control unit type & 0x3832 \\
> +\hline
> +3 & control unit model & <virtio device id> \\
> +\hline
> +4-5 & device type & zeroes (unset) \\
> +\hline
> +6 & device model & zeroes (unset) \\
> +\hline
> +7-255 & extended SenseId data & zeroes (unset) \\
> +\hline
> +\end{tabular}
>
> A driver for virtio-ccw devices MUST check for a control unit
> type of 0x3832 and MUST ignore the device type and model.
> @@ -1821,19 +1834,21 @@ virtio:
> The virtio-ccw device acts like a normal channel device, as specified
> in \hyperref[intro:S390 PoP]{[S390 PoP]} and \hyperref[intro:S390 Common I/O]{[S390 Common I/O]}. In particular:
>
> -- A device must post a unit check with command reject for any command
> +\begin{itemize}
> +\item A device must post a unit check with command reject for any command
> it does not support.
>
> -- If a driver did not suppress length checks for a channel command,
> +\item If a driver did not suppress length checks for a channel command,
> the device must present a subchannel status as detailed in the
> architecture when the actual length did not match the expected length.
>
> -- If a driver did suppress length checks for a channel command, the
> +\item If a driver did suppress length checks for a channel command, the
> device must present a check condition if the transmitted data does
> not contain enough data to process the command. If the driver submitted
> a buffer that was too long, the device should accept the command.
> The driver should attempt to provide the correct length even if it
> suppresses length checks.
> +\end{itemize}
>
> \subsection{Device Initialization}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Initialization}
>
> @@ -1858,18 +1873,17 @@ data portion and data revision-dependent additional desired options.
>
> The following values are supported:
>
> -\begin{verbatim}
> -+----------+--------+-----------+--------------------------------+
> -| revision | length | data | remarks |
> -|----------|--------|-----------|--------------------------------|
> -| 0 | 0 | <empty> | legacy interface; transitional |
> -| | | | devices only |
> -|----------|--------|-----------|--------------------------------|
> -| 1 | 0 | <empty> | Virtio 1.0 |
> -|----------|--------|-----------|--------------------------------|
> -| 2-n | | | reserved for later revisions |
> -+----------+--------+-----------+--------------------------------+
> -\end{verbatim}
> +\begin{tabular}{ |l|l|l|l| }
> +\hline
> +revision & length & data & remarks \\
> +\hline \hline
> +0 & 0 & <empty> & legacy interface; transitional devices only \\
> +\hline
> +1 & 0 & <empty> & Virtio 1.0 \\
> +\hline
> +2-n & & & reserved for later revisions \\
> +\hline
> +\end{tabular}
>
> Note that a change in the virtio standard does not neccessarily
> correspond to a change in the virtio-ccw revision.
> @@ -1970,11 +1984,11 @@ and align the alignment.
> The virtqueue is physically contiguous, with padded added to make the
> used ring meet the align value:
>
> -\begin{verbatim}
> -+-------------------+-----------------------------------+-----------+
> -| Descriptor Table | Available Ring (padding) | Used Ring |
> -+-------------------+-----------------------------------+-----------+
> -\end{verbatim}
> +\begin{tabular}{|l|l|l|}
> +\hline
> +Descriptor Table & Available Ring (\ldots padding\ldots) & Used Ring \\
> +\hline
> +\end{tabular}
>
> The calculation for total size is as follows:
>
> @@ -2080,10 +2094,12 @@ guest address of the indicators in a 64 bit value.
>
> Indicators for notification via adapter I/O interrupts consist of
> two stages:
> -- a summary indicator byte covering the virtqueues for one or more
> +\begin{itemize}
> +\item a summary indicator byte covering the virtqueues for one or more
> virtio-ccw proxy devices
> -- a set of contigous indicator bits for the virtqueues for a
> +\item a set of contigous indicator bits for the virtqueues for a
> virtio-ccw proxy device
> +\end{itemize}
>
> To communicate the location of the summary and queue indicator bits,
> the driver uses the CCW_CMD_SET_IND_ADAPTER command with the following
> @@ -2172,29 +2188,30 @@ characteristics of channel I/O interact badly with the host block
> I/O backend). Instead, it uses a diagnose 0x500 call with subcode
> 3 specifying the queue, as follows:
>
> -\begin{verbatim}
> -+------+-------------------+--------------+
> -| GPR | Input Value | Output Value |
> -+------+-------------------+--------------+
> -+------+-------------------+--------------+
> -| 1 | 0x3 | |
> -+------+-------------------+--------------+
> -| 2 | Subchannel ID | Host Cookie |
> -+------+-------------------+--------------+
> -| 3 | Virtqueue number | |
> -+------+-------------------+--------------+
> -| 4 | Host Cookie | |
> -+------+-------------------+--------------+
> -\end{verbatim}
> +\begin{tabular}{ |l|l|l| }
> +\hline
> +GPR & Input Value & Output Value \\
> +\hline \hline
> + 1 & 0x3 & \\
> +\hline
> + 2 & Subchannel ID & Host Cookie \\
> +\hline
> + 3 & Virtqueue number & \\
> +\hline
> + 4 & Host Cookie & \\
> +\hline
> +\end{tabular}
>
> Host cookie is an optional per-virtqueue 64 bit value that can be
> used by the hypervisor to speed up the notification execution.
> For each notification, the output value is returned in GPR2 and
> should be passed in GPR4 for the next notification:
>
> +\begin{lstlisting}
> info->cookie = do_notify(schid,
> virtqueue_get_queue_index(vq),
> info->cookie);
> +\end{lstlisting}
>
> \subsubsection{Early printk for Virtio Consoles}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Operation / Early printk for Virtio Consoles}
>
> @@ -2218,38 +2235,37 @@ defined in this standard.
>
> Discovering what devices are available and their type is bus-dependent.
>
> -\begin{verbatim}
> -+------------+--------------------+
> -| Device ID | Virtio Device |
> -+------------+--------------------+
> -+------------+--------------------+
> -| 0 | reserved (invalid) |
> -+------------+--------------------+
> -| 1 | network card |
> -+------------+--------------------+
> -| 2 | block device |
> -+------------+--------------------+
> -| 3 | console |
> -+------------+--------------------+
> -| 4 | entropy source |
> -+------------+--------------------+
> -| 5 | memory ballooning |
> -+------------+--------------------+
> -| 6 | ioMemory |
> -+------------+--------------------+
> -| 7 | rpmsg |
> -+------------+--------------------+
> -| 8 | SCSI host |
> -+------------+--------------------+
> -| 9 | 9P transport |
> -+------------+--------------------+
> -| 10 | mac80211 wlan |
> -+------------+--------------------+
> -| 11 | rproc serial |
> -+------------+--------------------+
> -| 12 | virtio CAIF |
> -+------------+--------------------+
> -\end{verbatim}
> +\begin{tabular} { |l|c| }
> +\hline
> +Device ID & Virtio Device \\
> +\hline \hline
> +0 & reserved (invalid) \\
> +\hline
> +1 & network card \\
> +\hline
> +2 & block device \\
> +\hline
> +3 & console \\
> +\hline
> +4 & entropy source \\
> +\hline
> +5 & memory ballooning \\
> +\hline
> +6 & ioMemory \\
> +\hline
> +7 & rpmsg \\
> +\hline
> +8 & SCSI host \\
> +\hline
> +9 & 9P transport \\
> +\hline
> +10 & mac80211 wlan \\
> +\hline
> +11 & rproc serial \\
> +\hline
> +12 & virtio CAIF \\
> +\hline
> +\end{tabular}
>
> \section{Network Device}\label{sec:Device Types / Network Device}
>
> @@ -2268,53 +2284,61 @@ features.
>
> \subsection{Virtqueues}\label{sec:Device Types / Network Device / Virtqueues}
>
> - 0:receiveq. 1:transmitq. 2:controlq
> +\begin{description}
> +\item[0] receiveq
> +\item[1] transmitq
> +\item[2] controlq
> +\end{description}
>
> Virtqueue 2 only exists if VIRTIO_NET_F_CTRL_VQ set.
>
> \subsection{Feature bits}\label{sec:Device Types / Network Device / Feature bits}
>
> - VIRTIO_NET_F_CSUM (0) Device handles packets with partial checksum
> +\begin{description}
> +\item[VIRTIO_NET_F_CSUM (0)] Device handles packets with partial checksum
>
> - VIRTIO_NET_F_GUEST_CSUM (1) Driver handles packets with partial checksum
> +\item[VIRTIO_NET_F_GUEST_CSUM (1)] Driver handles packets with partial checksum
>
> - VIRTIO_NET_F_CTRL_GUEST_OFFLOADS (2) Control channel offloads
> +\item[VIRTIO_NET_F_CTRL_GUEST_OFFLOADS (2)] Control channel offloads
> reconfiguration support.
>
> - VIRTIO_NET_F_MAC (5) Device has given MAC address.
> +\item[VIRTIO_NET_F_MAC (5)] Device has given MAC address.
>
> - VIRTIO_NET_F_GUEST_TSO4 (7) Driver can receive TSOv4.
> +\item[VIRTIO_NET_F_GUEST_TSO4 (7)] Driver can receive TSOv4.
>
> - VIRTIO_NET_F_GUEST_TSO6 (8) Driver can receive TSOv6.
> +\item[VIRTIO_NET_F_GUEST_TSO6 (8)] Driver can receive TSOv6.
>
> - VIRTIO_NET_F_GUEST_ECN (9) Driver can receive TSO with ECN.
> +\item[VIRTIO_NET_F_GUEST_ECN (9)] Driver can receive TSO with ECN.
>
> - VIRTIO_NET_F_GUEST_UFO (10) Driver can receive UFO.
> +\item[VIRTIO_NET_F_GUEST_UFO (10)] Driver can receive UFO.
>
> - VIRTIO_NET_F_HOST_TSO4 (11) Device can receive TSOv4.
> +\item[VIRTIO_NET_F_HOST_TSO4 (11)] Device can receive TSOv4.
>
> - VIRTIO_NET_F_HOST_TSO6 (12) Device can receive TSOv6.
> +\item[VIRTIO_NET_F_HOST_TSO6 (12)] Device can receive TSOv6.
>
> - VIRTIO_NET_F_HOST_ECN (13) Device can receive TSO with ECN.
> +\item[VIRTIO_NET_F_HOST_ECN (13)] Device can receive TSO with ECN.
>
> - VIRTIO_NET_F_HOST_UFO (14) Device can receive UFO.
> +\item[VIRTIO_NET_F_HOST_UFO (14)] Device can receive UFO.
>
> - VIRTIO_NET_F_MRG_RXBUF (15) Driver can merge receive buffers.
> +\item[VIRTIO_NET_F_MRG_RXBUF (15)] Driver can merge receive buffers.
>
> - VIRTIO_NET_F_STATUS (16) Configuration status field is
> +\item[VIRTIO_NET_F_STATUS (16)] Configuration status field is
> available.
>
> - VIRTIO_NET_F_CTRL_VQ (17) Control channel is available.
> +\item[VIRTIO_NET_F_CTRL_VQ (17)] Control channel is available.
>
> - VIRTIO_NET_F_CTRL_RX (18) Control channel RX mode support.
> +\item[VIRTIO_NET_F_CTRL_RX (18)] Control channel RX mode support.
>
> - VIRTIO_NET_F_CTRL_VLAN (19) Control channel VLAN filtering.
> +\item[VIRTIO_NET_F_CTRL_VLAN (19)] Control channel VLAN filtering.
>
> - VIRTIO_NET_F_GUEST_ANNOUNCE(21) Driver can send gratuitous
> +\item[VIRTIO_NET_F_GUEST_ANNOUNCE(21)] Driver can send gratuitous
> packets.
> +\end{description}
>
> \subsubsection{Legacy Interface: Feature bits}\label{sec:Device Types / Network Device / Feature bits / Legacy Interface: Feature bits}
> -VIRTIO_NET_F_GSO (6) Device handles packets with any GSO type.
> +\begin{description}
> +\item[VIRTIO_NET_F_GSO (6)] Device handles packets with any GSO type.
> +\end{description}
>
> This was supposed to indicate segmentation offload support, but
> upon further investigation it became clear that multiple bits
> @@ -2345,32 +2369,32 @@ native endian of the guest rather than (necessarily) little-endian.
>
> \subsection{Device Initialization}\label{sec:Device Types / Network Device / Device Initialization}
>
> -1. The initialization routine should identify the receive and
> +\begin{enumerate}
> +\item The initialization routine should identify the receive and
> transmission virtqueues.
>
> -2. If the VIRTIO_NET_F_MAC feature bit is set, the configuration
> +\item If the VIRTIO_NET_F_MAC feature bit is set, the configuration
> space “mac” entry indicates the “physical” address of the the
> network card, otherwise a private MAC address should be
> assigned. All drivers are expected to negotiate this feature if
> it is set.
>
> -3. If the VIRTIO_NET_F_CTRL_VQ feature bit is negotiated,
> +\item If the VIRTIO_NET_F_CTRL_VQ feature bit is negotiated,
> identify the control virtqueue.
>
> -4. If the VIRTIO_NET_F_STATUS feature bit is negotiated, the link
> +\item If the VIRTIO_NET_F_STATUS feature bit is negotiated, the link
> status can be read from the bottom bit of the “status” config
> field. Otherwise, the link should be assumed active.
>
> -5. The receive virtqueue should be filled with receive buffers.
> +\item The receive virtqueue should be filled with receive buffers.
> This is described in detail below in “Setting Up Receive
> Buffers”.
>
> -6. A driver can indicate that it will generate checksumless
> - packets by negotating the VIRTIO_NET_F_CSUM feature. This “
> - checksum offload” is a common feature on modern network cards.
> +\item A driver can indicate that it will generate checksumless
> + packets by negotating the VIRTIO_NET_F_CSUM feature. This
> + “checksum offload” is a common feature on modern network cards.
>
> -7. If that feature is negotiated
> -\footnote{ie. VIRTIO_NET_F_HOST_TSO* and VIRTIO_NET_F_HOST_UFO are
> +\item If that feature is negotiated\footnote{ie. VIRTIO_NET_F_HOST_TSO* and VIRTIO_NET_F_HOST_UFO are
> dependent on VIRTIO_NET_F_CSUM; a dvice which offers the offload
> features must offer the checksum feature, and a driver which
> accepts the offload features must accept the checksum feature.
> @@ -2382,13 +2406,11 @@ depending on VIRTIO_NET_F_GUEST_CSUM.
> (UDP fragmentation) features. It should not send TCP packets
> requiring segmentation offload which have the Explicit Congestion
> Notification bit set, unless the VIRTIO_NET_F_HOST_ECN feature is
> - negotiated.
> -\footnote{This is a common restriction in real, older network cards.
> + negotiated.\footnote{This is a common restriction in real, older network cards.
> }
>
> -8. The converse features are also available: a driver can save
> - the virtual device some work by negotiating these features.
> -\footnote{For example, a network packet transported between two guests on
> +\item The converse features are also available: a driver can save
> + the virtual device some work by negotiating these features.\footnote{For example, a network packet transported between two guests on
> the same system may not require checksumming at all, nor segmentation,
> if both guests are amenable.
> }
> @@ -2398,6 +2420,7 @@ if both guests are amenable.
> VIRTIO_NET_F_GUEST_UFO and VIRTIO_NET_F_GUEST_ECN are the input
> equivalents of the features described above.
> See \ref{sec:Device Types / Network Device / Device Operation / Setting Up Receive Buffers}~\nameref{sec:Device Types / Network Device / Device Operation / Setting Up Receive Buffers} and \ref{sec:Device Types / Network Device / Device Operation / Setting Up Receive Buffers}~\nameref{sec:Device Types / Network Device / Device Operation / Setting Up Receive Buffers} below.
> +\end{enumerate}
>
> \subsection{Device Operation}\label{sec:Device Types / Network Device / Device Operation}
>
> @@ -2436,19 +2459,22 @@ native endian of the guest rather than (necessarily) little-endian.
> Transmitting a single packet is simple, but varies depending on
> the different features the driver negotiated.
>
> -1. If the driver negotiated VIRTIO_NET_F_CSUM, and the packet has
> +\begin{enumerate}
> +\item If the driver negotiated VIRTIO_NET_F_CSUM, and the packet has
> not been fully checksummed, then the virtio_net_hdr's fields
> are set as follows. Otherwise, the packet must be fully
> checksummed, and flags is zero.
> + \begin{itemize}
> + \item flags has the VIRTIO_NET_HDR_F_NEEDS_CSUM set,
>
> - • flags has the VIRTIO_NET_HDR_F_NEEDS_CSUM set,
> -
> - • csum_start is set to the offset within the packet to begin checksumming,
> + \item csum_start is set to the offset within the packet to begin checksumming,
> and
>
> - • csum_offset indicates how many bytes after the csum_start the
> + \item csum_offset indicates how many bytes after the csum_start the
> new (16 bit ones' complement) checksum should be placed.
> -\footnote{For example, consider a partially checksummed TCP (IPv4) packet.
> + \end{itemize}
> +
> +For example, consider a partially checksummed TCP (IPv4) packet.
> It will have a 14 byte ethernet header and 20 byte IP header
> followed by the TCP header (with the TCP checksum field 16 bytes
> into that header). csum_start will be 14+20 = 34 (the TCP
> @@ -2457,9 +2483,8 @@ value in the TCP checksum field should be initialized to the sum
> of the TCP pseudo header, so that replacing it by the ones'
> complement checksum of the TCP header and body will give the
> correct result.
> -}
>
> -2. If the driver negotiated
> +\item If the driver negotiated
> VIRTIO_NET_F_HOST_TSO4, TSO6 or UFO, and the packet requires
> TCP segmentation or UDP fragmentation, then the “gso_type”
> field is set to VIRTIO_NET_HDR_GSO_TCPV4, TCPV6 or UDP.
> @@ -2468,32 +2493,32 @@ correct result.
> metadata indicates how to replicate the packet header to cut it
> into smaller packets. The other gso fields are set:
>
> - • hdr_len is a hint to the device as to how much of the header
> + \begin{itemize}
> + \item hdr_len is a hint to the device as to how much of the header
> needs to be kept to copy into each packet, usually set to the
> - length of the headers, including the transport header.
> -\footnote{Due to various bugs in implementations, this field is not useful
> + length of the headers, including the transport header.\footnote{Due to various bugs in implementations, this field is not useful
> as a guarantee of the transport header size.
> }
>
> - • gso_size is the maximum size of each packet beyond that
> + \item gso_size is the maximum size of each packet beyond that
> header (ie. MSS).
>
> - • If the driver negotiated the VIRTIO_NET_F_HOST_ECN feature,
> + \item If the driver negotiated the VIRTIO_NET_F_HOST_ECN feature,
> the VIRTIO_NET_HDR_GSO_ECN bit may be set in “gso_type” as
> - well, indicating that the TCP packet has the ECN bit set.
> -\footnote{This case is not handled by some older hardware, so is called out
> + well, indicating that the TCP packet has the ECN bit set.\footnote{This case is not handled by some older hardware, so is called out
> specifically in the protocol.
> }
> + \end{itemize}
>
> -3. If the driver negotiated the VIRTIO_NET_F_MRG_RXBUF feature,
> +\item If the driver negotiated the VIRTIO_NET_F_MRG_RXBUF feature,
> the num_buffers field is set to zero.
>
> -4. The header and packet are added as one output buffer to the
> +\item The header and packet are added as one output buffer to the
> transmitq, and the device is notified of the new entry
> - (see \ref{sec:Device Types / Network Device / Device Initialization}~\nameref{sec:Device Types / Network Device / Device Initialization}).
> -\footnote{Note that the header will be two bytes longer for the
> + (see \ref{sec:Device Types / Network Device / Device Initialization}~\nameref{sec:Device Types / Network Device / Device Initialization}).\footnote{Note that the header will be two bytes longer for the
> VIRTIO_NET_F_MRG_RXBUF case.
> }
> +\end{enumerate}
>
> \paragraph{Packet Transmission Interrupt}\label{sec:Device Types / Network Device / Device Operation / Packet Transmission / Packet Transmission Interrupt}
>
> @@ -2518,8 +2543,7 @@ VIRTIO_NET_F_GUEST_UFO features are used, the Driver will need to
> accept packets of up to 65550 bytes long (the maximum size of a
> TCP or UDP packet, plus the 14 byte ethernet header), otherwise
> 1514. bytes. So unless VIRTIO_NET_F_MRG_RXBUF is negotiated, every
> -buffer in the receive queue needs to be at least this length
> -\footnote{Obviously each one can be split across multiple descriptor
> +buffer in the receive queue needs to be at least this length.\footnote{Obviously each one can be split across multiple descriptor
> elements.
> }
>
> @@ -2530,12 +2554,13 @@ least the size of the struct virtio_net_hdr.
>
> When a packet is copied into a buffer in the receiveq, the
> optimal path is to disable further interrupts for the receiveq
> -(see 2.2.2.2. Receiving Used Buffers From The Device) and process
> +(see \ref{sec:General Initialization And Device Operation / Device Operation / Receiving Used Buffers From The Device}~\nameref{sec:General Initialization And Device Operation / Device Operation / Receiving Used Buffers From The Device}) and process
> packets until no more are found, then re-enable them.
>
> Processing packet involves:
>
> -1. If the driver negotiated the VIRTIO_NET_F_MRG_RXBUF feature,
> +\begin{enumerate}
> +\item If the driver negotiated the VIRTIO_NET_F_MRG_RXBUF feature,
> then the “num_buffers” field indicates how many descriptors
> this packet is spread over (including this one). This allows
> receipt of large packets without having to allocate large
> @@ -2544,21 +2569,22 @@ Processing packet involves:
> single packet. The other buffers will not begin with a struct
> virtio_net_hdr.
>
> -2. If the VIRTIO_NET_F_MRG_RXBUF feature was not negotiated, or
> +\item If the VIRTIO_NET_F_MRG_RXBUF feature was not negotiated, or
> the “num_buffers” field is one, then the entire packet will be
> contained within this buffer, immediately following the struct
> virtio_net_hdr.
>
> -3. If the VIRTIO_NET_F_GUEST_CSUM feature was negotiated, the
> +\item If the VIRTIO_NET_F_GUEST_CSUM feature was negotiated, the
> VIRTIO_NET_HDR_F_NEEDS_CSUM bit in the “flags” field may be
> set: if so, the checksum on the packet is incomplete and the “
> csum_start” and “csum_offset” fields indicate how to calculate
> it (see Packet Transmission point 1).
>
> -4. If the VIRTIO_NET_F_GUEST_TSO4, TSO6 or UFO options were
> +\item If the VIRTIO_NET_F_GUEST_TSO4, TSO6 or UFO options were
> negotiated, then the “gso_type” may be something other than
> VIRTIO_NET_HDR_GSO_NONE, and the “gso_size” field indicates the
> desired MSS (see Packet Transmission point 2).
> +\end{enumerate}
>
> \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue}
>
> @@ -2596,7 +2622,7 @@ and filtering of MAC addresses.
> Note that in general, these commands are best-effort: unwanted
> packets may still arrive.
>
> -Setting Promiscuous Mode
> +\paragraph{Setting Promiscuous Mode}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Setting Promiscuous Mode}
>
> \begin{lstlisting}
> #define VIRTIO_NET_CTRL_RX 0
> @@ -2623,8 +2649,7 @@ off. The command-specific-data is one byte containing 0 (off) or
> \end{lstlisting}
>
> The device can filter incoming packets by any number of destination
> -MAC addresses.
> -\footnote{Since there are no guarentees, it can use a hash filter or
> +MAC addresses.\footnote{Since there are no guarentees, it can use a hash filter or
> silently switch to allmulti or promiscuous mode if it is given too
> many addresses.
> } This table is set using the class
> @@ -2679,12 +2704,14 @@ this command.
>
> Processing this notification involves:
>
> -1. Sending the gratuitous packets or marking there are pending
> +\begin{enumerate}
> +\item Sending the gratuitous packets or marking there are pending
> gratuitous packets to be sent and letting deferred routine to
> send them.
>
> -2. Sending VIRTIO_NET_CTRL_ANNOUNCE_ACK command through control
> +\item Sending VIRTIO_NET_CTRL_ANNOUNCE_ACK command through control
> vq.
> +\end{enumerate}
>
> \paragraph{Offloads State Configuration}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Offloads State Configuration}
>
> @@ -2736,35 +2763,42 @@ device except where noted.
> 2
>
> \subsection{Virtqueues}\label{sec:Device Types / Block Device / Virtqueues}
> - 0:requestq
> +\begin{description}
> +\item[0] requestq
> +\end{description}
>
> \subsection{Feature bits}\label{sec:Device Types / Block Device / Feature bits}
>
> - VIRTIO_BLK_F_SIZE_MAX (1) Maximum size of any single segment is
> +\begin{description}
> +\item[VIRTIO_BLK_F_SIZE_MAX (1)] Maximum size of any single segment is
> in “size_max”.
>
> - VIRTIO_BLK_F_SEG_MAX (2) Maximum number of segments in a
> +\item[VIRTIO_BLK_F_SEG_MAX (2)] Maximum number of segments in a
> request is in “seg_max”.
>
> - VIRTIO_BLK_F_GEOMETRY (4) Disk-style geometry specified in “
> +\item[VIRTIO_BLK_F_GEOMETRY (4)] Disk-style geometry specified in “
> geometry”.
>
> - VIRTIO_BLK_F_RO (5) Device is read-only.
> +\item[VIRTIO_BLK_F_RO (5)] Device is read-only.
>
> - VIRTIO_BLK_F_BLK_SIZE (6) Block size of disk is in “blk_size”.
> +\item[VIRTIO_BLK_F_BLK_SIZE (6)] Block size of disk is in “blk_size”.
>
> - VIRTIO_BLK_F_TOPOLOGY (10) Device exports information on optimal I/O
> +\item[VIRTIO_BLK_F_TOPOLOGY (10)] Device exports information on optimal I/O
> alignment.
> +\end{description}
>
> \subsubsection{Legacy Interface: Feature bits}\label{sec:Device Types / Block Device / Feature bits / Legacy Interface: Feature bits}
> - VIRTIO_BLK_F_BARRIER (0) Device supports request barriers.
>
> - VIRTIO_BLK_F_SCSI (7) Device supports scsi packet commands.
> +\begin{description}
> +\item[VIRTIO_BLK_F_BARRIER (0)] Device supports request barriers.
> +
> +\item[VIRTIO_BLK_F_SCSI (7)] Device supports scsi packet commands.
>
> - VIRTIO_BLK_F_FLUSH (9) Cache flush command support.
> +\item[VIRTIO_BLK_F_FLUSH (9)] Cache flush command support.
>
> - VIRTIO_BLK_F_CONFIG_WCE (11) Device can toggle its cache between writeback
> +\item[VIRTIO_BLK_F_CONFIG_WCE (11)] Device can toggle its cache between writeback
> and writethrough modes.
> +\end{description}
>
> VIRTIO_BLK_F_FLUSH was also called VIRTIO_BLK_F_WCE: Legacy drivers
> should only negotiate this feature if they are capable of sending
> @@ -2809,23 +2843,25 @@ native endian of the guest rather than (necessarily) little-endian.
>
> \subsection{Device Initialization}\label{sec:Device Types / Block Device / Device Initialization}
>
> -1. The device size should be read from the “capacity”
> +\begin{enumerate}
> +\item The device size should be read from the “capacity”
> configuration field. No requests should be submitted which goes
> beyond this limit.
>
> -2. If the VIRTIO_BLK_F_BLK_SIZE feature is negotiated, the
> +\item If the VIRTIO_BLK_F_BLK_SIZE feature is negotiated, the
> blk_size field can be read to determine the optimal sector size
> for the driver to use. This does not affect the units used in
> the protocol (always 512 bytes), but awareness of the correct
> value can affect performance.
>
> -3. If the VIRTIO_BLK_F_RO feature is set by the device, any write
> +\item If the VIRTIO_BLK_F_RO feature is set by the device, any write
> requests will fail.
>
> -4. If the VIRTIO_BLK_F_TOPOLOGY feature is negotiated, the fields in the
> +\item If the VIRTIO_BLK_F_TOPOLOGY feature is negotiated, the fields in the
> topology struct can be read to determine the physical block size and optimal
> I/O lengths for the driver to use. This also does not affect the units
> in the protocol, only performance.
> +\end{enumerate}
>
> \subsubsection{Legacy Interface: Device Initialization}\label{sec:Device Types / Block Device / Device Initialization / Legacy Interface: Device Initialization}
>
> @@ -2858,8 +2894,7 @@ the device (not necessarily in order). Each request is of form:
>
> The type of the request is either a read (VIRTIO_BLK_T_IN), a write
> (VIRTIO_BLK_T_OUT), or a flush (VIRTIO_BLK_T_FLUSH or
> -VIRTIO_BLK_T_FLUSH_OUT
> -\footnote{The FLUSH and FLUSH_OUT types are equivalent, the device does not
> +VIRTIO_BLK_T_FLUSH_OUT\footnote{The FLUSH and FLUSH_OUT types are equivalent, the device does not
> distinguish between them
> }).
>
> @@ -2994,8 +3029,15 @@ data and outgoing characters are placed in the transmit queue.
>
> \subsection{Virtqueues}\label{sec:Device Types / Console Device / Virtqueues}
>
> - 0:receiveq(port0). 1:transmitq(port0), 2:control receiveq, 3:control transmitq, 4:receiveq(port1), 5:transmitq(port1),
> - ...
> +\begin{description}
> +\item[0] receiveq(port0)
> +\item[1] transmitq(port0)
> +\item[2] control receiveq
> +\item[3] control transmitq
> +\item[4] receiveq(port1)
> +\item[5] transmitq(port1)
> +\item[\ldots]
> +\end{description}
>
> Ports 2 onwards only exist if VIRTIO_CONSOLE_F_MULTIPORT is set.
>
> @@ -3030,10 +3072,11 @@ native endian of the guest rather than (necessarily) little-endian.
>
> \subsection{Device Initialization}\label{sec:Device Types / Console Device / Device Initialization}
>
> -1. If the VIRTIO_CONSOLE_F_SIZE feature is negotiated, the driver
> +\begin{enumerate}
> +\item If the VIRTIO_CONSOLE_F_SIZE feature is negotiated, the driver
> can read the console dimensions from the configuration fields.
>
> -2. If the VIRTIO_CONSOLE_F_MULTIPORT feature is negotiated, the
> +\item If the VIRTIO_CONSOLE_F_MULTIPORT feature is negotiated, the
> driver can spawn multiple ports, not all of which may be
> attached to a console. Some could be generic ports. In this
> case, the control virtqueues are enabled and according to the
> @@ -3046,14 +3089,15 @@ native endian of the guest rather than (necessarily) little-endian.
> for that port so the device can let us know of any additional
> configuration options set for that port.
>
> -3. The receiveq for each port is populated with one or more
> +\item The receiveq for each port is populated with one or more
> receive buffers.
> +\end{enumerate}
>
> \subsection{Device Operation}\label{sec:Device Types / Console Device / Device Operation}
>
> -1. For output, a buffer containing the characters is placed in
> - the port's transmitq.
> -\footnote{Because this is high importance and low bandwidth, the current
> +\begin{enumerate}
> +\item For output, a buffer containing the characters is placed in
> + the port's transmitq.\footnote{Because this is high importance and low bandwidth, the current
> Linux implementation polls for the buffer to be used, rather than
> waiting for an interrupt, simplifying the implementation
> significantly. However, for generic serial ports with the
> @@ -3062,25 +3106,25 @@ consumed buffers are freed upon the next write or poll call or
> when a port is closed or hot-unplugged.
> }
>
> -2. When a buffer is used in the receiveq (signalled by an
> +\item When a buffer is used in the receiveq (signalled by an
> interrupt), the contents is the input to the port associated
> with the virtqueue for which the notification was received.
>
> -3. If the driver negotiated the VIRTIO_CONSOLE_F_SIZE feature, a
> +\item If the driver negotiated the VIRTIO_CONSOLE_F_SIZE feature, a
> configuration change interrupt may occur. The updated size can
> be read from the configuration fields.
>
> -4. If the driver negotiated the VIRTIO_CONSOLE_F_MULTIPORT
> +\item If the driver negotiated the VIRTIO_CONSOLE_F_MULTIPORT
> feature, active ports are announced by the device using the
> VIRTIO_CONSOLE_PORT_ADD control message. The same message is
> used for port hot-plug as well.
>
> -5. If the device specified a port `name', a sysfs attribute is
> +\item If the device specified a port `name', a sysfs attribute is
> created with the name filled in, so that udev rules can be
> written that can create a symlink from the port's name to the
> char device for port discovery by applications in the driver.
>
> -6. Changes to ports' state are effected by control messages.
> +\item Changes to ports' state are effected by control messages.
> Appropriate action is taken on the port indicated in the
> control message. The layout of the structure of the control
> buffer and the events associated are:
> @@ -3102,6 +3146,7 @@ when a port is closed or hot-unplugged.
> #define VIRTIO_CONSOLE_PORT_OPEN 6
> #define VIRTIO_CONSOLE_PORT_NAME 7
> \end{lstlisting}
> +\end{enumerate}
>
> \subsubsection{Legacy Interface: Device Operation}\label{sec:Device Types / Console Device / Device Operation / Legacy Interface: Device Operation}
> For legacy devices, the fields in struct virtio_console_control are the
> @@ -3117,7 +3162,9 @@ guest use.
> 4
>
> \subsection{Virtqueues}\label{sec:Device Types / Entropy Device / Virtqueues}
> - 0:requestq.
> +\begin{description}
> +\item[0] requestq
> +\end{description}
>
> \subsection{Feature bits}\label{sec:Device Types / Entropy Device / Feature bits}
> None currently defined
> @@ -3127,7 +3174,9 @@ guest use.
>
> \subsection{Device Initialization}\label{sec:Device Types / Entropy Device / Device Initialization}
>
> -1. The virtqueue is initialized
> +\begin{enumerate}
> +\item The virtqueue is initialized
> +\end{enumerate}
>
> \subsection{Device Operation}\label{sec:Device Types / Entropy Device / Device Operation}
>
> @@ -3149,16 +3198,22 @@ guest memory statistics to the host.
> 5
>
> \subsection{Virtqueues}\label{sec:Device Types / Memory Balloon Device / Virtqueues}
> - 0:inflateq. 1:deflateq. 2:statsq.
> +\begin{description}
> +\item[0] inflateq
> +\item[1] deflateq
> +\item[2] statsq.
> +\end{description}
>
> Virtqueue 2 only exists if VIRTIO_BALLON_F_STATS_VQ set.
>
> \subsection{Feature bits}\label{sec:Device Types / Memory Balloon Device / Feature bits}
> - VIRTIO_BALLOON_F_MUST_TELL_HOST (0) Host must be told before
> +\begin{description}
> +\item[VIRTIO_BALLOON_F_MUST_TELL_HOST (0)] Host must be told before
> pages from the balloon are used.
>
> - VIRTIO_BALLOON_F_STATS_VQ (1) A virtqueue for reporting guest
> +\item[VIRTIO_BALLOON_F_STATS_VQ (1)] A virtqueue for reporting guest
> memory statistics is present.
> +\end{description}
>
> \subsection{Device configuration layout}\label{sec:Device Types / Memory Balloon Device / Device configuration layout}
> Both fields of this configuration
> @@ -3177,58 +3232,62 @@ that legacy device fields are guest endian.
>
> \subsection{Device Initialization}\label{sec:Device Types / Memory Balloon Device / Device Initialization}
>
> -1. The inflate and deflate virtqueues are identified.
> -
> -2. If the VIRTIO_BALLOON_F_STATS_VQ feature bit is negotiated:
> +\begin{enumerate}
> +\item The inflate and deflate virtqueues are identified.
>
> - (a) Identify the stats virtqueue.
> +\item If the VIRTIO_BALLOON_F_STATS_VQ feature bit is negotiated:
> + \begin{enumerate}
> + \item Identify the stats virtqueue.
>
> - (b) Add one empty buffer to the stats virtqueue and notify the
> + \item Add one empty buffer to the stats virtqueue and notify the
> device.
> + \end{enumerate}
> +\end{enumerate}
>
> Device operation begins immediately.
>
> \subsection{Device Operation}\label{sec:Device Types / Memory Balloon Device / Device Operation}
>
> -Memory Ballooning The device is driven by the receipt of a
> +The device is driven by the receipt of a
> configuration change interrupt.
>
> -1. The “num_pages” configuration field is examined. If this is
> +\begin{enumerate}
> +\item The “num_pages” configuration field is examined. If this is
> greater than the “actual” number of pages, memory must be given
> to the balloon. If it is less than the “actual” number of
> pages, memory may be taken back from the balloon for general
> use.
>
> -2. To supply memory to the balloon (aka. inflate):
> -
> - (a) The driver constructs an array of addresses of unused memory
> - pages. These addresses are divided by 4096
> -\footnote{This is historical, and independent of the guest page size
> +\item To supply memory to the balloon (aka. inflate):
> + \begin{enumerate}
> + \item The driver constructs an array of addresses of unused memory
> + pages. These addresses are divided by 4096\footnote{This is historical, and independent of the guest page size
> } and the descriptor
> describing the resulting 32-bit array is added to the inflateq.
> + \end{enumerate}
>
> -3. To remove memory from the balloon (aka. deflate):
> -
> - (a) The driver constructs an array of addresses of memory pages
> +\item To remove memory from the balloon (aka. deflate):
> + \begin{enumerate}
> + \item The driver constructs an array of addresses of memory pages
> it has previously given to the balloon, as described above.
> This descriptor is added to the deflateq.
>
> - (b) If the VIRTIO_BALLOON_F_MUST_TELL_HOST feature is negotiated, the
> + \item If the VIRTIO_BALLOON_F_MUST_TELL_HOST feature is negotiated, the
> guest may not use these requested pages until that descriptor
> in the deflateq has been used by the device.
>
> - (c) Otherwise, the guest may begin to re-use pages previously
> + \item Otherwise, the guest may begin to re-use pages previously
> given to the balloon before the device has acknowledged their
> - withdrawl.
> -\footnote{In this case, deflation advice is merely a courtesy
> + withdrawl.\footnote{In this case, deflation advice is merely a courtesy
> }
> + \end{enumerate}
>
> -4. In either case, once the device has completed the inflation or
> +\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 configuration space are not atomic, this field
> isn't particularly reliable, but can be used to diagnose buggy guests.
> }
> +\end{enumerate}
>
> \subsubsection{Memory Statistics}\label{sec:Device Types / Memory Balloon Device / Device Operation / Memory Statistics}
>
> @@ -3238,21 +3297,23 @@ driver initialization time when the driver adds an empty buffer
> and notifies the device. A request for memory statistics proceeds
> as follows:
>
> -1. The device pushes the buffer onto the used ring and sends an
> +\begin{enumerate}
> +\item The device pushes the buffer onto the used ring and sends an
> interrupt.
>
> -2. The driver pops the used buffer and discards it.
> +\item The driver pops the used buffer and discards it.
>
> -3. The driver collects memory statistics and writes them into a
> +\item The driver collects memory statistics and writes them into a
> new buffer.
>
> -4. The driver adds the buffer to the virtqueue and notifies the
> +\item The driver adds the buffer to the virtqueue and notifies the
> device.
>
> -5. The device pops the buffer (retaining it to initiate a
> +\item The device pops the buffer (retaining it to initiate a
> subsequent request) and consumes the statistics.
> +\end{enumerate}
>
> - Memory Statistics Format Each statistic consists of a 16 bit
> + Each statistic consists of a 16 bit
> tag and a 64 bit value. All statistics are optional and the
> driver may choose which ones to supply. To guarantee backwards
> compatibility, unsupported statistics should be omitted.
> @@ -3277,24 +3338,25 @@ native endian of the guest rather than (necessarily) little-endian.
>
> \subsubsection{Memory Statistics Tags}\label{sec:Device Types / Memory Balloon Device / Device Operation / Memory Statistics Tags}
>
> - VIRTIO_BALLOON_S_SWAP_IN The amount of memory that has been
> +\begin{description}
> +\item[VIRTIO_BALLOON_S_SWAP_IN (0)] The amount of memory that has been
> swapped in (in bytes).
>
> - VIRTIO_BALLOON_S_SWAP_OUT The amount of memory that has been
> +\item[VIRTIO_BALLOON_S_SWAP_OUT (1)] The amount of memory that has been
> swapped out to disk (in bytes).
>
> - VIRTIO_BALLOON_S_MAJFLT The number of major page faults that
> +\item[VIRTIO_BALLOON_S_MAJFLT (2)] The number of major page faults that
> have occurred.
>
> - VIRTIO_BALLOON_S_MINFLT The number of minor page faults that
> +\item[VIRTIO_BALLOON_S_MINFLT (3)] The number of minor page faults that
> have occurred.
>
> - VIRTIO_BALLOON_S_MEMFREE The amount of memory not being used
> +\item[VIRTIO_BALLOON_S_MEMFREE (4)] The amount of memory not being used
> for any purpose (in bytes).
>
> - VIRTIO_BALLOON_S_MEMTOT The total amount of memory available
> +\item[VIRTIO_BALLOON_S_MEMTOT (5)] The total amount of memory available
> (in bytes).
> -
> +\end{description}
>
> \section{SCSI Host Device}\label{sec:Device Types / SCSI Host Device}
>
> @@ -3304,11 +3366,12 @@ using the SCSI protocol. An instance of the device represents a
> SCSI host to which many targets and LUNs are attached.
>
> The virtio SCSI device services two kinds of requests:
> +\begin{itemize}
> +\item command requests for a logical unit;
>
> -• command requests for a logical unit;
> -
> -• task management functions related to a logical unit, target or
> +\item task management functions related to a logical unit, target or
> command.
> +\end{itemize}
>
> The device is also able to send out notifications about added and
> removed logical units. Together, these capabilities provide a
> @@ -3321,18 +3384,25 @@ targets that receive and process the requests.
> 8
>
> \subsection{Virtqueues}\label{sec:Device Types / SCSI Host Device / Virtqueues}
> - 0:controlq; 1:eventq; 2..n:request queues.
> +
> +\begin{description}
> +\item[0] controlq
> +\item[1] eventq
> +\item[2\ldots n] request queues
> +\end{description}
>
> \subsection{Feature bits}\label{sec:Device Types / SCSI Host Device / Feature bits}
>
> - VIRTIO_SCSI_F_INOUT (0) A single request can include both
> +\begin{description}
> +\item[VIRTIO_SCSI_F_INOUT (0)] A single request can include both
> read-only and write-only data buffers.
>
> - VIRTIO_SCSI_F_HOTPLUG (1) The host should enable
> +\item[VIRTIO_SCSI_F_HOTPLUG (1)] The host should enable
> hot-plug/hot-unplug of new LUNs and targets on the SCSI bus.
>
> - VIRTIO_SCSI_F_CHANGE (2) The host will report changes to LUN
> +\item[VIRTIO_SCSI_F_CHANGE (2)] The host will report changes to LUN
> parameters via a VIRTIO_SCSI_T_PARAM_CHANGE event.
> +\end{description}
>
> \subsection{Device configuration layout}\label{sec:Device Types / SCSI Host Device / Device configuration layout}
>
> @@ -3354,41 +3424,43 @@ targets that receive and process the requests.
> };
> \end{lstlisting}
>
> - num_queues is the total number of request virtqueues exposed by
> +\begin{description}
> +\item[num_queues] is the total number of request virtqueues exposed by
> the device. The driver is free to use only one request queue,
> or it can use more to achieve better performance.
>
> - seg_max is the maximum number of segments that can be in a
> +\item[seg_max] is the maximum number of segments that can be in a
> command. A bidirectional command can include seg_max input
> segments and seg_max output segments.
>
> - max_sectors is a hint to the driver about the maximum transfer
> +\item[max_sectors] is a hint to the driver about the maximum transfer
> size it should use.
>
> - cmd_per_lun is a hint to the driver about the maximum number of
> +\item[cmd_per_lun] is a hint to the driver about the maximum number of
> linked commands it should send to one LUN. The actual value
> to be used is the minimum of cmd_per_lun and the virtqueue
> size.
>
> - event_info_size is the maximum size that the device will fill
> +\item[event_info_size] is the maximum size that the device will fill
> for buffers that the driver places in the eventq. The driver
> should always put buffers at least of this size. It is
> written by the device depending on the set of negotated
> features.
>
> - sense_size is the maximum size of the sense data that the
> +\item[sense_size] is the maximum size of the sense data that the
> device will write. The default value is written by the device
> and will always be 96, but the driver can modify it. It is
> restored to the default when the device is reset.
>
> - cdb_size is the maximum size of the CDB that the driver will
> +\item[cdb_size] is the maximum size of the CDB that the driver will
> write. The default value is written by the device and will
> always be 32, but the driver can likewise modify it. It is
> restored to the default when the device is reset.
>
> - max_channel, max_target and max_lun can be used by the driver
> +\item[max_channel, max_target and max_lun] can be used by the driver
> as hints to constrain scanning the logical units on the
> host.h
> +\end{description}
>
> \subsubsection{Legacy Interface: Device configuration layout}\label{sec:Device Types / SCSI Host Device / Device configuration layout / Legacy Interface: Device configuration layout}
> For legacy devices, the fields in struct virtio_scsi_config are the
> @@ -3500,40 +3572,43 @@ defined in SAM.
> The response byte is written by the device to be one of the
> following:
>
> - VIRTIO_SCSI_S_OK when the request was completed and the status
> +\begin{description}
> +
> +\item[VIRTIO_SCSI_S_OK] when the request was completed and the status
> byte is filled with a SCSI status code (not necessarily
> "GOOD").
>
> - VIRTIO_SCSI_S_OVERRUN if the content of the CDB requires
> +\item[VIRTIO_SCSI_S_OVERRUN] if the content of the CDB requires
> transferring more data than is available in the data buffers.
>
> - VIRTIO_SCSI_S_ABORTED if the request was cancelled due to an
> +\item[VIRTIO_SCSI_S_ABORTED] if the request was cancelled due to an
> ABORT TASK or ABORT TASK SET task management function.
>
> - VIRTIO_SCSI_S_BAD_TARGET if the request was never processed
> +\item[VIRTIO_SCSI_S_BAD_TARGET] if the request was never processed
> because the target indicated by the lun field does not exist.
>
> - VIRTIO_SCSI_S_RESET if the request was cancelled due to a bus
> +\item[VIRTIO_SCSI_S_RESET] if the request was cancelled due to a bus
> or device reset (including a task management function).
>
> - VIRTIO_SCSI_S_TRANSPORT_FAILURE if the request failed due to a
> +\item[VIRTIO_SCSI_S_TRANSPORT_FAILURE] if the request failed due to a
> problem in the connection between the host and the target
> (severed link).
>
> - VIRTIO_SCSI_S_TARGET_FAILURE if the target is suffering a
> +\item[VIRTIO_SCSI_S_TARGET_FAILURE] if the target is suffering a
> failure and the driver should not retry on other paths.
>
> - VIRTIO_SCSI_S_NEXUS_FAILURE if the nexus is suffering a failure
> +\item[VIRTIO_SCSI_S_NEXUS_FAILURE] if the nexus is suffering a failure
> but retrying on other paths might yield a different result.
>
> - VIRTIO_SCSI_S_BUSY if the request failed but retrying on the
> +\item[VIRTIO_SCSI_S_BUSY] if the request failed but retrying on the
> same path should work.
>
> - VIRTIO_SCSI_S_FAILURE for other host or driver error. In
> +\item[VIRTIO_SCSI_S_FAILURE] for other host or driver error. In
> particular, if neither dataout nor datain is empty, and the
> VIRTIO_SCSI_F_INOUT feature has not been negotiated, the
> request will be immediately returned with a response equal to
> VIRTIO_SCSI_S_FAILURE.
> +\end{description}
>
> \paragraph{Legacy Interface: Device Operation: Request Queues}\label{sec:Device Types / SCSI Host Device / Device Operation / Device Operation: Request Queues / Legacy Interface: Device Operation: Request Queues}
> For legacy devices, the fields in struct virtio_scsi_req_cmd are the
> @@ -3735,17 +3810,19 @@ contents of the event field. The following events are defined:
>
> This event is fired in the following cases:
>
> - • When the device detects in the eventq a buffer that is
> +\begin{itemize}
> +\item When the device detects in the eventq a buffer that is
> shorter than what is indicated in the configuration field, it
> might use it immediately and put this dummy value in the
> event field. A well-written driver will never observe this
> situation.
>
> - • When events are dropped, the device may signal this event as
> +\item When events are dropped, the device may signal this event as
> soon as the drivers makes a buffer available, in order to
> request action from the driver. In this case, of course, this
> event will be reported with the VIRTIO_SCSI_T_EVENTS_MISSED
> flag.
> +\end{itemize}
>
> Transport reset
> \begin{lstlisting}
> @@ -3766,15 +3843,17 @@ contents of the event field. The following events are defined:
> The reason value is one of the three \#define values appearing
> above:
>
> - • VIRTIO_SCSI_EVT_RESET_REMOVED (“LUN/target removed”) is used
> + \begin{itemize}
> + \item VIRTIO_SCSI_EVT_RESET_REMOVED (“LUN/target removed”) is used
> if the target or logical unit is no longer able to receive
> commands.
>
> - • VIRTIO_SCSI_EVT_RESET_HARD (“LUN hard reset”) is used if the
> + \item VIRTIO_SCSI_EVT_RESET_HARD (“LUN hard reset”) is used if the
> logical unit has been reset, but is still present.
>
> - • VIRTIO_SCSI_EVT_RESET_RESCAN (“rescan LUN/target”) is used if
> + \item VIRTIO_SCSI_EVT_RESET_RESCAN (“rescan LUN/target”) is used if
> a target or logical unit has just appeared on the device.
> + \end{itemize}
>
> The “removed” and “rescan” events, when sent for LUN 0, may
> apply to the entire target. After receiving them the driver
> @@ -3788,14 +3867,16 @@ contents of the event field. The following events are defined:
> does not apply to newly appeared buses or targets, since the
> application has never discovered them):
>
> - • “LUN/target removed” maps to sense key ILLEGAL REQUEST, asc
> + \begin{itemize}
> + \item “LUN/target removed” maps to sense key ILLEGAL REQUEST, asc
> 0x25, ascq 0x00 (LOGICAL UNIT NOT SUPPORTED)
>
> - • “LUN hard reset” maps to sense key UNIT ATTENTION, asc 0x29
> + \item “LUN hard reset” maps to sense key UNIT ATTENTION, asc 0x29
> (POWER ON, RESET OR BUS DEVICE RESET OCCURRED)
>
> - • “rescan LUN/target” maps to sense key UNIT ATTENTION, asc
> + \item “rescan LUN/target” maps to sense key UNIT ATTENTION, asc
> 0x3f, ascq 0x0e (REPORTED LUNS DATA HAS CHANGED)
> + \end{itemize}
>
> The preferred way to detect transport reset is always to use
> events, because sense codes are only seen by the driver when it
> @@ -3853,11 +3934,12 @@ native endian of the guest rather than (necessarily) little-endian.
>
> Currently there are four device-independent feature bits defined:
>
> - VIRTIO_F_RING_INDIRECT_DESC (28) Negotiating this feature indicates
> +\begin{description}
> + \item[VIRTIO_F_RING_INDIRECT_DESC (28)] Negotiating this feature indicates
> that the driver can use descriptors with the VRING_DESC_F_INDIRECT
> flag set, as described in \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table / Indirect Descriptors}~\nameref{sec:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table / Indirect Descriptors}.
>
> - VIRTIO_F_RING_EVENT_IDX(29) This feature enables the used_event
> + \item[VIRTIO_F_RING_EVENT_IDX(29)] This feature enables the used_event
> and the avail_event fields. If set, it indicates that the
> device should ignore the flags field in the available ring
> structure. Instead, the used_event field in this structure is
> @@ -3868,9 +3950,10 @@ Currently there are four device-independent feature bits defined:
> driver should ignore the used_event field; the device should
> ignore the avail_event field; the flags field is used
>
> - VIRTIO_F_VERSION_1(32) This feature must be offered by any device
> + \item[VIRTIO_F_VERSION_1(32)] This feature must be offered by any device
> compliant with this specification, and acknowledged by all device
> drivers.
> +\end{description}
>
> In addition, bit 30 is used by qemu's implementation to check for experimental
> early versions of virtio which did not perform correct feature negotiation,
> @@ -3880,7 +3963,8 @@ and should not be used.
>
> Legacy or transitional devices may offer the following:
>
> -VIRTIO_F_NOTIFY_ON_EMPTY (24) Negotiating this feature
> +\begin{description}
> +\item[VIRTIO_F_NOTIFY_ON_EMPTY (24)] Negotiating this feature
> indicates that the driver wants an interrupt if the device runs
> out of available descriptors on a virtqueue, even though
> interrupts are suppressed using the VRING_AVAIL_F_NO_INTERRUPT
> @@ -3891,9 +3975,10 @@ VIRTIO_F_NOTIFY_ON_EMPTY (24) Negotiating this feature
> using a timer if the device interrupts it when all the packets
> are transmitted.
>
> -VIRTIO_F_ANY_LAYOUT (27) This feature indicates that the device
> +\item[VIRTIO_F_ANY_LAYOUT (27)] This feature indicates that the device
> accepts arbitrary descriptor layouts, as described in Section
> \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Message Framing / Legacy Interface: Message Framing}~\nameref{sec:Basic Facilities of a Virtio Device / Virtqueues / Message Framing / Legacy Interface: Message Framing}.
> +\end{description}
>
> \chapter{virtio_ring.h}\label{sec:virtio-ring.h}
>
> @@ -3935,8 +4020,7 @@ are atomically writable.
>
> Currently device numbers are assigned quite freely: a simple
> request mail to the author of this document or the Linux
> -virtualization mailing list
> -\footnote{https://lists.linux-foundation.org/mailman/listinfo/virtualization
> +virtualization mailing list\footnote{https://lists.linux-foundation.org/mailman/listinfo/virtualization
> } will be sufficient to secure a unique one.
>
> Meanwhile for experimental drivers, use 65535 and work backwards.
> @@ -3963,8 +4047,7 @@ altogether.
>
> Any change to configuration space, or new virtqueues, or
> behavioural changes, should be indicated by negotiation of a new
> -feature bit. This establishes clarity
> -\footnote{Even if it does mean documenting design or implementation
> +feature bit. This establishes clarity\footnote{Even if it does mean documenting design or implementation
> mistakes!
> } and avoids future expansion problems.
>
