\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 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".

\section{Device Status Field}\label{sec:Basic Facilities of a Virtio Device / Device Status Field}

The driver MUST update the Device Status field in the order below to
indicate its progress. This provides a simple low-level diagnostic:
it's most useful to imagine them hooked up to traffic lights on the
console indicating the status of each device.  The driver MUST NOT
clear a device status bit.

This field is 0 upon reset, otherwise at least one bit should be 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. Under Linux, drivers can be loadable modules so there
  may be a significant (or infinite) delay before setting this
  bit.

\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[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}

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 and it SHOULD go into backwards
compatibility mode. Similarly, if a driver is enhanced with a feature
that the device doesn't support, it see the new feature is not offered
and SHOULD go into backwards compatibility mode (or, for poor
implementations it MAY set the FAILED Device Status bit).

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 device MUST NOT offer a feature which requires another feature
which was not offered.

Feature bits are allocated as follows:

\begin{description}
\item[0 to 23] Feature bits for the specific device type

\item[24 to 32] Feature bits reserved for extensions to the queue and
  feature negotiation mechanisms

\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
packets.

In particular, new fields in the device configuration space are
indicated by offering a feature bit, so the driver MUST check that the
feature is offered before accessing that part of the configuration
space.

\subsection{Legacy Interface: A Note on transitions from earlier drafts}\label{sec:Basic Facilities of a Virtio Device / Feature Bits / Legacy Interface: A Note on transitions from earlier drafts}

Earlier drafts of this specification (up to 0.9.X) defined a similar, but
different interface between the hypervisor and the guest.
Since these are widely deployed, this specification
accommodates optional features to simplify transition
from these earlier draft interfaces. Specifically:

\begin{description}
\item[Legacy Interface]
        is an interface specified by an earlier draft of this specification
        (up to 0.9.X)
\item[Legacy Device]
        is a device implemented before this specification was released,
        and implementing a legacy interface on the host side
\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.

To simplify transition from these earlier draft interfaces,
it is possible to implement:

\begin{description}
\item[Transitional Device]
        a device supporting both drivers conforming to this
        specification, and allowing legacy drivers.

\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).

Devices or drivers with no legacy compatibility are referred to as
non-transitional devices and drivers, respectively.

Transitional Drivers can detect Legacy Devices by detecting that
the feature bit VIRTIO_F_VERSION_1 is not offered.
Transitional devices can 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.

To make them easier to locate, specification sections documenting
these transitional features are explicitly marked with 'Legacy
Interface' in the section title.

\section{Configuration Space}\label{sec:Basic Facilities of a Virtio Device / Configuration Space}

Configuration space is generally used for rarely-changing or
initialization-time parameters.  Drivers MUST NOT assume reads from
fields greater than 32 bits wide are atomic, nor or reads from
multiple fields.

Each transport provides a generation count for the configuration
space, which must change whenever there is a possibility that two
accesses to the configuration space can see different versions of that
space.

Thus drivers SHOULD read 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}

Note that configuration space uses the little-endian format
for multi-byte fields.

Note that future versions of this specification will likely
extend the configuration space for devices by adding extra fields
at the tail end of some structures in configuration space.

To allow forward compatibility with such extensions, drivers MUST
NOT limit structure size and configuration space size.  Instead,
drivers SHOULD only check that configuration space is *large enough* to
contain the fields required for device operation.

For example, if the specification states that configuration
space 'includes a single 8-bit field' drivers should understand this to mean that
the configuration space might also include an arbitrary amount of
tail padding, and accept any configuration space size equal to or
greater than the specified 8-bit size.

\subsection{Legacy Interface: A Note on Configuration Space endian-ness}\label{sec:Basic Facilities of a Virtio Device / Configuration Space / Legacy Interface: A Note on Configuration Space endian-ness}

Note that for legacy interfaces, configuration space is generally the
guest's native endian, rather than PCI's little-endian.

\subsection{Legacy Interface: Configuration Space}\label{sec:Basic Facilities of a Virtio Device / Configuration Space / Legacy Interface: Configuration Space}

Legacy devices did not have a configuration generation field, thus are
susceptible to race conditions if configuration is updated.  This
effects the block capacity and network mac fields; best practice is to
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: for example, the simplest network device has one 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 + 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
MUST be a multiple of the specified alignment value.

