renesas/periject.git - Renesas periject clone

diff options

Diffstat (limited to 'wiki/M3N_Salvator-XS/M3N_Salvator-X-v410.tar.bz2')

0 files changed, 0 insertions, 0 deletions

\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: \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[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. \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. \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 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} \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 / Feature bits / 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 + 4 * $(Queue Size) \\ \hline \end{tabular} The Alignment column gives the minimum alignment for each part of the virtqueue. The Size column gives the total number of bytes for each part of the virtqueue. Queue Size corresponds to the maximum number of buffers in the virtqueue\footnote{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. \drivernormative{\subsection}{Virtqueues}{Basic Facilities of a Virtio Device / Virtqueues} The driver MUST ensure that the physical address of the first byte of each virtqueue part is a multiple of the specified alignment value in the above table. \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 for the virtqueue. When using the legacy interface, the transitional driver MUST retrieve the Queue Size field from the device and MUST allocate the total number of bytes for the virtuqueue according to the following formula: \begin{lstlisting} #define ALIGN(x) (((x) + PAGE_SIZE) & ~PAGE_SIZE) static inline unsigned virtq_size(unsigned int qsz) { return ALIGN(sizeof(struct virtq_desc)*qsz + sizeof(u16)*(3 + qsz)) + ALIGN(sizeof(u16)*3 + sizeof(struct virtq_used_elem)*qsz); } \end{lstlisting} This wastes some space with padding. When using the legacy interface, both transitional devices and drivers MUST use the following virtqueue layout structure to locate elements of the virtqueue: \begin{lstlisting} struct virtq { // The actual descriptors (16 bytes each) struct virtq_desc desc[ Queue Size ]; // A ring of available descriptor heads with free-running index. struct virtq_avail avail; // Padding to the next PAGE_SIZE boundary. u8 pad[ Padding ]; // A ring of used descriptor heads with free-running index. struct virtq_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 when using the legacy interface, transitional devices and drivers MUST use the native endian of the guest as the endian of fields and in the virtqueue. This is opposed to little-endian for non-legacy interface 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 framing of messages with descriptors 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 device implementations 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! \devicenormative{\subsubsection}{Message Framing}{Basic Facilities of a Virtio Device / Message Framing} The device MUST NOT make assumptions about the particular arrangement of descriptors. The device MAY have a reasonable limit of descriptors it will allow in a chain. \drivernormative{\subsubsection}{Message Framing}{Basic Facilities of a Virtio Device / Message Framing} The driver MUST place any device-writable descriptor elements after any device-readable descriptor elements. The driver SHOULD NOT use an excessive number of descriptors to describe a buffer. \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}) Thus when using the legacy interface, the VIRTIO_F_ANY_LAYOUT feature indicates to both the device and the driver that no assumptions were made about framing. Requirements for transitional drivers when this is not negotiated are included in each device section. \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. \field{addr} is a physical address, and the buffers can be chained via \field{next}. Each descriptor describes a buffer which is read-only for the device (``device-readable'') or write-only for the device (``device-writable''), but a chain of descriptors can contain both device-readable and device-writable 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. \begin{lstlisting} struct virtq_desc { /* Address (guest-physical). */ le64 addr; /* Length. */ le32 len; /* This marks a buffer as continuing via the next field. */ #define VIRTQ_DESC_F_NEXT 1 /* This marks a buffer as device write-only (otherwise device read-only). */ #define VIRTQ_DESC_F_WRITE 2 /* This means the buffer contains a list of buffer descriptors. */ #define VIRTQ_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: this is the maximum possible descriptor chain length. \begin{note} The legacy \hyperref[intro:Virtio PCI Draft]{[Virtio PCI Draft]} referred to this structure as vring_desc, and the constants as VRING_DESC_F_NEXT, etc, but the layout and values were identical. \end{note} \devicenormative{\subsubsection}{The Virtqueue Descriptor Table}{Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table} A device MUST NOT write to a device-readable buffer, and a device SHOULD NOT read a device-writable buffer (it MAY do so for debugging or diagnostic purposes). \drivernormative{\subsubsection}{The Virtqueue Descriptor Table}{Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table} 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! \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_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 \field{flags}\&VIRTQ_DESC_F_INDIRECT on) that refers to memory buffer containing this indirect descriptor table; \field{addr} and \field{len} refer to the indirect table address and length in bytes, respectively. The indirect table layout structure looks like this (\field{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 virtq_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 \field{next}. An indirect descriptor without a valid \field{next} (with \field{flags}\&VIRTQ_DESC_F_NEXT off) signals the end of the descriptor. A single indirect descriptor table can include both device-readable and device-writable descriptors. \drivernormative{\paragraph}{Indirect Descriptors}{Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table / Indirect Descriptors} The driver MUST NOT set the VIRTQ_DESC_F_INDIRECT flag unless the VIRTIO_F_INDIRECT_DESC feature was negotiated. The driver MUST NOT set the VIRTQ_DESC_F_INDIRECT flag within an indirect descriptor (ie. only one table per descriptor). A driver MUST NOT create a descriptor chain longer than the Queue Size of the device. \devicenormative{\paragraph}{Indirect Descriptors}{Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table / Indirect Descriptors} The device MUST ignore the write-only flag (\field{flags}\&VIRTQ_DESC_F_WRITE) in the descriptor that refers to an indirect table. \subsection{The Virtqueue Available Ring}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Available Ring} \begin{lstlisting} struct virtq_avail { #define VIRTQ_AVAIL_F_NO_INTERRUPT 1 le16 flags; le16 idx; le16 ring[ /* Queue Size */ ]; le16 used_event; /* Only if VIRTIO_F_EVENT_IDX */ }; \end{lstlisting} The driver uses the available ring to offer buffers to 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. \field{idx} field indicates where the driver would put the next descriptor entry in the ring (modulo the queue size). This starts at 0, and increases. \begin{note} The legacy \hyperref[intro:Virtio PCI Draft]{[Virtio PCI Draft]} referred to this structure as vring_avail, and the constant as VRING_AVAIL_F_NO_INTERRUPT, but the layout and value were identical. \end{note} \subsection{Virtqueue Interrupt Suppression}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Interrupt Suppression} If the VIRTIO_F_EVENT_IDX feature bit is not negotiated, the \field{flags} field in the available ring offers a crude mechanism for the driver to inform the device that it doesn't want interrupts when buffers are used. Otherwise \field{used_event} is a more performant alterative where the driver specifies how far the device can progress before interrupting. Neither of these interrupt suppression methods are reliable, as they are not synchronized with the device, but they serve as useful optimizations. \drivernormative{\subsubsection}{Virtqueue Interrupt Suppression}{Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Interrupt Suppression} If the VIRTIO_F_EVENT_IDX feature bit is not negotiated: \begin{itemize} \item The driver MUST set \field{flags} to 0 or 1. \item The driver MAY set \field{flags} to 1 to advise the device that interrupts are not needed. \end{itemize} Otherwise, if the VIRTIO_F_EVENT_IDX feature bit is negotiated: \begin{itemize} \item The driver MUST set \field{flags} to 0. \item The driver MAY use \field{used_event} to advise the device that interrupts are unnecessary until the device writes entry with an index specified by \field{used_event} into the used ring (equivalently, until \field{idx} in the used ring will reach the value \field{used_event} + 1). \end{itemize} The driver MUST handle spurious interrupts from the device. \devicenormative{\subsubsection}{Virtqueue Interrupt Suppression}{Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Interrupt Suppression} If the VIRTIO_F_EVENT_IDX feature bit is not negotiated: \begin{itemize} \item The device MUST ignore the \field{used_event} value. \item After the device writes a descriptor index into the used ring: \begin{itemize} \item If \field{flags} is 1, the device SHOULD NOT send an interrupt. \item If \field{flags} is 0, the device MUST send an interrupt. \end{itemize} \end{itemize} Otherwise, if the VIRTIO_F_EVENT_IDX feature bit is negotiated: \begin{itemize} \item The device MUST ignore the lower bit of \field{flags}. \item After the device writes a descriptor index into the used ring: \begin{itemize} \item If the \field{idx} field in the used ring (which determined where that descriptor index was placed) was equal to \field{used_event}, the device MUST send an interrupt. \item Otherwise the device SHOULD NOT send an interrupt. \end{itemize} \end{itemize} \begin{note} For example, if \field{used_event} is 0, then a device using VIRTIO_F_EVENT_IDX would interrupt after the first buffer is used (and again after the 65536th buffer, etc). \end{note} \subsection{The Virtqueue Used Ring}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Used Ring} \begin{lstlisting} struct virtq_used { #define VIRTQ_USED_F_NO_NOTIFY 1 le16 flags; le16 idx; struct virtq_used_elem ring[ /* Queue Size */]; le16 avail_event; /* Only if VIRTIO_F_EVENT_IDX */ }; /* le32 is used here for ids for padding reasons. */ struct virtq_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: \field{id} indicates the head entry of the descriptor chain describing the buffer (this matches an entry placed in the available ring by the guest earlier), and \field{len} 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. \begin{note} The legacy \hyperref[intro:Virtio PCI Draft]{[Virtio PCI Draft]} referred to these structures as vring_used and vring_used_elem, and the constant as VRING_USED_F_NO_NOTIFY, but the layout and value were identical. \end{note} \subsection{Virtqueue Notification Suppression}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Notification Suppression} The device can suppress notifications in a manner analogous to the way drivers can suppress interrupts as detailed in section \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Interrupt Suppression}. The device manipulates \field{flags} or \field{avail_event} in the used ring the same way the driver manipulates \field{flags} or \field{used_event} in the available ring. \drivernormative{\subsubsection}{Virtqueue Notification Suppression}{Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Notification Suppression} The driver MUST initialize \field{flags} in the used ring to 0 when allocating the used ring. If the VIRTIO_F_EVENT_IDX feature bit is not negotiated: \begin{itemize} \item The driver MUST ignore the \field{avail_event} value. \item After the driver writes a descriptor index into the available ring: \begin{itemize} \item If \field{flags} is 1, the driver SHOULD NOT send a notification. \item If \field{flags} is 0, the driver MUST send a notification. \end{itemize} \end{itemize} Otherwise, if the VIRTIO_F_EVENT_IDX feature bit is negotiated: \begin{itemize} \item The driver MUST ignore the lower bit of \field{flags}. \item After the driver writes a descriptor index into the available ring: \begin{itemize} \item If the \field{idx} field in the available ring (which determined where that descriptor index was placed) was equal to \field{avail_event}, the driver MUST send a notification. \item Otherwise the driver SHOULD NOT send a notification. \end{itemize} \end{itemize} \devicenormative{\subsubsection}{Virtqueue Notification Suppression}{Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Notification Suppression} If the VIRTIO_F_EVENT_IDX feature bit is not negotiated: \begin{itemize} \item The device MUST set \field{flags} to 0 or 1. \item The device MAY set \field{flags} to 1 to advise the driver that notifications are not needed. \end{itemize} Otherwise, if the VIRTIO_F_EVENT_IDX feature bit is negotiated: \begin{itemize} \item The device MUST set \field{flags} to 0. \item The device MAY use \field{avail_event} to advise the driver that notifications are unnecessary until the driver writes entry with an index specified by \field{avail_event} into the available ring (equivalently, until \field{idx} in the available ring will reach the value \field{avail_event} + 1). \end{itemize} The device MUST handle spurious notifications from the driver. \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/uapi/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 is best 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} \drivernormative{\subsection}{Device Initialization}{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: the guest OS has notice the device. \item Set the DRIVER status bit: the guest OS knows how to drive the device. \item\label{itm:General Initialization And Device Operation / Device Initialization / Read feature bits} Read device feature bits, and write the subset of feature bits understood by the OS and driver to the device. During this step the driver MAY read (but MUST NOT write) the device-specific configuration fields to check that it can support the device before accepting it. \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 \field{device status} 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 driver MUST NOT notify the device before setting DRIVER_OK. \subsection{Legacy Interface: Device Initialization}\label{sec:General Initialization And Device Operation / Device Initialization / Legacy Interface: Device Initialization} Legacy devices did not support the FEATURES_OK status bit, and thus did not have a graceful way for the device to indicate unsupported feature combinations. They 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 driver implementations often used the device before setting the DRIVER_OK bit, and sometimes even before writing the feature bits to the device. 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 / Read feature bits}, \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. Therefore, when using the legacy interface: \begin{itemize} \item The transitional driver MUST execute the initialization sequence as described in \ref{sec:General Initialization And Device Operation / Device Initialization} but omitting 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}. \item The transitional device MUST support the driver writing device configuration fields before the step \ref{itm:General Initialization And Device Operation / Device Initialization / Read feature bits}. \item The transitional device MUST support the driver using the device before the step \ref{itm:General Initialization And Device Operation / Device Initialization / Set DRIVER-OK}. \end{itemize} \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. \begin{note} As an example, the simplest virtio network device has two virtqueues: the transmit virtqueue and the receive virtqueue. The driver adds outgoing (device-readable) packets to the transmit virtqueue, and then frees them after they are used. Similarly, incoming (device-writable) buffers are added to the receive virtqueue, and processed after they are used. \end{note} \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 performs suitable a memory barrier to ensure the device sees the updated descriptor table and available ring before the next step. \item The available \field{idx} is increased by the number of descriptor chain heads added to the available ring. \item The driver performs a suitable memory barrier to ensure that it updates the \field{idx} field before checking for notification suppression. \item If notifications are not suppressed, the driver notifies 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 (the highest power of 2 which fits in 16 bits), so the 16-bit \field{idx} value can always distinguish between a full and empty buffer. What follows is the requirements 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 device-readable physically-contiguous elements followed by zero or more physically-contiguous device-writable elements (each has 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 \field{d.addr} to the physical address of the start of b \item Set \field{d.len} to the length of b. \item If b is device-writable, set \field{d.flags} to VIRTQ_DESC_F_WRITE, otherwise 0. \item If there is a buffer element after this: \begin{enumerate} \item Set \field{d.next} to the index of the next free descriptor element. \item Set the VIRTQ_DESC_F_NEXT bit in \field{d.flags}. \end{enumerate} \end{enumerate} In practice, \field{d.next} is 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 descriptor chain head is the first d in the algorithm above, ie. the index of the descriptor table entry referring to the first part of the buffer. A naive driver implementation MAY 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 the driver MAY add many descriptor chains before it updates \field{idx} (at which point they become visible to the device), so it is common to keep a counter of how many the driver has added: \begin{lstlisting} avail->ring[(avail->idx + added++) % qsz] = head; \end{lstlisting} \subsubsection{Updating \field{idx}}\label{sec:General Initialization And Device Operation / Device Operation / Supplying Buffers to The Device / Updating idx} \field{idx} always increments, and wraps naturally at 65536: \begin{lstlisting} avail->idx += added; \end{lstlisting} Once available \field{idx} is updated by the driver, this exposes the descriptor and its contents. The device MAY access the descriptor chains the driver created and the memory they refer to immediately. \drivernormative{\paragraph}{Updating idx}{General Initialization And Device Operation / Device Operation / Supplying Buffers to The Device / Updating idx} The driver MUST perform a suitable memory barrier before the \field{idx} update, to ensure the device sees the most up-to-date copy. \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 MAY suppress such notifications if it doesn't need them, as detailed in section \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Notification Suppression}. The driver has to be careful to expose the new \field{idx} value before checking if notifications are suppressed. \drivernormative{\paragraph}{Notifying The Device}{General Initialization And Device Operation / Device Operation / Supplying Buffers to The Device / Notifying The Device} The driver MUST perform a suitable memory barrier before reading \field{flags} or \field{avail_event}, to avoid missing a notification. \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 buffers referred to by a descriptor (read from or written to them, or parts of both, depending on the nature of the virtqueue and the device), it interrupts the driver as detailed in section \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Interrupt Suppression}. \begin{note} For optimal performance, a driver MAY disable interrupts while processing the used ring, but beware the problem of missing interrupts between emptying the ring and reenabling interrupts. This is usually handled by re-checking for more used buffers after interrups are re-enabled: \begin{lstlisting} virtq_disable_interrupts(vq); for (;;) { if (vq->last_seen_used != le16_to_cpu(virtq->used.idx)) { virtq_enable_interrupts(vq); mb(); if (vq->last_seen_used != le16_to_cpu(virtq->used.idx)) break; virtq_disable_interrupts(vq); } struct virtq_used_elem *e = virtq.used->ring[vq->last_seen_used%vsz]; process_buffer(e); vq->last_seen_used++; } \end{lstlisting} \end{note} \subsection{Notification of Device Configuration Changes}\label{sec:General Initialization And Device Operation / Device Operation / Notification of Device Configuration Changes} For devices where the device-specific configuration information can be changed, an interrupt is delivered when a device-specific configuration change occurs. In addition, this interrupt is triggered by the device setting DEVICE_NEEDS_RESET (see \ref{sec:Basic Facilities of a Virtio Device / Device Status Field / DEVICENEEDSRESET}). \section{Device Cleanup}\label{sec:General Initialization And Device Operation / Device Cleanup} Once the driver has set the DRIVER_OK status bit, all the configured virtqueue of the device are considered live. None of the virtqueues of a device are live once the device has been reset. \drivernormative{\subsection}{Device Cleanup}{General Initialization And Device Operation / Device Cleanup} A driver MUST NOT alter descriptor table entries which have been exposed in the available ring (and not marked consumed by the device in the used ring) of a live virtqueue. A driver MUST NOT decrement the available \field{idx} on a live virtqueue (ie. there is no way to ``unexpose'' buffers). Thus a driver MUST ensure a virtqueue isn't live (by device reset) before removing exposed buffers. \chapter{Virtio Transport Options}\label{sec:Virtio Transport Options} Virtio can use various different buses, 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. A Virtio device can be implemented as any kind of PCI device: a Conventional PCI device or a PCI Express device. To assure designs meet the latest level requirements, see the PCI-SIG home page at \url{http://www.pcisig.com} for any approved changes. \devicenormative{\subsection}{Virtio Over PCI Bus}{Virtio Transport Options / Virtio Over PCI Bus} A Virtio device using Virtio Over PCI Bus MUST expose to guest an interface that meets the specification requirements of the appropriate PCI specification: \hyperref[intro:PCI]{[PCI]} and \hyperref[intro:PCIe]{[PCIe]} respectively. \subsection{PCI Device Discovery}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Discovery} Any PCI device with PCI Vendor ID 0x1AF4, and PCI Device ID 0x1000 through 0x107F inclusive is a virtio device. The actual value within this range indicates which virtio device is supported by the device. The PCI Device ID is calculated by adding 0x1040 to the Virtio Device ID, as indicated in section \ref{sec:Device Types}. Additionally, devices MAY utilize a Transitional PCI Device ID range, 0x1000 to 0x103F depending on the device type. \devicenormative{\subsubsection}{PCI Device Discovery}{Virtio Transport Options / Virtio Over PCI Bus / PCI Device Discovery} Devices MUST have the PCI Vendor ID 0x1AF4. Devices MUST either have the PCI Device ID calculated by adding 0x1040 to the Virtio Device ID, as indicated in section \ref{sec:Device Types} or have the Transitional PCI Device ID depending on the device type, as follows: \begin{tabular}{|l|c|} \hline Transitional PCI Device ID & Virtio Device \\ \hline \hline 0x1000 & network card \\ \hline 0x1001 & block device \\ \hline 0x1002 & memory ballooning (legacy) \\ \hline 0x1003 & console \\ \hline 0x1004 & SCSI host \\ \hline 0x1005 & entropy source \\ \hline 0x1009 & 9P transport \\ \hline \end{tabular} For example, the network card device with the Virtio Device ID 1 has the PCI Device ID 0x1041 or the Transitional PCI Device ID 0x1000. The PCI Subsystem Vendor ID and the PCI Subsystem Device ID MAY reflect the PCI Vendor and Device ID of the environment (for informational purposes by the driver). Non-transitional devices SHOULD have a PCI Device ID in the range 0x1040 to 0x107f. Non-transitional devices SHOULD have a PCI Revision ID of 1 or higher. Non-transitional devices SHOULD have a PCI Subsystem Device ID of 0x40 or higher. This is to reduce the chance of a legacy driver attempting to drive the device. \drivernormative{\subsubsection}{PCI Device Discovery}{Virtio Transport Options / Virtio Over PCI Bus / PCI Device Discovery} Drivers MUST match devices with the PCI Vendor ID 0x1AF4 and the PCI Device ID in the range 0x1040 to 0x107f, calculated by adding 0x1040 to the Virtio Device ID, as indicated in section \ref{sec:Device Types}. Drivers for device types listed in section \ref{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Discovery} MUST match devices with the PCI Vendor ID 0x1AF4 and the Transitional PCI Device ID indicated in section \ref{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Discovery}. Drivers MUST match any PCI Revision ID value. Drivers MAY match any PCI Subsystem Vendor ID and any PCI Subsystem Device ID value. \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 PCI Revision ID of 0. Transitional devices MUST have the PCI Subsystem Device ID matching the Virtio Device ID, as indicated in section \ref{sec:Device Types}. Transitional devices MUST have the Transitional PCI Device ID in the range 0x1000 to 0x103f. This is to match legacy drivers. \subsection{PCI Device Layout}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout} The device is configured via I/O and/or memory regions (though see \ref{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / PCI configuration access capability} for access via the PCI configuration space), as specified by Virtio Structure PCI Capabilities. Fields of different sizes are present in the device configuration regions. All 32-bit and 16-bit fields are little-endian. \drivernormative{\subsubsection}{PCI Device Layout}{Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout} The driver MUST access each field using the ``natural'' access method, i.e. 32-bit accesses for 32-bit fields, 16-bit accesses for 16-bit fields and 8-bit accesses for 8-bit fields. \subsection{Virtio Structure PCI Capabilities}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / Virtio Structure PCI Capabilities} The virtio device configuration layout includes several structures: \begin{itemize} \item Common configuration \item Notifications \item ISR Status \item Device-specific configuration (optional) \end{itemize} Each structure can be mapped by a Base Address register (BAR) belonging to the function, or accessed via the special VIRTIO_PCI_CAP_PCI_CFG field in the PCI configuration space. The location of each structure is specified using a vendor-specific PCI capability located on the capability list in PCI configuration space of the device. This virtio structure capability uses little-endian format; all fields are read-only for the driver unless stated otherwise: \begin{lstlisting} struct virtio_pci_cap { u8 cap_vndr; /* Generic PCI field: PCI_CAP_ID_VNDR */ u8 cap_next; /* Generic PCI field: next ptr. */ u8 cap_len; /* Generic PCI field: capability length */ u8 cfg_type; /* Identifies the structure. */ u8 bar; /* Where to find it. */ u8 padding[3]; /* Pad to full dword. */ le32 offset; /* Offset within bar. */ le32 length; /* Length of the structure, in bytes. */ }; \end{lstlisting} This structure can be followed by extra data, depending on \field{cfg_type}, as documented below. The fields are interpreted as follows: \begin{description} \item[\field{cap_vndr}] 0x09; Identifies a vendor-specific capability. \item[\field{cap_next}] Link to next capability in the capability list in the PCI configuration space. \item[\field{cap_len}] Length of this capability structure, including the whole of struct virtio_pci_cap, and extra data if any. This length MAY include padding, or fields unused by the driver. \item[\field{cfg_type}] identifies the structure, according to the following table: \begin{lstlisting} /* Common configuration */ #define VIRTIO_PCI_CAP_COMMON_CFG 1 /* Notifications */ #define VIRTIO_PCI_CAP_NOTIFY_CFG 2 /* ISR Status */ #define VIRTIO_PCI_CAP_ISR_CFG 3 /* Device specific configuration */ #define VIRTIO_PCI_CAP_DEVICE_CFG 4 /* PCI configuration access */ #define VIRTIO_PCI_CAP_PCI_CFG 5 \end{lstlisting} Any other value is reserved for future use. Each structure is detailed individually below. The device MAY offer more than one structure of any type - this makes it possible for the device to expose multiple interfaces to drivers. The order of the capabilities in the capability list specifies the order of preference suggested by the device. \begin{note} For example, on some hypervisors, notifications using IO accesses are faster than memory accesses. In this case, the device would expose two capabilities with \field{cfg_type} set to VIRTIO_PCI_CAP_NOTIFY_CFG: the first one addressing an I/O BAR, the second one addressing a memory BAR. In this example, the driver would use the I/O BAR if I/O resources are available, and fall back on memory BAR when I/O resources are unavailable. \end{note} \item[\field{bar}] values 0x0 to 0x5 specify a Base Address register (BAR) belonging to the function located beginning at 10h in PCI Configuration Space and used to map the structure into Memory or I/O Space. The BAR is permitted to be either 32-bit or 64-bit, it can map Memory Space or I/O Space. Any other value is reserved for future use. \item[\field{offset}] indicates where the structure begins relative to the base address associated with the BAR. The alignment requirements of \field{offset} are indicated in each structure-specific section below. \item[\field{length}] indicates the length of the structure. \field{length} MAY include padding, or fields unused by the driver, or future extensions. \begin{note} For example, a future device might present a large structure size of several MBytes. As current devices never utilize structures larger than 4KBytes in size, driver MAY limit the mapped structure size to e.g. 4KBytes (thus ignoring parts of structure after the first 4KBytes) to allow forward compatibility with such devices without loss of functionality and without wasting resources. \end{note} \end{description} \drivernormative{\subsubsection}{Virtio Structure PCI Capabilities}{Virtio Transport Options / Virtio Over PCI Bus / Virtio Structure PCI Capabilities} The driver MUST ignore any vendor-specific capability structure which has a reserved \field{cfg_type} value. The driver SHOULD use the first instance of each virtio structure type they can support. The driver MUST accept a \field{cap_len} value which is larger than specified here. The driver MUST ignore any vendor-specific capability structure which has a reserved \field{bar} value. The drivers SHOULD only map part of configuration structure large enough for device operation. The drivers MUST handle an unexpectedly large \field{length}, but MAY check that \field{length} is large enough for device operation. The driver MUST NOT write into any field of the capability structure, with the exception of those with \field{cap_type} VIRTIO_PCI_CAP_PCI_CFG as detailed in \ref{drivernormative:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / PCI configuration access capability}. \devicenormative{\subsubsection}{Virtio Structure PCI Capabilities}{Virtio Transport Options / Virtio Over PCI Bus / Virtio Structure PCI Capabilities} The device MUST include any extra data (from the beginning of the \field{cap_vndr} field through end of the extra data fields if any) in \field{cap_len}. The device MAY append extra data or padding to any structure beyond that. If the device presents multiple structures of the same type, it SHOULD order them from optimal (first) to least-optimal (last). \subsubsection{Common configuration structure layout}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Common configuration structure layout} The common configuration structure is found at the \field{bar} and \field{offset} within the VIRTIO_PCI_CAP_COMMON_CFG capability; its layout is below. \begin{lstlisting} struct virtio_pci_common_cfg { /* About the whole device. */ le32 device_feature_select; /* read-write */ le32 device_feature; /* read-only for driver */ le32 driver_feature_select; /* read-write */ le32 driver_feature; /* read-write */ le16 msix_config; /* read-write */ le16 num_queues; /* read-only for driver */ u8 device_status; /* read-write */ u8 config_generation; /* read-only for driver */ /* 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 for driver */ le64 queue_desc; /* read-write */ le64 queue_avail; /* read-write */ le64 queue_used; /* read-write */ }; \end{lstlisting} \begin{description} \item[\field{device_feature_select}] The driver uses this to select which feature bits \field{device_feature} shows. Value 0x0 selects Feature Bits 0 to 31, 0x1 selects Feature Bits 32 to 63, etc. \item[\field{device_feature}] The device uses this to report which feature bits it is offering to the driver: the driver writes to \field{device_feature_select} to select which feature bits are presented. \item[\field{driver_feature_select}] The driver uses this to select which feature bits \field{driver_feature} shows. Value 0x0 selects Feature Bits 0 to 31, 0x1 selects Feature Bits 32 to 63, etc. \item[\field{driver_feature}] The driver writes this to accept feature bits offered by the device. Driver Feature Bits selected by \field{driver_feature_select}. \item[\field{config_msix_vector}] The driver sets the Configuration Vector for MSI-X. \item[\field{num_queues}] The device specifies the maximum number of virtqueues supported here. \item[\field{device_status}] The driver writes the device status here (see \ref{sec:Basic Facilities of a Virtio Device / Device Status Field}). Writing 0 into this field resets the device. \item[\field{config_generation}] Configuration atomicity value. The device changes this every time the configuration noticeably changes. \item[\field{queue_select}] Queue Select. The driver selects which virtqueue the following fields refer to. \item[\field{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. A 0 means the queue is unavailable. \item[\field{queue_msix_vector}] The driver uses this to specify the queue vector for MSI-X. \item[\field{queue_enable}] The driver uses this to selectively prevent the device from executing requests from this virtqueue. 1 - enabled; 0 - disabled. \item[\field{queue_notify_off}] The driver reads this to calculate the offset from start of Notification structure at which this virtqueue is located. \begin{note} this is \em{not} an offset in bytes. See \ref{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Notification capability} below. \end{note} \item[\field{queue_desc}] The driver writes the physical address of Descriptor Table here. See section \ref{sec:Basic Facilities of a Virtio Device / Virtqueues}. \item[\field{queue_avail}] The driver writes the physical address of Available Ring here. See section \ref{sec:Basic Facilities of a Virtio Device / Virtqueues}. \item[\field{queue_used}] The driver writes the physical address of Used Ring here. See section \ref{sec:Basic Facilities of a Virtio Device / Virtqueues}. \end{description} \devicenormative{\paragraph}{Common configuration structure layout}{Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Common configuration structure layout} \field{offset} MUST be 4-byte aligned. The device MUST present at least one common configuration capability. The device MUST present the feature bits it is offering in \field{device_feature}, starting at bit \field{device_feature_select} $*$ 32 for any \field{device_feature_select} written by the driver. \begin{note} This means that it will present 0 for any \field{device_feature_select} other than 0 or 1, since no feature defined here exceeds 63. \end{note} The device MUST present any valid feature bits the driver has written in \field{driver_feature}, starting at bit \field{driver_feature_select} $*$ 32 for any \field{driver_feature_select} written by the driver. Valid feature bits are those which are subset of the corresponding \field{device_feature} bits. The device MAY present invalid bits written by the driver. \begin{note} This means that a device can ignore writes for feature bits it never offers, and simply present 0 on reads. Or it can just mirror what the driver wrote (but it will still have to check them when the driver sets FEATURES_OK). \end{note} \begin{note} A driver shouldn't write invalid bits anyway, as per \ref{drivernormative:General Initialization And Device Operation / Device Initialization}, but this attempts to handle it. \end{note} The device MUST present a changed \field{config_generation} after the driver has read a device-specific configuration value which has changed since any part of the device-specific configuration was last read. \begin{note} As \field{config_generation} is an 8-bit value, simply incrementing it on every configuration change could violate this requirement due to wrap. Better would be to set an internal flag when it has changed, and if that flag is set when the driver reads from the device-specific configuration, increment \field{config_generation} and clear the flag. \end{note} The device MUST reset when 0 is written to \field{device_status}, and present a 0 in \field{device_status} once that is done. The device MUST present a 0 in \field{queue_enable} on reset. The device MUST present a 0 in \field{queue_size} if the virtqueue corresponding to the current \field{queue_select} is unavailable. \drivernormative{\paragraph}{Common configuration structure layout}{Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Common configuration structure layout} The driver MUST NOT write to \field{device_feature}, \field{num_queues}, \field{config_generation} or \field{queue_notify_off}. The driver MUST NOT write a value which is not a power of 2 to \field{queue_size}. The driver MUST configure the other virtqueue fields before enabling the virtqueue with \field{queue_enable}. After writing 0 to \field{device_status}, the driver MUST wait for a read of \field{device_status} to return 0 before reinitializing the device. The driver MUST NOT write a 0 to \field{queue_enable}. \subsubsection{Notification structure layout}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Notification capability} The notification location is found using the VIRTIO_PCI_CAP_NOTIFY_CFG capability. This capability is immediately followed by an additional field, like so: \begin{lstlisting} struct virtio_pci_notify_cap { struct virtio_pci_cap cap; le32 notify_off_multiplier; /* Multiplier for queue_notify_off. */ }; \end{lstlisting} \field{notify_off_multiplier} is combined with the \field{queue_notify_off} to derive the Queue Notify address within a BAR for a virtqueue: \begin{lstlisting} cap.offset + queue_notify_off * notify_off_multiplier \end{lstlisting} The \field{cap.offset} and \field{notify_off_multiplier} are taken from the notification capability structure above, and the \field{queue_notify_off} is taken from the common configuration structure. \begin{note} For example, if \field{notifier_off_multiplier} is 0, the device uses the same Queue Notify address for all queues. \end{note} \devicenormative{\paragraph}{Notification capability}{Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Notification capability} The device MUST present at least one notification capability. The \field{cap.offset} MUST be 2-byte aligned. The device MUST either present \field{notify_off_multiplier} as an even power of 2, or present \field{notify_off_multiplier} as 0. The value \field{cap.length} presented by the device MUST be at least 2 and MUST be large enough to support queue notification offsets for all supported queues in all possible configurations. For all queues, the value \field{cap.length} presented by the device MUST satisfy: \begin{lstlisting} cap.length >= queue_notify_off * notify_off_multiplier + 2 \end{lstlisting} \subsubsection{ISR status capability}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / ISR status capability} The VIRTIO_PCI_CAP_ISR_CFG capability refers to at least a single byte, which contains the 8-bit ISR status field to be used for INT\#x interrupt handling. The \field{offset} for the \field{ISR status} has no alignment requirements. The ISR bits allow the device to distinguish between device-specific configuration change interrupts and normal virtqueue interrupts: \begin{tabular}{ |l||l|l|l| } \hline Bits & 0 & 1 & 2 to 31 \\ \hline Purpose & Device Configuration Interrupt & Queue Interrupt & Reserved \\ \hline \end{tabular} To avoid an extra access, simply reading this register resets it to 0 and causes the device to de-assert the interrupt. In this way, driver read of ISR status causes the device to de-assert an interrupt. See sections \ref{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Virtqueue Interrupts From The Device} and \ref{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Notification of Device Configuration Changes} for how this is used. \devicenormative{\paragraph}{ISR status capability}{Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / ISR status capability} The device MUST present at least one VIRTIO_PCI_CAP_ISR_CFG capability. The device MUST set the Device Configuration Interrupt bit in \field{ISR status} before sending a device configuration change notification to the driver. If MSI-X capability is disabled, the device MUST set the Queue Interrupt bit in \field{ISR status} before sending a virtqueue notification to the driver. If MSI-X capability is disabled, the device MUST set the Interrupt Status bit in the PCI Status register in the PCI Configuration Header of the device to the logical OR of all bits in \field{ISR status} of the device. The device then asserts/deasserts INT\#x interrupts unless masked according to standard PCI rules \hyperref[intro:PCI]{[PCI]}. The device MUST reset \field{ISR status} to 0 on driver read. \drivernormative{\paragraph}{ISR status capability}{Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / ISR status capability} If MSI-X capability is enabled, the driver SHOULD NOT access \field{ISR status} upon detecting a Queue Interrupt. \subsubsection{Device-specific configuration}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Device-specific configuration} The device MUST present at least one VIRTIO_PCI_CAP_DEVICE_CFG capability for any device type which has a device-specific configuration. \devicenormative{\paragraph}{Device-specific configuration}{Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Device-specific configuration} The \field{offset} for the device-specific configuration MUST be 4-byte aligned. \subsubsection{PCI configuration access capability}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / PCI configuration access capability} The VIRTIO_PCI_CAP_PCI_CFG capability creates an alternative (and likely suboptimal) access method to the common configuration, notification, ISR and device-specific configuration regions. The capability is immediately followed by an additional field like so: \begin{lstlisting} struct virtio_pci_cfg_cap { struct virtio_pci_cap cap; u8 pci_cfg_data[4]; /* Data for BAR access. */ }; \end{lstlisting} The fields \field{cap.bar}, \field{cap.length}, \field{cap.offset} and \field{pci_cfg_data} are read-write (RW) for the driver. To access a device region, the driver writes into the capability structure (ie. within the PCI configuration space) as follows: \begin{itemize} \item The driver sets the BAR to access by writing to \field{cap.bar}. \item The driver sets the size of the access by writing 1, 2 or 4 to \field{cap.length}. \item The driver sets the offset within the BAR by writing to \field{cap.offset}. \end{itemize} At that point, \field{pci_cfg_data} will provide a window of size \field{cap.length} into the given \field{cap.bar} at offset \field{cap.offset}. \devicenormative{\paragraph}{PCI configuration access capability}{Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / PCI configuration access capability} The device MUST present at least one VIRTIO_PCI_CAP_PCI_CFG capability. Upon detecting driver write access to \field{pci_cfg_data}, the device MUST execute a write access at offset \field{cap.offset} at BAR selected by \field{cap.bar} using the first \field{cap.length} bytes from \field{pci_cfg_data}. Upon detecting driver read access to \field{pci_cfg_data}, the device MUST execute a read access of length cap.length at offset \field{cap.offset} at BAR selected by \field{cap.bar} and store the first \field{cap.length} bytes in \field{pci_cfg_data}. \drivernormative{\paragraph}{PCI configuration access capability}{Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / PCI configuration access capability} The driver MUST NOT write a \field{cap.offset} which is not a multiple of \field{cap.length} (ie. all accesses MUST be aligned). \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 MUST 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. When using the legacy interface, transitional drivers MUST use the legacy configuration structure in BAR0 in the first I/O region of the PCI device, as documented below. When using the legacy interface the driver MAY access the device-specific configuration region using any width accesses, and a transitional device MUST present driver with the same results as when accessed using the ``natural'' access method (i.e. 32-bit accesses for 32-bit fields, etc). Note that this is possible because while the virtio common configuration structure is PCI (i.e. little) endian, when using the legacy interface the device-specific configuration region is encoded in the native endian of the guest (where such distinction is applicable). When used through the legacy interface, the virtio common configuration structure 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 Address & \field{queue_size} & \field{queue_select} & Queue Notify & 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) & \field{config_msix_vector} & \field{queue_msix_vector} \\ \hline \end{tabular} Note: When MSI-X capability is enabled, device-specific configuration starts at byte offset 24 in virtio common configuration structure 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! Any device-specific configuration space immediately follows these general headers: \begin{tabular}{|l||l|l|} \hline Bits & Device Specific & \multirow{3}{*}{\ldots} \\ \cline{1-2} Read / Write & Device Specific & \\ \cline{1-2} Purpose & Device Specific & \\ \hline \end{tabular} When accessing the device-specific configuration space using the legacy interface, transitional drivers MUST access the device-specific configuration space at an offset immediately following the general headers. When using the legacy interface, transitional devices MUST present the device-specific configuration space if any at an offset immediately following the general headers. 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 \field{config_generation} field, see \ref{sec:Basic Facilities of a Virtio Device / Device Configuration Space / Legacy Interface: Device Configuration Space}~\nameref{sec:Basic Facilities of a Virtio Device / Device Configuration Space / Legacy Interface: Device Configuration Space} for workarounds. \subsubsection{Non-transitional Device With Legacy Driver: A Note on PCI Device Layout}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Non-transitional Device With Legacy Driver: A Note on PCI Device Layout} Non-transitional devices, on a platform where a legacy driver for a legacy device with the same ID might have previously existed, SHOULD take the following steps to fail gracefully when a legacy driver attempts to drive them: \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} \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. \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, the driver scans the PCI capability list, detecting virtio configuration layout using Virtio Structure PCI capabilities as detailed in \ref{sec:Virtio Transport Options / Virtio Over PCI Bus / Virtio Structure PCI Capabilities} \paragraph{Non-transitional Device With Legacy Driver}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Device Initialization / Non-transitional Device With Legacy Driver} \drivernormative{\subparagraph}{Non-transitional Device With Legacy Driver}{Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Device Initialization / Non-transitional Device With Legacy Driver} Non-transitional devices, on a platform where a legacy driver for 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: \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} \subparagraph{Legacy Interface: A Note on Device Layout Detection}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Device Initialization / Virtio Device Configuration Layout Detection / Legacy Interface: A Note on Device Layout Detection} Legacy drivers skipped the Device Layout Detection step, assuming legacy device configuration space in BAR0 in I/O space unconditionally. Legacy devices did not have the Virtio PCI Capability in their capability list. Therefore: Transitional devices MUST expose the Legacy Interface in I/O space in BAR0. Transitional drivers MUST look for the Virtio PCI Capabilities on the capability list. If these are not present, driver MUST assume a legacy device, and use it through the legacy interface. Non-transitional drivers MUST look for the Virtio PCI Capabilities on the capability list. If these are not present, driver MUST assume a legacy device, and fail gracefully. \paragraph{MSI-X Vector Configuration}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Device Initialization / MSI-X Vector Configuration} When MSI-X capability is present and enabled in the device (through standard PCI configuration space) \field{config_msix_vector} and \field{queue_msix_vector} are used to map configuration change and queue interrupts to MSI-X vectors. In this case, the ISR Status is unused. Writing a valid MSI-X Table entry number, 0 to 0x7FF, to \field{config_msix_vector}/\field{queue_msix_vector} maps interrupts triggered by the configuration change/selected queue events respectively to the corresponding MSI-X vector. To disable interrupts for an event type, the driver unmaps this event by writing a special NO_VECTOR value: \begin{lstlisting} /* Vector value used to disable MSI for queue */ #define VIRTIO_MSI_NO_VECTOR 0xffff \end{lstlisting} Note that mapping an event to vector might require device to allocate internal device resources, and thus could fail. \devicenormative{\subparagraph}{MSI-X Vector Configuration}{Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Device Initialization / MSI-X Vector Configuration} A device that has an MSI-X capability SHOULD support at least 2 and at most 0x800 MSI-X vectors. Device MUST report the number of vectors supported in \field{Table Size} in the MSI-X Capability as specified in \hyperref[intro:PCI]{[PCI]}. The device SHOULD restrict the reported MSI-X Table Size field to a value that might benefit system performance. \begin{note} For example, a device which does not expect to send interrupts at a high rate might only specify 2 MSI-X vectors. \end{note} Device MUST support mapping any event type to any valid vector 0 to MSI-X \field{Table Size}. Device MUST support unmapping any event type. The device MUST return vector mapped to a given event, (NO_VECTOR if unmapped) on read of \field{config_msix_vector}/\field{queue_msix_vector}. The device MUST have all queue and configuration change events are unmapped upon reset. Devices SHOULD NOT cause mapping an event to vector to fail unless it is impossible for the device to satisfy the mapping request. Devices MUST report mapping failures by returning the NO_VECTOR value when the relevant \field{config_msix_vector}/\field{queue_msix_vector} field is read. \drivernormative{\subparagraph}{MSI-X Vector Configuration}{Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Device Initialization / MSI-X Vector Configuration} Driver MUST support device with any MSI-X Table Size 0 to 0x7FF. Driver MAY fall back on using INT\#x interrupts for a device which only supports one MSI-X vector (MSI-X Table Size = 0). Driver MAY intepret the Table Size as a hint from the device for the suggested number of MSI-X vectors to use. Driver MUST NOT attempt to map an event to a vector outside the MSI-X Table supported by the device, as reported by \field{Table Size} in the MSI-X Capability. After mapping an event to vector, the driver MUST verify success by reading the Vector field value: on success, the previously written value is returned, and on failure, NO_VECTOR is returned. If a mapping failure is detected, the driver MAY retry mapping with fewer vectors, disable MSI-X or report device failure. \paragraph{Virtqueue Configuration}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Device Initialization / Virtqueue Configuration} As a device can have zero or more virtqueues for bulk data transport\footnote{For example, the simplest network device has two virtqueues.}, the driver needs to configure them as part of the device-specific configuration. The driver typically does this as follows, for each virtqueue a device has: \begin{enumerate} \item Write the virtqueue index (first queue is 0) to \field{queue_select}. \item Read the virtqueue size from \field{queue_size}. 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. \item Optionally, select a smaller virtqueue size and write it to \field{queue_size}. \item Allocate and zero Descriptor Table, Available and Used rings for the virtqueue in contiguous physical memory. \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 into \field{queue_msix_vector}. Read \field{queue_msix_vector}: 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 enough to ensure that the separate parts of the virtqueue are on separate cache lines. }. There was no mechanism to negotiate the queue size. \subsubsection{Notifying The Device}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Notifying The Device} The driver notifies the device by writing the 16-bit virtqueue index of this virtqueue to the Queue Notify address. See \ref{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Notification capability} for how to calculate this address. \subsubsection{Virtqueue Interrupts From The Device}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Virtqueue Interrupts From The Device} If an interrupt is necessary for a virtqueue, the device would typically act as follows: \begin{itemize} \item If MSI-X capability is disabled: \begin{enumerate} \item Set the lower bit of the ISR Status field for the device. \item Send the appropriate PCI interrupt for the device. \end{enumerate} \item If MSI-X capability is enabled: \begin{enumerate} \item If \field{queue_msix_vector} is not NO_VECTOR, request the appropriate MSI-X interrupt message for the device, \field{queue_msix_vector} sets the MSI-X Table entry number. \end{enumerate} \end{itemize} \devicenormative{\paragraph}{Virtqueue Interrupts From The Device}{Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Virtqueue Interrupts From The Device} If MSI-X capability is enabled and \field{queue_msix_vector} is NO_VECTOR for a virtqueue, the device MUST NOT deliver an interrupt for that virtqueue. \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} Some virtio PCI devices can change the device configuration state, as reflected in the device-specific configuration region of the device. In this case: \begin{itemize} \item If MSI-X capability is disabled: \begin{enumerate} \item Set the second lower bit of the ISR Status field for the device. \item Send the appropriate PCI interrupt for the device. \end{enumerate} \item If MSI-X capability is enabled: \begin{enumerate} \item If \field{config_msix_vector} is not NO_VECTOR, request the appropriate MSI-X interrupt message for the device, \field{config_msix_vector} sets the MSI-X Table entry number. \end{enumerate} \end{itemize} A single interrupt MAY indicate both that one or more virtqueue has been used and that the configuration space has changed. \devicenormative{\paragraph}{Notification of Device Configuration Changes}{Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Notification of Device Configuration Changes} If MSI-X capability is enabled and \field{config_msix_vector} is NO_VECTOR, the device MUST NOT deliver an interrupt for device configuration space changes. \drivernormative{\paragraph}{Notification of Device Configuration Changes}{Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Notification of Device Configuration Changes} A driver MUST handle the case where the same interrupt is used to indicate both device configuration space change and one or more virtqueues being used. \subsubsection{Driver Handling Interrupts}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Driver Handling Interrupts} The driver interrupt handler would typically: \begin{itemize} \item If MSI-X capability is disabled: \begin{itemize} \item Read the ISR Status field, which will reset it to zero. \item If the lower bit is set: look through the used rings of all virtqueues for the device, to see if any progress has been made by the device which requires servicing. \item If the second lower bit is set: re-examine the configuration space to see what changed. \end{itemize} \item If MSI-X capability is enabled: \begin{itemize} \item Look through the used rings of all virtqueues mapped to that MSI-X vector for the device, to see if any progress has been made by the device which requires servicing. \item If the MSI-X vector is equal to \field{config_msix_vector}, re-examine the configuration space to see what changed. \end{itemize} \end{itemize} \section{Virtio Over MMIO}\label{sec:Virtio Transport Options / Virtio Over MMIO} Virtual environments without PCI support (a common situation in embedded devices models) might use simple memory mapped device (``virtio-mmio'') instead of the PCI device. The memory mapped virtio device behaviour is based on the PCI device specification. Therefore most operations including device initialization, queues configuration and buffer transfers are nearly identical. Existing differences are described in the following sections. \subsection{MMIO Device Discovery}\label{sec:Virtio Transport Options / Virtio Over MMIO / MMIO Device Discovery} Unlike PCI, MMIO provides no generic device discovery mechanism. For each device, the guest OS will need to know the location of the registers and interrupt(s) used. The suggested binding for systems using flattened device trees is shown in this example: \begin{lstlisting} // EXAMPLE: virtio_block device taking 512 bytes at 0x1e000, interrupt 42. virtio_block@1e000 { compatible = "virtio,mmio"; reg = <0x1e000 0x200>; interrupts = <42>; } \end{lstlisting} \subsection{MMIO Device Register Layout}\label{sec:Virtio Transport Options / Virtio Over MMIO / MMIO Device Register Layout} MMIO virtio devices provide a set of memory mapped control registers followed by a device-specific configuration space, described in the table~\ref{tab:Virtio Trasport Options / Virtio Over MMIO / MMIO Device Register Layout}. All register values are organized as Little Endian. \newcommand{\mmioreg}[5]{% Name Function Offset Direction Description {\field{#1}} \newline #3 \newline #4 & {\bf#2} \newline #5 \\ } \newcommand{\mmiodreg}[7]{% NameHigh NameLow Function OffsetHigh OffsetLow Direction Description {\field{#1}} \newline #4 \newline {\field{#2}} \newline #5 \newline #6 & {\bf#3} \newline #7 \\ } \begin{longtable}{p{0.2\textwidth}p{0.7\textwidth}} \caption {MMIO Device Register Layout} \label{tab:Virtio Trasport Options / Virtio Over MMIO / MMIO Device Register Layout} \\ \hline \mmioreg{Name}{Function}{Offset from base}{Direction}{Description} \hline \hline \endfirsthead \hline \mmioreg{Name}{Function}{Offset from the base}{Direction}{Description} \hline \hline \endhead \endfoot \endlastfoot \mmioreg{MagicValue}{Magic value}{0x000}{R}{% 0x74726976 (a Little Endian equivalent of the ``virt'' string). } \hline \mmioreg{Version}{Device version number}{0x004}{R}{% 0x2. \begin{note} Legacy devices (see \ref{sec:Virtio Transport Options / Virtio Over MMIO / Legacy interface}~\nameref{sec:Virtio Transport Options / Virtio Over MMIO / Legacy interface}) used 0x1. \end{note} } \hline \mmioreg{DeviceID}{Virtio Subsystem Device ID}{0x008}{R}{% See \ref{sec:Device Types}~\nameref{sec:Device Types} for possible values. Value zero (0x0) is used to define a system memory map with placeholder devices at static, well known addresses, assigning functions to them depending on user's needs. } \hline \mmioreg{VendorID}{Virtio Subsystem Vendor ID}{0x00c}{R}{} \hline \mmioreg{DeviceFeatures}{Flags representing features the device supports}{0x010}{R}{% Reading from this register returns 32 consecutive flag bits, the least significant bit depending on the last value written to \field{DeviceFeaturesSel}. Access to this register returns bits $\field{DeviceFeaturesSel}*32$ to $(\field{DeviceFeaturesSel}*32)+31$, eg. feature bits 0 to 31 if \field{DeviceFeaturesSel} is set to 0 and features bits 32 to 63 if \field{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}. } \hline \mmioreg{DeviceFeaturesSel}{Device (host) features word selection.}{0x014}{W}{% Writing to this register selects a set of 32 device feature bits accessible by reading from \field{DeviceFeatures}. } \hline \mmioreg{DriverFeatures}{Flags representing device features understood and activated by the driver}{0x020}{W}{% Writing to this register sets 32 consecutive flag bits, the least significant bit depending on the last value written to \field{DriverFeaturesSel}. Access to this register sets bits $\field{DriverFeaturesSel}*32$ to $(\field{DriverFeaturesSel}*32)+31$, eg. feature bits 0 to 31 if \field{DriverFeaturesSel} is set to 0 and features bits 32 to 63 if \field{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}. } \hline \mmioreg{DriverFeaturesSel}{Activated (guest) features word selection}{0x024}{W}{% Writing to this register selects a set of 32 activated feature bits accessible by writing to \field{DriverFeatures}. } \hline \mmioreg{QueueSel}{Virtual queue index}{0x030}{W}{% Writing to this register selects the virtual queue that the following operations on \field{QueueNumMax}, \field{QueueNum}, \field{QueueReady}, \field{QueueDescLow}, \field{QueueDescHigh}, \field{QueueAvailLow}, \field{QueueAvailHigh}, \field{QueueUsedLow} and \field{QueueUsedHigh} apply to. The index number of the first queue is zero (0x0). } \hline \mmioreg{QueueNumMax}{Maximum virtual queue size}{0x034}{R}{% Reading from the register returns the maximum size (number of elements) of the queue the device is ready to process or zero (0x0) if the queue is not available. This applies to the queue selected by writing to \field{QueueSel}. } \hline \mmioreg{QueueNum}{Virtual queue size}{0x038}{W}{% Queue size is the number of elements in the queue, therefore in each of the Descriptor Table, the Available Ring and the Used Ring. Writing to this register notifies the device what size of the queue the driver will use. This applies to the queue selected by writing to \field{QueueSel}. } \hline \mmioreg{QueueReady}{Virtual queue ready bit}{0x044}{RW}{% Writing one (0x1) to this register notifies the device that it can execute requests from this virtual queue. Reading from this register returns the last value written to it. Both read and write accesses apply to the queue selected by writing to \field{QueueSel}. } \hline \mmioreg{QueueNotify}{Queue notifier}{0x050}{W}{% Writing a queue index to this register notifies the device that there are new buffers to process in the queue. } \hline \mmioreg{InterruptStatus}{Interrupt status}{0x60}{R}{% Reading from this register returns a bit mask of events that caused the device interrupt to be asserted. The following events are possible: \begin{description} \item[Used Ring Update] - bit 0 - the interrupt was asserted because the device has updated the Used Ring in at least one of the active virtual queues. \item [Configuration Change] - bit 1 - the interrupt was asserted because the configuration of the device has changed. \end{description} } \hline \mmioreg{InterruptACK}{Interrupt acknowledge}{0x064}{W}{% Writing a value with bits set as defined in \field{InterruptStatus} to this register notifies the device that events causing the interrupt have been handled. } \hline \mmioreg{Status}{Device status}{0x070}{RW}{% Reading from this register returns the current device status flags. Writing non-zero values to this register sets the status flags, indicating the driver progress. Writing zero (0x0) to this register triggers a device reset. 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}. } \hline \mmiodreg{QueueDescLow}{QueueDescHigh}{Virtual queue's Descriptor Table 64 bit long physical address}{0x080}{0x084}{W}{% Writing to these two registers (lower 32 bits of the address to \field{QueueDescLow}, higher 32 bits to \field{QueueDescHigh}) notifies the device about location of the Descriptor Table of the queue selected by writing to \field{QueueSel} register. } \hline \mmiodreg{QueueAvailLow}{QueueAvailHigh}{Virtual queue's Available Ring 64 bit long physical address}{0x090}{0x094}{W}{% Writing to these two registers (lower 32 bits of the address to \field{QueueAvailLow}, higher 32 bits to \field{QueueAvailHigh}) notifies the device about location of the Available Ring of the queue selected by writing to \field{QueueSel}. } \hline \mmiodreg{QueueUsedLow}{QueueUsedHigh}{Virtual queue's Used Ring 64 bit long physical address}{0x0a0}{0x0a4}{W}{% Writing to these two registers (lower 32 bits of the address to \field{QueueUsedLow}, higher 32 bits to \field{QueueUsedHigh}) notifies the device about location of the Used Ring of the queue selected by writing to \field{QueueSel}. } \hline \mmioreg{ConfigGeneration}{Configuration atomicity value}{0x0fc}{R}{ Reading from this register returns a value describing a version of the device-specific configuration space (see \field{Config}). The driver can then access the configuration space and, when finished, read \field{ConfigGeneration} again. If no part of the configuration space has changed between these two \field{ConfigGeneration} reads, the returned values are identical. If the values are different, the configuration space accesses were not atomic and the driver has to perform the operations again. See also \ref {sec:Basic Facilities of a Virtio Device / Device Configuration Space}. } \hline \mmioreg{Config}{Configuration space}{0x100+}{RW}{ Device-specific configuration space starts at the offset 0x100 and is accessed with byte alignment. Its meaning and size depend on the device and the driver. } \hline \end{longtable} \devicenormative{\subsubsection}{MMIO Device Register Layout}{Virtio Transport Options / Virtio Over MMIO / MMIO Device Register Layout} The device MUST return 0x74726976 in \field{MagicValue}. The device MUST return value 0x2 in \field{Version}. The device MUST present each event by setting the corresponding bit in \field{InterruptStatus} from the moment it takes place, until the driver acknowledges the interrupt by writing a corresponding bit mask to the \field{InterruptACK} register. Bits which do not represent events which took place MUST be zero. Upon reset, the device MUST clear all bits in \field{InterruptStatus} and ready bits in the \field{QueueReady} register for all queues in the device. The device MUST change value returned in \field{ConfigGeneration} if there is any risk of a driver seeing an inconsistent configuration state. The device MUST NOT access virtual queue contents when \field{QueueReady} is zero (0x0). \drivernormative{\subsubsection}{MMIO Device Register Layout}{Virtio Transport Options / Virtio Over MMIO / MMIO Device Register Layout} The driver MUST NOT access memory locations not described in the table \ref{tab:Virtio Trasport Options / Virtio Over MMIO / MMIO Device Register Layout} (or, in case of the configuration space, described in the device specification), MUST NOT write to the read-only registers (direction R) and MUST NOT read from the write-only registers (direction W). The driver MUST only use 32 bit wide and aligned reads and writes to access the control registers described in table \ref{tab:Virtio Trasport Options / Virtio Over MMIO / MMIO Device Register Layout}. For the device-specific configuration space, the driver MUST use 8 bit wide accesses for 8 bit wide fields, 16 bit wide and aligned accesses for 16 bit wide fields and 32 bit wide and aligned accesses for 32 and 64 bit wide fields. The driver MUST ignore a device with \field{MagicValue} which is not 0x74726976, although it MAY report an error. The driver MUST ignore a device with \field{Version} which is not 0x2, although it MAY report an error. The driver MUST ignore a device with \field{DeviceID} 0x0, but MUST NOT report any error. Before reading from \field{DeviceFeatures}, the driver MUST write a value to \field{DeviceFeaturesSel}. Before writing to the \field{DriverFeatures} register, the driver MUST write a value to the \field{DriverFeaturesSel} register. The driver MUST write a value to \field{QueueNum} which is less than or equal to the value presented by the device in \field{QueueNumMax}. When \field{QueueReady} is not zero, the driver MUST NOT access \field{QueueNum}, \field{QueueDescLow}, \field{QueueDescHigh}, \field{QueueAvailLow}, \field{QueueAvailHigh}, \field{QueueUsedLow}, \field{QueueUsedHigh}. To stop using the queue the driver MUST write zero (0x0) to this \field{QueueReady} and MUST read the value back to ensure synchronization. The driver MUST ignore undefined bits in \field{InterruptStatus}. The driver MUST write a value with a bit mask describing events it handled into \field{InterruptACK} when it finishes handling an interrupt and MUST NOT set any of the undefined bits in the value. \subsection{MMIO-specific Initialization And Device Operation}\label{sec:Virtio Transport Options / Virtio Over MMIO / MMIO-specific Initialization And Device Operation} \subsubsection{Device Initialization}\label{sec:Virtio Transport Options / Virtio Over MMIO / MMIO-specific Initialization And Device Operation / Device Initialization} \drivernormative{\paragraph}{Device Initialization}{Virtio Transport Options / Virtio Over MMIO / MMIO-specific Initialization And Device Operation / Device Initialization} The driver MUST start the device initialization by reading and checking values from \field{MagicValue} and \field{Version}. If both values are valid, it MUST read \field{DeviceID} 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 \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} The driver will typically initialize the virtual queue in the following way: \begin{enumerate} \item Select the queue writing its index (first queue is 0) to \field{QueueSel}. \item Check if the queue is not already in use: read \field{QueueReady}, and expect a returned value of zero (0x0). \item Read maximum queue size (number of elements) from \field{QueueNumMax}. If the returned value is zero (0x0) the queue is not available. \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 the page size). \item Notify the device about the queue size by writing the size to \field{QueueNum}. \item Write physical addresses of the queue's Descriptor Table, Available Ring and Used Ring to (respectively) the \field{QueueDescLow}/\field{QueueDescHigh}, \field{QueueAvailLow}/\field{QueueAvailHigh} and \field{QueueUsedLow}/\field{QueueUsedHigh} register pairs. \item Write 0x1 to \field{QueueReady}. \end{enumerate} \subsubsection{Notifying The Device}\label{sec:Virtio Transport Options / Virtio Over MMIO / MMIO-specific Initialization And Device Operation / Notifying The Device} The driver notifies the device about new buffers being available in a queue by writing the index of the updated queue to \field{QueueNotify}. \subsubsection{Notifications From The Device}\label{sec:Virtio Transport Options / Virtio Over MMIO / MMIO-specific Initialization And Device Operation / Notifications From The Device} The memory mapped virtio device is using a single, dedicated interrupt signal, which is asserted when at least one of the bits described in the description of \field{InterruptStatus} is set. This is how the device notifies the driver about a new used buffer being available in the queue or about a change in the device configuration. \drivernormative{\paragraph}{Notifications From The Device}{Virtio Transport Options / Virtio Over MMIO / MMIO-specific Initialization And Device Operation / Notifications From The Device} After receiving an interrupt, the driver MUST read \field{InterruptStatus} to check what caused the interrupt (see the register description). After the interrupt is handled, the driver MUST acknowledge it by writing a bit mask corresponding to the handled events to the InterruptACK register. \subsection{Legacy interface}\label{sec:Virtio Transport Options / Virtio Over MMIO / Legacy interface} The legacy MMIO transport used page-based addressing, resulting in a slightly different control register layout, the device initialization and the virtual queue configuration procedure. Table \ref{tab:Virtio Trasport Options / Virtio Over MMIO / MMIO Device Legacy Register Layout} presents control registers layout, omitting descriptions of registers which did not change their function nor behaviour: \begin{longtable}{p{0.2\textwidth}p{0.7\textwidth}} \caption {MMIO Device Legacy Register Layout} \label{tab:Virtio Trasport Options / Virtio Over MMIO / MMIO Device Legacy Register Layout} \\ \hline \mmioreg{Name}{Function}{Offset from base}{Direction}{Description} \hline \hline \endfirsthead \hline \mmioreg{Name}{Function}{Offset from the base}{Direction}{Description} \hline \hline \endhead \endfoot \endlastfoot \mmioreg{MagicValue}{Magic value}{0x000}{R}{} \hline \mmioreg{Version}{Device version number}{0x004}{R}{Legacy device returns value 0x1.} \hline \mmioreg{DeviceID}{Virtio Subsystem Device ID}{0x008}{R}{} \hline \mmioreg{VendorID}{Virtio Subsystem Vendor ID}{0x00c}{R}{} \hline \mmioreg{HostFeatures}{Flags representing features the device supports}{0x010}{R}{} \hline \mmioreg{HostFeaturesSel}{Device (host) features word selection.}{0x014}{W}{} \hline \mmioreg{GuestFeatures}{Flags representing device features understood and activated by the driver}{0x020}{W}{} \hline \mmioreg{GuestFeaturesSel}{Activated (guest) features word selection}{0x024}{W}{} \hline \mmioreg{GuestPageSize}{Guest page size}{0x028}{W}{% The driver writes the guest page size in bytes to the register during initialization, before any queues are used. This value should be a power of 2 and is used by the device to calculate the Guest address of the first queue page (see QueuePFN). } \hline \mmioreg{QueueSel}{Virtual queue index}{0x030}{W}{% Writing to this register selects the virtual queue that the following operations on the \field{QueueNumMax}, \field{QueueNum}, \field{QueueAlign} and \field{QueuePFN} registers apply to. The index number of the first queue is zero (0x0). . } \hline \mmioreg{QueueNumMax}{Maximum virtual queue size}{0x034}{R}{% 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 available. This applies to the queue selected by writing to \field{QueueSel} and is allowed only when \field{QueuePFN} is set to zero (0x0), so when the queue is not actively used. } \hline \mmioreg{QueueNum}{Virtual queue size}{0x038}{W}{% Queue size is the number of elements in the queue, therefore size of the descriptor table and both available and used rings. Writing to this register notifies the device what size of the queue the driver will use. This applies to the queue selected by writing to \field{QueueSel}. } \hline \mmioreg{QueueAlign}{Used Ring alignment in the virtual queue}{0x03c}{W}{% Writing to this register notifies the device about alignment boundary of the Used Ring in bytes. This value should be a power of 2 and applies to the queue selected by writing to \field{QueueSel}. } \hline \mmioreg{QueuePFN}{Guest physical page number of the virtual queue}{0x040}{RW}{% Writing to this register notifies the device about location of the virtual queue in the Guest's physical address space. This value is the index number of a page starting with the queue Descriptor Table. Value zero (0x0) means physical address zero (0x00000000) and is illegal. When the driver stops using the queue it writes zero (0x0) to this register. Reading from this register returns the currently used page number of the queue, therefore a value other than zero (0x0) means that the queue is in use. Both read and write accesses apply to the queue selected by writing to \field{QueueSel}. } \hline \mmioreg{QueueNotify}{Queue notifier}{0x050}{W}{} \hline \mmioreg{InterruptStatus}{Interrupt status}{0x60}{R}{} \hline \mmioreg{InterruptACK}{Interrupt acknowledge}{0x064}{W}{} \hline \mmioreg{Status}{Device status}{0x070}{RW}{% Reading from this register returns the current device status flags. Writing non-zero values to this register sets the status flags, indicating the OS/driver progress. Writing zero (0x0) to this register triggers a device reset. The device sets \field{QueuePFN} to zero (0x0) for all queues in the device. Also see \ref{sec:General Initialization And Device Operation / Device Initialization}~\nameref{sec:General Initialization And Device Operation / Device Initialization}. } \hline \mmioreg{Config}{Configuration space}{0x100+}{RW}{} \hline \end{longtable} The virtual queue page size is defined by writing to \field{GuestPageSize}, as written by the guest. The driver does this before the virtual queues are configured. The virtual queue layout follows p. \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Legacy Interfaces: A Note on Virtqueue Layout}~\nameref{sec:Basic Facilities of a Virtio Device / Virtqueues / Legacy Interfaces: A Note on Virtqueue Layout}, with the alignment defined in \field{QueueAlign}. The virtual queue is configured as follows: \begin{enumerate} \item Select the queue writing its index (first queue is 0) to \field{QueueSel}. \item Check if the queue is not already in use: read \field{QueuePFN}, expecting a returned value of zero (0x0). \item Read maximum queue size (number of elements) from \field{QueueNumMax}. If the returned value is zero (0x0) the queue is not available. \item Allocate and zero the queue pages in contiguous virtual memory, aligning the Used Ring to an optimal boundary (usually page size). The driver should choose a queue size smaller than or equal to \field{QueueNumMax}. \item Notify the device about the queue size by writing the size to \field{QueueNum}. \item Notify the device about the used alignment by writing its value in bytes to \field{QueueAlign}. \item Write the physical number of the first page of the queue to the \field{QueuePFN} register. \end{enumerate} Notification mechanisms did not change. \section{Virtio Over Channel I/O}\label{sec:Virtio Transport Options / Virtio Over Channel I/O} S/390 based virtual machines support neither PCI nor MMIO, so a different transport is needed there. virtio-ccw uses the standard channel I/O based mechanism used for the majority of devices on S/390. A virtual channel device with a special control unit type acts as proxy to the virtio device (similar to the way virtio-pci uses a PCI device) and configuration and operation of the virtio device is accomplished (mostly) via channel commands. This means virtio devices are discoverable via standard operating system algorithms, and adding virtio support is mainly a question of supporting a new control unit type. As the S/390 is a big endian machine, the data structures transmitted via channel commands are big-endian: this is made clear by use of the types be16, be32 and be64. \subsection{Basic Concepts}\label{sec:Virtio Transport Options / Virtio over channel I/O / Basic Concepts} As a proxy device, virtio-ccw uses a channel-attached I/O control unit with a special control unit type (0x3832) and a control unit model corresponding to the attached virtio device's subsystem device ID, accessed via a virtual I/O subchannel and a virtual channel path of type 0x32. This proxy device is discoverable via normal channel subsystem device discovery (usually a STORE SUBCHANNEL loop) and answers to the basic channel commands, most importantly SENSE ID. For a virtio-ccw proxy device, SENSE ID will return the following information: \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} In addition to the basic channel commands, virtio-ccw defines a set of channel commands related to configuration and operation of virtio: \begin{lstlisting} #define CCW_CMD_SET_VQ 0x13 #define CCW_CMD_VDEV_RESET 0x33 #define CCW_CMD_SET_IND 0x43 #define CCW_CMD_SET_CONF_IND 0x53 #define CCW_CMD_SET_IND_ADAPTER 0x73 #define CCW_CMD_READ_FEAT 0x12 #define CCW_CMD_WRITE_FEAT 0x11 #define CCW_CMD_READ_CONF 0x22 #define CCW_CMD_WRITE_CONF 0x21 #define CCW_CMD_WRITE_STATUS 0x31 #define CCW_CMD_READ_VQ_CONF 0x32 #define CCW_CMD_SET_VIRTIO_REV 0x83 \end{lstlisting} \devicenormative{\subsubsection}{Basic Concepts}{Virtio Transport Options / Virtio over channel I/O / Basic Concepts} 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: \begin{itemize} \item A device MUST post a unit check with command reject for any command it does not support. \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. \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. \end{itemize} \drivernormative{\subsubsection}{Basic Concepts}{Virtio Transport Options / Virtio over channel I/O / Basic Concepts} A driver for virtio-ccw devices MUST check for a control unit type of 0x3832 and MUST ignore the device type and model. A driver SHOULD attempt to provide the correct length in a channel command even if it suppresses length checks for that command. \subsection{Device Initialization}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Initialization} virtio-ccw uses several channel commands to set up a device. \subsubsection{Setting the Virtio Revision}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Initialization / Setting the Virtio Revision} CCW_CMD_SET_VIRTIO_REV is issued by the driver to set the revision of the virtio-ccw transport it intends to drive the device with. It uses the following communication structure: \begin{lstlisting} struct virtio_rev_info { be16 revision; be16 length; u8 data[]; }; \end{lstlisting} \field{revision} contains the desired revision id, \field{length} the length of the data portion and \field{data} revision-dependent additional desired options. The following values are supported: \begin{tabular}{ |l|l|l|l| } \hline \field{revision} & \field{length} & \field{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 necessarily correspond to a change in the virtio-ccw revision. \devicenormative{\paragraph}{Setting the Virtio Revision}{Virtio Transport Options / Virtio over channel I/O / Device Initialization / Setting the Virtio Revision} A device MUST post a unit check with command reject for any \field{revision} it does not support. For any invalid combination of \field{revision}, \field{length} and \field{data}, it MUST post a unit check with command reject as well. A non-transitional device MUST reject revision id 0. A device MUST answer with command reject to any virtio-ccw specific channel command that is not contained in the revision selected by the driver. A device MUST answer with command reject to any attempt to select a different revision after a revision has been successfully selected by the driver. A device MUST treat the revision as unset from the time the associated subchannel has been enabled until a revision has been successfully set by the driver. This implies that revisions are not persistent across disabling and enabling of the associated subchannel. \drivernormative{\paragraph}{Setting the Virtio Revision}{Virtio Transport Options / Virtio over channel I/O / Device Initialization / Setting the Virtio Revision} A driver SHOULD start with trying to set the highest revision it supports and continue with lower revisions if it gets a command reject. A driver MUST NOT issue any other virtio-ccw specific channel commands prior to setting the revision. After a revision has been successfully selected by the driver, it MUST NOT attempt to select a different revision. \paragraph{Legacy Interfaces: A Note on Setting the Virtio Revision}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Initialization / Setting the Virtio Revision / Legacy Interfaces: A Note on Setting the Virtio Revision} A legacy device will not support the CCW_CMD_SET_VIRTIO_REV and answer with a command reject. A non-transitional driver MUST stop trying to operate this device in that case. A transitional driver MUST operate the device as if it had been able to set revision 0. A legacy driver will not issue the CCW_CMD_SET_VIRTIO_REV prior to issuing other virtio-ccw specific channel commands. A non-transitional device therefore MUST answer any such attempts with a command reject. A transitional device MUST assume in this case that the driver is a legacy driver and continue as if the driver selected revision 0. This implies that the device MUST reject any command not valid for revision 0, including a subsequent CCW_CMD_SET_VIRTIO_REV. \subsubsection{Configuring a Virtqueue}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Initialization / Configuring a Virtqueue} CCW_CMD_READ_VQ_CONF is issued by the driver to obtain information about a queue. It uses the following structure for communicating: \begin{lstlisting} struct vq_config_block { be16 index; be16 max_num; }; \end{lstlisting} The requested number of buffers for queue \field{index} is returned in \field{max_num}. Afterwards, CCW_CMD_SET_VQ is issued by the driver to inform the device about the location used for its queue. The transmitted structure is \begin{lstlisting} struct vq_info_block { be64 desc; be32 res0; be16 index; be16 num; be64 avail; be64 used; }; \end{lstlisting} \field{desc}, \field{avail} and \field{used} contain the guest addresses for the descriptor table, available ring and used ring for queue \field{index}, respectively. The actual virtqueue size (number of allocated buffers) is transmitted in \field{num}. \devicenormative{\paragraph}{Configuring a Virtqueue}{Virtio Transport Options / Virtio over channel I/O / Device Initialization / Configuring a Virtqueue} \field{res0} is reserved and MUST be ignored by the device. \paragraph{Legacy Interface: A Note on Configuring a Virtqueue}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Initialization / Configuring a Virtqueue / Legacy Interface: A Note on Configuring a Virtqueue} For a legacy driver or for a driver that selected revision 0, CCW_CMD_SET_VQ uses the following communication block: \begin{lstlisting} struct vq_info_block_legacy { be64 queue; be32 align; be16 index; be16 num; }; \end{lstlisting} \field{queue} contains the guest address for queue \field{index}, \field{num} the number of buffers and \field{align} the alignment. \subsubsection{Virtqueue Layout}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Initialization / Virtqueue Layout} The virtqueue is physically contiguous, with padding added to make the used ring meet the align value: \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: \begin{lstlisting} #define ALIGN(x) (((x) + align) & ~align) static inline unsigned virtq_size(unsigned int num) { return ALIGN(sizeof(struct virtq_desc)*num + sizeof(u16)*(3 + num)) + ALIGN(sizeof(u16)*3 + sizeof(struct virtq_used_elem)*num); } \end{lstlisting} \subsubsection{Communicating Status Information}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Initialization / Communicating Status Information} The driver changes the status of a device via the CCW_CMD_WRITE_STATUS command, which transmits an 8 bit status value. \subsubsection{Handling Device Features}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Initialization / Handling Device Features} Feature bits are arranged in an array of 32 bit values, making for a total of 8192 feature bits. Feature bits are in little-endian byte order. The CCW commands dealing with features use the following communication block: \begin{lstlisting} struct virtio_feature_desc { le32 features; u8 index; }; \end{lstlisting} \field{features} are the 32 bits of features currently accessed, while \field{index} describes which of the feature bit values is to be accessed. No padding is added at the end of the structure, it is exactly 5 bytes in length. The guest obtains the device's device feature set via the CCW_CMD_READ_FEAT command. The device stores the features at \field{index} to \field{features}. For communicating its supported features to the device, the driver uses the CCW_CMD_WRITE_FEAT command, denoting a \field{features}/\field{index} combination. \subsubsection{Device Configuration}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Initialization / Device Configuration} The device's configuration space is located in host memory. To obtain information from the configuration space, the driver uses CCW_CMD_READ_CONF, specifying the guest memory for the device to write to. For changing configuration information, the driver uses CCW_CMD_WRITE_CONF, specifying the guest memory for the device to read from. In both cases, the complete configuration space is transmitted. This allows the driver to compare the new configuration space with the old version, and keep a generation count internally whenever it changes. \subsubsection{Setting Up Indicators}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Initialization / Setting Up Indicators} In order to set up the indicator bits for host->guest notification, the driver uses different channel commands depending on whether it wishes to use traditional I/O interrupts tied to a subchannel or adapter I/O interrupts for virtqueue notifications. For any given device, the two mechanisms are mutually exclusive. For the configuration change indicators, only a mechanism using traditional I/O interrupts is provided, regardless of whether traditional or adapter I/O interrupts are used for virtqueue notifications. \paragraph{Setting Up Classic Queue Indicators}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Initialization / Setting Up Indicators / Setting Up Classic Queue Indicators} Indicators for notification via classic I/O interrupts are contained in a 64 bit value per virtio-ccw proxy device. To communicate the location of the indicator bits for host->guest notification, the driver uses the CCW_CMD_SET_IND command, pointing to a location containing the guest address of the indicators in a 64 bit value. If the driver has already set up two-staged queue indicators via the CCW_CMD_SET_IND_ADAPTER command, the device MUST post a unit check with command reject to any subsequent CCW_CMD_SET_IND command. \paragraph{Setting Up Configuration Change Indicators}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Initialization / Setting Up Indicators / Setting Up Configuration Change Indicators} Indicators for configuration change host->guest notification are contained in a 64 bit value per virtio-ccw proxy device. To communicate the location of the indicator bits used in the configuration change host->guest notification, the driver issues the CCW_CMD_SET_CONF_IND command, pointing to a location containing the guest address of the indicators in a 64 bit value. \paragraph{Setting Up Two-Stage Queue Indicators}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Initialization / Setting Up Indicators / Setting Up Two-Stage Queue Indicators} Indicators for notification via adapter I/O interrupts consist of two stages: \begin{itemize} \item a summary indicator byte covering the virtqueues for one or more virtio-ccw proxy devices \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 payload: \begin{lstlisting} struct virtio_thinint_area { be64 summary_indicator; be64 indicator; be64 bit_nr; u8 isc; } __attribute__ ((packed)); \end{lstlisting} \field{summary_indicator} contains the guest address of the 8 bit summary indicator. \field{indicator} contains the guest address of an area wherein the indicators for the devices are contained, starting at \field{bit_nr}, one bit per virtqueue of the device. Bit numbers start at the left, i.e. the most significant bit in the first byte is assigned the bit number 0. \field{isc} contains the I/O interruption subclass to be used for the adapter I/O interrupt. It MAY be different from the isc used by the proxy virtio-ccw device's subchannel. No padding is added at the end of the structure, it is exactly 25 bytes in length. \devicenormative{\subparagraph}{Setting Up Two-Stage Queue Indicators}{Virtio Transport Options / Virtio over channel I/O / Device Initialization / Setting Up Indicators / Setting Up Two-Stage Queue Indicators} If the driver has already set up classic queue indicators via the CCW_CMD_SET_IND command, the device MUST post a unit check with command reject to any subsequent CCW_CMD_SET_IND_ADAPTER command. \paragraph{Legacy Interfaces: A Note on Setting Up Indicators}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Initialization / Setting Up Indicators / Legacy Interfaces: A Note on Setting Up Indicators} Legacy devices will only support classic queue indicators; they will reject CCW_CMD_SET_IND_ADAPTER as they don't know that command. \subsection{Device Operation}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Operation} \subsubsection{Host->Guest Notification}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Operation / Host->Guest Notification} There are two modes of operation regarding host->guest notification, classic I/O interrupts and adapter I/O interrupts. The mode to be used is determined by the driver by using CCW_CMD_SET_IND respectively CCW_CMD_SET_IND_ADAPTER to set up queue indicators. For configuration changes, the driver always uses classic I/O interrupts. \paragraph{Notification via Classic I/O Interrupts}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Operation / Host->Guest Notification / Notification via Classic I/O Interrupts} If the driver used the CCW_CMD_SET_IND command to set up queue indicators, the device will use classic I/O interrupts for host->guest notification about virtqueue activity. For notifying the driver of virtqueue buffers, the device sets the corresponding bit in the guest-provided indicators. If an interrupt is not already pending for the subchannel, the device generates an unsolicited I/O interrupt. If the device wants to notify the driver about configuration changes, it sets bit 0 in the configuration indicators and generates an unsolicited I/O interrupt, if needed. This also applies if adapter I/O interrupts are used for queue notifications. \paragraph{Notification via Adapter I/O Interrupts}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Operation / Host->Guest Notification / Notification via Adapter I/O Interrupts} If the driver used the CCW_CMD_SET_IND_ADAPTER command to set up queue indicators, the device will use adapter I/O interrupts for host->guest notification about virtqueue activity. For notifying the driver of virtqueue buffers, the device sets the bit in the guest-provided indicator area at the corresponding offset. The guest-provided summary indicator is set to 0x01. An adapter I/O interrupt for the corresponding interruption subclass is generated. The recommended way to process an adapter I/O interrupt by the driver is as follows: \begin{itemize} \item Process all queue indicator bits associated with the summary indicator. \item Clear the summary indicator, performing a synchronization (memory barrier) afterwards. \item Process all queue indicator bits associated with the summary indicator again. \end{itemize} \devicenormative{\subparagraph}{Notification via Adapter I/O Interrupts}{Virtio Transport Options / Virtio over channel I/O / Device Operation / Host->Guest Notification / Notification via Adapter I/O Interrupts} The device SHOULD only generate an adapter I/O interrupt if the summary indicator had not been set prior to notification. \drivernormative{\subparagraph}{Notification via Adapter I/O Interrupts}{Virtio Transport Options / Virtio over channel I/O / Device Operation / Host->Guest Notification / Notification via Adapter I/O Interrupts} The driver MUST clear the summary indicator after receiving an adapter I/O interrupt before it processes the queue indicators. \paragraph{Legacy Interfaces: A Note on Host->Guest Notification}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Operation / Host->Guest Notification / Legacy Interfaces: A Note on Host->Guest Notification} As legacy devices and drivers support only classic queue indicators, host->guest notification will always be done via classic I/O interrupts. \subsubsection{Guest->Host Notification}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Operation / Guest->Host Notification} For notifying the device of virtqueue buffers, the driver unfortunately can't use a channel command (the asynchronous 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{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} \devicenormative{\paragraph}{Guest->Host Notification}{Virtio Transport Options / Virtio over channel I/O / Device Operation / Guest->Host Notification} The device MUST ignore bits 0-31 (counting from the left) of GPR2. This aligns passing the subchannel ID with the way it is passed for the existing I/O instructions. The device MAY return a 64-bit host cookie in GPR2 to speed up the notification execution. \drivernormative{\paragraph}{Guest->Host Notification}{Virtio Transport Options / Virtio over channel I/O / Device Operation / Guest->Host Notification} For each notification, the driver SHOULD use GPR4 to pass the host cookie received in GPR2 from the previous notication. \begin{note} For example: \begin{lstlisting} info->cookie = do_notify(schid, virtqueue_get_queue_index(vq), info->cookie); \end{lstlisting} \end{note} \subsubsection{Resetting Devices}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Operation / Resetting Devices} In order to reset a device, a driver sends the CCW_CMD_VDEV_RESET command. \chapter{Device Types}\label{sec:Device Types} On top of the queues, config space and feature negotiation facilities built into virtio, several devices are defined. The following device IDs are used to identify different types of virtio devices. Some device IDs are reserved for devices which are not currently defined in this standard. Discovering what devices are available and their type is bus-dependent. \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 (legacy) \\ \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 13 & memory balloon \\ \hline 16 & GPU device \\ \hline 17 & Timer/Clock device \\ \hline 18 & Input device \\ \hline \end{tabular} Some of the devices above are unspecified by this document, because they are seen as immature or especially niche. Be warned that some are only specified by the sole existing implementation; they could become part of a future specification, be abandoned entirely, or live on outside this standard. We shall speak of them no further. \section{Network Device}\label{sec:Device Types / Network Device} The virtio network device is a virtual ethernet card, and is the most complex of the devices supported so far by virtio. It has enhanced rapidly and demonstrates clearly how support for new features are added to an existing device. Empty buffers are placed in one virtqueue for receiving packets, and outgoing packets are enqueued into another for transmission in that order. A third command queue is used to control advanced filtering features. \subsection{Device ID}\label{sec:Device Types / Network Device / Device ID} 1 \subsection{Virtqueues}\label{sec:Device Types / Network Device / Virtqueues} \begin{description} \item[0] receiveq1 \item[1] transmitq1 \item[\ldots] \item[2N] receiveqN \item[2N+1] transmitqN \item[2N+2] controlq


context:
space:
mode: