diff --git a/commands.tex b/commands.tex index 25ea8ee..122a97f 100644 --- a/commands.tex +++ b/commands.tex @@ -7,9 +7,10 @@ % How we format a field name \newcommand{\field}[1]{\emph{#1}} -% Mark a normative section (driver or device) +% Mark a normative section (driver, device, or bus) \newcommand{\drivernormative}[3]{#1{Driver Requirements: #2}\label{drivernormative:#3}} \newcommand{\devicenormative}[3]{#1{Device Requirements: #2}\label{devicenormative:#3}} +\newcommand{\busnormative}[3]{#1{Bus Requirements: #2}\label{busnormative:#3}} \newcounter{clausecounter} \newcommand{\conformance}[2]{ \stepcounter{clausecounter} diff --git a/conformance.tex b/conformance.tex index d92a236..4ebcf9d 100644 --- a/conformance.tex +++ b/conformance.tex @@ -14,7 +14,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \item[Driver] A driver MUST conform to four conformance clauses: \begin{itemize} \item Clause \ref{sec:Conformance / Driver Conformance}. - \item One of clauses \ref{sec:Conformance / Driver Conformance / PCI Driver Conformance}, \ref{sec:Conformance / Driver Conformance / MMIO Driver Conformance} or \ref{sec:Conformance / Driver Conformance / Channel I/O Driver Conformance}. + \item One of clauses \ref{sec:Conformance / Driver Conformance / PCI Driver Conformance}, \ref{sec:Conformance / Driver Conformance / MMIO Driver Conformance}, \ref{sec:Conformance / Driver Conformance / Channel I/O Driver Conformance} or \ref{sec:Conformance / Driver Conformance / Virtio Over Messages Driver Conformance}. \item One of clauses \ref{sec:Conformance / Driver Conformance / Network Driver Conformance}, \ref{sec:Conformance / Driver Conformance / Block Driver Conformance}, @@ -42,7 +42,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \item[Device] A device MUST conform to four conformance clauses: \begin{itemize} \item Clause \ref{sec:Conformance / Device Conformance}. - \item One of clauses \ref{sec:Conformance / Device Conformance / PCI Device Conformance}, \ref{sec:Conformance / Device Conformance / MMIO Device Conformance} or \ref{sec:Conformance / Device Conformance / Channel I/O Device Conformance}. + \item One of clauses \ref{sec:Conformance / Device Conformance / PCI Device Conformance}, \ref{sec:Conformance / Device Conformance / MMIO Device Conformance}, \ref{sec:Conformance / Device Conformance / Channel I/O Device Conformance} or \ref{sec:Conformance / Device Conformance / Virtio Over Messages Device Conformance}. \item One of clauses \ref{sec:Conformance / Device Conformance / Network Device Conformance}, \ref{sec:Conformance / Device Conformance / Block Device Conformance}, @@ -68,6 +68,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \item Clause \ref{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance}. \end{itemize} +\item[Bus] A bus implementation MUST conform to clause \ref{sec:Conformance / Bus Conformance / Virtio Over Messages Bus Conformance} when providing Virtio Over Messages. \end{description} \conformance{\section}{Driver Conformance}\label{sec:Conformance / Driver Conformance} @@ -142,6 +143,42 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \item \ref{drivernormative:Virtio Transport Options / Virtio over channel I/O / Device Operation / Resetting Devices} \end{itemize} +\conformance{\subsection}{Virtio Over Messages Driver Conformance}\label{sec:Conformance / Driver Conformance / Virtio Over Messages Driver Conformance} + +A Virtio Over Messages driver MUST conform to the following normative statements: + +\begin{itemize} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Revisions / Driver Limits} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Versioning and Forward Compatibility / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Generation Count / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Endianness / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Common Message Format / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Device Initialization / Overview / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Information / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Features / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Configuration / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Device Initialization / Virtqueue Configuration / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Device Initialization / Status Information / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Device Initialization / Finalizing Initialization / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Device Operation / Driver Notifications / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Device Operation / Device Notifications / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Device Operation / Configuration Changes During Operation / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Device Operation / Virtqueue Changes During Operation / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Device Operation / Reset / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / Mandatory / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_DEVICE_INFO / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_DEVICE_FEATURES / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_DRIVER_FEATURES / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_CONFIG / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_CONFIG / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_DEVICE_STATUS / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_VQUEUE / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_RESET_VQUEUE / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_CONFIG / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_AVAIL / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_USED / Driver} +\end{itemize} + \input{device-types/net/driver-conformance.tex} \input{device-types/blk/driver-conformance.tex} \input{device-types/console/driver-conformance.tex} @@ -233,6 +270,43 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \item \ref{devicenormative:Virtio Transport Options / Virtio over channel I/O / Device Operation / Resetting Devices} \end{itemize} +\conformance{\subsection}{Virtio Over Messages Device Conformance}\label{sec:Conformance / Device Conformance / Virtio Over Messages Device Conformance} + +A Virtio Over Messages device MUST conform to the following normative statements: + +\begin{itemize} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Revisions / Device Limits} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Versioning and Forward Compatibility / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Generation Count / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Feature Blocks / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Error Signaling / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Endianness / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Common Message Format / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Features / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Configuration / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Device Initialization / Virtqueue Configuration / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Device Initialization / Status Information / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Device Initialization / Finalizing Initialization / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Device Operation / Device Notifications / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Device Operation / Configuration Changes During Operation / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Device Operation / Virtqueue Changes During Operation / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Device Operation / Reset / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / Mandatory / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_DEVICE_INFO / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_DEVICE_FEATURES / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_DRIVER_FEATURES / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_CONFIG / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_CONFIG / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_DEVICE_STATUS / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_DEVICE_STATUS / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_VQUEUE / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_VQUEUE / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_RESET_VQUEUE / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_SHM / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_CONFIG / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_USED / Device} +\end{itemize} + \input{device-types/net/device-conformance.tex} \input{device-types/blk/device-conformance.tex} \input{device-types/console/device-conformance.tex} @@ -255,6 +329,33 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \input{device-types/can/device-conformance.tex} \input{device-types/spi/device-conformance.tex} +\conformance{\section}{Bus Conformance}\label{sec:Conformance / Bus Conformance} + +A bus implementation MUST conform to the relevant bus normative statements. + +\conformance{\subsection}{Virtio Over Messages Bus Conformance}\label{sec:Conformance / Bus Conformance / Virtio Over Messages Bus Conformance} + +A Virtio Over Messages bus implementation MUST conform to the following normative statements: + +\begin{itemize} +\item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Relationship between bus and transport / Bus Messages} +\item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Relationship between bus and transport / Transport Message Forwarding} +\item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Revisions / Advertising Transport Parameters} +\item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Revisions / Message Size} +\item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Versioning and Forward Compatibility / Bus} +\item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Device Numbers / Assignment} +\item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Error Signaling / Bus} +\item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Common Message Format / Bus} +\item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Ordering / Bus} +\item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Device Discovery / Bus} +\item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Device Operation / Driver Notifications / Bus} +\item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Device Operation / Device Notifications / Bus} +\item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Device Operation / Hotplug and Removal / Bus} +\item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_AVAIL / Bus} +\item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Bus Messages / GET_DEVICES / Bus} +\item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Bus Messages / PING / Bus} +\end{itemize} + \conformance{\section}{Legacy Interface: Transitional Device and Transitional Driver Conformance}\label{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance} A conformant implementation MUST be either transitional or non-transitional, see \ref{intro:Legacy diff --git a/transport-msg.tex b/transport-msg.tex index eaab0eb..d4e31d7 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -3,9 +3,8 @@ \section{Virtio Over Messages}\label{sec:Virtio Transport Options / Virtio Over \newcommand{\conceptref}[1]{\hyperref[sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / #1]{#1}} \newcommand{\msgref}[1]{\hyperref[sec:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_#1]{VIRTIO_MSG_#1}} \newcommand{\busref}[1]{\hyperref[sec:Virtio Transport Options / Virtio Over Messages / Bus Messages / BUS_MSG_#1]{BUS_MSG_#1}} - -\subsection{Introduction} -\label{sec:Virtio Transport Options / Virtio Over Messages / Introduction} +\newcommand{\msgdef}[1]{\subsubsection{VIRTIO_MSG_#1}\label{sec:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_#1}} +\newcommand{\busdef}[1]{\subsubsection{BUS_MSG_#1}\label{sec:Virtio Transport Options / Virtio Over Messages / Bus Messages / BUS_MSG_#1}} This section defines \textbf{virtio-msg}, a transport mechanism that encapsulates virtio operations as discrete message exchanges rather than relying on PCI or @@ -14,13 +13,11 @@ \subsection{Introduction} negotiation, virtqueue setup), ensuring that a single, generic transport layer can be reused across multiple bus implementations. -\subsubsection{Purpose} - virtio-msg addresses several key objectives: \begin{itemize} \item \textbf{Support multiple bus implementations:} - Systems may rely on various communication methods such as hypercalls, local + Systems can rely on various communication methods such as hypercalls, local IPC, network channels, or device trees for enumerating devices. virtio-msg defines a common transport interface suitable for any of these mechanisms. @@ -37,20 +34,29 @@ \subsubsection{Purpose} integrate smoothly once a device is discovered and registered. \end{itemize} +\subsection{Basic Concepts} +\label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts} + +The virtio-msg transport relies on a set of foundational concepts to ensure +reusability across different bus implementations and flexibility in device +capabilities. This section defines those concepts and clarifies how they apply, +regardless of whether the bus leverages message-based enumeration or platform +data for device discovery. + \subsubsection{High-Level Architecture} virtio-msg operates around two layers: \begin{enumerate} \item \textbf{Bus Layer}: A \emph{bus instance} exposes zero or more virtio - devices. It can detect available devices through: + devices. It discovers available devices through mechanisms such as: \begin{itemize} \item Optional message-based queries (\busref{GET_DEVICES}), \item External data sources (e.g., device tree, ACPI tables, hypervisor firmware calls), \item Dynamic hotplug notifications (optionally via \busref{EVENT_DEVICE}). \end{itemize} - Once a device is identified, regardless of discovery method, the bus typically + Once a device is identified, regardless of discovery method, the bus uses \msgref{GET_DEVICE_INFO} to read its device ID and vendor ID, then \emph{registers} that device with the host OS so the usual virtio driver probe can occur. @@ -71,12 +77,69 @@ \subsubsection{High-Level Architecture} environments. \end{enumerate} +\subsubsection{Relationship Between Bus and Transport} +\label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Relationship between bus and transport} + +This subsubsection explains the division of responsibilities: the bus layer is +the mandatory carrier that moves messages between driver and device endpoints +(e.g., over IPC, shared memory with signalling or hardware messaging), while +the virtio-msg transport defines the semantics of those messages. + +virtio-msg groups messages into two categories: + +\begin{description} + \item[\textbf{Bus Messages}:] + Intended for global bus operations such as enumerating device numbers + (\busref{GET_DEVICES}), managing device hotplug events (\busref{EVENT_DEVICE}) + or assessing bus-wide health (\busref{PING}). + These messages are \emph{optional} in environments where + device discovery or state changes occur through other means (e.g., device + tree). However, if a bus chooses to handle those tasks via messages, + it implements the appropriate bus message definitions described in this + section. + + \item[\textbf{Transport Messages}:] + Used for device-specific operations, such as: + \begin{itemize} + \item Retrieving or setting features (\msgref{GET_DEVICE_FEATURES}, + \msgref{SET_DRIVER_FEATURES}), + \item Accessing device configuration (\msgref{GET_CONFIG}, + \msgref{SET_CONFIG}), + \item Managing virtqueues (\msgref{SET_VQUEUE}, \msgref{RESET_VQUEUE}), + \item Handling device status and notifications (\msgref{SET_DEVICE_STATUS}, + \msgref{EVENT_USED}, etc.). + \end{itemize} +\end{description} + +This separation lets a bus remain minimal if it obtains device information from +firmware tables, while still supporting fully message-based enumeration and +hotplug when desired. + +\busnormative{\paragraph}{Bus Message Implementation}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Relationship between bus and transport / Bus Messages} +\begin{itemize} + \item A bus implementation that provides enumeration, hotplug, or bus + health handling via bus messages SHOULD implement the corresponding Bus + Message definitions described in this section. +\end{itemize} + +\busnormative{\paragraph}{Transport Message Forwarding}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Relationship between bus and transport / Transport Message Forwarding} +\begin{itemize} + \item A bus implementation MUST relay each transport message to the device + number identified in the message header, regardless of how it + discovered or enumerated that device. + \item A bus implementation SHOULD treat transport messages as opaque apart + from enforcing generic transport limits, such as the advertised maximum + message size, and SHOULD NOT modify the transport payload. +\end{itemize} + \subsubsection{System Topology} +A virtio-msg system contains the following elements: + \begin{itemize} - \item \textbf{Bus Instances and Devices}: Each bus instance can advertise - different capabilities (e.g., transport revision, maximum message size) - and may discover devices via a message-based or external mechanism. + \item \textbf{Bus Instances and Devices}: Each bus instance advertises its + capabilities (e.g., transport revision, maximum message size) and + discovers devices via message-based queries or external data sources. Every discovered device has a unique \emph{device number}. \item \textbf{Driver}: Communicates with the bus to learn about available devices. Once a device is recognized, the driver uses the @@ -87,56 +150,55 @@ \subsubsection{System Topology} the correct device instance based on device number. \end{itemize} -\subsubsection{Optional Bus Messages} - -This specification \emph{defines} messages such as \busref{GET_DEVICES}, -\busref{EVENT_DEVICE}, and \busref{PING} for a -completely message-based approach to enumeration, hotplug, and bus-wide health. -However, these are \emph{not} mandatory if a bus instance already handles those -functions via firmware, device tree, or other platform features. The only strict -requirement is that the bus \emph{MUST} be able to forward device-specific -\emph{transport messages} once a device is recognized, so the virtio-msg driver -can manage it. - -\subsection{Basic Concepts} -\label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts} - -The virtio-msg transport relies on a set of foundational concepts to ensure -reusability across different bus implementations and flexibility in device -capabilities. This section defines those concepts and clarifies how they apply, -regardless of whether the bus leverages message-based enumeration or platform -data for device discovery. - \subsubsection{Transport Revisions and Maximum Message Size} \label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Revisions} Each \textbf{virtio-msg bus instance} advertises the following to the transport layer: \begin{itemize} - \item A \textbf{transport revision} indicating the protocol version it - supports. This revision is separate from the overall Virtio - specification version. - \item A \textbf{maximum message size} representing the largest payload - (in bytes) the bus can reliably carry per request or response. - \item A \textbf{feature bits} indicating a list of revision specific - optional features that are supported or not by the bus instance. + \item \textbf{Transport revision}: the protocol version supported by the bus + instance (independent of the overall Virtio specification version). + \item \textbf{Maximum message size}: the largest payload (in bytes) that can + be carried per request or response, including the common header. + \item \textbf{Transport feature bits}: revision-specific optional features + implemented by the bus instance. +\end{itemize} + +The mechanism for obtaining these parameters is implementation-defined and can +vary between bus instances. Common approaches include: +\begin{itemize} + \item Reading firmware or device-tree data that describes each bus instance, + \item Performing a message exchange during bus setup to retrieve the values, + \item Relying on per-bus configuration structures or driver-specific defaults. \end{itemize} -These parameters \emph{MAY} vary between bus instances within the same system. -The bus implementation obtains a bus's revision, maximum message size and list -of features through an \emph{implementation-defined} mechanism, which could be: +\busnormative{\paragraph}{Advertising Transport Parameters}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Revisions / Advertising Transport Parameters} \begin{itemize} - \item A device tree or firmware method providing bus configuration, - \item A message exchange during bus setup, - \item A per bus instance list of properties, - \item A static definition built into the driver for a known environment. + \item Each bus instance MUST make its transport revision, maximum message + size, and transport feature bits available to the virtio-msg transport + before any transport messages are exchanged for that device. + \item A bus instance MUST apply the same limits to both driver-originated and + device-originated transport messages; if the values change, the bus + MUST inform the transport layer before accepting additional messages. \end{itemize} -After learning these parameters, the transport layer \emph{MUST} respect them -for all messages involving that bus instance. For example, it \emph{MUST NOT} -send a message exceeding the \textbf{maximum message size}, and it \emph{MUST} -avoid using advanced features or messages unavailable in the bus's advertised -\textbf{transport revision}. +\drivernormative{\paragraph}{Respecting Bus Limits}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Revisions / Driver Limits} +\begin{itemize} + \item A driver MUST NOT send a transport message whose total size exceeds the + maximum message size advertised for the target bus instance. + \item A driver MUST NOT rely on transport features or messages that require a + higher transport revision than the bus instance reports. +\end{itemize} + +\devicenormative{\paragraph}{Respecting Bus Limits}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Revisions / Device Limits} +\begin{itemize} + \item A device MUST ensure its responses and device-originated messages do + not exceed the maximum message size advertised by the bus instance that + relays them. + \item A device MUST NOT require transport features or messages beyond the + transport revision reported by the bus instance, and MUST respond with + an error or ignore requests for unsupported features. +\end{itemize} \paragraph{virtio-msg revisions} @@ -153,20 +215,65 @@ \subsubsection{Transport Revisions and Maximum Message Size} Note that a change in the virtio standard does not necessarily correspond to a change in the virtio-msg revision. -The maximum message size is from the common transport level point of -view and includes the headers and payload described here. If the bus adds its -own overhead (e.x. its own header) this is not included in the maximum message -size. The maximum useful message size is currently expected to be 274. -This value is large enough to support a GET_CONFIG or SET_CONFIG message with a -configuration data payload of 256 bytes. +The maximum message size is specified from the transport-layer point of view +and includes the 8-byte common header plus payload. Any extra encapsulation +imposed by the underlying bus (for example, a framing header) does not count +against this limit. Today the largest practical transport payload is 256 bytes: +messages such as GET_CONFIG and SET_CONFIG can carry up to 256 bytes of device +configuration in one transfer, and larger configuration regions can be accessed +through multiple exchanges without requiring a larger per-message limit. + +\busnormative{\paragraph}{Message Size Bounds}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Revisions / Message Size} +\begin{itemize} + \item A bus implementation MUST advertise a maximum message size of at least + 44 bytes. + \item A bus implementation SHOULD NOT advertise a maximum message size that + exceeds 264 bytes (256-byte payload plus the common header). +\end{itemize} + +\paragraph{Versioning and Forward Compatibility} + +A higher transport revision or additional transport feature bits extend the +protocol with new messages or capabilities. Implementations are expected to +remain interoperable across revisions: devices and drivers designed for a newer +revision still implement the mandatory messages and semantics defined in prior +revisions. + +\drivernormative{\paragraph}{Revision Compatibility}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Versioning and Forward Compatibility / Driver} +\begin{itemize} + \item A driver that negotiates transport revision $N$ MUST implement all + mandatory driver behavior defined for revisions $1$ through $N$. + \item If a driver receives a device-originated message or feature indication + that requires an unsupported revision or transport feature, it MUST + ignore the message (or treat the request as failed) and MUST NOT act on + partially understood data. +\end{itemize} + +\devicenormative{\paragraph}{Revision Compatibility}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Versioning and Forward Compatibility / Device} +\begin{itemize} + \item A device that advertises transport revision $N$ MUST implement all + mandatory device behavior defined for revisions $1$ through $N$. + \item If a device receives a driver request that relies on an unsupported + revision or transport feature, it MUST reject the request using the + message-specific error mechanism (if any) or silently ignore it. +\end{itemize} + +\busnormative{\paragraph}{Revision Compatibility}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Versioning and Forward Compatibility / Bus} +\begin{itemize} + \item A bus instance that advertises transport revision $N$ MUST satisfy every + bus requirement defined for revisions $1$ through $N$. + \item If a bus instance cannot forward a message because it requires an + unsupported revision or transport feature, it MUST surface a transport + error or drop the message without forwarding it. +\end{itemize} \subsubsection{Device Numbers and Enumeration} \label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Device Numbers} Each virtio-msg bus instance contains one or more \emph{devices}, identified -by a 16-bit \textbf{device number}. Buses \emph{MAY} discover these device -numbers in multiple ways: +by a 16-bit \textbf{device number}. Buses discover these device numbers through +mechanisms such as: \begin{itemize} \item \textbf{Message-Based Enumeration}: Using \busref{GET_DEVICES} to query which numbers exist (optional). @@ -174,137 +281,142 @@ \subsubsection{Device Numbers and Enumeration} might inform the bus of available device numbers and their properties. \end{itemize} -Once a bus confirms that a given device number is valid (regardless of the method), -it typically issues \msgref{GET_DEVICE_INFO} to retrieve the device's Device ID -and vendor ID. The bus can then register the device with the host OS to initiate -the usual Virtio driver binding process. +Once a bus confirms that a device number is valid—regardless of the discovery +method—it normally issues \msgref{GET_DEVICE_INFO} to retrieve the device and +vendor IDs before registering the device with the host OS so the usual Virtio +driver binding process can begin. + +\busnormative{\paragraph}{Device Number Assignment}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Device Numbers / Assignment} +\begin{itemize} + \item A bus implementation MUST assign a unique device number to every + device on a given bus instance and MUST NOT forward transport messages + for a device number that has not been validated. + \item A bus implementation SHOULD provide the driver with sufficient + information—either via \busref{GET_DEVICES} or equivalent platform + data—to discover each valid device number. +\end{itemize} \subsubsection{Configuration Generation Count} -\label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / ConfigGen} +\label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Generation Count} Each device maintains a \textbf{Configuration Generation Count} to prevent inconsistent updates. This count is incremented at least once by the device for -every driver visible change it makes to its own copy of the configuration data. -A configuration change is made visible to the driver via \msgref{EVENT_CONFIG} -or the response to \msgref{GET_CONFIG} which also both provide the device's -current configuration count. The device may change any amount of data for one -generation count increment. If the change cannot fit in one \msgref{EVENT_CONFIG} -message, the device \emph{SHOULD} send an \msgref{EVENT_CONFIG} message -with a zero data length and the new generation count to the driver. -The device \emph{MUST NOT} provide the same generation count in -multiple \msgref{EVENT_CONFIG} messages that contain non-zero length config -data. The driver includes its view of the current generation count in -\msgref{SET_CONFIG} requests. The configuration generation count does not -necessarily start at 0 and \emph{SHOULD NOT} reset to 0 on device reset. - -\begin{itemize} - \item If the driver's generation count does not match the device's current - count, the \msgref{SET_CONFIG} request \emph{MUST} be rejected by the - device. - \item The driver may have received \msgref{EVENT_CONFIG} messages - between the request and the response and will know the current - configuration data and generation count. If not it \emph{SHOULD} - re-read the configuration and generation count via \msgref{GET_CONFIG}), - and then resend the \msgref{SET_CONFIG} if still desired. +every driver-visible change it makes to its configuration data. The current +count is exposed in \msgref{EVENT_CONFIG} and \msgref{GET_CONFIG} responses so +the driver can determine whether its view of the configuration is current. The +count does not necessarily start at zero and is not automatically reset when +the device resets. + +\devicenormative{\paragraph}{Configuration Generation Count}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Generation Count / Device} +\begin{itemize} + \item A device MUST increment the generation count before it makes a change + that is visible to the driver and MUST ensure that each + \msgref{EVENT_CONFIG} carrying configuration data uses a unique + generation count. + \item If updated configuration data cannot fit in a single + \msgref{EVENT_CONFIG}, the device SHOULD send an \msgref{EVENT_CONFIG} + with zero data length to advertise the new generation count and MUST + make the updated data available via \msgref{GET_CONFIG}. + \item If a \msgref{SET_CONFIG} request includes a generation count that does + not match the device's current count, the device MUST reject the + request. +\end{itemize} + +\drivernormative{\paragraph}{Configuration Generation Count}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Generation Count / Driver} +\begin{itemize} + \item A driver MUST track the most recent generation count observed (via + \msgref{EVENT_CONFIG} or \msgref{GET_CONFIG}) and include it in every + \msgref{SET_CONFIG} request. + \item If a \msgref{SET_CONFIG} request is rejected due to a mismatched + generation count, the driver SHOULD issue \msgref{GET_CONFIG} to obtain + the latest configuration data and generation count before retrying. \end{itemize} This mechanism ensures updates are not lost or overwritten due to stale information. \subsubsection{Feature Negotiation Blocks} -\label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / FeatureBlocks} +\label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Feature Blocks} -The virtio-msg transport handles feature bits in one or more -\textbf{32-bits blocks}, accessed via \msgref{GET_DEVICE_FEATURES} and -\msgref{SET_DRIVER_FEATURES}. Each block corresponds to up to 32 features: +The virtio-msg transport organizes feature bits into 32-bit blocks accessed by +\msgref{GET_DEVICE_FEATURES} and \msgref{SET_DRIVER_FEATURES}. Each block +represents up to 32 feature bits: \begin{itemize} \item \textbf{Block Index}: The starting block (e.g., block 0 for features 0--31, block 1 for features 32--63, etc.). \item \textbf{Number of Blocks}: How many blocks the driver wishes to retrieve or modify in a single message. - \item \textbf{Feature Data}: The 32 bits values representing a device's - supported or requested feature bits. + \item \textbf{Feature Data}: The 32-bit values representing the supported (or + driver-requested) feature bits in the selected blocks. \end{itemize} -A device \emph{MUST} respond with all zero feature data for features bit -requested beyond those the device implements. +\devicenormative{\paragraph}{Feature Blocks}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Feature Blocks / Device} +\begin{itemize} + \item When \msgref{GET_DEVICE_FEATURES} covers blocks that extend beyond the + features a device implements, the device MUST return zero for the + feature data in those positions. +\end{itemize} \subsubsection{Error Signaling} -\label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / ErrorSignaling} +\label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Error Signaling} -Errors may arise from: (a) malformed or unsupported transport messages, (b) -transmission or routing issues within a bus implementation, or (c) device-side -failures while processing a valid request. Local detection and recovery are -preferred, but a virtio-msg bus \textbf{MAY} report transmission errors to the -virtio-msg transport when it cannot deliver a request or obtain a response -within a bounded policy. +Transport errors can arise from malformed messages, routing failures inside a +bus implementation, or device-side faults while processing a valid request. +Implementations should handle such faults locally where possible, but a bus may +surface an error to the virtio-msg transport if it cannot deliver a request or +obtain a response within its policy. -The following rules apply: +\busnormative{\paragraph}{Error Handling}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Error Signaling / Bus} \begin{itemize} - \item A bus implementation \textbf{MAY} surface a transport-visible failure - (implementation-defined) after exhausting any bounded retry policy for - a transmission error. - \item Malformed headers or unsupported \field{msg_id} values \textbf{SHOULD} - be discarded; the receiver \textbf{MAY} log them and \textbf{SHOULD NOT} - generate further protocol traffic in response. - \item Event (one-way) messages \textbf{MUST NOT} elicit an error response. - \item Recovery actions (retry, selective reset, device removal) are - environment-specific but \textbf{MUST} comply with any normative reset - or status handling semantics described in - \ref{sec:Virtio Transport Options / Virtio Over Messages / Device Operation}. + \item A bus implementation MAY report a transport-visible failure (for + example, after exhausting a bounded retry policy) when it cannot deliver + a request or obtain a response. + \item A bus implementation MUST treat malformed headers or unsupported + \field{msg_id} values as invalid, MUST discard them without generating + additional protocol traffic, and MAY log the condition for diagnostics. + \item A bus implementation MUST NOT generate error responses to event + (one-way) messages. \end{itemize} -This specification does not mandate a specific error reporting message for -transmission failures; it only permits a virtio-msg bus to surface such -failures to the virtio-msg transport when silent recovery is not feasible. - -\subsubsection{Bus vs. Transport Messages} -\label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / BusVsTransport} - -virtio-msg groups messages into two categories: - -\begin{description} - \item[\textbf{Bus Messages}:] - Intended for global bus operations such as enumerating device numbers - (\busref{GET_DEVICES}), managing device hotplug events (\busref{EVENT_DEVICE}) - or assessing bus-wide health (\busref{PING}). - These messages are \emph{optional} in environments where - device discovery or state changes occur through other means (e.g., device - tree). However, if a bus chooses to handle those tasks via messages, - it \emph{should} implement the appropriate bus message definitions. - - \item[\textbf{Transport Messages}:] - Used for device-specific operations, such as: - \begin{itemize} - \item Retrieving or setting features (\msgref{GET_DEVICE_FEATURES}, - \msgref{SET_DRIVER_FEATURES}), - \item Accessing device configuration (\msgref{GET_CONFIG}, - \msgref{SET_CONFIG}), - \item Managing virtqueues (\msgref{SET_VQUEUE}, \msgref{RESET_VQUEUE}), - \item Handling device status and notifications (\msgref{SET_DEVICE_STATUS}, - \msgref{EVENT_USED}, etc.). - \end{itemize} - The bus \emph{MUST} relay these messages to the correct device, - regardless of how the bus discovered or enumerated that device. -\end{description} +\devicenormative{\paragraph}{Error Handling}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Error Signaling / Device} +\begin{itemize} + \item A device receiving a malformed or unsupported transport message MUST + discard it without producing further protocol traffic. + \item Recovery actions taken in response to an error (such as retries, + selective resets, or device removal) MUST follow the normative reset and + status semantics defined in + \ref{sec:Virtio Transport Options / Virtio Over Messages / Device Operation}. +\end{itemize} -The resulting design allows a bus to remain minimal if it obtains device -information from a device tree or firmware tables, while still supporting -fully message-based enumeration and hotplug if desired. +This specification does not define a dedicated error-reporting message; it only +permits implementations to surface failures when silent recovery is not +feasible. \subsubsection{Endianness} \label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Endianness} -All values and fields defined in the virtio-msg messages \emph{MUST} -be encoded in little-endian. +Unless otherwise stated, all numeric fields defined for virtio-msg messages use +little-endian encoding. + +\drivernormative{\paragraph}{Endianness}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Endianness / Driver} +\begin{itemize} + \item A driver MUST encode and decode the common header and payload fields + defined by this transport using little-endian byte order. +\end{itemize} + +\devicenormative{\paragraph}{Endianness}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Endianness / Device} +\begin{itemize} + \item A device MUST emit and consume the common header and payload fields + defined by this transport using little-endian byte order. +\end{itemize} \subsubsection{Common Message Format} \label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Common Message Format} -All virtio-msg exchanges, whether \emph{bus messages} or -\emph{transport messages}, begin with an 8 byte header followed by an optional -payload. +All virtio-msg exchanges, whether \emph{bus messages} or \emph{transport +messages}, begin with an 8-byte header followed by an optional payload. The +fields below describe the wire format for that header. The header layout is: \begin{lstlisting} @@ -312,7 +424,7 @@ \subsubsection{Common Message Format} u8 type; /* request/response + bus/transport */ u8 msg_id; /* message id */ le16 dev_num; /* device number (0 for bus messages) */ - le16 token; /* correlation identifier (0 for events) */ + le16 token; /* bus-managed correlation identifier */ le16 msg_size; /* total size: header (8) + payload */ u8 payload[]; }; @@ -323,153 +435,118 @@ \subsubsection{Common Message Format} \item \field{type}: \begin{itemize} \item Bit[0]: 0=request, 1=response. - \item Bit[1]: 0=Transport Message, 1=Bus Message. - \item Bits[2..7]: \textbf{MUST} be zero; receivers \textbf{MUST} ignore. + \item Bit[1]: 0=transport message, 1=bus message. + \item Bits[2..7]: reserved for future use. \end{itemize} \item \field{msg_id}: Message ID identifying the message definition. Ranges are defined in \ref{sec:Virtio Transport Options / Virtio Over Messages / Transport Messages} and \ref{sec:Virtio Transport Options / Virtio Over Messages / Bus Messages}. - \item \field{dev_num}: For Transport Messages, the target device number; for - Bus Messages \textbf{MUST} be zero. - \item \field{token}: Non-zero for requests (which expect a response); zero - \textbf{MUST} be used only for event (one-way) messages. Responses - \textbf{MUST} echo the request's \field{token}. - \item \field{msg_size}: Total size in bytes of the complete message (header + - payload). \textbf{MUST} be \(\ge 8\) and \textbf{MUST NOT} exceed the - bus's maximum message size. - \item \field{payload}: Operation-specific data. Unused trailing bytes (if any - introduced by a bus framing) \textbf{MUST} be zero and \textbf{MUST} be - ignored by receivers. -\end{itemize} - -All reserved header bits and any unspecified header values \textbf{MUST} be -sent as zero and \textbf{MUST} be ignored on receive to preserve forward -compatibility. - -\subsubsection{Message Correlation} -\label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Correlation} - -Messages are either requests or events. Requests require a response. Events are -one way and do not have a response. Most requests defined today originate at the -driver side but bus message requests such as \busref{PING} may originate at -either driver side or device side. - -This section defines how responses are correlated to requests. An implementation -does not need to support sending multiple requests in parallel but these rules -allow for that possibility. - -The token field in the message header is part of a tuple that is unique during -a request to response interval. -\begin{itemize} - \item Message tuple: ( \field{dev_num}, \field{token} ). + \item \field{dev_num}: For transport messages, the device number that should + receive the message. Bus messages operate on device number 0. + \item \field{token}: Correlation identifier managed by the bus. Drivers and + devices treat this field as opaque; the bus MAY overwrite it to track + outstanding requests or maintain ordering. + \item \field{msg_size}: Total size in bytes of the complete message (header + plus payload). + \item \field{payload}: Operation-specific data. If a bus introduces extra + padding bytes, those bytes are not part of the payload semantics. \end{itemize} -Rules: +\drivernormative{\paragraph}{Common Header}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Common Message Format / Driver} \begin{itemize} - \item The request originator assigns a non-zero \field{token} for every - request such that the tuple is unique for all inflight requests. - \item Event (one-way) messages \textbf{MUST} set \field{token}=0 - \item A response \textbf{MUST} echo \field{token} and \field{dev_num}. - \item Reception of unknown or already completed correlation tuples - \textbf{SHOULD} result in discarding the response without further protocol - action. + \item A driver MUST set bits 2..7 of \field{type} to zero and MUST treat them + as reserved when parsing received headers. + \item A driver MUST ensure \field{msg_size} reflects the total message length + (header plus payload) and MUST NOT exceed the maximum message size + advertised by the bus instance. + \item When sending a transport message, a driver MUST set \field{dev_num} to + the intended device number. + \item If a driver introduces padding bytes that become part of the transport + payload, it MUST set those bytes to zero. + \item A driver MUST treat the \field{token} field as opaque and MUST NOT rely + on its value when processing received messages. \end{itemize} -\subsection{Bus Operation} -\label{sec:Virtio Transport Options / Virtio Over Messages / Bus Operation} - -A \textbf{virtio-msg bus} is responsible for identifying available virtio devices -and informing the operating system (or higher-level software environment) so -that those devices can be bound to the appropriate driver. The following -subsections describe optional messaging mechanisms that a bus \emph{MAY} use to -discover or manage devices, as well as general guidelines for completing the -device registration process. - -\subsubsection{Device Discovery} -\label{sec:Virtio Transport Options / Virtio Over Messages / Bus Operation / Device Discovery} - -Bus implementations \emph{MAY} discover their devices in various ways: +\devicenormative{\paragraph}{Common Header}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Common Message Format / Device} \begin{itemize} - \item By parsing platform data such as a device tree or ACPI tables, - \item By receiving enumeration data from a hypervisor or firmware, - \item By using \busref{GET_DEVICES} messages - to query which device numbers are present on this bus instance. + \item A device MUST set bits 2..7 of \field{type} to zero in transmitted + messages and MUST ignore those bits on receive. + \item A device MUST ensure \field{msg_size} reflects the total message length + (header plus payload) and does not exceed the bus's advertised maximum. + \item When sending a transport message, a device MUST set \field{dev_num} to + its own device number. + \item A device MUST ignore padding bytes that are documented as bus-specific + and MUST zero any such bytes it introduces into the transport payload. + \item A device MUST treat the \field{token} field as opaque and MUST NOT rely + on its value when processing received messages. \end{itemize} -This specification \emph{defines} \busref{GET_DEVICES} for implementations that -wish to carry out discovery entirely via messages, but it does \textbf{not} -mandate use of this approach. A bus implementation \emph{MAY} skip -\busref{GET_DEVICES} altogether if it already knows which devices exist (e.g., -via a device tree). In any case, once a bus has established the presence of a -device, it \emph{SHOULD} call \msgref{GET_DEVICE_INFO} to retrieve the device ID -and vendor ID. The bus can then register the device with the host OS -so the appropriate virtio driver probe routine is invoked. - -\subsubsection{Device Hotplug} -\label{sec:Virtio Transport Options / Virtio Over Messages / Bus Operation / Device Hotplug} - -If the bus supports dynamic addition or removal of devices at runtime, it -\emph{MAY} announce these events using messages: +\busnormative{\paragraph}{Common Header}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Common Message Format / Bus} \begin{itemize} - \item \busref{EVENT_DEVICE} with state DEVICE_BUS_STATE_READY for a newly - available device, - \item \busref{EVENT_DEVICE} with state DEVICE_BUS_STATE_REMOVED for a device - that is no longer accessible. + \item A bus implementation MUST deliver bus messages with \field{dev_num}=0 + and MUST NOT alter \field{dev_num} for transport messages beyond the + routing needed to reach the addressed device. + \item A bus implementation MUST set bits 2..7 of \field{type} to zero when + generating bus messages and MUST ignore those bits when forwarding + transport messages. + \item If the bus adds framing or padding bytes around the common header or + payload, it MUST set those bytes to zero before delivering the message + to the opposite side and MUST present the same zero padding when the + opposite side reads a message. + \item A bus implementation owns the \field{token} field; it MAY insert or + overwrite values for correlation purposes and MUST ensure that any such + use is transparent to drivers and devices. \end{itemize} -Alternatively, the bus \emph{MAY} rely on external signals (e.g., an event from -the platform or hypervisor) and inform the OS of hotplug changes out-of-band. -This specification \emph{defines} \busref{EVENT_DEVICE} -for implementations that prefer a fully message-based -approach but does not require their use. In any scenario, once notified that a -device has appeared, the bus \emph{SHOULD} query the device (e.g., via -\msgref{GET_DEVICE_INFO}) and register it with the OS. If a device is -removed, the bus \emph{SHOULD} prompt the OS to unbind and release resources. +Reserved header bits and unspecified header values MUST be transmitted as zero +and ignored on receive to preserve forward compatibility. -\subsubsection{Monitoring the Bus} -\label{sec:Virtio Transport Options / Virtio Over Messages / Bus Operation / Monitoring} +\subsubsection{Message Ordering} +\label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Ordering} -An optional \busref{PING} message is provided for bus implementations that want -to periodically verify connectivity with the other end (driver or device). -Implementations \emph{MAY} use other keepalive or health-check -protocols instead. The general usage of \busref{PING} (if implemented) is: +Transport messages fall into two classes: requests (which expect responses) and +events (which are one-way). Drivers and devices rely on the bus to preserve the +relative ordering of request/response pairs for each device number; they do not +interpret the \field{token} field directly. +\busnormative{\paragraph}{Message Ordering}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Ordering / Bus} \begin{itemize} - \item The initiator sends a 32-bit data field, - \item The recipient responds by echoing this same 32-bit data, - \item If a response does not arrive in time, the initiator \emph{MAY} treat - the bus as unresponsive and trigger a global reset or other fallback - procedure. + \item For each device number, a bus implementation MUST deliver responses to + the driver in the same order that it forwarded the corresponding + requests to the device. + \item A bus implementation MUST ensure that every request forwarded to a + device results in exactly one response delivered to the driver (unless + the request is defined as an event). \end{itemize} -\subsubsection{Bus Specific Messages} -\label{sec:Virtio Transport Options / Virtio Over Messages / Bus Operation / Bus Specific Messages} +\subsection{Device Discovery}\label{sec:Virtio Transport Options / Virtio Over Messages / Device Discovery} -A range of message IDs are reserved for use by the specific bus -implementation. These messages can be used for any implementation specific -usage. Example usage could include: +A virtio-msg implementation can learn about devices via bus-level enumeration +(e.g., \busref{GET_DEVICES}), platform data (e.g., device tree, ACPI), or +hypervisor/firmware interfaces. The following informative text describes +typical flows; the normative obligations follow. + +Bus implementations discover their devices through a mix of platform data, +hypervisor-provided enumeration, or message-based queries such as +\busref{GET_DEVICES}. This specification defines \busref{GET_DEVICES} for +environments that prefer message-driven enumeration, but it does not require +its use when equivalent information is already known out-of-band. +\busnormative{\paragraph}{Device Discovery}{Virtio Transport Options / Virtio Over Messages / Device Discovery / Bus} \begin{itemize} - \item Configuration of out-of-band notification methods - \item Setup shared memory regions to be used for buffers or virtqueues - \item Declare bus specific error conditions - \item Provide extra debug or logging information + \item A bus implementation MUST ensure that every device number it exposes to + the driver has been validated via either platform data or a successful + query such as \busref{GET_DEVICES}. + \item Once a device number is deemed present, the bus implementation SHOULD + invoke \msgref{GET_DEVICE_INFO} so it can register the device with the + host OS and allow the appropriate virtio driver to bind. + \item If a bus implementation provides an alternative enumeration mechanism + (e.g., ACPI, device tree), it MAY omit \busref{GET_DEVICES} provided the + alternative delivers equivalent information to the driver. \end{itemize} -\subsubsection{Interaction with Transport Messages} -\label{sec:Virtio Transport Options / Virtio Over Messages / Bus Operation / Interaction with Transport} - -The bus is also responsible for forwarding device-specific \emph{transport -messages} to the correct device for each device number. Typically the bus does -not interpret or modify these transport messages; its role is simply to ensure -they reach the intended device. If the bus does not rely on messages for device -enumeration or hotplug itself, it \emph{MUST} still be capable of transporting -\msgref{GET_DEVICE_INFO}, \msgref{GET_DEVICE_FEATURES}, \msgref{SET_CONFIG}, etc. -once the OS driver has identified a device and is performing initialization -via the virtio-msg transport. - \subsection{Device Initialization} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Initialization} @@ -483,159 +560,208 @@ \subsubsection{Initialization Flow Overview} A typical device initialization flow includes: \begin{enumerate} - \item \textbf{Obtain Device Information:} - The driver queries the device's Device ID, vendor ID, feature block count, - configuration size, and other static parameters of the device using - \msgref{GET_DEVICE_INFO}. - \item \textbf{Negotiate Features:} - The driver retrieves the device's feature bits (\msgref{GET_DEVICE_FEATURES}), - determines which features it wants to enable, and writes the desired set - with (\msgref{SET_DRIVER_FEATURES}). It then attempts to set the - FEATURES_OK bit in the device status (\msgref{SET_DEVICE_STATUS}) and - verifies that it is set in the return device status. - \item \textbf{Initialize Configuration Space:} - The driver may read (\msgref{GET_CONFIG}) or modify (\msgref{SET_CONFIG}) - configuration data, using the device's \emph{Configuration Generation Count} - to prevent race conditions. - \item \textbf{Set Up Virtqueues:} - The driver configures each virtqueue (e.g., number of descriptors, base - addresses) via \msgref{SET_VQUEUE} and verifies each queue's readiness - (\msgref{GET_VQUEUE}). - \item \textbf{Set Device Status:} - The driver updates the device's status with \msgref{SET_DEVICE_STATUS} to - indicate initialization progress (e.g., from "reset" to "acknowledge," - "driver," or "driver OK," following Virtio conventions). + \item \textbf{Obtain Device Information:} + Query static parameters with \msgref{GET_DEVICE_INFO}. + \item \textbf{Negotiate Features:} + Read feature blocks via \msgref{GET_DEVICE_FEATURES}, decide which to + enable, and write them back with \msgref{SET_DRIVER_FEATURES} before + updating the device status. + \item \textbf{Initialize Configuration Space:} + Read or write configuration data with + \msgref{GET_CONFIG}/\msgref{SET_CONFIG}, guarding updates with the + configuration generation count. + \item \textbf{Set Up Virtqueues:} + Configure each virtqueue via \msgref{SET_VQUEUE} and verify the settings + with \msgref{GET_VQUEUE}. + \item \textbf{Set Device Status:} + Use \msgref{SET_DEVICE_STATUS} to drive the device through the standard + virtio status states. \end{enumerate} -This sequence may vary slightly depending on the device's requirements, but it -serves as a common baseline for virtio-msg transport implementations. +The exact order may vary slightly across implementations, but these steps form +the baseline for virtio-msg initialization. + +\drivernormative{\paragraph}{Initialization Flow}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Overview / Driver} +\begin{itemize} + \item A driver MUST issue \msgref{GET_DEVICE_INFO} before attempting feature + negotiation or queue setup. + \item A driver MUST complete feature negotiation via + \msgref{GET_DEVICE_FEATURES}/\msgref{SET_DRIVER_FEATURES} + and confirm the FEATURES\_OK state via \msgref{SET_DEVICE_STATUS} before + enabling virtqueues. + \item A driver MUST configure each virtqueue via \msgref{SET_VQUEUE} and + confirm its parameters (e.g., with \msgref{GET_VQUEUE}) before marking + the queue ready for I/O. + \item A driver MUST drive the device status transitions using + \msgref{SET_DEVICE_STATUS}, ensuring the device reaches DRIVER\_OK + before issuing normal I/O. +\end{itemize} \subsubsection{Device Information} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Information} -Once the bus or driver knows a device number is present, it \emph{SHOULD} send a -\msgref{GET_DEVICE_INFO} to retrieve: +Once a device number is confirmed, the driver uses \msgref{GET_DEVICE_INFO} to +retrieve static identification data (device ID, vendor ID), the number of +feature bits, configuration space size, maximum virtqueues, shared memory +segments, and any admin virtqueue details. This information determines which +virtio driver should bind to the device, how many feature blocks to query, and +how much configuration space is valid. +\drivernormative{\paragraph}{Device Information}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Information / Driver} \begin{itemize} - \item \textbf{Device ID}: Identifies the type of Virtio device (e.g., network, - block, console). - \item \textbf{Vendor ID}: Identifies the vendor or implementation source. - \item \textbf{Number of Feature Bits}: Indicates how many bits (organized in - 32-bit blocks) the device uses for feature negotiation. - \item \textbf{Configuration Size}: The total size (in bytes) of the device's - configuration space. - \item \textbf{Number of virtqueues}: The maximum number of virtqueues the - device supports. - \item \textbf{Number of SHM segments}: The number of device owned - shared memory segments this device has. - \item \textbf{Admin virtqueue starting index}: The virtqueue index for the - first admin virtqueue supported by the device. - \item \textbf{Admin virtqueue count}: The number of admin virtqueues - supported by the device. + \item A driver MUST issue \msgref{GET_DEVICE_INFO} before attempting feature + negotiation or queue setup so it can discover the device ID, vendor ID, + feature count, configuration size, and virtqueue limits. + \item A driver MUST use the configuration size reported via + \msgref{GET_DEVICE_INFO} to bound any offsets and lengths supplied in + \msgref{GET_CONFIG} and \msgref{SET_CONFIG} requests. \end{itemize} -Armed with these details, the driver knows how many feature blocks to query, -what portion of the configuration space is valid, and which OS-level virtio -driver might bind to this device based on the Device ID. - -It also knows of any device owned shared memory segments and any admin -virtqueues supported by the device. - \subsubsection{Feature Negotiation} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Features} -The driver reads the device's available features in \textbf{blocks of 32 bits} -using \msgref{GET_DEVICE_FEATURES}, supplying a \emph{block index} and -\emph{number of blocks} to retrieve. The device responds with the feature bits -in that range, filling any out-of-range blocks with zero. +Drivers read available features in 32-bit blocks using +\msgref{GET_DEVICE_FEATURES}; the device returns the requested bitfields, +padding with zeros for any out-of-range blocks. To enable selected features, the +driver writes them back with \msgref{SET_DRIVER_FEATURES} and then updates the +device status via \msgref{SET_DEVICE_STATUS}, checking whether the FEATURES\_OK +bit remains set. -The driver then determines which features it can or wants to enable. Enabling a -feature requires the driver to set the corresponding bit(s) and send -them back to the device with \msgref{SET_DRIVER_FEATURES}. Once the driver has -set all desired features it tries to set the FEATURES_OK bit in the device status -via the \msgref{SET_DEVICE_STATUS} message. The device may accept or reject the -selected features by returning the new device status with the FEATURES_OK bit -set (accepted) or cleared (rejected). +\drivernormative{\paragraph}{Feature Negotiation}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Features / Driver} +\begin{itemize} + \item A driver MUST use \msgref{GET_DEVICE_FEATURES} to discover the feature + bits offered by the device and MUST write back only the features it + intends to enable via \msgref{SET_DRIVER_FEATURES}. + \item After writing the desired features, the driver MUST attempt to set the + FEATURES\_OK bit using \msgref{SET_DEVICE_STATUS} and MUST check the + returned status to ensure the device accepted the set. +\end{itemize} -If the driver requests blocks beyond the number of feature bits the device -exposes, the device \emph{MUST} respond with all zeros for the unsupported -features. +\devicenormative{\paragraph}{Feature Negotiation}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Features / Device} +\begin{itemize} + \item When handling \msgref{GET_DEVICE_FEATURES}, a device MUST return zero + for any requested bits that fall outside the number of feature bits it + implements. + \item After receiving \msgref{SET_DRIVER_FEATURES}, a device MUST update its + internal feature mask to match the acknowledged set and MUST reflect + acceptance or rejection by leaving the FEATURES\_OK bit set or clearing + it in the status returned by \msgref{SET_DEVICE_STATUS}. +\end{itemize} \subsubsection{Device Configuration} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Configuration} -\paragraph{Reading Configuration} +Drivers use \msgref{GET_CONFIG} to read portions of the configuration space by +supplying an offset and length; the device returns the requested data plus the +current configuration generation count. Writing is performed via +\msgref{SET_CONFIG}, which carries the same offset/length along with the +driver's notion of the generation count and the new data. -The driver can read portions of the device's configuration space using -\msgref{GET_CONFIG}. It supplies: +\drivernormative{\paragraph}{Device Configuration}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Configuration / Driver} \begin{itemize} - \item \textbf{Offset}: The byte offset from the start of the configuration - space, - \item \textbf{Number of bytes}: How many bytes to retrieve. + \item A driver MUST ensure that the offset and length in each + \msgref{GET_CONFIG} or \msgref{SET_CONFIG} request stay within the + configuration size reported by \msgref{GET_DEVICE_INFO}. + \item A driver MUST include its most recently observed configuration + generation count in a \msgref{SET_CONFIG} request and SHOULD re-read the + configuration (via \msgref{GET_CONFIG}) if the request is rejected for a + generation mismatch. \end{itemize} -The device returns the requested data along with the current \emph{Configuration -Generation Count}, which changes each time the device updates its configuration -internally. -\paragraph{Writing Configuration} - -To write a portion of the configuration space, the driver uses -\msgref{SET_CONFIG}, providing: +\devicenormative{\paragraph}{Device Configuration}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Configuration / Device} \begin{itemize} - \item \textbf{Offset} and \textbf{Number of bytes}, - \item \textbf{Configuration generation count} as read earlier, - \item The \textbf{new configuration data} to be written. + \item A device MUST reject a \msgref{SET_CONFIG} request whose generation + count does not match its current value and MUST indicate the rejection + in the response. + \item A device MUST return the current configuration generation count + alongside any data returned via \msgref{GET_CONFIG}. \end{itemize} -If the generation count does not match the device's current value, the device -\emph{MUST} reject the update as defined in the \msgref{SET_CONFIG} response. -The driver \emph{SHOULD} then read the updated configuration space and -reattempt if necessary. - \subsubsection{Virtqueue Configuration} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Initialization / Virtqueue Configuration} -Virtqueues are configured via a set of transport messages: +Drivers query virtqueue parameters with \msgref{GET_VQUEUE}, configure them via +\msgref{SET_VQUEUE}, and optionally reset them using \msgref{RESET_VQUEUE} (if +VIRTIO\_F\_RING\_RESET is negotiated). Each queue is typically configured by +reading its maximum size, provisioning descriptor/available/used buffers, and +then calling \msgref{SET_VQUEUE} with the chosen size and guest-physical +addresses. +\drivernormative{\paragraph}{Virtqueue Configuration}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Virtqueue Configuration / Driver} \begin{itemize} - \item \msgref{GET_VQUEUE} obtains information about a specific virtqueue, - including its maximum size (e.g., number of descriptors) and current - configuration if already set. - \item \msgref{SET_VQUEUE} sets or updates the virtqueue parameters (e.g., - queue size, descriptor area addresses, driver address, device address). - \item \msgref{RESET_VQUEUE} disables and resets the virtqueue, freeing its - resources on the device side. The use of this message is dependent on the - VIRTIO_F_RING_RESET feature being negotiated. + \item A driver MUST use \msgref{GET_VQUEUE} to determine the maximum queue + size and confirm that a queue is inactive before programming it. + \item A driver MUST ensure the queue size provided in \msgref{SET_VQUEUE} does + not exceed the maximum reported by the device and MUST supply valid + descriptor/driver/device addresses before enabling the queue. + \item If VIRTIO\_F\_RING\_RESET has been negotiated and a queue requires + reinitialization, the driver SHOULD use \msgref{RESET_VQUEUE} before + reprogramming it. \end{itemize} -A typical approach is: -\begin{enumerate} - \item \textbf{GET\_VQUEUE}: Determine maximum size and confirm that the queue - is inactive or empty. - \item \textbf{SET\_VQUEUE}: Specify the number of descriptors (not exceeding - the maximum) and the addresses for the descriptor table, driver area, - and device area. -\end{enumerate} - -The driver repeats these steps for each queue the device supports. +\devicenormative{\paragraph}{Virtqueue Configuration}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Virtqueue Configuration / Device} +\begin{itemize} + \item A device MUST report accurate maximum queue sizes in \msgref{GET_VQUEUE} + and MUST persist the parameters supplied via \msgref{SET_VQUEUE} (size, + descriptor, driver, and device addresses). + \item When \msgref{RESET_VQUEUE} is issued (and VIRTIO\_F\_RING\_RESET is + negotiated), the device MUST quiesce the queue, release any resources + associated with it, and allow the driver to reconfigure it. +\end{itemize} \subsubsection{Status Information} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Initialization / Status Information} -During initialization, the driver \emph{MAY} query the device's status via -\msgref{GET_DEVICE_STATUS} to check for errors or to see if the device is ready -for feature negotiation or configuration changes. To advance or reset the -device's state, the driver sends \msgref{SET_DEVICE_STATUS} with the desired -status bits (e.g., "ACKNOWLEDGE," "DRIVER," "DRIVER OK"). Setting the device's -status to 0 triggers a device reset, invalidating configuration and -virtqueues. +Drivers query the device status via \msgref{GET_DEVICE_STATUS} to observe +progress or detect errors, and they drive the Virtio status transitions via +\msgref{SET_DEVICE_STATUS}. Writing zero to the status field resets the device, +invalidating any configuration or virtqueue state. + +\drivernormative{\paragraph}{Status Handling}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Status Information / Driver} +\begin{itemize} + \item A driver SHOULD read the device status via \msgref{GET_DEVICE_STATUS} + when diagnosing errors or determining whether the device is ready to + move to the next initialization phase. + \item A driver MUST use \msgref{SET_DEVICE_STATUS} to drive the device through + the virtio-defined status states and MUST write 0 to request a device + reset when needed. +\end{itemize} + +\devicenormative{\paragraph}{Status Handling}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Status Information / Device} +\begin{itemize} + \item Upon receiving a \msgref{SET_DEVICE_STATUS} write of 0, a device MUST + reset its internal state, invalidate existing configuration and + virtqueue settings, and present the status field as 0. + \item A device MUST report its current status accurately via + \msgref{GET_DEVICE_STATUS}, including whether the FEATURES\_OK bit has + been accepted or cleared. +\end{itemize} \subsubsection{Finalizing Initialization} -Once all virtqueues are configured and any required features have been enabled, -the driver typically sets the final status bits (e.g., "DRIVER OK") via -\msgref{SET_DEVICE_STATUS}. At this point, the device is considered fully -initialized, and normal I/O operations can begin using virtio queues. +After configuring virtqueues and agreeing on features, the driver transitions +the device to DRIVER\_OK (and any other required status bits) via +\msgref{SET_DEVICE_STATUS}. At that point, the device is considered ready for +normal virtqueue I/O. + +\drivernormative{\paragraph}{Final Status}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Finalizing Initialization / Driver} +\begin{itemize} + \item A driver MUST set DRIVER\_OK via \msgref{SET_DEVICE_STATUS} only after + it has completed feature negotiation and initialized all required + virtqueues. + \item A driver MUST NOT queue normal I/O until the device reports a status + that includes DRIVER\_OK. + \item A driver MUST NOT supply buffers or send driver notifications for a + virtqueue until that queue has been configured via \msgref{SET_VQUEUE}. +\end{itemize} + +\devicenormative{\paragraph}{Final Status}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Finalizing Initialization / Device} +\begin{itemize} + \item A device MUST NOT process normal virtqueue I/O until the driver has set + DRIVER\_OK. + \item Once DRIVER\_OK is set, the device MUST begin processing virtqueue + requests subject to the negotiated features and queue configurations. +\end{itemize} \subsection{Device Operation} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Operation} @@ -650,127 +776,187 @@ \subsection{Device Operation} \subsubsection{Driver Notifications} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / Driver Notifications} -After setting up one or more virtqueues, the driver \emph{MUST} send notifications -to signal that new buffers are available for processing. The virtio-msg transport -defines the message, \msgref{EVENT_AVAIL}, that the driver will use to -notify the device of pending buffers. +After buffers are made available to a virtqueue, the driver issues +\msgref{EVENT_AVAIL} to notify the device. A bus implementation may translate +these notifications into an out-of-band mechanism or deliver them in-band. -The driver side bus \emph{MAY} convert them to some form of -out-of-band (OoB) notification. If not using OoB notifications, the driver -side bus \emph{SHOULD} send the messages via the normal message channel. -As a final option, the bus \emph{MAY} discard the messages but only if it knows -that the device will poll the virtqueues directly. +\drivernormative{\paragraph}{Driver Notifications}{Virtio Transport Options / Virtio Over Messages / Device Operation / Driver Notifications / Driver} +\begin{itemize} + \item A driver MUST send \msgref{EVENT_AVAIL} when it places new buffers on a + virtqueue. + \item Each \msgref{EVENT_AVAIL} MUST identify the target virtqueue index. + \item If VIRTIO\_F\_NOTIFICATION\_DATA has been negotiated, the driver MUST + populate the “next offset and wrap” fields so the device can locate the + head of the updated ring; otherwise those fields MUST be zero. +\end{itemize} -\paragraph{EVENT\_AVAIL Usage} +\busnormative{\paragraph}{Driver Notifications}{Virtio Transport Options / Virtio Over Messages / Device Operation / Driver Notifications / Bus} \begin{itemize} - \item \textbf{Virtqueue Index}: Identifies which queue has new buffers. - \item \textbf{Next Offset and Wrap}: If the VIRTIO_F_NOTIFICATION_DATA feature - has been negotiated, the driver \emph{MUST} sets these fields to - indicate the next descriptor offset and wrap state - so the device can jump directly to the updated buffers. - If this features has not been negotiated these fields \emph{MUST} be 0. - \item \textbf{Response}: The \msgref{EVENT_AVAIL} message does not have a - direct response, but the device will subsequently process available - buffers and eventually notify the driver when they are used. + \item A bus implementation MAY convert \msgref{EVENT_AVAIL} into an + out-of-band notification but, if it does not, it MUST relay the message + over the virtio-msg channel. + \item A bus implementation MUST NOT drop \msgref{EVENT_AVAIL} unless it has + arranged for the device to detect new buffers through polling or an + equivalent mechanism. \end{itemize} \subsubsection{Device Notifications} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / Device Notifications} -During normal operation, the driver side bus \emph{MUST} send notifications to -the driver about configuration changes, device status changes, or the -completion of buffers in virtqueues using the messages described below. -These notifications may be the result of: +\msgref{EVENT_CONFIG} and \msgref{EVENT_USED} provide asynchronous notifications +from the device (or device-side bus) to the driver. The bus may forward these +messages in-band or synthesize them based on other signals such as interrupts +or polling. +\devicenormative{\paragraph}{Device Notifications}{Virtio Transport Options / Virtio Over Messages / Device Operation / Device Notifications / Device} \begin{itemize} - \item The same messages received in-band on the message channel from the - device side bus. - \item Manufactured by the driver side bus based on reception of an - out-of-band (OoB) notification from the device side. Example OoB - notifications include things like specific MSIX or other IRQ signals. - \item Manufactured by the device side bus periodically (polling). - This option should be reserved only for situation where nothing else - will work. - \end{itemize} + \item A device (or device-side bus) MUST send \msgref{EVENT_CONFIG} whenever + it makes a configuration change or status update that becomes visible to + the driver. The message MUST include the new configuration generation + count and MAY include the updated configuration data. + \item If the configuration data is omitted from \msgref{EVENT_CONFIG}, the + device SHOULD include the relevant offsets/lengths so the driver can + re-fetch the data via \msgref{GET_CONFIG}. + \item A device SHOULD send \msgref{EVENT_USED} to inform the driver when + buffers on a virtqueue have been consumed, unless the device relies on + an alternative, agreed-upon completion mechanism. +\end{itemize} -\paragraph{EVENT\_CONFIG} +\drivernormative{\paragraph}{Device Notifications}{Virtio Transport Options / Virtio Over Messages / Device Operation / Device Notifications / Driver} \begin{itemize} - \item Sent by the device when a configuration field or device status changes - at runtime. - \item Includes the new \emph{Configuration Generation Count}, current device - status, and optionally the updated portion of the configuration data. - \item If the data is not included, the driver \emph{SHOULD} issue - \msgref{GET_CONFIG} to discover the updated configuration. + \item Upon receiving \msgref{EVENT_CONFIG}, a driver SHOULD update its view of + the configuration using the provided data (or by issuing + \msgref{GET_CONFIG} if necessary) before resuming normal I/O. + \item Upon receiving \msgref{EVENT_USED}, a driver MUST examine the indicated + virtqueue (for example, by reading the used ring) to reclaim completed + buffers. \end{itemize} -\paragraph{EVENT\_USED} +\busnormative{\paragraph}{Device Notifications}{Virtio Transport Options / Virtio Over Messages / Device Operation / Device Notifications / Bus} \begin{itemize} - \item Signifies that one or more buffers in a specific virtqueue have been - processed or consumed by the device and the buffer has been added to the - used ring of the virtqueue. - \item The driver uses normal virtio methods (e.g., reading the "used" ring) to - identify which buffers are complete. - \item If a device does not support sending \msgref{EVENT_USED}, the driver - \emph{MAY} rely on standard virtqueue polling mechanisms to detect - completion. + \item A bus implementation MUST forward \msgref{EVENT_CONFIG} and + \msgref{EVENT_USED} notifications (or their equivalents) to the driver, + either in-band or by synthesizing the appropriate message. + \item If a bus implementation relies on polling or other mechanisms instead of + direct notifications, it SHOULD limit that mode to scenarios where no + other notification method is available. \end{itemize} -These messages enable asynchronous updates from the device. - \subsubsection{Configuration Changes During Operation} -\label{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / ConfigUpdates} +\label{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / Configuration Changes During Operation} -The driver \emph{MAY} issue new \msgref{SET_CONFIG} -messages after initialization if device configuration needs to be -changed at runtime. The device \emph{MAY} also make configuration changes at -runtime and \emph{MUST} signal those changes with \msgref{EVENT_CONFIG} -messages. +Drivers may update configuration fields at runtime using \msgref{SET_CONFIG} +when features such as device modes or limits need to change. Devices can also +update configuration data autonomously but must signal those changes via +\msgref{EVENT_CONFIG}. + +\drivernormative{\paragraph}{Runtime Configuration}{Virtio Transport Options / Virtio Over Messages / Device Operation / Configuration Changes During Operation / Driver} +\begin{itemize} + \item A driver MAY issue \msgref{SET_CONFIG} after initialization, provided it + includes the current configuration generation count and follows the same + validation rules as during setup. + \item Upon receiving an \msgref{EVENT_CONFIG}, the driver SHOULD refresh its + view of the configuration (via the data provided or by reissuing + \msgref{GET_CONFIG}) before relying on the updated values. +\end{itemize} + +\devicenormative{\paragraph}{Runtime Configuration}{Virtio Transport Options / Virtio Over Messages / Device Operation / Configuration Changes During Operation / Device} +\begin{itemize} + \item If a device updates its configuration after initialization, it MUST send + \msgref{EVENT_CONFIG} to inform the driver of the change and provide the + new configuration generation count. +\end{itemize} \subsubsection{Virtqueue Changes During Operation} -\label{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / VQueueUpdates} +\label{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / Virtqueue Changes During Operation} + +Drivers may provision unused virtqueues later in the device lifetime by issuing +\msgref{SET_VQUEUE}, and they may reconfigure existing queues if the +VIRTIO\_F\_RING\_RESET feature has been negotiated. + +\drivernormative{\paragraph}{Runtime Virtqueue Changes}{Virtio Transport Options / Virtio Over Messages / Device Operation / Virtqueue Changes During Operation / Driver} +\begin{itemize} + \item A driver MAY configure additional virtqueues after initialization using + \msgref{SET_VQUEUE}, provided it follows the same validation steps + (e.g., checking the maximum queue size). + \item If VIRTIO\_F\_RING\_RESET is negotiated, the driver SHOULD use + \msgref{RESET_VQUEUE} before reprogramming a queue to avoid races with + the device. +\end{itemize} -The driver \emph{MAY} issue new \msgref{SET_VQUEUE} for virtqueues that have not -yet be setup. If the VIRTIO_F_RING_RESET feature has been negotiated, -individual virtqueues can be reset and then optionally re-configured. +\devicenormative{\paragraph}{Runtime Virtqueue Changes}{Virtio Transport Options / Virtio Over Messages / Device Operation / Virtqueue Changes During Operation / Device} +\begin{itemize} + \item A device MUST honor \msgref{SET_VQUEUE} requests issued after + initialization and update the queue parameters accordingly. + \item When \msgref{RESET_VQUEUE} is received (and VIRTIO\_F\_RING\_RESET is + negotiated), the device MUST quiesce the queue and allow the driver to + reconfigure it without processing stale data. +\end{itemize} \subsubsection{Device Reset and Shutdown} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / Reset} -The driver \emph{MAY} reset or shut down a device at any time by writing a status -of 0 via \msgref{SET_DEVICE_STATUS}. This forces the device to discard its state -and any pending operations on virtqueues. Once a device is reset, the driver -\emph{MAY} reinitialize the device (see -\ref{sec:Virtio Transport Options / Virtio Over Messages / Device Initialization}) -if it wishes to use the device again. - -\paragraph{Device Side Initiated Reset} -In some circumstances, the device \emph{MAY} also trigger a reset if it -encounters an unrecoverable error. This can be signaled to the driver by sending -an \msgref{EVENT_CONFIG} with a \emph{device status} with the DEVICE_NEEDS_RESET -bit set. The driver \emph{SHOULD} reset the device by writing a status of 0 -via the \msgref{SET_DEVICE_STATUS} message. The driver \emph{MAY} reinitialize -the device if it wishes to use the device again. +Drivers reset a device by writing 0 to the status field via \msgref{SET_DEVICE_STATUS}, +which forces the device to discard pending operations and return to the initial state. +A device may also signal that a reset is required by sending \msgref{EVENT_CONFIG} +with the DEVICE\_NEEDS\_RESET bit set. + +\drivernormative{\paragraph}{Reset and Shutdown}{Virtio Transport Options / Virtio Over Messages / Device Operation / Reset / Driver} +\begin{itemize} + \item A driver MAY request a device reset at any time by writing 0 through + \msgref{SET_DEVICE_STATUS} and MAY reinitialize the device afterwards if + it intends to resume operation. + \item If a device signals DEVICE\_NEEDS\_RESET (for example, via + \msgref{EVENT_CONFIG}), the driver SHOULD write 0 to + \msgref{SET_DEVICE_STATUS} and reinitialize the device before resuming + I/O. +\end{itemize} + +\devicenormative{\paragraph}{Reset and Shutdown}{Virtio Transport Options / Virtio Over Messages / Device Operation / Reset / Device} +\begin{itemize} + \item Upon receiving a \msgref{SET_DEVICE_STATUS} write of 0, a device MUST + reset its internal state, discard pending virtqueue operations, and + present the status field as 0. + \item If the device encounters an unrecoverable error that requires driver + intervention, it SHOULD signal DEVICE\_NEEDS\_RESET (such as via + \msgref{EVENT_CONFIG}) so the driver can initiate a reset. +\end{itemize} + +\subsubsection{Hotplug and Removal} +\label{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / Hotplug and Removal} + +If the bus supports dynamic addition or removal of devices, it can advertise +those changes with \busref{EVENT_DEVICE} (READY or REMOVED). Some platforms may +instead rely on external signals such as ACPI, device tree updates, or +hypervisor events; virtio-msg does not mandate a specific mechanism. + +\busnormative{\paragraph}{Hotplug and Removal}{Virtio Transport Options / Virtio Over Messages / Device Operation / Hotplug and Removal / Bus} +\begin{itemize} + \item A bus implementation that uses \busref{EVENT_DEVICE} MUST send the READY + event when a device becomes accessible and the REMOVED event when it is + no longer available. + \item Regardless of how hotplug information is delivered, once a new device is + reported the bus SHOULD query it (e.g., via \msgref{GET_DEVICE_INFO}) + and register it with the host OS. When a device is removed, the bus + SHOULD prompt the OS to quiesce and release the associated driver. +\end{itemize} \subsection{Transport Messages}\label{sec:Virtio Transport Options / Virtio Over Messages / Transport Messages} -Transport messages are used to configure and operate individual virtio devices. -Unlike bus messages (which handle device enumeration, hotplug, or global resets), -transport messages \textbf{MUST} be implemented by any virtio-msg device and -driver pair to enable standard virtio functionality (feature negotiation, -configuration, virtqueues, etc.). The subsections below describe each message -and clarify its required fields, typical usage patterns, and possible responses. +Transport messages configure and operate virtio devices once they have been +discovered. Unlike bus messages (which cover enumeration or hotplug), transport +messages focus on feature negotiation, configuration access, virtqueue setup, +and runtime notifications. The subsections below describe each message and how +it is used in the virtio-msg transport. \subsubsection{Overview} \label{sec:Virtio Transport Options / Virtio Over Messages / Transport Messages / Overview} -A driver typically sends these messages to a known device number, -and the virtio-msg device responds or notifies as appropriate. The -bus \emph{forwards} these messages but does not interpret or modify them beyond -basic checks (e.g., ensuring the size does not exceed the maximum size -supported, verifying the target device number exists). - -Most transport messages adopt a \emph{request/response} pattern, but some are -unidirectional (e.g., asynchronous notifications). +Drivers send transport messages to a specific device number, and the virtio-msg +device replies or emits events accordingly. The bus simply forwards these +messages after enforcing generic checks such as maximum size or verifying that +the target device exists. Most transport messages are request/response pairs, +with events reserved for asynchronous notifications. \paragraph{Messages IDs and issuers} @@ -813,331 +999,490 @@ \subsubsection{Overview} \hline \end{tabular} -Transport message IDs 0x00 to 0x3F are used for messages that require a response -and IDs 0x40 to 0x7F are used for event messages. Transport message IDs 0x80 -and above are reserved by this specification. +IDs are grouped as follows; bit 6 distinguishes requests (0) from events (1): -\paragraph{Mandatory Transport Messages} -For a virtio-msg device to be fully operational, the following messages -\textbf{MUST} be supported: +\begin{tabular}{|l|l|p{7cm}|} +\hline +Range & Usage & Notes \\ +\hline +0x00-0x3F & Request/Response & Standard transport requests that expect responses. \\ +0x40-0x7F & Events & Standard transport events (no response). \\ +0x80-0xBF & Implementation-defined Requests & Optional, transport-specific request extensions. \\ +0xC0-0xFF & Implementation-defined Events & Optional, transport-specific event extensions. \\ +\hline +\end{tabular} + +\devicenormative{\paragraph}{Core Messages}{Virtio Transport Options / Virtio Over Messages / Transport Messages / Mandatory / Device} \begin{itemize} - \item \msgref{GET_DEVICE_INFO} - \item \msgref{GET_DEVICE_FEATURES} and \msgref{SET_DRIVER_FEATURES} - \item \msgref{GET_CONFIG} and \msgref{SET_CONFIG} - \item \msgref{GET_DEVICE_STATUS} and \msgref{SET_DEVICE_STATUS} - \item \msgref{GET_VQUEUE}, \msgref{SET_VQUEUE}, and \msgref{RESET_VQUEUE} + \item A device MUST implement \msgref{GET_DEVICE_INFO}, + \msgref{GET_DEVICE_FEATURES}, \msgref{SET_DRIVER_FEATURES}, + \msgref{GET_CONFIG}, \msgref{SET_CONFIG}, \msgref{GET_DEVICE_STATUS}, + \msgref{SET_DEVICE_STATUS}, \msgref{GET_VQUEUE}, \msgref{SET_VQUEUE}, + and \msgref{RESET_VQUEUE}. \end{itemize} -The functionality of the following messages \textbf{MUST} be provided by -in-band messages, out-of-band event notification, or bus implementation based -polling: +\drivernormative{\paragraph}{Core Messages}{Virtio Transport Options / Virtio Over Messages / Transport Messages / Mandatory / Driver} \begin{itemize} - \item \msgref{EVENT_AVAIL} - \item \msgref{EVENT_USED} - \item \msgref{EVENT_CONFIG} + \item A driver MUST support sending and interpreting the messages listed + above in order to initialize and operate a virtio-msg device. \end{itemize} -\newcommand{\msgdef}[1]{\subsubsection{VIRTIO_MSG_#1}\label{sec:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_#1}} +As described in Sections +\ref{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / Driver Notifications} +and +\ref{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / Device Notifications}, +runtime notifications (\msgref{EVENT_AVAIL}, \msgref{EVENT_USED}, and +\msgref{EVENT_CONFIG}) may be delivered in-band or via equivalent out-of-band +mechanisms. \msgdef{GET_DEVICE_INFO} -This message is sent by the virtio-msg transport driver and requires a -response from the device. +The driver issues \msgref{GET_DEVICE_INFO} to discover static identification +data and limits for a device. It is the only transport message permitted before +the device transitions out of the inactive state. -\begin{tabular}{|l|l|l|l|} -\hline -Type & Offset & Size (bytes) & Content \\ -\hline \hline -Request & 0 & 0 & None \\ -\hline -Answer & 0 & 4 & Device ID \\ -& 4 & 4 & Vendor ID \\ -& 8 & 4 & Number of feature bits \\ -& 12 & 4 & Configuration size in bytes \\ -& 16 & 4 & Maximum number of virtqueues \\ -& 20 & 2 & Admin virtqueue start index \\ -& 22 & 2 & Admin virtqueue count \\ -\hline -\end{tabular} +\begin{lstlisting} +struct virtio_msg_get_device_info_req { + /* no payload */ +}; -The number of feature bits must be a multiple of 32. +struct virtio_msg_get_device_info_resp { + le32 device_id; /* virtio device type */ + le32 vendor_id; /* implementation-defined vendor ID */ + le32 num_feature_bits; /* total feature bits (multiples of 32) */ + le32 config_size; /* bytes in the device configuration space */ + le32 max_virtqueues; /* maximum virtqueues supported */ + le16 admin_vq_start; /* index of the first admin virtqueue */ + le16 admin_vq_count; /* number of admin virtqueues */ +}; +\end{lstlisting} -This is the only message allowed for an inactive device. If this message queries -an inactive device all fields in the response should be 0. +\devicenormative{\paragraph}{GET\_DEVICE\_INFO}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_DEVICE_INFO / Device} +\begin{itemize} + \item A device MUST respond to \msgref{GET_DEVICE_INFO} while inactive and + MUST supply consistent values for device ID, vendor ID, feature count (a + multiple of 32 bits), configuration size, and virtqueue limits. +\end{itemize} + +\drivernormative{\paragraph}{GET\_DEVICE\_INFO}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_DEVICE_INFO / Driver} +\begin{itemize} + \item A driver SHOULD treat the response as the authoritative source for + feature count, configuration size, and virtqueue limits before + proceeding with initialization. +\end{itemize} \msgdef{GET_DEVICE_FEATURES} -This message is sent by the virtio-msg transport driver and requires a -response from the device. +Drivers retrieve device feature bits in 32-bit blocks via +\msgref{GET_DEVICE_FEATURES}; the response echoes the requested block index and +returns one or more 32-bit values with the feature bits in that range. -\begin{tabular}{|l|l|l|l|} -\hline -Type & Offset & Size (bytes) & Content \\ -\hline \hline -Request & 0 & 4 & Feature block index \\ -& 4 & 4 & Number of feature blocks \\ -\hline -Answer & 0 & 4 & Feature block index \\ -& 4 & 4 & Number of feature blocks \\ -& 8 & ... & Feature data \\ -\hline -\end{tabular} +\begin{lstlisting} +struct virtio_msg_get_device_features_req { + le32 block_index; /* starting block (0 == bits 0-31) */ + le32 num_blocks; /* number of 32-bit blocks requested */ +}; + +struct virtio_msg_get_device_features_resp { + le32 block_index; /* echoed starting block */ + le32 num_blocks; /* echoed number of blocks */ + le32 features[]; /* num_blocks entries, zero-padded if needed */ +}; +\end{lstlisting} -A feature block is a group of 32 bits. The feature data \emph{MUST} be a -multiple of 4 bytes in length. +\devicenormative{\paragraph}{GET\_DEVICE\_FEATURES}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_DEVICE_FEATURES / Device} +\begin{itemize} + \item A device MUST return zero for any feature bits beyond those it + implements when responding to \msgref{GET_DEVICE_FEATURES}. +\end{itemize} + +\drivernormative{\paragraph}{GET\_DEVICE\_FEATURES}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_DEVICE_FEATURES / Driver} +\begin{itemize} + \item A driver MUST treat the returned data as 32-bit feature blocks starting + at the requested index, padding with zeros as needed, before deciding + which features to enable. +\end{itemize} \msgdef{SET_DRIVER_FEATURES} -This message is sent by the virtio-msg transport driver and requires a -response from the device. +Drivers use \msgref{SET_DRIVER_FEATURES} to acknowledge the subset of feature +bits they wish to enable. The payload mirrors \msgref{GET_DEVICE_FEATURES}, +supplying an index, count, and 32-bit feature data for the selected blocks. -\begin{tabular}{|l|l|l|l|} -\hline -Type & Offset & Size (bytes) & Content \\ -\hline \hline -Request & 0 & 4 & Feature block index \\ -& 4 & 4 & Number of feature blocks \\ -& 8 & ... & Feature data \\ -\hline -Answer & 0 & 0 & no extra data \\ -\hline -\end{tabular} +\begin{lstlisting} +struct virtio_msg_set_driver_features_req { + le32 block_index; /* starting block being acknowledged */ + le32 num_blocks; /* number of blocks provided */ + le32 features[]; /* num_blocks entries with desired bits */ +}; + +struct virtio_msg_set_driver_features_resp { + /* no payload */ +}; +\end{lstlisting} -A feature block is a group of 32 bits. The feature data \emph{MUST} be a -multiple of 4 bytes in length. +\drivernormative{\paragraph}{SET\_DRIVER\_FEATURES}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_DRIVER_FEATURES / Driver} +\begin{itemize} + \item A driver MUST set only the feature bits it intends to enable in the + blocks supplied to \msgref{SET_DRIVER_FEATURES}. +\end{itemize} -Note: As defined in \ref{sec:Basic Facilities of a Virtio Device / Feature Bits}, -if the device is not OK with the features set, it \emph{MUST} not allow -the FEATURES_OK bit in the device status to be set. +\devicenormative{\paragraph}{SET\_DRIVER\_FEATURES}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_DRIVER_FEATURES / Device} +\begin{itemize} + \item After processing \msgref{SET_DRIVER_FEATURES}, a device MUST update its + acknowledged feature set to match the data supplied and MUST report that + set consistently in subsequent \msgref{GET_DEVICE_FEATURES} responses. + If it cannot support the requested set, it SHOULD clear the FEATURES\_OK + bit in the device status. +\end{itemize} \msgdef{GET_CONFIG} -This message is sent by the virtio-msg transport driver and requires a -response from the device. +\msgref{GET_CONFIG} reads a portion of the configuration space. The request +specifies the byte offset and length; the response echoes those values, returns +the data, and includes the current configuration generation count. -\begin{tabular}{|l|l|l|l|} -\hline -Type & Offset & Size (bytes) & Content \\ -\hline \hline -Request & 0 & 4 & Configuration offset in bytes \\ -& 4 & 4 & Number of bytes \\ -\hline -Answer & 0 & 4 & Configuration generation count \\ -& 4 & 4 & Configuration offset in bytes \\ \\ -& 8 & 4 & Number of bytes \\ -& 12 & ... & Configuration data \\ -\hline -\end{tabular} +\begin{lstlisting} +struct virtio_msg_get_config_req { + le32 offset; /* byte offset into configuration space */ + le32 length; /* number of bytes requested */ +}; + +struct virtio_msg_get_config_resp { + le32 generation; /* current configuration generation count */ + le32 offset; /* echoed offset */ + le32 length; /* echoed length */ + u8 data[]; /* configuration payload */ +}; +\end{lstlisting} + +\drivernormative{\paragraph}{GET\_CONFIG}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_CONFIG / Driver} +\begin{itemize} + \item A driver MUST ensure the requested offset and length in \msgref{GET_CONFIG} + stay within the configuration size reported by \msgref{GET_DEVICE_INFO}. +\end{itemize} + +\devicenormative{\paragraph}{GET\_CONFIG}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_CONFIG / Device} +\begin{itemize} + \item A device MUST return the current configuration generation count with + every \msgref{GET_CONFIG} response. +\end{itemize} \msgdef{SET_CONFIG} -This message is sent by the virtio-msg transport driver and requires a -response from the device. +\msgref{SET_CONFIG} writes a portion of configuration space, supplying the +offset, length, the driver's view of the generation count, and the new data. +The device echoes the offset/length, returns the resulting generation count, +and may mirror the applied data or set the length to zero if the write was +rejected. -\begin{tabular}{|l|l|l|l|} -\hline -Type & Offset & Size (bytes) & Content \\ -\hline \hline -Request & 0 & 4 & Configuration generation count \\ -& 4 & 4 & Configuration offset in bytes \\ -& 8 & 4 & Number of bytes \\ -& 12 & ... & Configuration data \\ -\hline -Answer & 0 & 4 & New Configuration generation count \\ -& 4 & 4 & Configuration offset in bytes \\ -& 8 & 4 & Number of bytes, or 0 if rejected \\ -& 12 & ... & Configuration data \\ -\hline -\end{tabular} +\begin{lstlisting} +struct virtio_msg_set_config_req { + le32 generation; /* driver's view of generation count */ + le32 offset; /* byte offset being written */ + le32 length; /* number of bytes written */ + u8 data[]; /* configuration payload */ +}; -See \ref{sec:Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Configuration} -for details about rejection and for new data not equal to written data. +struct virtio_msg_set_config_resp { + le32 generation; /* resulting generation count */ + le32 offset; /* echoed offset */ + le32 length; /* bytes applied (0 if rejected) */ + u8 data[]; /* optional echoed data */ +}; +\end{lstlisting} + +\drivernormative{\paragraph}{SET\_CONFIG}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_CONFIG / Driver} +\begin{itemize} + \item A driver MUST include its most recent configuration generation count in + each \msgref{SET_CONFIG} request and MUST keep the offset and length + within the reported configuration size. +\end{itemize} + +\devicenormative{\paragraph}{SET\_CONFIG}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_CONFIG / Device} +\begin{itemize} + \item A device MUST reject a \msgref{SET_CONFIG} request if the supplied + generation count does not match its current value and MUST report that + rejection in the response. +\end{itemize} \msgdef{GET_DEVICE_STATUS} -This message is sent by the virtio-msg transport driver and requires a -response from the device. +\msgref{GET_DEVICE_STATUS} reads the current device status (e.g., ACKNOWLEDGE, +DRIVER, DRIVER\_OK, FEATURES\_OK, or DEVICE\_NEEDS\_RESET bits). The request has +no payload; the response returns the 32-bit status value. -\begin{tabular}{|l|l|l|l|} -\hline -Type & Offset & Size (bytes) & Content \\ -\hline \hline -Request & 0 & 0 & None \\ -\hline -Answer & 0 & 4 & Device status \\ -\hline -\end{tabular} +\begin{lstlisting} +struct virtio_msg_get_device_status_req { + /* no payload */ +}; + +struct virtio_msg_get_device_status_resp { + le32 status; /* current device status bits */ +}; +\end{lstlisting} + +\devicenormative{\paragraph}{GET\_DEVICE\_STATUS}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_DEVICE_STATUS / Device} +\begin{itemize} + \item A device MUST report its current status accurately via + \msgref{GET_DEVICE_STATUS}, including whether FEATURES\_OK or + DEVICE\_NEEDS\_RESET are set. +\end{itemize} \msgdef{SET_DEVICE_STATUS} -This message is sent by the virtio-msg transport driver and requires a -response from the device. +\msgref{SET_DEVICE_STATUS} writes a new device status value. Drivers use it to +progress through the virtio-defined states or to request a reset by writing 0. +The device responds with its resulting status, which may differ (for example, +if it refuses FEATURES\_OK or sets DEVICE\_NEEDS\_RESET). -\begin{tabular}{|l|l|l|l|} -\hline -Type & Offset & Size (bytes) & Content \\ -\hline \hline -Request & 0 & 4 & Device status \\ -\hline -Answer & 0 & 4 & New device status \\ -\hline -\end{tabular} +\begin{lstlisting} +struct virtio_msg_set_device_status_req { + le32 status; /* desired device status value */ +}; + +struct virtio_msg_set_device_status_resp { + le32 status; /* resulting device status */ +}; +\end{lstlisting} + +\drivernormative{\paragraph}{SET\_DEVICE\_STATUS}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_DEVICE_STATUS / Driver} +\begin{itemize} + \item A driver MUST write 0 via \msgref{SET_DEVICE_STATUS} to request a device + reset and MUST re-read the status (e.g., via \msgref{GET_DEVICE_STATUS}) + if it needs to confirm acceptance. +\end{itemize} -The resulting device status is returned and may not match the status set. The -device may set the DEVICE_NEEDS_RESET bit if it has an issue. The device may -refuse to set the FEATURES_OK bit if it cannot operate with the features set -by the driver. +\devicenormative{\paragraph}{SET\_DEVICE\_STATUS}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_DEVICE_STATUS / Device} +\begin{itemize} + \item A device MAY clear FEATURES\_OK or set DEVICE\_NEEDS\_RESET in its + response if it cannot accept the requested status, but it MUST report + the resulting status accurately. +\end{itemize} \msgdef{GET_VQUEUE} -This message is sent by the virtio-msg transport driver and requires a -response from the device. +\msgref{GET_VQUEUE} returns information about a specific virtqueue, including +its maximum size, current size, and, if already configured, the descriptor, +driver, and device area addresses. -\begin{tabular}{|l|l|l|l|} -\hline -Type & Offset & Size (bytes) & Content \\ -\hline \hline -Request & 0 & 4 & Virtqueue index \\ -\hline -Answer & 0 & 4 & Virtqueue index \\ -& 4 & 4 & Maximum virtqueue size \\ -& 8 & 4 & Current virtqueue size \\ -& 12 & 4 & Reserved (Must Be Zero - MBZ) \\ -& 16 & 8 & Descriptor address \\ -& 24 & 8 & Driver address \\ -& 32 & 8 & Device address \\ -\hline -\end{tabular} +\begin{lstlisting} +struct virtio_msg_get_vqueue_req { + le32 index; /* virtqueue index */ +}; -If the maximum virtqueue size is zero, the virtqueue is not valid and -\emph{MUST} not be used. +struct virtio_msg_get_vqueue_resp { + le32 index; /* echoed virtqueue index */ + le32 max_size; /* maximum queue size */ + le32 cur_size; /* current size (0 if unconfigured) */ + le32 reserved; /* must be zero */ + le64 desc_addr; /* descriptor area address */ + le64 driver_addr; /* driver area address */ + le64 device_addr; /* device area address */ +}; +\end{lstlisting} + +\devicenormative{\paragraph}{GET\_VQUEUE}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_VQUEUE / Device} +\begin{itemize} + \item A device MUST report accurate maxima and current queue sizes for each + virtqueue and MUST return zero as the current size if the queue has not + yet been configured. +\end{itemize} \msgdef{SET_VQUEUE} -This message is sent by the virtio-msg transport driver and requires a -response from the device. +\msgref{SET_VQUEUE} programs a virtqueue's size and buffer addresses. The driver +selects a queue index, supplies the desired size (not exceeding the maximum +reported via \msgref{GET_VQUEUE}), and provides guest-physical addresses for the +descriptor, driver, and device areas. -\begin{tabular}{|l|l|l|l|} -\hline -Type & Offset & Size (bytes) & Content \\ -\hline \hline -Request & 0 & 4 & Virtqueue index \\ -& 4 & 4 & Reserved (Must Be Zero - MBZ) \\ -& 8 & 4 & Current virtqueue size \\ -& 12 & 4 & Reserved (Must Be Zero - MBZ) \\ -& 16 & 8 & Descriptor address \\ -& 24 & 8 & Driver address \\ -& 32 & 8 & Device address \\ -\hline -Answer & 0 & 0 & no extra data \\ -\hline -\end{tabular} +\begin{lstlisting} +struct virtio_msg_set_vqueue_req { + le32 index; /* virtqueue index */ + le32 reserved0; /* must be zero */ + le32 size; /* number of descriptors */ + le32 reserved1; /* must be zero */ + le64 desc_addr; /* descriptor area address */ + le64 driver_addr; /* driver area address */ + le64 device_addr; /* device area address */ +}; + +struct virtio_msg_set_vqueue_resp { + /* no payload */ +}; +\end{lstlisting} + +\drivernormative{\paragraph}{SET\_VQUEUE}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_VQUEUE / Driver} +\begin{itemize} + \item A driver MUST set the virtqueue size field to a value not exceeding the + maximum reported by \msgref{GET_VQUEUE} and MUST ensure the supplied + addresses point to properly aligned memory. +\end{itemize} + +\devicenormative{\paragraph}{SET\_VQUEUE}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_VQUEUE / Device} +\begin{itemize} + \item A device MUST configure the queue using the parameters provided via + \msgref{SET_VQUEUE} and treat the queue as inactive until + \msgref{SET_VQUEUE} has successfully completed. +\end{itemize} \msgdef{RESET_VQUEUE} -This message is sent by the virtio-msg transport driver and requires a -response from the device. +\msgref{RESET_VQUEUE} resets an individual virtqueue (if VIRTIO\_F\_RING\_RESET +has been negotiated). It requires only the queue index; the device responds +after the queue has been quiesced. -The driver \emph{SHOULD NOT} send this message unless the VIRTIO_F_RING_RESET -feature has been negotiated. +\begin{lstlisting} +struct virtio_msg_reset_vqueue_req { + le32 index; /* virtqueue index */ +}; -\begin{tabular}{|l|l|l|l|} -\hline -Type & Offset & Size (bytes) & Content \\ -\hline \hline -Request & 0 & 4 & Virtqueue index \\ -\hline -Answer & 0 & 0 & no extra data \\ -\hline -\end{tabular} +struct virtio_msg_reset_vqueue_resp { + /* no payload */ +}; +\end{lstlisting} + +\drivernormative{\paragraph}{RESET\_VQUEUE}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_RESET_VQUEUE / Driver} +\begin{itemize} + \item A driver SHOULD issue \msgref{RESET_VQUEUE} only if + VIRTIO\_F\_RING\_RESET has been negotiated and it needs to reconfigure + or recover a specific queue. +\end{itemize} + +\devicenormative{\paragraph}{RESET\_VQUEUE}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_RESET_VQUEUE / Device} +\begin{itemize} + \item Upon receiving \msgref{RESET_VQUEUE}, a device MUST stop processing the + indicated queue, reset its internal state for that queue, and allow the + driver to reconfigure it via \msgref{SET_VQUEUE}. +\end{itemize} \msgdef{GET_SHM} -This message is sent by the virtio-msg transport driver and requires a -response from the device. +\msgref{GET_SHM} returns the location and size of a device-owned shared memory +region. The request carries the region index; the response echoes the index and +provides the base address and length. A length of zero indicates that the +specified region does not exist. -\begin{tabular}{|l|l|l|l|} -\hline -Type & Offset & Size (bytes) & Content \\ -\hline \hline -Request & 0 & 4 & Shared memory region index \\ -\hline -Answer & 0 & 4 & Shared memory region index \\ -& 4 & 4 & Shared memory region length \\ -& 8 & 4 & Shared memory region address \\ -\hline -\end{tabular} +\begin{lstlisting} +struct virtio_msg_get_shm_req { + le32 index; /* shared memory region index */ +}; -If the returned shared memory region length is zero, the memory region does not -exist. +struct virtio_msg_get_shm_resp { + le32 index; /* echoed index */ + le32 length; /* region length (0 if nonexistent) */ + le32 address;/* region address */ +}; +\end{lstlisting} -Note: these shared memory regions are device owned and supported on other virtio -transports since virtio v1.3. These shared memory regions are separate and -distinct from any shared memory regions defined by the bus implementation. +\devicenormative{\paragraph}{GET\_SHM}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_SHM / Device} +\begin{itemize} + \item A device MUST return zero length if the requested shared memory region + does not exist and MUST report accurate address/length information for + regions it supports. +\end{itemize} \msgdef{EVENT_CONFIG} -This message is sent by the virtio-msg device and there is no response. +\msgref{EVENT_CONFIG} notifies the driver about configuration or status changes. +The payload includes the current device status, configuration generation count, +and optionally the updated configuration data (offset plus length). A length of +zero indicates that the driver should re-fetch the affected range via +\msgref{GET_CONFIG}. -\begin{tabular}{|l|l|l|l|} -\hline -Type & Offset & Size (bytes) & Content \\ -\hline \hline -Request & 0 & 4 & Device status \\ -& 4 & 4 & Configuration generation count \\ -& 8 & 4 & Configuration offset \\ -& 12 & 4 & Number of bytes (\emph{MAY} be zero) \\ -& 16 & ... & Configuration data \\ -\hline -\end{tabular} +\begin{lstlisting} +struct virtio_msg_event_config { + le32 device_status; /* new device status value */ + le32 generation; /* configuration generation count */ + le32 offset; /* configuration offset */ + le32 length; /* number of bytes (may be zero) */ + u8 data[]; /* optional configuration data */ +}; +\end{lstlisting} -The number of bytes field \emph{MAY} be zero. If so the configuration data field -will also be of zero length. This is the normal case when the configuration -generation count has not been changed. +\drivernormative{\paragraph}{EVENT\_CONFIG}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_CONFIG / Driver} +\begin{itemize} + \item When \msgref{EVENT_CONFIG} provides configuration data, the driver + SHOULD apply it; otherwise it SHOULD re-read the affected range via + \msgref{GET_CONFIG} before proceeding. +\end{itemize} -If the number of bytes field is zero and the configuration generation count is -changed, then the driver is responsible for discovering any changed -configuration data via \msgref{GET_CONFIG} messages. +\devicenormative{\paragraph}{EVENT\_CONFIG}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_CONFIG / Device} +\begin{itemize} + \item A device MUST send \msgref{EVENT_CONFIG} whenever it changes + configuration data or status in a way that is visible to the driver, + including the new configuration generation count. +\end{itemize} \msgdef{EVENT_AVAIL} -This message is sent by the virtio-msg driver and there is no response. +\msgref{EVENT_AVAIL} notifies the device that a virtqueue has new buffers. The +message includes the queue index and, if VIRTIO\_F\_NOTIFICATION\_DATA is +negotiated, a combined next-offset/next-wrap field so the device can jump +directly to the updated position. Otherwise that field is zero. -\begin{tabular}{|l|l|l|l|} -\hline -Type & Offset & Size (bytes) & Content \\ -\hline \hline -Request & 0 & 4 & Virtqueue index \\ -& 4 & 4 & Next offset and Next wrap \\ -\hline -\end{tabular} +\begin{lstlisting} +struct virtio_msg_event_avail { + le32 vq_index; /* virtqueue index */ + le32 next_offset; /* bits[30:0] offset, bit[31] wrap; zero if unused */ +}; +\end{lstlisting} + +\drivernormative{\paragraph}{EVENT\_AVAIL}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_AVAIL / Driver} +\begin{itemize} + \item If VIRTIO\_F\_NOTIFICATION\_DATA has not been negotiated, a driver MUST + set the next offset/wrap field to zero in \msgref{EVENT_AVAIL} messages. + If it has been negotiated, the driver MUST fill in the field with the + current available ring position. +\end{itemize} -The \textbf{Next wrap} field is the MSB of the 32 bit value. The -\textbf{Next offset} field is the other 31 bits. These fields should be 0 if -the VIRTIO_F_NOTIFICATION_DATA feature has not been negotiated. If the bus -implementation is using out-of-band notifications, it should prevent this -feature from being negotiated. +\busnormative{\paragraph}{EVENT\_AVAIL}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_AVAIL / Bus} +\begin{itemize} + \item A bus implementation that uses out-of-band notifications SHOULD prevent + negotiation of VIRTIO\_F\_NOTIFICATION\_DATA so that devices do not + expect in-band offset/wrap values. +\end{itemize} \msgdef{EVENT_USED} -This message is sent by the virtio-msg device and there is no response. +\msgref{EVENT_USED} notifies the driver that buffers on a particular virtqueue +have been consumed. The payload carries only the queue index; the driver uses +its used ring to determine which descriptors completed. -\begin{tabular}{|l|l|l|l|} -\hline -Type & Offset & Size (bytes) & Content \\ -\hline \hline -Request & 0 & 4 & Virtqueue index \\ -\hline -\end{tabular} +\begin{lstlisting} +struct virtio_msg_event_used { + le32 vq_index; /* virtqueue index */ +}; +\end{lstlisting} + +\devicenormative{\paragraph}{EVENT\_USED}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_USED / Device} +\begin{itemize} + \item A device SHOULD send \msgref{EVENT_USED} (or an equivalent notification) + when it processes buffers on a virtqueue unless the driver has + explicitly disabled such notifications. +\end{itemize} + +\drivernormative{\paragraph}{EVENT\_USED}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_USED / Driver} +\begin{itemize} + \item Upon receiving \msgref{EVENT_USED}, a driver MUST examine the indicated + virtqueue (for example, by reading the used ring) to reclaim completed + buffers. +\end{itemize} \subsection{Bus Messages}\label{sec:Virtio Transport Options / Virtio Over Messages / Bus Messages} -The bus messages defined in this specification facilitate device discovery, -hotplug management, and liveness checks at the bus level. -They are intended for bus implementations that wish to perform these operations -\emph{via virtio-msg} rather than relying exclusively on external means (e.g., -firmware tables, device trees). Each bus instance \emph{may} use a subset of or -all these messages according to its design. +Bus messages cover device discovery, hotplug notifications, and bus-level +liveness checks. Implementations that already provide equivalent functionality +through platform mechanisms (e.g., ACPI, device tree, hypervisor events) may +reuse that infrastructure instead of the messages defined here. The following +subsections describe standardized bus messages that virtio-msg supports today. + +\subsubsection{Overview} +\label{sec:Virtio Transport Options / Virtio Over Messages / Bus Messages / Overview} + +Each bus implementation chooses which of these messages to support. Some may +implement all of them for a fully message-based workflow, while others may rely +on out-of-band enumeration and use only the subset that fits their needs. \paragraph{Messages IDs and issuers} @@ -1158,255 +1503,138 @@ \subsection{Bus Messages}\label{sec:Virtio Transport Options / Virtio Over Messa \hline \end{tabular} -Bus message IDs below 0x80 are reserved for standardized (but optional) bus -messages. A few are used here and more are expected in the future. Bus message -IDs below 0x40 are used for request/response messages and 0x40 and above for -event messages. - -Bus message IDs 0x80 and above are bus implementation specific. Bus -implementations \emph{MAY} specify the policy that IDs below 0xC0 be used -for request/response messages and IDs 0xC0 and above are used for event messages. +Bus message IDs are grouped as follows: -\paragraph{Note:} A bus implementation \textbf{is not required} to use these -messages if it already provides equivalent functionality through some -platform-specific mechanism. However, if a bus chooses to handle enumeration, -hotplug, etc. via virtio-msg, it \emph{should} implement the corresponding -message definitions below. - -\newcommand{\busdef}[1]{\subsubsection{BUS_MSG_#1}\label{sec:Virtio Transport Options / Virtio Over Messages / Bus Messages / BUS_MSG_#1}} - -\busdef{GET_DEVICES} - -This message is sent by the virtio-msg driver side bus and requires a response -from the device side bus. - -\begin{tabular}{|l|l|l|l|} -\hline -Type & Offset & Size (bytes) & Content \\ -\hline \hline -Request & 0 & 2 & Offset \\ - & 2 & 2 & Number of device numbers requested \\ +\begin{tabular}{|l|l|p{7cm}|} \hline -Answer & 0 & 2 & Offset \\ - & 2 & 2 & Number of device numbers in the answer \\ - & 4 & 2 & Next offset or 0 if no devices after Offset \\ - & 6 & .. & Bit[n]: Device[offset + n] not available(0)/available(1) \\ +Range & Usage & Notes \\ \hline -\end{tabular} - -The offset and number of device numbers requested \emph{MUST} be multiples of 8. -The next offset \emph{MUST} also be a multiple of 8. -The device available data is packed into a sequence of bytes with the first -device in the least significant bit of the first byte, the eighth device in -the most significant bit of the first byte, etc. - -\busdef{EVENT_DEVICE} - -This message is sent by the virtio-msg device side bus and there is no response. - -\begin{tabular}{|l|l|l|l|} -\hline -Type & Offset & Size (bytes) & Content \\ -\hline \hline -Request & 0 & 2 & Device Number \\ - & 2 & 2 & Device Bus State \\ +0x00-0x3F & Request/Response & Standardized bus request messages. \\ +0x40-0x7F & Events & Standardized bus event messages. \\ +0x80-0xBF & Implementation-defined Requests & Optional, bus-specific request messages. \\ +0xC0-0xFF & Implementation-defined Events & Optional, bus-specific event messages. \\ \hline \end{tabular} -\begin{tabular}{|l|l|l|} -\hline -Device Bus State & Value & Meaning \\ -\hline -\hline -DEVICE_BUS_STATE_READY & 0x1 & Device is present and ready \\ -\hline -DEVICE_BUS_STATE_REMOVED & 0x2 & Device is no longer present \\ -\hline -reserved & 0x3 to 0x7FFF & Reserved for standard use \\ -\hline -any & 0x8000 to 0xFFFF & may be used by bus implementations \\ -\hline -\end{tabular} - -This event is sent when the bus level state of the device has changed. -It can indicate when a device is added or removed. It may also be used by -bus implementations to indicate other states. - -\busdef{PING} - -This message is sent by the virtio-msg driver side bus or device side bus and -requires a response. +\paragraph{Bus Specific Messages} +\label{sec:Virtio Transport Options / Virtio Over Messages / Bus Operation / Bus Specific Messages} -\begin{tabular}{|l|l|l|l|} -\hline -Type & Offset & Size (bytes) & Content \\ -\hline \hline -Request & 0 & 4 & Data \\ -\hline -Answer & 0 & 4 & Request Data \\ -\hline -\end{tabular} +A range of message IDs are reserved for use by the specific bus +implementation. These messages can be used for any implementation specific +usage. Example usage could include: -\subsection{Compliance} -\label{sec:Virtio Transport Options / Virtio Over Messages / Compliance} +\begin{itemize} + \item Configuration of out-of-band notification methods + \item Setup shared memory regions to be used for buffers or virtqueues + \item Declare bus specific error conditions + \item Provide extra debug or logging information +\end{itemize} -This section details the requirements that an implementation \emph{MUST} meet to -be considered compliant with the virtio-msg transport. It distinguishes between -\emph{mandatory} behaviors that all implementations \emph{MUST} support and -\emph{optional} behaviors that are permissible but not required. +\busdef{GET_DEVICES} -\subsubsection{Normative References} -\label{sec:Virtio Transport Options / Virtio Over Messages / Compliance / NormativeRefs} -The terms \textbf{MUST}, \textbf{MUST NOT}, \textbf{SHOULD}, \textbf{SHOULD NOT}, -and \textbf{MAY} in this document are to be interpreted as specified by -\href{https://www.rfc-editor.org/rfc/rfc2119}{RFC 2119}. +The driver-side bus uses this request to enumerate device numbers on the +device-side bus. The response describes a “window” of device numbers and signals +which entries are present. -\subsubsection{Mandatory Requirements} -\label{sec:Virtio Transport Options / Virtio Over Messages / Compliance / Mandatory} +\begin{lstlisting} +struct virtio_bus_msg_get_devices_req { + le16 offset; /* starting device number */ + le16 count; /* number of device-number slots (multiple of 8) */ +}; -\paragraph{General Transport Requirements} -\begin{itemize} - \item An implementation \textbf{MUST} correctly process or generate all - \emph{transport messages} defined by this specification that are necessary - for device operation. At minimum, this includes: - \begin{itemize} - \item \msgref{GET_DEVICE_INFO}, \msgref{GET_DEVICE_FEATURES}, \msgref{SET_DRIVER_FEATURES} - \item \msgref{GET_CONFIG}, \msgref{SET_CONFIG} - \item \msgref{GET_VQUEUE}, \msgref{SET_VQUEUE}, \msgref{RESET_VQUEUE} - \item \msgref{GET_DEVICE_STATUS}, \msgref{SET_DEVICE_STATUS} - \end{itemize} - Failure to support these messages renders a device or driver noncompliant. - \item An implementation \textbf{MUST} adhere to the - \textbf{transport revision} and \textbf{maximum message size} constraints - indicated by each bus instance. For example, it \textbf{MUST NOT} exceed - the \textbf{maximum message size} in any message. -\end{itemize} +struct virtio_bus_msg_get_devices_resp { + le16 offset; /* echoed starting device number */ + le16 count; /* window length actually returned */ + le16 next_offset; /* 0 or suggested start for next query */ + u8 bitmap[]; /* count/8 bytes, LSB-first packing */ +}; +\end{lstlisting} -\paragraph{Device-Side Requirements} -\begin{itemize} - \item A device \textbf{MUST} provide accurate data in response to - \msgref{GET_DEVICE_INFO}, including the correct \emph{device ID}, \emph{vendor ID}, - number of feature bits, and configuration size. - \item A device \textbf{MUST} accept or reject driver-requested features via - \msgref{SET_DRIVER_FEATURES} consistently with its capabilities and \textbf{MUST} - return the final agreed-upon feature bits to the driver. - \item A device \textbf{MUST} maintain a valid \emph{Configuration Generation - Count} and \textbf{MUST} reject \msgref{SET_CONFIG} or similar operations if - the generation count supplied by the driver does not match. - \item A device \textbf{MUST} properly manage virtqueues configured via - \msgref{SET_VQUEUE}, including storing and using the provided addresses for - descriptor, driver, and device areas. - \item A device \textbf{MUST} respect \msgref{SET_DEVICE_STATUS} changes: if the - status is set to zero, the device \emph{MUST} reset its internal state and - discard any pending operations. -\end{itemize} +The \textbf{(offset, count)} tuple defines a window of \textbf{count} +consecutive device numbers beginning at \textbf{offset}. The number of present +devices equals the number of 1-bits in the bitmap. Responders SHOULD return the +requested \textbf{count} unless constrained (e.g., by maximum message size); +otherwise they MAY return a smaller value, in which case the bitmap covers the +reduced window. -\paragraph{Driver-Side Requirements} -\begin{itemize} - \item A driver \textbf{MUST} send valid requests that do not exceed - the \textbf{maximum message size}, including correct offsets and block - counts in \msgref{GET_DEVICE_FEATURES}, \msgref{SET_DRIVER_FEATURES}, \msgref{GET_CONFIG}, - and \msgref{SET_CONFIG}. - \item A driver \emph{MUST} handle a \msgref{SET_CONFIG} being rejected for a - mismatched configuration generation count. - \item A driver \textbf{MUST} initialize each device's virtqueues (where needed) - via \msgref{SET_VQUEUE} before attempting normal I/O and \textbf{SHOULD} - query the device's status or configuration if an unexpected - \msgref{EVENT_CONFIG} or error arises. -\end{itemize} +Example: a request with \textbf{offset}=0, \textbf{count}=16 might produce +\textbf{bitmap}=0b00100101 00000000 and \textbf{next_offset}=16. That indicates +devices 0, 2, and 5 are present within the 0–15 window and suggests continuing +at device number 16. -\subsubsection{Optional Requirements} -\label{sec:Virtio Transport Options / Virtio Over Messages / Compliance / Optional} +\paragraph{Intended usage} +Drivers MAY use this message to enumerate device numbers. Treat each window as +a snapshot, advance using \textbf{next_offset}, and confirm candidates via +\msgref{GET_DEVICE_INFO} before issuing other transport messages. -\paragraph{Bus Messages for Enumeration and Hotplug} +\busnormative{\paragraph}{GET\_DEVICES}{Virtio Transport Options / Virtio Over Messages / Bus Messages / GET_DEVICES / Bus} \begin{itemize} - \item Implementations \emph{MAY} use \busref{GET_DEVICES} - and \busref{EVENT_DEVICE} for discovering and managing devices in a - message-driven manner. However, this is not mandatory if other enumeration - methods (e.g., device tree, ACPI, hypervisor firmware) are used. - \item If a bus chooses to implement these messages, it \textbf{MUST} do - so in compliance with their defined formats and semantics (see - \ref{sec:Virtio Transport Options / Virtio Over Messages / Bus Messages}). + \item The bus-side responder MUST enforce that \textbf{offset} and + \textbf{count} are multiples of 8, and it MUST return a bitmap of length + \textbf{count/8} packed least-significant-bit first. + \item \textbf{next\_offset} MUST be 0 (indicating no further windows) or an + aligned value $\ge \textbf{offset} + \textbf{count}$ recommending where + the driver should query next. + \item Responders SHOULD return the requested \textbf{count} unless constrained + (e.g., by maximum message size); if a smaller count is returned, the + bitmap MUST still represent the window defined by the echoed + \textbf{offset} and \textbf{count}. \end{itemize} -\paragraph{Optional Bus-Level Messages} -\begin{itemize} - \item \busref{PING} \emph{MAY} be implemented for keepalive or health checks. - If used, both sides \textbf{MUST} echo the 32-bit data field precisely. -\end{itemize} +\busdef{PING} -\paragraph{Runtime Notifications} -\begin{itemize} - \item A device or the driver side bus \emph{MUST} send \msgref{EVENT_CONFIG} - to inform the driver of configuration of device status changes. - \item A device or the driver side bus \emph{MUST} send \msgref{EVENT_USED} - to inform the driver of (likely) buffer completions. - \item A driver \emph{MUST} send \msgref{EVENT_AVAIL} to notify the device that - new buffers are available. -\end{itemize} +\busref{PING} is a simple liveness check that can be sent by either side of the +bus; the response echoes the 32-bit data value from the request. -\subsubsection{Compliance for Different Environments} -\label{sec:Virtio Transport Options / Virtio Over Messages / Compliance / DifferentEnvs} +\begin{lstlisting} +struct virtio_bus_msg_ping_req { + le32 data; /* arbitrary value chosen by the sender */ +}; -\paragraph{Bus Implementation} -A \emph{bus implementation} is compliant if: -\begin{itemize} - \item It forwards \textbf{transport messages} to the appropriate device - without altering or discarding valid requests. - \item It enforces the \textbf{maximum message size} and \textbf{transport - revision} advertised for its instance. - \item If it implements bus messages (e.g., \busref{GET_DEVICES}, \busref{PING}), - those must follow the formats in - \ref{sec:Virtio Transport Options / Virtio Over Messages / Bus Messages}. -\end{itemize} +struct virtio_bus_msg_ping_resp { + le32 data; /* echoed request data */ +}; +\end{lstlisting} -\paragraph{Driver Implementation} -A \emph{driver} is compliant if: -\begin{itemize} - \item It correctly sends and interprets all required transport messages - (\msgref{GET_DEVICE_INFO}, \msgref{SET_DRIVER_FEATURES}, \msgref{SET_CONFIG}, etc.). - \item It respects the bus \textbf{transport revision} and \textbf{maximum - message size} limits for each bus instance. - \item It properly handles device resets, ensuring that any - subsequent re-initialization follows - \ref{sec:Virtio Transport Options / Virtio Over Messages / Device Initialization}. -\end{itemize} +\paragraph{Intended usage} +Drivers or bus implementations MAY use \busref{PING} as a keepalive. If a reply +is missing or delayed beyond policy, the initiator SHOULD verify device status +(e.g., via \msgref{GET_DEVICE_STATUS}) and take recovery actions as needed. -\paragraph{Device Implementation} -A \emph{device} is compliant if: +\busnormative{\paragraph}{PING}{Virtio Transport Options / Virtio Over Messages / Bus Messages / PING / Bus} \begin{itemize} - \item It supports the core transport messages and enforces the - \emph{Configuration Generation Count}. - \item It implements feature negotiation correctly - \item It respects \msgref{SET_DEVICE_STATUS} changes, resetting or shutting - down if the status is cleared. + \item The bus-side responder MUST echo the 32-bit data field from the request + exactly in the \busref{PING} response. \end{itemize} -\subsubsection{Conformance Statements} -\label{sec:Virtio Transport Options / Virtio Over Messages / Compliance / Conformance} - -An implementation \textbf{MUST} meet all "MUST" requirements stated in: -\begin{itemize} - \item \ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts} (Basic Concepts) - \item \ref{sec:Virtio Transport Options / Virtio Over Messages / Bus Operation} (Bus Operation) - \item \ref{sec:Virtio Transport Options / Virtio Over Messages / Device Initialization} (Device Initialization) - \item \ref{sec:Virtio Transport Options / Virtio Over Messages / Device Operation} (Device Operation) - \item This \ref{sec:Virtio Transport Options / Virtio Over Messages / Compliance} (Compliance) section -\end{itemize} -to claim compliance with the virtio-msg specification. +\busdef{EVENT_DEVICE} -Implementations that do not follow these mandatory rules \emph{MUST NOT} declare -themselves conformant. Features or messages labeled as "optional" (\emph{MAY}) -do not invalidate compliance if omitted, provided all required behaviors are -still correctly implemented. +\busref{EVENT_DEVICE} signals device-level hotplug changes. The driver-side bus +receives these indications from the device-side bus; the table below lists the +defined device bus states. -\subsubsection{Versioning and Forward Compatibility} -\label{sec:Virtio Transport Options / Virtio Over Messages / Compliance / Versioning} +\begin{lstlisting} +struct virtio_bus_msg_event_device { + le16 device_number; + le16 device_bus_state; /* see table below */ +}; +\end{lstlisting} -A higher transport \textbf{transport revision} or additional \textbf{feature -bits} \emph{MAY} extend the protocol with new messages or capabilities. However, -to remain compliant with earlier revisions, devices and drivers \emph{SHOULD} -continue to honor the mandatory messages and semantics from prior revisions. If -a bus instance or device does not support an advanced feature, it \emph{SHOULD} -reject or ignore those requests rather than undefined behavior. +\begin{tabular}{|l|l|p{7cm}|} +\hline +Constant & Value & Meaning \\ +\hline +DEVICE\_BUS\_STATE\_READY & 0x0001 & Device is present and ready. \\ +DEVICE\_BUS\_STATE\_REMOVED & 0x0002 & Device is no longer present. \\ +Reserved & 0x0003–0x7FFF & Reserved for standard use. \\ +Implementation-defined & 0x8000–0xFFFF & MAY be used by the bus implementation. \\ +\hline +\end{tabular} +\paragraph{Intended usage} +Upon receiving DEVICE\_BUS\_STATE\_READY, drivers SHOULD probe the device via +\msgref{GET_DEVICE_INFO} and proceed with initialization if successful. Upon +DEVICE\_BUS\_STATE\_REMOVED, drivers MUST stop queueing new work, quiesce and +reset as applicable, and release resources. Drivers SHOULD tolerate duplicate or +out-of-order events and MAY rely on additional bus-level monitoring (e.g., +\busref{PING}) if needed.