The Size column gives the total number of bytes required for each
part of the virtqueue.

Queue Size corresponds to the maximum number of buffers in the
virtqueue.  For example, if Queue Size is 4 then at most 4 buffers
can be queued at any given time.  Queue Size value is always a
power of 2.  The maximum Queue Size value is 32768.  This value
is specified in a bus-specific way.

When the driver wants to send a buffer to the device, it fills in
a slot in the descriptor table (or chains several together), and
writes the descriptor index into the available ring.  It then
notifies the device. When the device has finished a buffer, it
writes the descriptor index into the used ring, and sends an interrupt.


\subsection{Legacy Interfaces: A Note on Virtqueue Layout}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / Legacy Interfaces: A Note on Virtqueue Layout}

For Legacy Interfaces, several additional
restrictions are placed on the virtqueue layout:

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

\begin{lstlisting}
	#define ALIGN(x) (((x) + PAGE_SIZE) & ~PAGE_SIZE)
	static inline unsigned vring_size(unsigned int qsz)
	{
	     return ALIGN(sizeof(struct vring_desc)*qsz + sizeof(u16)*(3 + qsz))
	          + ALIGN(sizeof(u16)*3 + sizeof(struct vring_used_elem)*qsz);
	}
\end{lstlisting}

This wastes some space with padding.
The legacy virtqueue layout structure therefore looks like this:

\begin{lstlisting}
	struct vring {
		// The actual descriptors (16 bytes each)
		struct vring_desc desc[ Queue Size ];

		// A ring of available descriptor heads with free-running index.
		struct vring_avail avail;

		// Padding to the next PAGE_SIZE boundary.
		char pad[ Padding ];

		// A ring of used descriptor heads with free-running index.
		struct vring_used used;
	};
\end{lstlisting}

\subsection{Legacy Interfaces: A Note on Virtqueue Endianness}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / Legacy Interfaces: A Note on Virtqueue Endianness}

Note that the endian of fields and in the virtqueue is the native
endian of the guest, not little-endian as specified by this standard.
It is assumed that the host is already aware of the guest endian.

\subsection{Message Framing}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / Message Framing}
The device MUST NOT make assumptions about the particular arrangement
of descriptors: the message framing is
independent of the contents of the buffers. For example, a network
transmit buffer consists of a 12 byte header followed by the network
packet. This could be most simply placed in the descriptor table as a
12 byte output descriptor followed by a 1514 byte output descriptor,
but it could also consist of a single 1526 byte output descriptor in
the case where the header and packet are adjacent, or even three or
more descriptors (possibly with loss of efficiency in that case).

Note that, some implementations may have large-but-reasonable
restrictions on total descriptor size (such as based on IOV_MAX in the
host OS). This has not been a problem in practice: little sympathy
will be given to drivers which create unreasonably-sized descriptors
such as by dividing a network packet into 1500 single-byte
descriptors!

\subsubsection{Legacy Interface: Message Framing}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / Message Framing / Legacy Interface: Message Framing}

Regrettably, initial driver implementations used simple layouts, and
devices came to rely on it, despite this specification wording.  In
addition, the specification for virtio_blk SCSI commands required
intuiting field lengths from frame boundaries (see
 \ref{sec:Device Types / Block Device / Device Operation / Legacy Interface: Device Operation}~\nameref{sec:Device Types / Block Device / Device Operation / Legacy Interface: Device Operation})

It is thus recommended that when using legacy interfaces, transitional
drivers be conservative in their assumptions, unless the
VIRTIO_F_ANY_LAYOUT feature is accepted.

\subsection{The Virtqueue Descriptor Table}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table}

The descriptor table refers to the buffers the driver is using for
the device. The addresses are physical addresses, and the buffers
can be chained via the next field. Each descriptor describes a
buffer which is read-only or write-only, but a chain of
descriptors can contain both read-only and write-only buffers.

The actual contents of the memory offered to the device depends on the
device type.  Most common is to begin the data with a header
(containing little-endian fields) for the device to read, and postfix
it with a status tailer for the device to write.

Drivers MUST NOT add a descriptor chain over than $2^{32}$ bytes long in total;
this implies that loops in the descriptor chain are forbidden!

