\chapter{Basic Facilities of a Virtio Device}\label{sec:Basic Facilities of a Virtio Device}
A virtio device is discovered and identified by a bus-specific method
(see the bus specific sections: \ref{sec:Virtio Transport Options / Virtio Over PCI Bus}~\nameref{sec:Virtio Transport Options / Virtio Over PCI Bus},
\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:
\begin{itemize}
\item Device status field
\item Feature bits
\item Device Configuration space
\item One or more virtqueues
\end{itemize}
\section{\field{Device Status} Field}\label{sec:Basic Facilities of a Virtio Device / Device Status Field}
During device initialization by a driver,
the driver follows the sequence of steps specified in
\ref{sec:General Initialization And Device Operation / Device
Initialization}.
The \field{device status} field provides a simple low-level
indication of the completed steps of this sequence.
It's most useful to imagine it hooked up to traffic
lights on the console indicating the status of each device. The
following bits are defined (listed below in the order in which
they would be typically set):
\begin{description}
\item[ACKNOWLEDGE (1)] Indicates that the guest OS has found the
device and recognized it as a valid virtio device.
\item[DRIVER (2)] Indicates that the guest OS knows how to drive the
device.
\begin{note}
There could be a significant (or infinite) delay before setting
this bit. For example, under Linux, drivers can be loadable modules.
\end{note}
\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.
\item[FEATURES_OK (8)] Indicates that the driver has acknowledged all the
features it understands, and feature negotiation is complete.
\item[DRIVER_OK (4)] Indicates that the driver is set up and ready to
drive the device.
\item[DEVICE_NEEDS_RESET (64)] Indicates that the device has experienced
an error from which it can't recover.
\end{description}
\drivernormative{\subsection}{Device Status Field}{Basic Facilities of a Virtio Device / Device Status Field}
The driver MUST update \field{device status},
setting bits to indicate the completed steps of the driver
initialization sequence specified in
\ref{sec:General Initialization And Device Operation / Device
Initialization}.
The driver MUST NOT clear a
\field{device status} bit. If the driver sets the FAILED bit,
the driver MUST later reset the device before attempting to re-initialize.
The driver SHOULD NOT rely on completion of operations of a
device if DEVICE_NEEDS_RESET is set.
\begin{note}
For example, the driver can't assume requests in flight will be
completed if DEVICE_NEEDS_RESET is set, nor can it assume that
they have not been completed. A good implementation will try to
recover by issuing a reset.
\end{note}
\devicenormative{\subsection}{Device Status Field}{Basic Facilities of a Virtio Device / Device Status Field}
The device MUST initialize \field{device status} to 0 upon reset.
The device MUST NOT consume buffers or notify the driver before DRIVER_OK.
\label{sec:Basic Facilities of a Virtio Device / Device Status Field / DEVICENEEDSRESET}The device SHOULD set DEVICE_NEEDS_RESET when it enters an error state
that a reset is needed. If DRIVER_OK is set, after it sets DEVICE_NEEDS_RESET, the device
MUST send a device configuration change notification to the driver.
\section{Feature Bits}\label{sec:Basic Facilities of a Virtio Device / Feature Bits}
Each virtio device offers all the features it understands. During
device initialization, the driver reads this and tells the device the
subset that it accepts. The only way to renegotiate is to reset
the device.
This allows for forwards and backwards compatibility: if the device is
enhanced with a new feature bit, older drivers will not write that
feature bit back to the device. Similarly, if a driver is enhanced with a feature
that the device doesn't support, it see the new feature is not offered.
Feature bits are allocated as follows:
\begin{description}
\item[0 to 23] Feature bits for the specific device type
\item[24 to 33] Feature bits reserved for extensions to the queue and
feature negotiation mechanisms
\item[34 and above] Feature bits reserved for future extensions.
\end{description}
\begin{note}
For example, feature bit 0 for a network device (i.e.
Device ID 1) indicates that the device supports checksumming of
packets.
\end{note}
In particular, new fields in the device configuration space are
indicated by offering a new feature bit.
\drivernormative{\subsection}{Feature Bits}{Basic Facilities of a Virtio Device / Feature Bits}
The driver MUST NOT accept a feature which the device did not offer,
and MUST NOT accept a feature which requires another feature which was
not accepted.
The driver SHOULD go into backwards compatibility mode
if the device does not offer a feature it understands, otherwise MUST
set the FAILED \field{device status} bit and cease initialization.
\devicenormative{\subsection}{Feature Bits}{Basic Facilities of a Virtio Device / Feature Bits}
The device MUST NOT offer a feature which requires another feature
which was not offered. The device SHOULD accept any valid subset
of features the driver accepts, otherwise it MUST fail to set the
FEATURES_OK \field{device status} bit when the driver writes it.
\subsection{Legacy Interface: A Note on Feature
Bits}\label{sec:Basic Facilities of a Virtio Device / Feature
Bits / Legacy Interface: A Note on Feature Bits}
Transitional Drivers MUST detect Legacy Devices by detecting that
the feature bit VIRTIO_F_VERSION_1 is not offered.
Transitional devices MUST detect Legacy drivers by detecting that
VIRTIO_F_VERSION_1 has not been acknowledged by the driver.
In this case device is used through the legacy interface.
Legacy interface support is OPTIONAL.
Thus, both transitional and non-transitional devices and
drivers are compliant with this specification.
Requirements pertaining to transitional devices and drivers
is contained in sections named 'Legacy Interface' like this one.
When device is used through the legacy interface, transitional
devices and transitional drivers MUST operate according to the
requirements documented within these legacy interface sections.
Specification text within these sections generally does not apply
to non-transitional devices.
\section{Device Configuration Space}\label{sec:Basic Facilities of a Virtio Device / Device Configuration Space}
Device configuration space is generally used for rarely-changing or
initialization-time parameters. Where configuration fields are
optional, their existence is indicated by feature bits: Future
versions of this specification will likely extend the device
configuration space by adding extra fields at the tail.
\begin{note}
The device configuration space uses the little-endian format
for multi-byte fields.
\end{note}
Each transport also provides a generation count for the device configuration
space, which will change whenever there is a possibility that two
accesses to the device configuration space can see different versions of that
space.
\drivernormative{\subsection}{Device Configuration Space}{Basic Facilities of a Virtio Device / Device Configuration Space}
Drivers MUST NOT assume reads from
fields greater than 32 bits wide are atomic, nor are reads from
multiple fields: drivers SHOULD read device configuration space fields like so:
\begin{lstlisting}
u32 before, after;
do {
before = get_config_generation(device);
// read config entry/entries.
after = get_config_generation(device);
} while (after != before);
\end{lstlisting}
For optional configuration space fields, the driver MUST check that the
corresponding feature is offered before accessing that part of the configuration
space.
\begin{note}
See section \ref{sec:General Initialization And Device Operation / Device Initialization} for details on feature negotiation.
\end{note}
Drivers MUST
NOT limit structure size and device configuration space size. Instead,
drivers SHOULD only check that device configuration space is {\em large enough} to
contain the fields necessary for device operation.
\begin{note}
For example, if the specification states that device configuration
space 'includes a single 8-bit field' drivers should understand this to mean that
the device configuration space might also include an arbitrary amount of
tail padding, and accept any device configuration space size equal to or
greater than the specified 8-bit size.
\end{note}
\devicenormative{\subsection}{Device Configuration Space}{Basic Facilities of a Virtio Device / Device Configuration Space}
The device MUST allow reading of any device-specific configuration
field before FEATURES_OK is set by the driver. This includes fields which are
conditional on feature bits, as long as those feature bits are offered
by the device.
\subsection{Legacy Interface: A Note on Device Configuration Space endian-ness}\label{sec:Basic Facilities of a Virtio Device / Device Configuration Space / Legacy Interface: A Note on Configuration Space endian-ness}
Note that for legacy interfaces, device configuration space is generally the
guest's native endian, rather than PCI's little-endian.
The correct endian-ness is documented for each device.
\subsection{Legacy Interface: Device Configuration Space}\label{sec:Basic Facilities of a Virtio Device / Device Configuration Space / Legacy Interface: Device Configuration Space}
Legacy devices did not have a configuration generation field, thus are
susceptible to race conditions if configuration is updated. This
affects the block \field{capacity} (see \ref{sec:Device Types /
Block Device / Device configuration layout}) and
network \field{mac} (see \ref{sec:Device Types / Network Device /
Device configuration layout}) fields;
when using the legacy interface, drivers SHOULD
read these fields multiple times until two reads generate a consistent
result.
\section{Virtqueues}\label{sec:Basic Facilities of a Virtio Device / Virtqueues}
The mechanism for bulk data transport on virtio devices is
pretentiously called a virtqueue. Each device can have zero or more
virtqueues\footnote{For example, the simplest network device has one virtqueue for
transmit and one for receive.}. Each queue has a 16-bit queue size
parameter, which sets the number of entries and implies the total size
of the queue.
Each virtqueue consists of three parts:
\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.
The memory aligment and size requirements, in bytes, of each part of the
virtqueue are summarized in the following table:
\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 + 8 * $(Queue Size) \\
\hline
| 