diff --git a/.prjinfo/sendmail/cover.txt b/.prjinfo/sendmail/cover.txt index b6c4755..a63cdc0 100644 --- a/.prjinfo/sendmail/cover.txt +++ b/.prjinfo/sendmail/cover.txt @@ -34,7 +34,8 @@ standardize a bus level message for that. We are working on a few reusable bus implementations: -* virtio-msg-ffa based on Arm FF-A interface for use between: +* virtio-msg-ffa based on Arm's Virtio Message Bus over FF-A specification [6] + for use between: * normal world and secure world * host and VM or VM to VM * Can be used w/ or with out a hypervisor @@ -61,41 +62,125 @@ We also anticipate a few more: * Usable on any Xen system (including x86 where FF-A does not exist) * Using Xen events and page grants -* virtio-msg over admin virtqueues - * This allows any virtio-pci device that supports admin virtqueues to also - support a virtio-msg bus that supports sub devices - * [We are looking for collaborators for this work] - -Changes since RFC2: - -Spec Functional: -* Made the common message header 8 bytes and added a token for optional use - when parallel outstanding requests are possible -* Made the 8 byte fields align to 8 byte offsets. - This effects the {SET,GET}_VQUEUE messages -* Many conformance cases have been tightened. - -Spec Editorial: -* Major restructure to better align with virtio spec - * Conformance model now matches other transports - * Use C structures to define messages instead of tables -* Added a section to describe how responses are matched to requests - This includes the use of the new token field -* Redefined / better described error handling between transport and bus - layers to eliminate the need for the bus to generate fake response messages -* Included editorial feedback from RFC2 +This series keeps 16-bit dev_num values per bus instance; deployments that need +more than roughly 65k devices can scale by using multiple bus instances. + +Changes since v1 (virtio-msg-patch1): + +First, thank you for the detailed comments and broad interest on v1. +This revision incorporates review feedback from Peter Hilber, Demi Marie +Obenour, Parav Pandit, Andrei Homescu, Manos Pitsidianakis, Michael S. +Tsirkin, Bill Mills, and HVAC group discussion. + +Highlights of the changes since v1: + +* Finalized the common transport message model: + * keep the 8-byte common header + * keep 16-bit device numbers per bus instance and a 16-bit msg_size field + * note that deployments needing more than roughly 65k devices can scale by + using multiple bus instances + * clarify common message-ID encoding and validation boundaries + * define request completion more precisely: a valid supported request + completes with exactly one protocol response or a transport-visible failure + * clarify request/response correlation and token handling, including the + rule that devices echo the request token while the bus may rewrite tokens + internally for correlation + * preserve per driver/device request ordering while still allowing + bus-correlated out-of-order responses and events + +* Clarified bus versus transport responsibilities and enumeration: + * keep GET_DEVICE_INFO as a driver-issued transport message, and GET_DEVICES, + PING, and EVENT_DEVICE as optional bus messages + * require bus messages to use dev_num = 0 + * bus implementations must expose only validated device numbers, may expose + zero devices, and should delay device-number reuse to reduce races + * EVENT_DEVICE is defined as a bus-originated ADDED/REMOVED hotplug event + * tighten GET_DEVICES enumeration semantics, including empty-bitmap cases and + guaranteed forward progress + +* Tightened initialization and feature negotiation: + * use transport revision terminology consistently + * keep GET_DEVICE_INFO as the only transport message used for early discovery + * align the rest of initialization with the core virtio flow through reset, + status progression, feature negotiation, FEATURES_OK verification, and + DRIVER_OK + * keep transport feature bits separate from device feature negotiation + * define GET_DEVICE_FEATURES as reporting the feature blocks offered by the + device + * require GET_DEVICE_INFO to report enough feature blocks to cover all + offered feature bits and bound max_virtqueues to 65536 + * define SET_DRIVER_FEATURES as addressed-block updates carrying the subset + chosen by the driver, which may be built up across multiple requests before + FEATURES_OK + * keep FEATURES_OK as the point where the device accepts or rejects the + negotiated set + * make GET_SHM mandatory for devices to implement while keeping driver use + optional, and align the shared-memory identifier semantics with core virtio + +* Aligned configuration, status, and notification behavior with core virtio: + * align GET_CONFIG, SET_CONFIG, EVENT_CONFIG, and device status handling more + closely with the core virtio model + * keep VIRTIO_MSG_F_STRICT_CONFIG_GENERATION only as optional strict-profile + SET_CONFIG mismatch enforcement + * define nonzero SET_CONFIG writes as all-or-nothing and rejected writes as + length = 0 with no payload + * limit EVENT_CONFIG status notifications to device-originated asynchronous + status changes + * make polling-only operation explicit, with EVENT_AVAIL and EVENT_USED used + only when the endpoints choose event-driven notification + * keep bus-side forwarding, polling, or synthesized notification delivery + transparent to the transport-visible model + +* Refined virtqueue and reset semantics: + * clarify queue-state transitions, SET_VQUEUE update behavior, and invalid + reconfiguration cases + * make SET_VQUEUE and RESET_VQUEUE reject cases deterministic no-op empty + responses + * define deterministic GET_VQUEUE zero-sentinel responses for unavailable, + unimplemented, and out-of-range queues + * define local admin virtqueue field semantics and the EVENT_AVAIL + notification-data encoding more precisely + * clarify reset-completion checks without duplicating the core virtio reset + rules + +* Improved document quality: + * reworked the chapter to better match existing virtio specification style + * removed duplicated or ambiguous requirements + * fixed label paths, direct field references, punctuation, and ambiguous + wording + * added informative known bus implementation examples + * completed conformance coverage for driver, device, and bus clauses + * normalized punctuation and wording for consistency with the rest of the spec + +Open topics and ongoing discussion: +* Out-of-order/performance extensions: + We kept the baseline behavior simple in this revision. If clear performance + benefit is demonstrated, we are open to introducing an optional feature-bit + based extension in a follow-up patch set. +* Graceful device removal sequencing: + Current direction is to handle graceful-remove sequencing in bus-specific + specifications. We welcome feedback on whether any additional transport-level + guidance would be useful. +* Transport scope and mapping guidance: + Discussion is still ongoing on transport-vs-bus binding scope, response + status modeling, and mapping guidance for mmio/pci/vhost-user/KVM userspace + cases. We are collecting reviewer input before deciding on follow-up text. +* Potential virtio-msg over virtqueues for PCI/MMIO: + This is still early discussion, including whether admin virtqueues should be + used or extended for this purpose. There is no consensus yet, and we are + continuing design exploration. Eco-system: * Added virtio-msg-loopback demo -* Arm has published the first draft of the virtio-msg over FFA spec [6] -* virtio-msg over FFA has been demonstrated with both Trusty and OP-TEE +* Arm has published the Virtio Message Bus over FF-A specification [6] +* virtio-msg over FF-A has been demonstrated with both Trusty and OP-TEE secure world * LKML RFC has been sent [7] * QEMU RFC has been sent [8] -This is the first non-RFC patch series. The known short comings have been -addressed. We ask for review in earnest on this series and thank you for -any feedback you can provide. +This is v2 of the first non-RFC patch series. We are grateful for the review +feedback and interest received on v1, and we ask for continued review on this +revision. Background info and work in progress implementations: * HVAC project page with intro slides [1] @@ -117,6 +202,6 @@ with this version of the spec. [3] https://git.kernel.org/pub/scm/linux/kernel/git/vireshk/linux.git/log/?h=virtio/msg [4] https://github.com/edgarigl/qemu/commits/edgar/virtio-msg-rfc/ [5] https://github.com/arnopo/open-amp/commits/virtio-msg/ -[6] https://documentation-service.arm.com/static/68f647791134f773ab3f0a7c +[6] https://developer.arm.com/documentation/den0153/0101/ [7] https://lore.kernel.org/all/cover.1753865268.git.viresh.kumar@linaro.org/ [8] https://mail.gnu.org/archive/html/qemu-devel/2025-10/msg07438.html diff --git a/conformance.tex b/conformance.tex index 7d5d00f..3955da4 100644 --- a/conformance.tex +++ b/conformance.tex @@ -155,33 +155,28 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \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 / Configuration Semantics Profiles / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Error Signaling / 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_GET_DEVICE_STATUS / 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_GET_VQUEUE / 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} @@ -285,24 +280,17 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \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 / Configuration Semantics Profiles / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Device 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 / Basic Concepts / Ordering / 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} @@ -311,8 +299,6 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \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} @@ -358,12 +344,18 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \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 / Transport Messages / Runtime 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} + +If a Virtio Over Messages bus implementation supports optional bus messages, it +MUST also conform to the corresponding normative statements: + +\begin{itemize} +\item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Bus Messages / GET_DEVICES / Bus} (if BUS_MSG_GET_DEVICES is supported) +\item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Bus Messages / PING / Bus} (if BUS_MSG_PING is supported) +\item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Bus Messages / EVENT_DEVICE / Bus} (if BUS_MSG_EVENT_DEVICE is supported) \end{itemize} \conformance{\section}{Legacy Interface: Transitional Device and Transitional Driver Conformance}\label{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance} diff --git a/content.tex b/content.tex index c785c5c..b7775ac 100644 --- a/content.tex +++ b/content.tex @@ -2,7 +2,9 @@ \chapter{Basic Facilities of a Virtio Device}\label{sec:Basic Facilities of a Vi A virtio device is discovered and identified by a bus-specific method (see the bus specific sections: \ref{sec:Virtio Transport Options / Virtio Over PCI Bus}~\nameref{sec:Virtio Transport Options / Virtio Over PCI Bus}, -\ref{sec:Virtio Transport Options / Virtio Over MMIO}~\nameref{sec:Virtio Transport Options / Virtio Over MMIO} and \ref{sec:Virtio Transport Options / Virtio Over Channel I/O}~\nameref{sec:Virtio Transport Options / Virtio Over Channel I/O}). Each +\ref{sec:Virtio Transport Options / Virtio Over MMIO}~\nameref{sec:Virtio Transport Options / Virtio Over MMIO}, +\ref{sec:Virtio Transport Options / Virtio Over Channel I/O}~\nameref{sec:Virtio Transport Options / Virtio Over Channel I/O} +and \ref{sec:Virtio Transport Options / Virtio Over Messages}~\nameref{sec:Virtio Transport Options / Virtio Over Messages}). Each device consists of the following parts: \begin{itemize} @@ -931,11 +933,16 @@ \chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits} \item[VIRTIO_F_ADMIN_VQ(41)] This feature indicates that the device exposes one or more administration virtqueues. - At the moment this feature is only supported for devices using - \ref{sec:Virtio Transport Options / Virtio Over PCI + Devices using \ref{sec:Virtio Transport Options / Virtio Over PCI Bus}~\nameref{sec:Virtio Transport Options / Virtio Over PCI Bus} - as the transport and is reserved for future use for - devices using other transports (see + expose administration virtqueues using the transport-specific + fields defined by that transport. Devices using + \ref{sec:Virtio Transport Options / Virtio Over Messages}~\nameref{sec:Virtio Transport Options / Virtio Over Messages} + expose administration virtqueues through the device information + reported by that transport. + + For devices using other transports, this feature is reserved for + future use (see \ref{drivernormative:Basic Facilities of a Virtio Device / Feature Bits} and \ref{devicenormative:Basic Facilities of a Virtio Device / Feature Bits} for diff --git a/introduction.tex b/introduction.tex index 9a9cbde..8795cf3 100644 --- a/introduction.tex +++ b/introduction.tex @@ -20,7 +20,7 @@ \chapter{Introduction} \item[Standard:] Virtio makes no assumptions about the environment in which it operates, beyond supporting the bus to which device is attached. In this specification, virtio - devices are implemented over MMIO, Channel I/O and PCI bus transports + devices are implemented over MMIO, Channel I/O, PCI bus, and message-based transports \footnote{The Linux implementation further separates the virtio transport code from the specific virtio drivers: these drivers are shared between different transports. @@ -92,6 +92,9 @@ \section{Normative References}\label{sec:Normative References} \phantomsection\label{intro:I2C}\textbf{[I2C]} & I2C-bus specification and user manual, \newline\url{https://www.nxp.com/docs/en/user-guide/UM10204.pdf}\\ + \phantomsection\label{intro:FFA-BUS}\textbf{[FFA-BUS]} & + Arm, Virtio Message Bus over FF-A, DEN0153, + \newline\url{https://developer.arm.com/documentation/den0153/0101/}\\ \phantomsection\label{intro:SCMI}\textbf{[SCMI]} & Arm System Control and Management Interface, DEN0056, \newline\url{https://developer.arm.com/docs/den0056/c}, version C and any future revisions\\ @@ -350,4 +353,3 @@ \section{Constant Specifications}\label{sec:Constant Specifications} either VIRTIO_FLD_A or VIRTIO_FLD_B. \newpage - diff --git a/transport-msg.tex b/transport-msg.tex index d4e31d7..e428e38 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -31,7 +31,7 @@ \section{Virtio Over Messages}\label{sec:Virtio Transport Options / Virtio Over \item \textbf{Preserve virtio semantics:} The transport leverages standard virtio concepts (features, configuration space, virtqueues), so existing virtio drivers and device implementations can - integrate smoothly once a device is discovered and registered. + integrate smoothly once a device is discovered. \end{itemize} \subsection{Basic Concepts} @@ -56,10 +56,9 @@ \subsubsection{High-Level Architecture} firmware calls), \item Dynamic hotplug notifications (optionally via \busref{EVENT_DEVICE}). \end{itemize} - 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. + Once a device number is identified, regardless of discovery method, the bus + layer exposes that device number and availability state to the driver side + of the transport. \item \textbf{Transport Layer}: After the bus knows about a device, the virtio-msg transport handles all device-specific operations: @@ -82,7 +81,7 @@ \subsubsection{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 +(e.g., over IPC, shared memory with signaling or hardware messaging), while the virtio-msg transport defines the semantics of those messages. virtio-msg groups messages into two categories: @@ -117,19 +116,44 @@ \subsubsection{Relationship Between Bus and Transport} \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. + \item A bus implementation MAY support any subset of \busref{GET_DEVICES}, + \busref{PING}, and \busref{EVENT_DEVICE}. + \item If a bus implementation supports one of these bus messages, it MUST + conform to the normative definition for that message. \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 validate the device number in each transport + message before forwarding it. \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. + \item If a bus implementation cannot validate or route a transport request + that expects a response, it MUST surface a transport-visible failure + for that request. + \item If a bus implementation cannot validate or route a one-way transport + event, it MAY drop the event or handle it according to + message-specific bus requirements. +\end{itemize} + +\subsubsection{Known Bus Implementation Examples} +\label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Known Bus Implementation Examples} + +This subsubsection lists informative examples of bus implementations and related +work for virtio-msg. + +\begin{itemize} + \item \textbf{Virtio Message Bus over FF-A}: specified by Arm in + \hyperref[intro:FFA-BUS]{[FFA-BUS]}. + \item \textbf{Virtio Message Bus over PCI for AMP}: under development; proof + of concept: + \url{https://github.com/wmamills/hvac-demo}. + \item \textbf{Virtio Message Bus over Xen grant tables and events}: under + discussion. \end{itemize} \subsubsection{System Topology} @@ -145,8 +169,8 @@ \subsubsection{System Topology} available devices. Once a device is recognized, the driver uses the common transport messages to perform feature negotiation, configuration, and virtqueue setup. - \item \textbf{Device}: Implement virtio device functionality and - respond to the transport messages. The bus forwards these messages to + \item \textbf{Device}: Implements virtio device functionality and + responds to the transport messages. The bus forwards these messages to the correct device instance based on device number. \end{itemize} @@ -158,12 +182,16 @@ \subsubsection{Transport Revisions and Maximum Message Size} \begin{itemize} \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{Maximum message size}: the largest message size (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} +Transport feature bits are determined per bus instance. When both sides expose +transport feature masks, the bus instance presents only the common subset as +the effective transport feature mask for that bus instance. + The mechanism for obtaining these parameters is implementation-defined and can vary between bus instances. Common approaches include: \begin{itemize} @@ -177,9 +205,19 @@ \subsubsection{Transport Revisions and Maximum Message Size} \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 expose transport feature bits independently of the + device feature blocks exchanged by \msgref{GET_DEVICE_FEATURES} and + \msgref{SET_DRIVER_FEATURES}. + \item A bus instance MUST advertise only the transport feature bits supported + by both sides of that bus instance. \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. + device-originated transport messages. + \item For an active device, a bus instance MUST treat the advertised + transport revision, maximum message size, and transport feature bits as + stable. + \item If these values change, a bus instance MUST notify the transport layer + and MUST require transport-layer revalidation before accepting + additional transport messages for the affected device. \end{itemize} \drivernormative{\paragraph}{Respecting Bus Limits}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Revisions / Driver Limits} @@ -200,33 +238,41 @@ \subsubsection{Transport Revisions and Maximum Message Size} an error or ignore requests for unsupported features. \end{itemize} -\paragraph{virtio-msg revisions} +\paragraph{virtio-msg transport revisions} -The following table lists the currently defined virtio-msg revisions: +The following table lists the currently defined virtio-msg transport revisions +and their protocol-defined maximum message sizes. Transport feature bits are +defined separately in +\ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Transport Feature Bits}. -\begin{tabular}{ |l|l|l|l| } +\begin{tabular}{ |l|l|l| } \hline -\field{revision} & \field{maximum size} & \field{features} & remarks \\ +\field{revision} & \field{maximum size} & remarks \\ \hline \hline -1 & 44-65536 & & Virtio Message Revision 1 \\ +1 & 52-65535 & Virtio Message Revision 1 \\ \hline \end{tabular} +The table reflects the protocol-defined maximum size; the recommended +advertised maximum remains 264 bytes for interoperability. + Note that a change in the virtio standard does not necessarily -correspond to a change in the virtio-msg revision. +correspond to a change in the virtio-msg transport revision. 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. +against this limit. Today the largest practical inline configuration payload is +244 bytes: messages such as GET_CONFIG and SET_CONFIG use 12 bytes of +message-specific fields, leaving up to 244 bytes for device configuration data +in one transfer when the recommended 264-byte maximum message size is used. +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. + 52 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} @@ -267,12 +313,36 @@ \subsubsection{Transport Revisions and Maximum Message Size} error or drop the message without forwarding it. \end{itemize} +\subsubsection{Transport Feature Bits} +\label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Transport Feature Bits} + +Transport feature bits are bus-instance parameters. They are advertised as part +of the transport parameters described in +\ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Revisions} +and are not carried in the device feature blocks exchanged by +\msgref{GET_DEVICE_FEATURES} and \msgref{SET_DRIVER_FEATURES}. + +The following transport feature bits are defined: + +\begin{tabular}{|l|l|l|p{7cm}|} +\hline +Bit & Name & Minimum revision & Meaning \\ +\hline +0 & \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} & 1 & +Select strict configuration semantics profile. When this feature is not +advertised for the bus instance, the baseline profile applies. See +\ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles}. \\ +\hline +\end{tabular} + \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 discover these device numbers through +Each virtio-msg bus instance contains zero or more \emph{devices}, identified +by a 16-bit \textbf{device number}. The device number is a bus-assigned +identifier and is distinct from the virtio device ID (device type) returned by +\msgref{GET_DEVICE_INFO}. Buses discover these device numbers through mechanisms such as: \begin{itemize} \item \textbf{Message-Based Enumeration}: Using \busref{GET_DEVICES} to query @@ -281,117 +351,242 @@ \subsubsection{Device Numbers and Enumeration} might inform the bus of available device numbers and their properties. \end{itemize} -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. +The 16-bit device-number space provides roughly 65k device slots per bus +instance. Deployments that require more devices can instantiate multiple bus +instances and distribute devices across those instances. + +Once a bus confirms that a device number is valid, regardless of the discovery +method, it exposes that number to the driver side of the transport. The driver +then issues \msgref{GET_DEVICE_INFO} as the first transport message for that +device number before other transport operations. \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 / 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 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. + device on a given bus instance. + \item A bus implementation SHOULD prevent reuse of a device number + immediately after a device is removed, to reduce race conditions with + delayed messages associated with the removed device. + \item A bus implementation MUST provide the driver with sufficient + information, either via \busref{GET_DEVICES}, \busref{EVENT_DEVICE}, + or equivalent platform data, to discover each valid device number. \end{itemize} -\drivernormative{\paragraph}{Configuration Generation Count}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Generation Count / Driver} +\subsubsection{Configuration Semantics Profiles} +\label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles} + +virtio-msg defines two configuration semantics profiles selected by the +transport feature bits advertised for the bus instance: \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. + \item \textbf{Baseline profile}: applies when + \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is not advertised for + the bus instance. + \item \textbf{Strict profile}: applies when + \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is advertised for the + bus instance. +\end{itemize} + +The profiles apply to \msgref{GET_CONFIG}, \msgref{SET_CONFIG}, and +\msgref{EVENT_CONFIG}. + +\drivernormative{\paragraph}{Configuration Semantics Profiles}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles / Driver} +\begin{itemize} + \item A driver MUST determine the active profile before issuing + \msgref{SET_CONFIG}. + \item A driver MUST determine the active profile from the transport feature + bits advertised for the target bus instance, not from + \msgref{GET_DEVICE_FEATURES}/\msgref{SET_DRIVER_FEATURES}. + \item In any profile, a driver SHOULD use generation values from + \msgref{GET_CONFIG} and \msgref{EVENT_CONFIG} to detect concurrent + configuration changes and SHOULD re-read required configuration until + it observes a stable generation value. + \item In baseline profile, a driver MUST set \field{generation} to 0 in + \msgref{SET_CONFIG} requests. + \item In baseline profile, upon \msgref{EVENT_CONFIG}, a driver SHOULD refresh + required configuration via \msgref{GET_CONFIG} when event data is + omitted or when \field{offset} and \field{length} are zero. + \item In strict profile, a driver MUST track generation values from + \msgref{GET_CONFIG}/\msgref{EVENT_CONFIG} and MUST include its most + recent generation value in \msgref{SET_CONFIG}. + \item In strict profile, if a \msgref{SET_CONFIG} request is rejected due to a + mismatched generation count, a driver SHOULD issue \msgref{GET_CONFIG} + to obtain the latest configuration data and generation count before + retrying. + \item In any profile, a driver MUST NOT assume generation count is monotonic + or preserved across device resets. +\end{itemize} + +\devicenormative{\paragraph}{Configuration Semantics Profiles}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles / Device} +\begin{itemize} + \item A device MUST apply the configuration semantics profile selected by the + transport feature bits advertised for the bus instance that relays its + messages. + \item In any profile, a device MUST provide its current generation count in + \msgref{GET_CONFIG} responses, \msgref{SET_CONFIG} responses, and + \msgref{EVENT_CONFIG} messages. + \item In any profile, a device MUST change \field{generation} whenever there + is a possibility that two accesses to the device configuration space + can observe different versions of that space, as described in + \ref{sec:Basic Facilities of a Virtio Device / Device Configuration Space}. + \item In baseline profile, a device MUST ignore request \field{generation} in + \msgref{SET_CONFIG}. For requests that are otherwise valid, the device + MUST apply the write regardless of request \field{generation} and MUST + NOT reject \msgref{SET_CONFIG} due solely to generation mismatch. + \item A device MUST NOT send \msgref{EVENT_CONFIG} solely because a + \msgref{SET_CONFIG} request carried a mismatched \field{generation} + value. + \item In any profile, a device MAY send a generic + \msgref{EVENT_CONFIG} notification with \field{offset} and + \field{length} set to 0 and no \field{data} when the affected + configuration change cannot be represented as a bounded range + (for example, when only an equivalent out-of-band notification is + available without affected-range details). + \item A device transport layer implementation MUST originate + \msgref{EVENT_CONFIG} whenever it changes configuration data in a way + that is visible to the driver. + \item A device transport layer implementation MUST originate + \msgref{EVENT_CONFIG} for status only when a device-originated + asynchronous status change requires asynchronous reporting to the + driver. + \item A device MUST NOT send \msgref{EVENT_CONFIG} solely because the driver + wrote status via \msgref{SET_DEVICE_STATUS}; such writes MAY be + followed by \msgref{EVENT_CONFIG} only if a distinct + device-originated asynchronous status change occurs afterward. + \item If \msgref{EVENT_CONFIG} reports only a status change, a device MUST + set \field{offset} and \field{length} to 0. + \item In any profile, a device MAY reset generation count, including when it + resets internal state. + \item In strict profile, if a \msgref{SET_CONFIG} request includes a + \field{generation} count that does not match the device's current + count, the device MUST reject the request. + \item If updated configuration data cannot fit in a single + \msgref{EVENT_CONFIG}, a device SHOULD send an \msgref{EVENT_CONFIG} + without configuration data and MUST make updated data available via + \msgref{GET_CONFIG}. In strict profile, the device SHOULD set + \field{offset}/\field{length} to the affected range. \end{itemize} -This mechanism ensures updates are not lost or overwritten due to stale -information. +This subsection defines baseline and strict semantics together so that +generation and mismatch behavior remains explicit and consistent across message +definitions. -\subsubsection{Feature Negotiation Blocks} -\label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Feature Blocks} +\subsubsection{Device Feature Blocks} +\label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Device Feature Blocks} -The virtio-msg transport organizes feature bits into 32-bit blocks accessed by +Device feature bits are organized 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.). + 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-bit values representing the supported (or - driver-requested) feature bits in the selected blocks. + \item \textbf{Feature Data}: The 32-bit values representing either the + device-offered feature bits or the driver-selected subset for the + selected blocks. \end{itemize} -\devicenormative{\paragraph}{Feature Blocks}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Feature Blocks / Device} +Virtio-msg device feature blocks may include core virtio feature bits. They are +distinct from the transport feature bits defined in +\ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Transport Feature Bits}. +This transport does not support VIRTIO\_F\_NOTIF\_CONFIG\_DATA; device feature +negotiation requirements are defined in +\ref{sec:Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Features}. + +\devicenormative{\paragraph}{Device Feature Blocks}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Device 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. + \item After processing \msgref{SET_DRIVER_FEATURES}, a device MUST update + only the driver-selected feature blocks addressed by that request and + MUST leave all other driver-selected feature blocks unchanged. + \item A device MUST report the device-offered feature set in + \msgref{GET_DEVICE_FEATURES} responses and MUST NOT reflect the + driver-selected subset in those responses. \end{itemize} \subsubsection{Error Signaling} \label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Error Signaling} 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. +bus implementation, or faults while processing a valid request in the device +transport layer. +Implementations should handle such faults locally where possible. For +request/response messages that use the existing wire format, the completion +contract is deterministic: +\begin{itemize} + \item For a valid, supported request accepted for processing, completion is + exactly one protocol response. + \item If routing, policy, timeout, or completion constraints prevent that + response, completion is a transport-visible failure surfaced by the + bus implementation. + \item One-way events do not define a completion outcome. Unless a + message-specific rule states otherwise, they MAY be dropped without a + protocol error response or transport-visible failure. + \item Malformed or unsupported messages are discarded without protocol error + responses; for request/response messages, the originating side observes + completion according to the bounded transport-visible failure policy. +\end{itemize} \busnormative{\paragraph}{Error Handling}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Error Signaling / Bus} \begin{itemize} - \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 apply a bounded completion policy for each + valid, supported transport request that expects a response. + \item A bus implementation MUST complete each such request with exactly one + of the following outcomes: + \begin{itemize} + \item one protocol response, or + \item a transport-visible failure when routing, policy, timeout, or + completion constraints prevent response delivery. + \end{itemize} + \item A bus implementation MUST NOT wait indefinitely for response delivery. + \item A bus implementation MUST treat malformed headers or unsupported bus + \field{msg_id} values in bus messages as invalid, MUST discard them + without generating additional protocol traffic, and MAY log the + condition for diagnostics. + \item A bus implementation MUST NOT validate transport \field{msg_id} values; + unsupported transport \field{msg_id} handling is performed by the + transport layer. \item A bus implementation MUST NOT generate error responses to event (one-way) messages. + \item Unless a message-specific rule states otherwise, a bus implementation + MAY discard an event without surfacing a completion outcome. +\end{itemize} + +\drivernormative{\paragraph}{Error Handling}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Error Signaling / Driver} +\begin{itemize} + \item A driver transport layer implementation receiving a malformed or + unsupported transport message MUST discard it without producing further + protocol traffic. + \item A driver MUST apply a bounded timeout and retry policy when waiting for + transport-request completion, including reset-completion checks. + \item If that bounded policy is exhausted, a driver MUST treat the request as + failed and MUST perform recovery using the reset and status semantics + defined in + \ref{sec:Virtio Transport Options / Virtio Over Messages / Device Operation}. \end{itemize} \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 A device transport layer implementation 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} -This specification does not define a dedicated error-reporting message; it only -permits implementations to surface failures when silent recovery is not -feasible. +This specification does not define a dedicated error-reporting message. +Transport-visible failure is surfaced under the existing wire model as a bus +completion outcome for a request, not as a new protocol message. + +Some bus implementations may reject requests that violate their local policy +or that are not valid for the current device state. In such cases, the bus may +return a bus-specific error indication to the transport, which can then surface +that failure to the driver. \subsubsection{Endianness} \label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Endianness} @@ -423,7 +618,7 @@ \subsubsection{Common Message Format} struct virtio_msg_header { u8 type; /* request/response + bus/transport */ u8 msg_id; /* message id */ - le16 dev_num; /* device number (0 for bus messages) */ + le16 dev_num; /* target device number; bus messages MUST use 0 */ le16 token; /* bus-managed correlation identifier */ le16 msg_size; /* total size: header (8) + payload */ u8 payload[]; @@ -434,8 +629,11 @@ \subsubsection{Common Message Format} \begin{itemize} \item \field{type}: \begin{itemize} - \item Bit[0]: 0=request, 1=response. - \item Bit[1]: 0=transport message, 1=bus message. + \item Bit[0]: 0=request, 1=response. Messages whose \field{msg_id} identifies + an event MUST use Bit[0]=0 and MUST NOT be sent as responses. + \item Bit[1]: 0=transport message, 1=bus message. This bit selects whether + \field{msg_id} is interpreted in the transport-message namespace or the + bus-message namespace. \item Bits[2..7]: reserved for future use. \end{itemize} \item \field{msg_id}: Message ID identifying the message definition. Ranges @@ -443,11 +641,21 @@ \subsubsection{Common Message Format} \ref{sec:Virtio Transport Options / Virtio Over Messages / Transport Messages} and \ref{sec:Virtio Transport Options / Virtio Over Messages / Bus Messages}. + \begin{itemize} + \item Bits[0..5]: message number within the selected range. + \item Bit[6]: 0=request/response message, 1=event. + \item Bit[7]: 0=standardized message ID, 1=implementation-defined message ID. + \end{itemize} \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. + receive the message. Device number 0 is not reserved for transport + messages. Bus messages are identified by \field{type} and MUST carry + \field{dev_num}=0. + \item \field{token}: Correlation identifier owned and managed by the bus. + Drivers and devices treat this field as opaque. A bus implementation MAY + transparently insert or overwrite \field{token} values on the request leg, + response leg, or both to correlate concurrent requests and responses or to + compensate for transport-specific reordering. A device copies the request + \field{token} into the matching response before any bus-side rewrite. \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 @@ -481,6 +689,9 @@ \subsubsection{Common Message Format} 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. + \item For each request/response message pair, a device MUST copy the + \field{token} value from the received request into the matching + response. \end{itemize} \busnormative{\paragraph}{Common Header}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Common Message Format / Bus} @@ -498,27 +709,68 @@ \subsubsection{Common Message Format} \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. + \item A bus implementation MAY rewrite \field{token} values on the request + path, response path, or both, provided this remains transparent to + drivers and devices. + \item A bus implementation MUST ensure that any use of \field{token} for + request/response correlation or to compensate for transport-specific + reordering remains transparent to drivers and devices. \end{itemize} -Reserved header bits and unspecified header values MUST be transmitted as zero -and ignored on receive to preserve forward compatibility. +A message originator MUST transmit reserved header bits and unspecified header +values as zero, and receivers MUST ignore those bits on receive to preserve +forward compatibility. + +Virtqueue descriptors and buffer data are exchanged via shared memory or other +DMA-accessible memory, as with other virtio transports. Transport messages are +used for control operations, configuration, and notifications, not for +virtqueue data transfer. \subsubsection{Message Ordering} \label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Ordering} 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. +events (which are one-way). Drivers and devices do not interpret the +\field{token} field directly. A bus implementation MAY have multiple +outstanding requests for the same device number and MAY use the bus-owned +\field{token} field to correlate each response with its originating request. +The device copies the received request token into the matching response, and +the bus may transparently rewrite token values on either leg while preserving +request/response correlation for both endpoints. +Events are asynchronous notifications and MAY be delivered at any time +relative to request/response traffic. Messages for different device numbers MAY +be interleaved by the bus. +Some response payloads repeat request parameters (for example, indices or +offsets). Drivers and devices MAY use these repeated values for validation, +but request/response association is determined by the bus implementation's +correlation state, not by response ordering or by those repeated values. \busnormative{\paragraph}{Message Ordering}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Ordering / Bus} \begin{itemize} - \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). + \item For each transport request that expects a response, a bus + implementation MUST preserve sufficient correlation state to complete + that request with exactly one protocol response or one + transport-visible failure. + \item A bus implementation MAY forward multiple requests concurrently for the + same device number. + \item For each driver/device pair, a bus implementation MUST preserve request + order when presenting requests to the device-side transport. + \item For concurrently outstanding requests, a bus implementation MAY deliver + responses in an order different from the corresponding request order, + provided it correlates each response with the originating request + before exposing completion to the driver side. + \item A bus implementation MUST NOT delay an event solely to preserve a + request-before-event or response-before-event ordering rule. +\end{itemize} + +\devicenormative{\paragraph}{Message Ordering}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Ordering / Device} +\begin{itemize} + \item A device MUST process requests in receive order for each driver/device + pair. + \item A device MUST send exactly one response for each valid, supported + request it receives and accepts for processing. + \item For malformed or unsupported requests, a device MUST discard the + request without sending a protocol response. \end{itemize} \subsection{Device Discovery}\label{sec:Virtio Transport Options / Virtio Over Messages / Device Discovery} @@ -539,9 +791,9 @@ \subsection{Device Discovery}\label{sec:Virtio Transport Options / Virtio Over M \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 Once a device number is deemed present, the bus implementation MUST + expose that number to the driver side so the driver can issue + \msgref{GET_DEVICE_INFO}. \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. @@ -560,32 +812,39 @@ \subsubsection{Initialization Flow Overview} A typical device initialization flow includes: \begin{enumerate} - \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:} + \item \textbf{Early Discovery Exception:} + Query static parameters with \msgref{GET_DEVICE_INFO}. This is the only + transport message exception allowed before normal initialization sequencing. + \item \textbf{Reset And Baseline Status:} + Reset the device and transition status through ACKNOWLEDGE then DRIVER via + \msgref{SET_DEVICE_STATUS}. + \item \textbf{Negotiate Device Features:} + Read device feature blocks via \msgref{GET_DEVICE_FEATURES}, decide which + to enable, and send the selected subset via one or more + \msgref{SET_DRIVER_FEATURES} requests. Verify FEATURES\_OK via + \msgref{SET_DEVICE_STATUS}. Transport feature bits are bus-instance + parameters and are determined separately from this per-device exchange. + \item \textbf{Device-Specific Setup:} 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 + \msgref{GET_CONFIG}/\msgref{SET_CONFIG} using the active configuration + semantics profile defined in + \ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles}, + then configure each virtqueue via \msgref{SET_VQUEUE} and verify 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. + \item \textbf{Finalize Initialization:} + Use \msgref{SET_DEVICE_STATUS} to transition to DRIVER\_OK. \end{enumerate} -The exact order may vary slightly across implementations, but these steps form -the baseline for virtio-msg initialization. +After \msgref{GET_DEVICE_INFO}, a driver MUST follow the core virtio status +progression for initialization: reset, ACKNOWLEDGE, DRIVER, feature +negotiation and FEATURES\_OK verification, device-specific setup, then +DRIVER\_OK. \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 + \item A driver MUST complete device 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. @@ -602,16 +861,13 @@ \subsubsection{Device Information} 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. +feature blocks, configuration space size, maximum virtqueues, 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 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. @@ -620,18 +876,23 @@ \subsubsection{Device Information} \subsubsection{Feature Negotiation} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Features} -Drivers read available features in 32-bit blocks using +Drivers read available device feature bits 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. +padding with zeros for any out-of-range blocks. To enable selected device +features, the driver sends the desired subset with one or more +\msgref{SET_DRIVER_FEATURES} requests and then updates the device status via +\msgref{SET_DEVICE_STATUS}, checking whether the FEATURES\_OK bit remains set. +Transport feature bits are bus-instance +parameters and are not part of this message exchange. Zero-padding and +block-scoped update semantics are defined in +\ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Device Feature Blocks}. \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 A driver MUST NOT negotiate VIRTIO\_F\_NOTIF\_CONFIG\_DATA. \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. @@ -639,43 +900,33 @@ \subsubsection{Feature Negotiation} \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}. + \item A device MUST NOT offer VIRTIO\_F\_NOTIF\_CONFIG\_DATA. + \item If the device cannot support the driver-selected feature set presented + before FEATURES\_OK is processed, it MUST clear the FEATURES\_OK bit 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} 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. - -\drivernormative{\paragraph}{Device Configuration}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Configuration / Driver} -\begin{itemize} - \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} - -\devicenormative{\paragraph}{Device Configuration}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Configuration / Device} -\begin{itemize} - \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} +supplying \field{offset} and \field{length}; the device returns the requested +data plus the configuration generation field. Writing is performed via +\msgref{SET_CONFIG}, which carries the same \field{offset}/\field{length} plus +generation and new data. +Generation-field handling follows the active profile defined in +\ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles}, +with strict profile defining generation-mismatch rejection for \msgref{SET_CONFIG}. +The message definitions for \msgref{GET_CONFIG} and \msgref{SET_CONFIG} +define request validation and completion behavior, while +\ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles} +defines generation handling and \msgref{EVENT_CONFIG} semantics throughout +initialization and operation. + +Configuration space is intended for device control and configuration data. +When a device can instead expose data through a virtqueue, that mechanism is +preferred; configuration reads and writes are asynchronous in virtio-msg and +may require the driver to wait for a response. \subsubsection{Virtqueue Configuration} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Initialization / Virtqueue Configuration} @@ -684,58 +935,23 @@ \subsubsection{Virtqueue Configuration} \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 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} - -\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} +then calling \msgref{SET_VQUEUE} with the chosen size, physical addresses, and +queue-state operation in \field{flags}. A \msgref{GET_VQUEUE} response with +\field{max_size}=0 indicates that the requested queue is not available for +configuration. The message definitions for \msgref{GET_VQUEUE}, +\msgref{SET_VQUEUE}, and \msgref{RESET_VQUEUE} define the normative +queue-availability, reconfiguration, and reset rules; this subsection +describes the usual sequencing. \subsubsection{Status Information} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Initialization / Status Information} 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} +\msgref{SET_DEVICE_STATUS}. Writing zero to the status field requests a device +reset, which can complete synchronously or asynchronously. The normative +status-reporting and reset-completion rules are defined by +\msgref{GET_DEVICE_STATUS} and \msgref{SET_DEVICE_STATUS}. \subsubsection{Finalizing Initialization} @@ -776,70 +992,67 @@ \subsection{Device Operation} \subsubsection{Driver Notifications} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / Driver Notifications} -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. +Drivers and devices MAY select polling-only operation for virtqueue +availability/completion handling. In polling-only mode, \msgref{EVENT_AVAIL} +and \msgref{EVENT_USED} are not semantic requirements. When endpoints use +event-driven notifications, drivers use \msgref{EVENT_AVAIL} to notify the +device of available buffers. A driver-side bus implementation may forward +\msgref{EVENT_AVAIL} in-band or translate it into an out-of-band notification +mechanism, but \msgref{EVENT_AVAIL} remains the standardized transport +representation of each driver notification occurrence. Generic bus delivery +rules for runtime notifications are defined later in the transport-message +overview. \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} - -\busnormative{\paragraph}{Driver Notifications}{Virtio Transport Options / Virtio Over Messages / Device Operation / Driver Notifications / Bus} -\begin{itemize} - \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. + \item A driver and device MAY select polling-only operation for virtqueue + notification/completion handling. + \item If polling-only mode is selected, a driver MAY omit + \msgref{EVENT_AVAIL} and rely on polling for progress. + \item If polling-only mode is not selected, a driver MUST use + \msgref{EVENT_AVAIL} to notify the device of available buffers. \end{itemize} \subsubsection{Device Notifications} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / Device Notifications} \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. - +from the device to the driver through the bus layer. Endpoints MAY select +polling-only operation for used-buffer completion; in that mode, +\msgref{EVENT_USED} is not a semantic requirement. A device-side transport +implementation originates event-driven notifications using the standardized +event messages. The local bus implementation may forward those events in-band +or translate them into out-of-band signaling. The receiving-side bus +implementation then forwards the originating event or synthesizes one +equivalent transport event so the driver-side transport observes exactly one +transport-visible notification occurrence when events are used. Generic bus +delivery rules for runtime notifications are defined later in the +transport-message overview. \devicenormative{\paragraph}{Device Notifications}{Virtio Transport Options / Virtio Over Messages / Device Operation / Device Notifications / Device} \begin{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. + \item A device transport layer implementation MUST originate + \msgref{EVENT_USED} notification occurrences for used buffers on a + virtqueue when polling-only mode is not selected by the endpoints. + \item If polling-only mode is selected by the endpoints, a device MAY omit + \msgref{EVENT_USED} and rely on polling-visible queue state changes for + completion observation. \end{itemize} \drivernormative{\paragraph}{Device Notifications}{Virtio Transport Options / Virtio Over Messages / Device Operation / Device Notifications / Driver} \begin{itemize} \item Upon receiving \msgref{EVENT_CONFIG}, a driver SHOULD update its view of - the configuration using the provided data (or by issuing + the configuration using provided data (or by issuing \msgref{GET_CONFIG} if necessary) before resuming normal I/O. + \item If \msgref{EVENT_CONFIG} provides no data and has + \field{offset} and \field{length} set to 0, a driver SHOULD treat it as + a generic configuration-change notification and refresh required + configuration via \msgref{GET_CONFIG}. \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} - -\busnormative{\paragraph}{Device Notifications}{Virtio Transport Options / Virtio Over Messages / Device Operation / Device Notifications / Bus} -\begin{itemize} - \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. + \item If polling-only mode is selected by the endpoints, a driver MAY rely on + polling to observe used-buffer completion and MUST NOT require a + transport-visible \msgref{EVENT_USED} semantic occurrence. \end{itemize} \subsubsection{Configuration Changes During Operation} @@ -848,97 +1061,52 @@ \subsubsection{Configuration Changes During Operation} 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} +\msgref{EVENT_CONFIG}. The same \msgref{GET_CONFIG}, \msgref{SET_CONFIG}, and +\msgref{EVENT_CONFIG} rules continue to apply after initialization, including +the active configuration semantics profile. \subsubsection{Virtqueue Changes During Operation} \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} - -\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} +\msgref{SET_VQUEUE}. Queue reconfiguration remains constrained to disabled +queues. If a queue is enabled, the driver first resets that queue via +\msgref{RESET_VQUEUE} when VIRTIO\_F\_RING\_RESET is negotiated. The same +\msgref{GET_VQUEUE}, \msgref{SET_VQUEUE}, and \msgref{RESET_VQUEUE} rules +continue to apply after initialization. \subsubsection{Device Reset and Shutdown} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / Reset} -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} +Drivers request a device reset by writing 0 to \field{status} via +\msgref{SET_DEVICE_STATUS}. Reset completion can be synchronous or +asynchronous. A driver confirms completion from a +\msgref{SET_DEVICE_STATUS} response \field{status} of 0 or by polling +\msgref{GET_DEVICE_STATUS} until \field{status} is 0. A device may also signal +that a reset is required by setting DEVICE\_NEEDS\_RESET in its +\field{status} and reporting the updated \field{status} to the driver. After +reset completion, the core virtio post-reset requirements continue to apply. +The normative reset-completion rules are defined by +\msgref{GET_DEVICE_STATUS} and \msgref{SET_DEVICE_STATUS}. \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 +those changes with \busref{EVENT_DEVICE} (ADDED 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 + \item A bus implementation that uses \busref{EVENT_DEVICE} MUST send the ADDED 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. + reported the bus implementation MUST expose the device number to the + driver side so the driver can issue \msgref{GET_DEVICE_INFO}. When a + device is removed, the bus implementation MUST notify the driver side + so it can quiesce and release the associated driver state. \end{itemize} \subsection{Transport Messages}\label{sec:Virtio Transport Options / Virtio Over Messages / Transport Messages} @@ -958,59 +1126,52 @@ \subsubsection{Overview} the target device exists. Most transport messages are request/response pairs, with events reserved for asynchronous notifications. -\paragraph{Messages IDs and issuers} +\paragraph{Message IDs and initiating side} + +In the table below, the initiating side identifies which side of the +transport-message exchange starts the message. \begin{tabular}{|l|l|l|} \hline -Name & ID & Sender \\ +Name & ID & Initiating side \\ \hline \hline Reserved & 0x0 & \\ \hline Reserved & 0x1 & \\ \hline -\msgref{GET_DEVICE_INFO} & 0x2 & Driver \\ +\msgref{GET_DEVICE_INFO} & 0x2 & Driver side \\ \hline -\msgref{GET_DEVICE_FEATURES} & 0x3 & Driver \\ +\msgref{GET_DEVICE_FEATURES} & 0x3 & Driver side \\ \hline -\msgref{SET_DRIVER_FEATURES} & 0x4 & Driver \\ +\msgref{SET_DRIVER_FEATURES} & 0x4 & Driver side \\ \hline -\msgref{GET_CONFIG} & 0x5 & Driver \\ +\msgref{GET_CONFIG} & 0x5 & Driver side \\ \hline -\msgref{SET_CONFIG} & 0x6 & Driver \\ +\msgref{SET_CONFIG} & 0x6 & Driver side \\ \hline -\msgref{GET_DEVICE_STATUS} & 0x7 & Driver \\ +\msgref{GET_DEVICE_STATUS} & 0x7 & Driver side \\ \hline -\msgref{SET_DEVICE_STATUS} & 0x8 & Driver \\ +\msgref{SET_DEVICE_STATUS} & 0x8 & Driver side \\ \hline -\msgref{GET_VQUEUE} & 0x9 & Driver \\ +\msgref{GET_VQUEUE} & 0x9 & Driver side \\ \hline -\msgref{SET_VQUEUE} & 0xA & Driver \\ +\msgref{SET_VQUEUE} & 0xA & Driver side \\ \hline -\msgref{RESET_VQUEUE} & 0xB & Driver \\ +\msgref{RESET_VQUEUE} & 0xB & Driver side \\ \hline -\msgref{GET_SHM} & 0xC & Driver \\ +\msgref{GET_SHM} & 0xC & Driver side \\ \hline -\msgref{EVENT_CONFIG} & 0x40 & Device \\ +\msgref{EVENT_CONFIG} & 0x40 & Device side \\ \hline -\msgref{EVENT_AVAIL} & 0x41 & Driver \\ +\msgref{EVENT_AVAIL} & 0x41 & Driver side \\ \hline -\msgref{EVENT_USED} & 0x42 & Device \\ +\msgref{EVENT_USED} & 0x42 & Device side \\ \hline \end{tabular} -IDs are grouped as follows; bit 6 distinguishes requests (0) from events (1): - -\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} +Transport-message ID bit encoding is defined in +\ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Common Message Format}. \devicenormative{\paragraph}{Core Messages}{Virtio Transport Options / Virtio Over Messages / Transport Messages / Mandatory / Device} \begin{itemize} @@ -1018,13 +1179,18 @@ \subsubsection{Overview} \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}. + \msgref{RESET_VQUEUE}, and \msgref{GET_SHM}. \end{itemize} \drivernormative{\paragraph}{Core Messages}{Virtio Transport Options / Virtio Over Messages / Transport Messages / Mandatory / Driver} \begin{itemize} - \item A driver MUST support sending and interpreting the messages listed - above in order to initialize and operate a virtio-msg device. + \item A driver MUST support sending and interpreting + \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} in order to + initialize and operate a virtio-msg device. \end{itemize} As described in Sections @@ -1032,14 +1198,57 @@ \subsubsection{Overview} 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. +\msgref{EVENT_CONFIG}) are defined as transport messages. Out-of-band signaling +may be used as a wakeup hint, but each notification occurrence still has one +authoritative transport-message path. + +\busnormative{\paragraph}{Runtime Notifications}{Virtio Transport Options / Virtio Over Messages / Transport Messages / Runtime Notifications / Bus} +\begin{itemize} + \item A bus implementation MUST specify whether runtime notifications + (\msgref{EVENT_AVAIL}, \msgref{EVENT_USED}, and \msgref{EVENT_CONFIG}) + use forwarding or synthesis as the authoritative transport-message path. + \item If a bus implementation specifies out-of-band signaling, it MUST + document the mechanism and any required configuration to use it. + \item For each \msgref{EVENT_CONFIG} notification occurrence, and for each + \msgref{EVENT_AVAIL} or \msgref{EVENT_USED} notification occurrence + when the endpoints use transport-visible notifications for that + direction, a bus implementation MUST produce exactly one authoritative + transport-message occurrence and MUST NOT combine forwarding and + synthesis for the same occurrence. + \item If a bus implementation uses out-of-band signaling for a runtime + notification occurrence, the receiving-side bus implementation MUST + forward the originating event or synthesize exactly one equivalent + transport message. It MUST NOT expose both forwarded and synthesized + events for the same occurrence. + \item Out-of-band signaling MUST be treated as a wakeup hint and MUST NOT be + treated as an additional semantic notification occurrence. + \item If polling-only mode is selected by the endpoints for availability + handling or used-buffer completion, any bus-side polling, forwarding, + or synthesis logic for that function MUST remain transparent and MUST + NOT create a transport-visible \msgref{EVENT_AVAIL} or + \msgref{EVENT_USED} semantic occurrence. + \item A bus implementation MUST use bounded timeout and polling policies for + runtime-notification delivery. If delivery cannot be completed within + the bounded policy for a notification occurrence that requires a + transport-visible event, it MUST surface a transport-visible failure + and MUST define recovery behavior using the reset and status + mechanisms. +\end{itemize} \msgdef{GET_DEVICE_INFO} 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. +data and limits for a device. The response includes \field{device_uuid}, a +16-byte UUID value. The nil UUID defined by +\hyperref[intro:rfc4122]{[RFC4122]} indicates that no UUID is provided. +\field{admin_vq_start} and \field{admin_vq_count} identify a contiguous range +of administration virtqueues within \field{max_virtqueues}. If +\field{admin_vq_count} is 0, the device exposes no administration virtqueues +and \field{admin_vq_start} is 0. +\msgref{GET_DEVICE_INFO} is the only transport message that may be issued as an +early-discovery exception before the normal initialization sequence begins. +After \msgref{GET_DEVICE_INFO}, drivers follow the standard virtio +initialization sequence and use other transport messages only within that flow. \begin{lstlisting} struct virtio_msg_get_device_info_req { @@ -1049,33 +1258,59 @@ \subsubsection{Overview} 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) */ + u8 device_uuid[16]; /* UUID, or nil UUID if unavailable */ + le32 num_feature_blocks; /* total number of 32-bit feature blocks */ 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 */ + le32 admin_vq_start; /* index of the first admin virtqueue */ + le32 admin_vq_count; /* number of admin virtqueues */ }; \end{lstlisting} \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. + MUST supply consistent values for device ID, vendor ID, feature-block + count, configuration size, and virtqueue limits. + \item A device MUST report \field{num_feature_blocks} large enough to cover + every feature bit the device offers. + \item A device MUST report \field{max_virtqueues} no greater than 65536. + \item \field{max_virtqueues} MUST include any administration virtqueues + described by \field{admin_vq_start} and \field{admin_vq_count}. + \item If \field{admin_vq_count} is 0, a device MUST set + \field{admin_vq_start} to 0. + \item If \field{admin_vq_count} is greater than 0, a device MUST ensure + \field{admin_vq_start} + \field{admin_vq_count} does not exceed + \field{max_virtqueues}. + \item A device MAY set \field{device_uuid} to a UUID value that can be used + as a unique identifier. + \item If a device sets \field{device_uuid} to a non-nil value, it SHOULD use + a version 4 UUID as specified by + \hyperref[intro:rfc4122]{[RFC4122]}. + \item If a device does not support UUID reporting or does not have an + identifier, it MUST set \field{device_uuid} to the nil UUID. \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 + feature-block count, configuration size, and virtqueue limits before proceeding with initialization. + \item A driver MUST interpret \field{admin_vq_count}=0 as indicating that the + device exposes no administration virtqueues. + \item If \field{admin_vq_count} is greater than 0, a driver MUST treat the + range starting at \field{admin_vq_start} and spanning + \field{admin_vq_count} entries as part of \field{max_virtqueues}. + \item A driver MUST interpret a nil UUID in \field{device_uuid} as indicating + that no UUID is provided. \end{itemize} \msgdef{GET_DEVICE_FEATURES} 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. +returns one or more 32-bit values with the device-offered feature bits in that +range. \begin{lstlisting} struct virtio_msg_get_device_features_req { @@ -1090,11 +1325,8 @@ \subsubsection{Overview} }; \end{lstlisting} -\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} +Zero-padding for out-of-range blocks is defined in +\ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Device Feature Blocks}. \drivernormative{\paragraph}{GET\_DEVICE\_FEATURES}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_DEVICE_FEATURES / Driver} \begin{itemize} @@ -1105,13 +1337,17 @@ \subsubsection{Overview} \msgdef{SET_DRIVER_FEATURES} -Drivers use \msgref{SET_DRIVER_FEATURES} to acknowledge the subset of feature +Drivers use \msgref{SET_DRIVER_FEATURES} to convey 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. +Each \msgref{SET_DRIVER_FEATURES} request updates only the addressed blocks; +blocks outside the addressed range are unchanged. Drivers MAY send multiple +\msgref{SET_DRIVER_FEATURES} requests at different block offsets before setting +FEATURES\_OK. The response has no payload. \begin{lstlisting} struct virtio_msg_set_driver_features_req { - le32 block_index; /* starting block being acknowledged */ + le32 block_index; /* starting block being selected */ le32 num_blocks; /* number of blocks provided */ le32 features[]; /* num_blocks entries with desired bits */ }; @@ -1125,22 +1361,21 @@ \subsubsection{Overview} \begin{itemize} \item A driver MUST set only the feature bits it intends to enable in the blocks supplied to \msgref{SET_DRIVER_FEATURES}. + \item A driver MAY use multiple \msgref{SET_DRIVER_FEATURES} requests with + different \field{block_index} values to build the final driver-selected + feature set before setting FEATURES\_OK. \end{itemize} -\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} +Block-scoped update semantics for \msgref{SET_DRIVER_FEATURES} are defined in +\ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Device Feature Blocks}. \msgdef{GET_CONFIG} \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. +specifies the byte \field{offset} and \field{length}; the response echoes those +values, returns the data, and includes the current generation count. Generation +semantics follow the active configuration profile defined in +\ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles}. \begin{lstlisting} struct virtio_msg_get_config_req { @@ -1149,7 +1384,7 @@ \subsubsection{Overview} }; struct virtio_msg_get_config_resp { - le32 generation; /* current configuration generation count */ + le32 generation; /* current generation count */ le32 offset; /* echoed offset */ le32 length; /* echoed length */ u8 data[]; /* configuration payload */ @@ -1158,52 +1393,75 @@ \subsubsection{Overview} \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}. + \item A driver MUST ensure the requested \field{offset} and \field{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. + \item A device MUST include its current generation count in the + \field{generation} field of every \msgref{GET_CONFIG} response. \end{itemize} \msgdef{SET_CONFIG} \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. +\field{offset}, \field{length}, the driver's view of the generation count, and +the new data. The device echoes the \field{offset}/\field{length}, returns the +resulting generation count, and reports in response \field{length} whether the +requested nonzero write was applied in full. A request with \field{length}=0 is +a valid no-op. For a request with \field{length}>0, the device either applies +all requested bytes and returns response \field{length} equal to the request +\field{length}, or applies nothing and returns response \field{length}=0 with no +payload bytes. +Generation-mismatch rejection is defined only for strict profile. +Generation semantics follow the active configuration profile defined in +\ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles}. \begin{lstlisting} struct virtio_msg_set_config_req { - le32 generation; /* driver's view of generation count */ + le32 generation; /* driver's view; used for mismatch rejection only in + * strict profile (MUST be 0 otherwise) */ le32 offset; /* byte offset being written */ - le32 length; /* number of bytes written */ + le32 length; /* number of bytes requested; 0 is a valid no-op */ u8 data[]; /* configuration payload */ }; 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 */ + le32 length; /* request length if fully applied; 0 if not applied */ + u8 data[]; /* echoed data for a fully applied nonzero write; omitted if length is 0 */ }; \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. + \item A driver MUST keep the \field{offset} and \field{length} within the + reported + configuration size in each \msgref{SET_CONFIG} request. + \item A driver MAY issue \msgref{SET_CONFIG} with \field{length}=0 as a + no-op. + \item If a driver issues \msgref{SET_CONFIG} with request \field{length}>0, + it MUST treat response \field{length} equal to the request + \field{length} as fully applied and response \field{length}=0 as not + applied; partial nonzero lengths are not valid success indications. \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. + \item A device MUST set response \field{generation} to its current generation + count in every \msgref{SET_CONFIG} response. + \item If a device accepts \msgref{SET_CONFIG} with request \field{length}=0, + it MUST treat the request as a no-op. + \item For \msgref{SET_CONFIG} requests with request \field{length}>0, a + device MUST either apply all requested bytes and set response + \field{length} to the request \field{length}, or apply no bytes and set + response \field{length} to 0; partial nonzero application is not + allowed. + \item If a device sets response \field{length} to 0, it MUST NOT include + response \field{data} bytes. \end{itemize} \msgdef{GET_DEVICE_STATUS} @@ -1222,19 +1480,40 @@ \subsubsection{Overview} }; \end{lstlisting} +\drivernormative{\paragraph}{GET\_DEVICE\_STATUS}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_DEVICE_STATUS / Driver} +\begin{itemize} + \item A driver MAY send \msgref{GET_DEVICE_STATUS} whenever it needs the + current device status bits. + \item If device status reports DEVICE\_NEEDS\_RESET, a driver SHOULD write 0 + via \msgref{SET_DEVICE_STATUS} and reinitialize the device before + resuming I/O. + \item When waiting for reset completion after writing status 0 via + \msgref{SET_DEVICE_STATUS} and synchronous completion is not indicated, + a driver MUST poll \msgref{GET_DEVICE_STATUS} until + \field{status}=0 before continuing initialization. +\end{itemize} + \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. + \item If a device encounters an unrecoverable error that requires driver + intervention, it SHOULD set DEVICE\_NEEDS\_RESET in the status it + reports to the driver. \end{itemize} \msgdef{SET_DEVICE_STATUS} \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). +The response reports the \field{status} value observed when the response is +generated. For a reset request (\field{status} == 0), a response +\field{status} of 0 indicates reset completion; a non-zero \field{status} +indicates that reset completion may still be pending. The resulting +\field{status} may differ from the requested \field{status} (for example, if +the device refuses FEATURES\_OK or sets DEVICE\_NEEDS\_RESET). After reset +completion, core virtio post-reset requirements continue to apply. \begin{lstlisting} struct virtio_msg_set_device_status_req { @@ -1249,22 +1528,34 @@ \subsubsection{Overview} \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. + reset. + \item A driver that needs to confirm reset completion MUST treat a + \msgref{SET_DEVICE_STATUS} response \field{status} of 0 as completion; + otherwise it MUST poll \msgref{GET_DEVICE_STATUS} until the device + reports \field{status}=0 before reinitializing the device. \end{itemize} \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. + response if it cannot accept the requested \field{status}, but it MUST + report the resulting \field{status} accurately. + \item Upon receiving \msgref{SET_DEVICE_STATUS} with \field{status} set to 0, + a device MUST start reset processing and MUST eventually complete reset + by reporting \field{status}=0. + \item A device MAY complete reset before sending the + \msgref{SET_DEVICE_STATUS} response (synchronous completion) or after + sending it (asynchronous completion). + \item A device MUST NOT report \field{status}=0 until reset completion. \end{itemize} \msgdef{GET_VQUEUE} \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. +its maximum size, current size, enabled state, and, if already configured, the +descriptor, driver, and device area physical addresses. For unavailable, +unimplemented, or out-of-range queue indexes, the response uses a +deterministic zero sentinel while still echoing the requested \field{index}. \begin{lstlisting} struct virtio_msg_get_vqueue_req { @@ -1273,38 +1564,56 @@ \subsubsection{Overview} 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 */ + le32 max_size; /* maximum queue size (0 if unavailable) */ + le32 cur_size; /* current size (0 if unconfigured/unavailable) */ + le32 flags; /* bit0: enabled state, 0 if unavailable */ + le64 desc_addr; /* descriptor area physical address (0 if unavailable) */ + le64 driver_addr; /* driver area physical address (0 if unavailable) */ + le64 device_addr; /* device area physical address (0 if unavailable) */ }; \end{lstlisting} +\drivernormative{\paragraph}{GET\_VQUEUE}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_VQUEUE / Driver} +\begin{itemize} + \item Before configuring a virtqueue, a driver MUST query that queue with + \msgref{GET_VQUEUE} and MUST treat \field{max_size}=0 as unavailable, + unimplemented, or out of range. + \item When issuing \msgref{SET_VQUEUE} for a queue with nonzero + \field{max_size}, a driver MUST NOT request a queue size greater than + the \field{max_size} reported by \msgref{GET_VQUEUE}. +\end{itemize} + \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. + \item For an available and implemented virtqueue index, a device MUST report + accurate maxima and current queue sizes and MUST return zero as the + current size if the queue has not yet been configured. + \item For an unavailable, unimplemented, or out-of-range virtqueue index + (\field{index} >= \field{max_virtqueues} from \msgref{GET_DEVICE_INFO}), + a device MUST return the deterministic unavailable-queue sentinel: + \field{max_size}=0, \field{cur_size}=0, \field{flags}=0, + \field{desc_addr}=0, \field{driver_addr}=0, and \field{device_addr}=0, + while echoing the requested \field{index}. + \item A device MUST report queue enabled state in \field{flags} bit 0 and + MUST set \field{flags} bits 31:1 to zero. \end{itemize} \msgdef{SET_VQUEUE} -\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. +\msgref{SET_VQUEUE} updates a virtqueue's parameters and queue state. The +driver selects a queue index and uses \field{flags} to indicate whether queue +state should be enabled, kept disabled, or kept unchanged, and which queue +fields should be ignored versus updated. \begin{lstlisting} struct virtio_msg_set_vqueue_req { le32 index; /* virtqueue index */ - le32 reserved0; /* must be zero */ + le32 flags; /* state op + ignore bits */ 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 */ + le32 reserved; /* must be zero */ + le64 desc_addr; /* descriptor area physical address */ + le64 driver_addr; /* driver area physical address */ + le64 device_addr; /* device area physical address */ }; struct virtio_msg_set_vqueue_resp { @@ -1312,25 +1621,90 @@ \subsubsection{Overview} }; \end{lstlisting} +\field{flags} is defined as: +\begin{itemize} + \item Bits [1:0] (\textbf{State Operation}): + \begin{itemize} + \item 0: keep queue disabled. + \item 1: enable queue. + \item 2: keep current queue state. + \item 3: reserved. + \end{itemize} + \item Bit 2 (\textbf{size\_ignore}): 0=apply \field{size}, 1=ignore. + \item Bit 3 (\textbf{desc\_addr\_ignore}): 0=apply \field{desc_addr}, + 1=ignore. + \item Bit 4 (\textbf{driver\_addr\_ignore}): 0=apply \field{driver_addr}, + 1=ignore. + \item Bit 5 (\textbf{device\_addr\_ignore}): 0=apply \field{device_addr}, + 1=ignore. + \item Bits [31:6]: reserved, MUST be zero. +\end{itemize} + +When \field{flags} is zero, \msgref{SET_VQUEUE} uses current behavior: +if the queue is disabled, all queue fields in the request are applied and the +queue remains disabled. + \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. + \item A driver MUST set \field{reserved} to zero and MUST set \field{flags} + bits [31:6] to zero. + \item A driver MUST NOT use state operation value 3 in \field{flags} bits + [1:0]. + \item A driver SHOULD use \msgref{GET_VQUEUE} to determine whether a queue is + available before relying on \msgref{SET_VQUEUE} to modify it. + \item A driver MUST NOT use state operation value 0 as a request to disable an + already enabled queue. + \item If \field{size\_ignore} is 0, a driver MUST set \field{size} to a value + not exceeding the maximum reported by \msgref{GET_VQUEUE}. + \item If any address ignore bit is 0, a driver MUST ensure the corresponding + physical address points to properly aligned memory. + \item A driver MUST NOT attempt to update queue size or queue addresses via + \msgref{SET_VQUEUE} while the queue is enabled. + \item If a driver needs to reconfigure an enabled queue, it MUST issue + \msgref{RESET_VQUEUE} first when VIRTIO\_F\_RING\_RESET is negotiated. + \item Because \msgref{SET_VQUEUE} has no response payload, a driver that + needs confirmation of acceptance MUST verify the resulting queue + parameters and state via \msgref{GET_VQUEUE} before relying on the + requested updates. \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. + \item For an unavailable, unimplemented, or out-of-range virtqueue index + (\field{index} >= \field{max_virtqueues} from \msgref{GET_DEVICE_INFO}), + a device MUST treat \msgref{SET_VQUEUE} as a no-op and MUST NOT modify + any queue state or parameters. + \item If \field{reserved} is nonzero, if \field{flags} bits [31:6] are + nonzero, or if \field{flags} bits [1:0] use state operation value 3, a + device MUST do nothing (no queue state or parameter change) and MUST + return the normal empty \msgref{SET_VQUEUE} response. + \item If \field{flags} requests state operation value 0 for a queue that is + currently enabled, a device MUST do nothing (no queue state or + parameter change) and MUST return the normal empty + \msgref{SET_VQUEUE} response. + \item A device MUST process \msgref{SET_VQUEUE} updates atomically: it MUST + either apply all requested field updates and queue-state changes, or + do nothing (no queue state or parameter change) and return the normal + empty \msgref{SET_VQUEUE} response. + \item If an ignore bit is 0, a device MUST apply the corresponding field from + \msgref{SET_VQUEUE}; if an ignore bit is 1, a device MUST keep the + current value for that field unchanged. + \item For a queue that is enabled, if \msgref{SET_VQUEUE} attempts to update + \field{size}, \field{desc_addr}, \field{driver_addr}, or + \field{device_addr}, a device MUST do nothing (no queue state or + parameter change) and MUST return the normal empty + \msgref{SET_VQUEUE} response. + \item A device MUST apply queue state according to \field{flags} bits [1:0] + after processing requested field updates, and MUST NOT perform an + enabled-to-disabled transition via \msgref{SET_VQUEUE}. \end{itemize} \msgdef{RESET_VQUEUE} \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. +after the queue has been quiesced. After reset completion, the core virtio +post-reset requirements for that queue continue to apply. \begin{lstlisting} struct virtio_msg_reset_vqueue_req { @@ -1344,110 +1718,147 @@ \subsubsection{Overview} \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 + \item A driver MUST issue \msgref{RESET_VQUEUE} only if VIRTIO\_F\_RING\_RESET has been negotiated and it needs to reconfigure or recover a specific queue. + \item A driver SHOULD use \msgref{GET_VQUEUE} to determine whether a queue is + available before relying on \msgref{RESET_VQUEUE} to affect it. + \item If an enabled queue requires reconfiguration and + VIRTIO\_F\_RING\_RESET is negotiated, a driver MUST wait for + \msgref{RESET_VQUEUE} completion before issuing \msgref{SET_VQUEUE} + updates for that queue. \end{itemize} \devicenormative{\paragraph}{RESET\_VQUEUE}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_RESET_VQUEUE / Device} \begin{itemize} + \item For an unavailable, unimplemented, or out-of-range virtqueue index + (\field{index} >= \field{max_virtqueues} from \msgref{GET_DEVICE_INFO}), + a device MUST treat \msgref{RESET_VQUEUE} as a no-op and MUST NOT + modify any queue state. + \item If VIRTIO\_F\_RING\_RESET has not been negotiated, a device MUST do + nothing (no queue state change) and MUST return the normal empty + \msgref{RESET_VQUEUE} response. \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}. + driver to reconfigure it via \msgref{SET_VQUEUE} while the queue is + disabled. \end{itemize} \msgdef{GET_SHM} \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. +region. The request carries the shared-memory region identifier +\field{shmid}; the response echoes \field{shmid} and provides the base +physical \field{address} and \field{length}. A \field{length} of zero +indicates that the specified \field{shmid} is not supported by the device. \begin{lstlisting} struct virtio_msg_get_shm_req { - le32 index; /* shared memory region index */ + le32 shmid; /* shared memory region identifier */ }; struct virtio_msg_get_shm_resp { - le32 index; /* echoed index */ - le32 length; /* region length (0 if nonexistent) */ - le32 address;/* region address */ + le32 shmid; /* echoed region identifier */ + le32 reserved; /* must be zero */ + le64 length; /* region length (0 if nonexistent) */ + le64 address; /* region physical address */ }; \end{lstlisting} \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. + \item A device MUST return zero \field{length} if the requested + \field{shmid} is not supported and MUST report accurate physical + \field{address}/\field{length} information for regions it supports. + \item A device MUST set the \field{reserved} field in \msgref{GET_SHM} + responses to zero. \end{itemize} \msgdef{EVENT_CONFIG} -\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}. +\msgref{EVENT_CONFIG} notifies the driver about configuration changes or +device-originated asynchronous status changes that require asynchronous +reporting. The payload includes current device status, generation, and +configuration \field{offset}/\field{length}. The configuration data can be +omitted; if omitted, the driver re-fetches via \msgref{GET_CONFIG}. Generation +and \field{offset}/\field{length} semantics are defined in +\ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles}. +Ordinary driver-originated status writes via \msgref{SET_DEVICE_STATUS} are +already observed synchronously and do not by themselves trigger +\msgref{EVENT_CONFIG}; an event may be sent later only when a distinct +device-originated asynchronous status change occurs afterward. +If the event reports only a status change with no configuration update, the +device sets \field{offset} and \field{length} to zero. \begin{lstlisting} struct virtio_msg_event_config { le32 device_status; /* new device status value */ - le32 generation; /* configuration generation count */ + le32 generation; /* current generation count */ le32 offset; /* configuration offset */ - le32 length; /* number of bytes (may be zero) */ + le32 length; /* number of bytes in affected range */ u8 data[]; /* optional configuration data */ }; \end{lstlisting} -\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} - -\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} +The conditions that require \msgref{EVENT_CONFIG}, and its generation and +\field{offset}/\field{length} semantics, are defined by +\ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles} +and +\ref{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / Device Notifications}. \msgdef{EVENT_AVAIL} \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. +message includes the virtqueue index in \field{vq_index} and, if +VIRTIO\_F\_NOTIFICATION\_DATA is negotiated, a combined next-offset/next-wrap +field in \field{next_offset} so the device can jump directly to the updated +position. If VIRTIO\_F\_NOTIFICATION\_DATA is not negotiated, \field{next_offset} +is reserved and is set to zero. This transport does not support +VIRTIO\_F\_NOTIF\_CONFIG\_DATA; \field{vq_index} always identifies the target +virtqueue by index. When VIRTIO\_F\_NOTIFICATION\_DATA is negotiated, +\field{next_offset} encodes core virtio notification data: +\field{next_offset}[30:0] carries core \field{next_off}, and +\field{next_offset}[31] carries core \field{next_wrap}. For split virtqueues, +\field{next_off} is derived from split-ring available-index progression and +\field{next_wrap} is zero. For packed virtqueues, \field{next_off} and +\field{next_wrap} are derived from packed-ring notification-data values as +defined by core virtio. \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 */ + le32 next_offset; /* bits[30:0] offset, bit[31] wrap; reserved if unused */ }; \end{lstlisting} \drivernormative{\paragraph}{EVENT\_AVAIL}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_AVAIL / Driver} \begin{itemize} + \item A driver MUST identify the target virtqueue in \field{vq_index}. \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. + set \field{next_offset} to zero in \msgref{EVENT_AVAIL} messages. If it + has been negotiated, the driver MUST encode core \field{next_off} in + \field{next_offset}[30:0] and core \field{next_wrap} in + \field{next_offset}[31], using split-queue or packed-queue derivation + as defined by core virtio. \end{itemize} \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. + \item If a bus implementation cannot preserve + VIRTIO\_F\_NOTIFICATION\_DATA semantics for \msgref{EVENT_AVAIL}, it + MUST prevent negotiation of VIRTIO\_F\_NOTIFICATION\_DATA. \end{itemize} \msgdef{EVENT_USED} \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. +its used ring to determine which descriptors completed. If polling-only mode is +selected by the endpoints, \msgref{EVENT_USED} is not a semantic requirement +for completion observation. Polling-only selection and the requirement to +originate \msgref{EVENT_USED} when event-driven completion is used are defined +in +\ref{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / Device Notifications}. \begin{lstlisting} struct virtio_msg_event_used { @@ -1455,19 +1866,6 @@ \subsubsection{Overview} }; \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} @@ -1484,101 +1882,121 @@ \subsubsection{Overview} 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} +\paragraph{Message IDs and initiating side} + +In the table below, the initiating side identifies which side of the bus +message exchange starts the message, not the local software component that +serializes it on a particular implementation. \begin{tabular}{|l|l|l|} \hline -Name & ID & Sender \\ +Name & ID & Initiating side \\ \hline \hline Reserved & 0x0 & \\ \hline Reserved & 0x1 & \\ \hline -\busref{GET_DEVICES} & 0x2 & Driver \\ +\busref{GET_DEVICES} & 0x2 & Driver side \\ \hline -\busref{PING} & 0x3 & Any \\ +\busref{PING} & 0x3 & Either side \\ \hline -\busref{EVENT_DEVICE} & 0x40 & Device \\ +\busref{EVENT_DEVICE} & 0x40 & Device side \\ \hline \end{tabular} -Bus message IDs are grouped as follows: - -\begin{tabular}{|l|l|p{7cm}|} -\hline -Range & Usage & Notes \\ -\hline -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} +Bus-message ID bit encoding is defined in +\ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Common Message Format}. \paragraph{Bus Specific Messages} -\label{sec:Virtio Transport Options / Virtio Over Messages / Bus Operation / Bus Specific Messages} +\label{sec:Virtio Transport Options / Virtio Over Messages / Bus Messages / Bus Specific Messages} A range of message IDs are reserved for use by the specific bus -implementation. These messages can be used for any implementation specific +implementation. These messages can be used for any implementation-specific usage. Example usage could include: \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 Declare bus-specific error conditions \item Provide extra debug or logging information \end{itemize} \busdef{GET_DEVICES} -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. +A bus implementation uses this request to enumerate device numbers exposed by a +peer bus instance. The response describes a window of device numbers and +signals which entries are present. \begin{lstlisting} struct virtio_bus_msg_get_devices_req { le16 offset; /* starting device number */ - le16 count; /* number of device-number slots (multiple of 8) */ + le16 count; /* number of device-number slots requested */ }; 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 */ + le16 count; /* number of slots returned */ + u8 bitmap[]; /* ((count + 7) / 8) bytes, LSB-first packing */ }; \end{lstlisting} -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. - -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 +The (\field{offset}, \field{count}) tuple defines a window of \field{count} +consecutive device numbers beginning at \field{offset}. A request with +\field{count}=0 is valid and requests an empty window. The number of present +devices equals the number of set bits in the first \field{count} positions of +\field{bitmap}. The \field{bitmap} size in bytes is +\textbf{(\field{count} + 7) / 8}. The response \field{count} MUST NOT exceed +the request \field{count}. Responders SHOULD return the requested +\field{count} unless constrained +(e.g., by maximum message size) or when trailing parts of the requested window +contain no present device numbers; in those cases they MAY return a smaller +value, and the \field{bitmap} covers the reduced window. A response with +\field{count}=0 returns an empty \field{bitmap}; this is valid for a request +with \field{count}=0 and also when no devices are present in the returned +window. + +Example: a request with \field{offset}=0, \field{count}=16 might produce +\field{bitmap}=0b00100101 00000000 and \field{next_offset}=16. That indicates +devices 0, 2, and 5 are present within the 0-15 window and suggests continuing at device number 16. -\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. +Drivers can use this message to enumerate device numbers. Each window can be +treated as a snapshot, advanced using \field{next_offset}, and validated with +\msgref{GET_DEVICE_INFO} before other transport messages are issued. A response +with \field{next_offset}=0 is terminal. Otherwise, \field{next_offset} +recommends a later starting device number and advances enumeration beyond the +request \field{offset}. \busnormative{\paragraph}{GET\_DEVICES}{Virtio Transport Options / Virtio Over Messages / Bus Messages / GET_DEVICES / Bus} \begin{itemize} - \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}. + \item The responding bus implementation MUST interpret \field{count} as a + number of + device-number slots and MUST return a \field{bitmap} of + \textbf{(\field{count} + 7) / 8} bytes, packed least-significant-bit + first. + \item A request with \field{count}=0 is valid. In response to such a request, + the responding bus implementation MUST return \field{count}=0 and an + empty \field{bitmap}. + \item The responding bus implementation MUST NOT return a \field{count} value + greater + than the \field{count} value from the request. + \item If \field{count} is not a multiple of 8, the responder MUST set unused + bits in the last \field{bitmap} byte (positions at or above + \field{count}) to zero. + \item For a terminal response, the responding bus implementation MUST set + \field{next\_offset} to 0. + \item For a nonterminal response, the responding bus implementation MUST set + \field{next\_offset} to a value strictly greater than the request + \field{offset}. + \item Responders SHOULD return the requested \field{count} unless constrained + (e.g., by maximum message size) or when trailing parts of the requested + window contain no present device numbers; if a smaller \field{count} is + returned, the \field{bitmap} MUST still represent the window defined by + the echoed \field{offset} and \field{count}. + \item If no devices are present in the requested window, a responder MAY + return \field{count}=0 with an empty \field{bitmap}. \end{itemize} \busdef{PING} @@ -1596,22 +2014,23 @@ \subsubsection{Overview} }; \end{lstlisting} -\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. +Drivers or bus implementations can use \busref{PING} as a liveness check. If a +reply is missing or delayed beyond local policy, the initiator can verify +device status (for example, with \msgref{GET_DEVICE_STATUS}) and perform +recovery as needed. \busnormative{\paragraph}{PING}{Virtio Transport Options / Virtio Over Messages / Bus Messages / PING / Bus} \begin{itemize} - \item The bus-side responder MUST echo the 32-bit data field from the request - exactly in the \busref{PING} response. + \item The responding bus implementation MUST echo the 32-bit data field from + the request exactly in the \busref{PING} response. \end{itemize} \busdef{EVENT_DEVICE} -\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. +\busref{EVENT_DEVICE} signals device-level hotplug changes as a bus-originated +control-plane event. The bus instance on the driver side receives these +indications from the peer bus instance; the table below lists the defined +device bus states. \begin{lstlisting} struct virtio_bus_msg_event_device { @@ -1624,17 +2043,29 @@ \subsubsection{Overview} \hline Constant & Value & Meaning \\ \hline -DEVICE\_BUS\_STATE\_READY & 0x0001 & Device is present and ready. \\ +DEVICE\_BUS\_STATE\_ADDED & 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. \\ +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. +Upon receiving DEVICE\_BUS\_STATE\_ADDED, drivers typically probe the device +with \msgref{GET_DEVICE_INFO} before continuing initialization. Upon receiving +DEVICE\_BUS\_STATE\_REMOVED, drivers typically stop queueing new work, quiesce +the device instance, tear down local driver state, and release resources. +Duplicate or out-of-order events can occur and can be handled with additional +bus-level monitoring, such as \busref{PING}. + +\busnormative{\paragraph}{EVENT\_DEVICE}{Virtio Transport Options / Virtio Over Messages / Bus Messages / EVENT_DEVICE / Bus} +\begin{itemize} + \item A bus implementation that sends \busref{EVENT_DEVICE} MUST set + \field{device\_number} to a valid bus device number exposed to the + driver side. + \item A bus implementation that sends \busref{EVENT_DEVICE} with + DEVICE\_BUS\_STATE\_ADDED MUST do so only when the referenced device is + accessible for transport-message processing. + \item A bus implementation that sends \busref{EVENT_DEVICE} with + DEVICE\_BUS\_STATE\_REMOVED MUST do so when the referenced device is no + longer available for transport-message processing. +\end{itemize}