\begin{lstlisting}
	struct vring_desc {
		/* Address (guest-physical). */
		le64 addr;
		/* Length. */
		le32 len;

	/* This marks a buffer as continuing via the next field. */
	#define VRING_DESC_F_NEXT   1
	/* This marks a buffer as write-only (otherwise read-only). */
	#define VRING_DESC_F_WRITE     2
	/* This means the buffer contains a list of buffer descriptors. */
	#define VRING_DESC_F_INDIRECT   4
		/* The flags as indicated above. */
		le16 flags;
		/* Next field if flags & NEXT */
		le16 next;
	};
\end{lstlisting}

The number of descriptors in the table is defined by the queue size
for this virtqueue.

\subsubsection{Indirect Descriptors}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table / Indirect Descriptors}

Some devices benefit by concurrently dispatching a large number
of large requests. The VIRTIO_RING_F_INDIRECT_DESC feature allows this (see \ref{sec:virtio-ring.h}~\nameref{sec:virtio-ring.h}). To increase
ring capacity the driver can store a table of indirect
descriptors anywhere in memory, and insert a descriptor in main
virtqueue (with flags\&VRING_DESC_F_INDIRECT on) that refers to memory buffer
containing this indirect descriptor table; fields addr and len
refer to the indirect table address and length in bytes,
respectively.

The driver MUST NOT set the VRING_DESC_F_INDIRECT flag unless the
VIRTIO_RING_F_INDIRECT_DESC feature was negotiated.

The indirect table layout structure looks like this
(len is the length of the descriptor that refers to this table,
which is a variable, so this code won't compile):

\begin{lstlisting}
	struct indirect_descriptor_table {
		/* The actual descriptors (16 bytes each) */
		struct vring_desc desc[len / 16];
	};
\end{lstlisting}

The first indirect descriptor is located at start of the indirect
descriptor table (index 0), additional indirect descriptors are
chained by next field. An indirect descriptor without next field
(with flags\&VRING_DESC_F_NEXT off) signals the end of the descriptor.
An
indirect descriptor can not refer to another indirect descriptor
table (flags\&VRING_DESC_F_INDIRECT MUST be off). A single indirect descriptor
table can include both read-only and write-only descriptors;
the device MUST ignore the write-only flag (flags\&VRING_DESC_F_WRITE) in the descriptor that refers to it.

\subsection{The Virtqueue Available Ring}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Available Ring}

\begin{lstlisting}
	struct vring_avail {
	#define VRING_AVAIL_F_NO_INTERRUPT      1
		le16 flags;
		le16 idx;
		le16 ring[ /* Queue Size */ ];
		le16 used_event;	/* Only if VIRTIO_RING_F_EVENT_IDX */
	};
\end{lstlisting}

The available ring refers to what descriptor chains the driver is offering the
device: each ring entry refers to the head of a descriptor chain.  It is only
written by the driver and read by the device.

The “idx” field indicates where we would put the next descriptor
entry in the ring (modulo the queue size). This starts at 0, and increases.

If the VIRTIO_RING_F_INDIRECT_DESC feature bit is not negotiated, the
“flags” field offers a crude interrupt control mechanism.  The driver
MUST set this to 0 or 1: 1 indicates that the device SHOULD NOT send
an interrupt when it consumes a descriptor chain from the available
ring.  The device MUST ignore the used_event value in this case.

Otherwise, if the VIRTIO_RING_F_EVENT_IDX feature bit is negotiated,
the driver MUST set the "flags" field to 0, and use the “used_event”
field in the used ring instead.  The driver can ask the device to delay interrupts
until an entry with an index specified by the “used_event” field is
written in the used ring (equivalently, until the idx field in the
used ring will reach the value used_event + 1).

The driver MUST handle spurious interrupts: either form of interrupt
suppression is merely an optimization; it may not suppress interrupts
entirely.

\subsection{The Virtqueue Used Ring}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Used Ring}

\begin{lstlisting}
	struct vring_used {
	#define VRING_USED_F_NO_NOTIFY  1
		le16 flags;
		le16 idx;
		struct vring_used_elem ring[ /* Queue Size */];
		le16 avail_event; /* Only if VIRTIO_RING_F_EVENT_IDX */
	};

	/* le32 is used here for ids for padding reasons. */
	struct vring_used_elem {
		/* Index of start of used descriptor chain. */
		le32 id;
		/* Total length of the descriptor chain which was used (written to) */
		le32 len;
	};
\end{lstlisting}

The used ring is where the device returns buffers once it is done with
them: it is only written to by the device, and read by the driver.

Each entry in the ring is a pair: the head entry of the
descriptor chain describing the buffer (this matches an entry
placed in the available ring by the guest earlier), and the total
of bytes written into the buffer. The latter is extremely useful
for drivers using untrusted buffers: if you do not know exactly
how much has been written by the device, you usually have to zero
the buffer to ensure no data leakage occurs.

If the VIRTIO_RING_F_INDIRECT_DESC feature bit is not negotiated, the
“flags” field offers a crude interrupt control mechanism.  The driver
MUST initialize this to 0, the device MUST set this to 0 or 1: 1
indicates that the driver SHOULD NOT send an notification when it adds
a descriptor chain to the available ring.  The driver MUST ignore the
used_event value in this case.

Otherwise, if the VIRTIO_RING_F_EVENT_IDX feature bit is negotiated,
the device MUST leave the "flags" field at 0, and use the
“avail_event” field in the used ring instead.  The device can ask the
driver to delay notifications until an entry with an index specified
by the “avail_event” field is written in the available ring (equivalently,
until the idx field in the used ring will reach the value avail_event +
1).

The device MUST handle spurious notification: either form of
notification suppression is merely an optimization; it may not
suppress them entirely.

\subsection{Helpers for Operating Virtqueues}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / Helpers for Operating Virtqueues}

The Linux Kernel Source code contains the definitions above and
helper routines in a more usable form, in
include/linux/virtio_ring.h. This was explicitly licensed by IBM
and Red Hat under the (3-clause) BSD license so that it can be
freely used by all other projects, and is reproduced (with slight
variation to remove Linux assumptions) in \ref{sec:virtio-ring.h}~\nameref{sec:virtio-ring.h}.

\chapter{General Initialization And Device Operation}\label{sec:General Initialization And Device Operation}

We start with an overview of device initialization, then expand on the
details of the device and how each step is preformed.  This section
should be read along with the bus-specific section which describes
how to communicate with the specific device.

\section{Device Initialization}\label{sec:General Initialization And Device Operation / Device Initialization}

The driver MUST follow this sequence to initialize a device:

\begin{enumerate}
\item Reset the device.

\item Set the ACKNOWLEDGE status bit: we have noticed the device.

\item Set the DRIVER status bit: we know how to drive the device.

\item Read device feature bits, and write the subset of feature bits
   understood by the OS and driver to the device.

\item\label{itm:General Initialization And Device Operation / Device Initialization / Set FEATURES-OK} Set the FEATURES_OK status bit.  The driver MUST not accept
   new feature bits after this step.

\item\label{itm:General Initialization And Device Operation / Device Initialization / Re-read FEATURES-OK} 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.

\item\label{itm:General Initialization And Device Operation / Device Initialization / Device-specific Setup} 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.

\item\label{itm:General Initialization And Device Operation / Device Initialization / Set DRIVER-OK} 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
device (it can reset the device later to restart if desired).  The
driver MUST not continue initialization in that case.

The device MUST NOT consume buffers before DRIVER_OK, and the driver
MUST NOT notify the device before it sets DRIVER_OK.

Devices SHOULD support all valid combinations of features, but we know
that implementations may well make assuptions that they will only be
used by fully-optimized drivers.  The resetting of the FEATURES_OK flag
provides a semi-graceful failure mode for this case.

\subsection{Legacy Interface: Device Initialization}\label{sec:General Initialization And Device Operation / Device Initialization / Legacy Interface: Device Initialization}
Legacy devices do not support the FEATURES_OK status bit, and thus did
not have a graceful way for the device to indicate unsupported feature
combinations.  It also did not provide a clear mechanism to end
feature negotiation, which meant that devices finalized features on
first-use, and no features could be introduced which radically changed
the initial operation of the device.

Legacy device implementations often used the device before setting the
DRIVER_OK bit.

The result was the steps \ref{itm:General Initialization And Device Operation / Device Initialization / Set FEATURES-OK} and \ref{itm:General Initialization And Device Operation / Device Initialization / Re-read FEATURES-OK} were omitted, and steps \ref{itm:General Initialization And Device Operation / Device Initialization / Device-specific Setup} and \ref{itm:General Initialization And Device Operation / Device Initialization / Set DRIVER-OK}
were conflated.

\section{Device Operation}\label{sec:General Initialization And Device Operation / Device Operation}

There are two parts to device operation: supplying new buffers to
the device, and processing used buffers from the device. As an
example, the simplest virtio network device has two virtqueues: the
transmit virtqueue and the receive virtqueue. The driver adds
outgoing (read-only) packets to the transmit virtqueue, and then
frees them after they are used. Similarly, incoming (write-only)
buffers are added to the receive virtqueue, and processed after
they are used.

\subsection{Supplying Buffers to The Device}\label{sec:General Initialization And Device Operation / Device Operation / Supplying Buffers to The Device}

The driver offers buffers to one of the device's virtqueues as follows:

\begin{enumerate}
\item\label{itm:General Initialization And Device Operation / Device Operation / Supplying Buffers to The Device / Place Buffers} 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}).

\item\label{itm:General Initialization And Device Operation / Device Operation / Supplying Buffers to The Device / Place Index} The driver places the index of the head of the descriptor chain
   into the next ring entry of the available ring.

\item Steps \ref{itm:General Initialization And Device Operation / Device Operation / Supplying Buffers to The Device / Place Buffers} and \ref{itm:General Initialization And Device Operation / Device Operation / Supplying Buffers to The Device / Place Index} may be performed repeatedly if batching
  is possible.

\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.

\item The available “idx” field is increased by the number of
  descriptor chain heads added to the available ring.

\item The driver MUST perform a suitable memory barrier to ensure that it updates
  the "idx" field before checking for notification suppression.

\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
the ring buffer is the same size as the descriptor table, so step
(1) will prevent such a condition.

In addition, the maximum queue size is 32768 (it must be a power
of 2 which fits in 16 bits), so the 16-bit “idx” value can always
distinguish between a full and empty buffer.

Here is a description of each stage in more detail.

\subsubsection{Placing Buffers Into The Descriptor Table}\label{sec:General Initialization And Device Operation / Device Operation / Supplying Buffers to The Device / Placing Buffers Into The Descriptor Table}

A buffer consists of zero or more read-only physically-contiguous
elements followed by zero or more physically-contiguous
write-only elements (it must have at least one element). This
algorithm maps it into the descriptor table to form a descriptor
chain:

for each buffer element, b:

\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.
\item If there is a buffer element after this:
    \begin{enumerate}
    \item Set d.next to the index of the next free descriptor
      element.
    \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
free descriptors before beginning the mappings.

\subsubsection{Updating The Available Ring}\label{sec:General Initialization And Device Operation / Device Operation / Supplying Buffers to The Device / Updating The Available Ring}

The head of the buffer we mapped is the first d in the algorithm
above (the descriptor chain head).  A naive implementation would do the following (with the
appropriate conversion to-and-from little-endian assumed):

\begin{lstlisting}
	avail->ring[avail->idx % qsz] = head;
\end{lstlisting}

However, in general we can add many descriptor chains before we update
the “idx” field (at which point they become visible to the
device), so we keep a counter of how many we've added:

\begin{lstlisting}
	avail->ring[(avail->idx + added++) % qsz] = head;
\end{lstlisting}

\subsubsection{Updating The Index Field}\label{sec:General Initialization And Device Operation / Device Operation / Supplying Buffers to The Device / Updating The Index Field}

Once the index field of the virtqueue is updated, the device will
be able to access the descriptor chains we've created and the
memory they refer to. This is why a memory barrier is generally
used before the index update, to ensure it sees the most up-to-date
copy.

The index field always increments, and we let it wrap naturally at
65536:

\begin{lstlisting}
	avail->idx += added;
\end{lstlisting}

\subsubsection{Notifying The Device}\label{sec:General Initialization And Device Operation / Device Operation / Supplying Buffers to The Device / Notifying The Device}

The actual method of device notification is bus-specific, but generally
it can be expensive.  So the device can suppress such notifications if it
doesn't need them.  The driver has to be careful to expose the new index
value before checking if notifications are suppressed: it's OK to notify
gratuitously, but not to omit a required notification. So again,
we use a memory barrier here before reading the flags or the
avail_event field.

If the VIRTIO_F_RING_EVENT_IDX feature is not negotiated, and if the
VRING_USED_F_NOTIFY flag is not set, we go ahead and notify the
device.

If the VIRTIO_F_RING_EVENT_IDX feature is negotiated, we read the
avail_event field in the available ring structure. If the
available index crossed_the avail_event field value since the
last notification, we go ahead and write to the PCI configuration
space.  The avail_event field wraps naturally at 65536 as well,
iving the following algorithm for calculating whether a device needs
notification:

\begin{lstlisting}
	(u16)(new_idx - avail_event - 1) < (u16)(new_idx - old_idx)
\end{lstlisting}

\subsection{Receiving Used Buffers From The Device}\label{sec:General Initialization And Device Operation / Device Operation / Receiving Used Buffers From The Device}

Once the device has used a buffer (read from or written to it, or
parts of both, depending on the nature of the virtqueue and the
device), it sends an interrupt, following an algorithm very
similar to the algorithm used for the driver to send the device a
buffer:

\begin{enumerate}
\item Write the head descriptor number to the next field in the used
  ring.

\item Update the used ring index.

\item Deliver an interrupt if necessary:

  \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.

  \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.
It can then process used ring entries finally enabling interrupts
by clearing the VRING_AVAIL_F_NO_INTERRUPT flag or updating the
EVENT_IDX field in the available structure.  The driver should then
execute a memory barrier, and then recheck the ring empty
condition. This is necessary to handle the case where after the
last check and before enabling interrupts, an interrupt has been
suppressed by the device:

\begin{lstlisting}
	vring_disable_interrupts(vq);

	for (;;) {
		if (vq->last_seen_used != le16_to_cpu(vring->used.idx)) {
			vring_enable_interrupts(vq);
			mb();

			if (vq->last_seen_used != le16_to_cpu(vring->used.idx))
				break;
		}

		struct vring_used_elem *e = vring.used->ring[vq->last_seen_used%vsz];
		process_buffer(e);
		vq->last_seen_used++;
	}
\end{lstlisting}

\subsection{Notification of Device Configuration Changes}\label{sec:General Initialization And Device Operation / Device Operation / Notification of Device Configuration Changes}

For devices where the configuration information can be changed, an
interrupt is delivered when a configuration change occurs.



\chapter{Virtio Transport Options}\label{sec:Virtio Transport Options}

Virtio can use various different busses, thus the standard is split
into virtio general and bus-specific sections.

\section{Virtio Over PCI Bus}\label{sec:Virtio Transport Options / Virtio Over PCI Bus}

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
}.

The Subsystem Device ID indicates which virtio device is
supported by the device. The Subsystem Vendor ID SHOULD reflect
the PCI Vendor ID of the environment (it's currently only used
for informational purposes by the driver).

All drivers MUST match devices with any Revision ID, this
is to allow devices to be versioned without breaking drivers.

\subsubsection{Legacy Interfaces: A Note on PCI Device Discovery}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Discovery / Legacy Interfaces: A Note on PCI Device Discovery}
Transitional devices must have a Revision ID of 0 to match
legacy drivers.

Non-transitional devices must have a Revision ID of 1 or higher.

Both transitional and non-transitional drivers must match
any Revision ID value.

\subsection{PCI Device Layout}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout}

To configure the device,
use I/O and/or memory regions and/or PCI configuration space of the PCI device.
These contain the virtio header registers, the notification register, the
ISR status register and device specific registers, as specified by Virtio
Structure PCI Capabilities.

There may be different widths of accesses to the I/O region; the
“natural” access method for each field must be
used (i.e. 32-bit accesses for 32-bit fields, etc).

PCI Device Configuration Layout includes the common configuration,
ISR, notification and device specific configuration
structures.

All multi-byte fields are little-endian.

\subsubsection{Common configuration structure layout}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Common configuration structure layout}
Common configuration structure layout is documented below:

\begin{lstlisting}
	struct virtio_pci_common_cfg {
		/* About the whole device. */
		le32 device_feature_select;	/* read-write */
		le32 device_feature;		/* read-only */
		le32 driver_feature_select;	/* read-write */
		le32 driver_feature;		/* read-write */
		le16 msix_config;		/* read-write */
		le16 num_queues;		/* read-only */
		u8 device_status;		/* read-write */
		u8 config_generation;		/* read-only */

		/* About a specific virtqueue. */
		le16 queue_select;		/* read-write */
		le16 queue_size;		/* read-write, power of 2, or 0. */
		le16 queue_msix_vector;		/* read-write */
		le16 queue_enable;		/* read-write */
		le16 queue_notify_off;		/* read-only */
		le64 queue_desc;		/* read-write */
		le64 queue_avail;		/* read-write */
		le64 queue_used;		/* read-write */
	};
\end{lstlisting}

\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.

\item[device_feature]
        The device uses this to report Feature Bits to the driver.
        Device Feature Bits selected by device_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
        When set to any other value, reads from driver_feature
        return 0, writing 0 into driver_feature has no effect.  The driver
        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).

\item[driver_feature]
        The driver writes this to accept feature bits offered by the device.
        Driver Feature Bits selected by driver_feature_select.

\item[msix_config]
        The driver sets the Configuration Vector for MSI-X.

\item[num_queues]
        The device specifies the maximum number of virtqueues supported here.

\item[device_status]
        The driver writes the Device Status here. Writing 0 into this
        field resets the device.

\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.

\item[queue_select]
        Queue Select. The driver selects which virtqueue the following
        fields refer to.

\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.

\item[queue_msix_vector]
        The driver uses this to specify the Queue Vector for MSI-X.

\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.

\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.

\item[queue_desc]
        The driver writes the physical address of Descriptor Table here.

\item[queue_avail]
        The driver writes the physical address of Available Ring here.

\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.

\subsubsection{Notification structure layout}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Notification structure layout}
Notification structure is always a multiple of 2 bytes in size.
It includes 2-byte Queue Notify fields for each virtqueue of
the device. Note that multiple virtqueues can use the same
Queue Notify field, if necessary: see notify_off_multiplier below.

\subsubsection{Device specific structure}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Device specific structure}

Device specific structure is optional.

\subsubsection{Legacy Interfaces: A Note on PCI Device Layout}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Legacy Interfaces: A Note on PCI Device Layout}

Transitional devices should present part of configuration
registers in a legacy configuration structure in BAR0 in the first I/O
region of the PCI device, as documented below.

There may be different widths of accesses to the I/O region; the
“natural” access method for each field in the virtio header must be
used (i.e. 32-bit accesses for 32-bit fields, etc), but 
when accessed through the legacy interface the
device-specific region can be accessed using any width accesses, and
should obtain the same results.

Note that this is possible because while the virtio header is PCI
(i.e. little) endian, when using the legacy interface the device-specific
region is encoded in the native endian of the guest (where such distinction is
applicable).

When used through the legacy interface, the virtio header looks as follows:

\begin{tabularx}{\textwidth}{ |X||X|X|X|X|X|X|X|X| }
\hline
 Bits & 32 & 32 & 32 & 16 & 16 & 16 & 8 & 8 \\
\hline
 Read / Write & R & R+W & R+W & R & R+W & R+W & R+W & R \\
\hline
 Purpose & Device Features bits 0:31 & Driver Features bits 0:31 &
  Queue Size & Queue Select & Queue Notify & Queue Address &
  Device Status & ISR \newline Status \\
\hline
\end{tabularx}

If MSI-X is enabled for the device, two additional fields
immediately follow this header:

\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
enabled, device specific configuration starts at byte offset 20 in virtio
header.  ie. once you enable MSI-X on the device, the other fields move.
If you turn it off again, they move back!

Immediately following these general headers, there may be
device-specific headers:

\begin{tabular}{|l||l|l|}
\hline
Bits & Device Specific & \multirow{3}{*}{...} \\
\cline{1-2}
Read / Write & Device Specific & \\
\cline{1-2}
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,
Transitional Devices must assume that Feature Bits 32 to 63
are not acknowledged by Driver.

As legacy devices had no configuration generation field,
see \ref{sec:Basic Facilities of a Virtio Device / Configuration Space / Legacy Interface: Configuration Space}~\nameref{sec:Basic Facilities of a Virtio Device / Configuration Space / Legacy Interface: Configuration Space} for workarounds.

\subsection{PCI-specific Initialization And Device Operation}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation}

\subsubsection{Device Initialization}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Device Initialization}

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
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}

As a prerequisite to device initialization, driver executes a
PCI capability list scan, detecting virtio configuration layout using Virtio
Structure PCI capabilities.

Virtio Device Configuration Layout includes virtio configuration header, Notification
and ISR Status and device configuration structures.