diff --git a/.prjinfo/sendmail/cover.txt b/.prjinfo/sendmail/cover.txt index b6c4755..0fc684a 100644 --- a/.prjinfo/sendmail/cover.txt +++ b/.prjinfo/sendmail/cover.txt @@ -61,41 +61,81 @@ 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 +Changes since v1 (virtio-msg-patch1): + +First, thank you for the detailed comments and broad interest on v1. +We tried to address most review feedback in this revision. + +Spec Functional / Behavioral: +* Finalized the common header and addressing model: + * Keep a 16-byte common header + * Use 64-bit device numbers + * Use 16-bit msg_size plus 16-bit reserved + Rationale: support larger device-number spaces while keeping the transport + control-plane focused and limiting payload-transfer misuse. +* Clarified device-number lifecycle guidance so bus implementations should avoid + immediate reuse of removed device numbers. + Rationale: reduce races with delayed messages when devices are removed and + added again. +* Added explicit configuration semantics profiles (baseline vs strict) and + gated generation-mismatch refusal to strict-profile negotiation. + Rationale: preserve compatibility in baseline mode while allowing stricter + behavior when both sides opt in. +* Clarified SET_CONFIG rejection behavior: rejected responses return + length = 0 with no payload. + Rationale: remove ambiguity for parser/validation behavior. +* Clarified ordering baseline: request/response ordering is per-device in-order, + while events remain asynchronous and may arrive at any time relative to + request/response traffic. + Rationale: keep baseline semantics clear without over-constraining event + delivery. +* Clarified virtqueue state transitions and reconfiguration rules around + enabled/disabled/reset states. + Rationale: align with transport expectations and avoid ambiguous queue-state + behavior. +* Clarified GET_DEVICE_INFO semantics using number of 32-bit feature blocks and + aligned related field descriptions. + Rationale: improve consistency and implementation clarity. +* Clarified GET_DEVICES semantics using direct slot/byte units; responders must + not return count values larger than requested; smaller (including zero) count + is valid when appropriate. + Rationale: make enumeration behavior precise while allowing efficient sparse + windows. +* Added an informative known bus implementation examples section, including the + FF-A bus specification reference and current implementation examples. + Rationale: provide concrete context without constraining architecture choices. +* Tightened conformance text to match the clarified normative behavior. + +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] +* Arm has published a second draft of the virtio message bus over FF-A + specification (1.0 ALP1), aligned with the virtio-msg v1 proposal [6] * virtio-msg over FFA 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 +157,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..7fb57ee 100644 --- a/conformance.tex +++ b/conformance.tex @@ -155,7 +155,7 @@ \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 / 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} @@ -285,7 +285,7 @@ \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 / Configuration Semantics Profiles / Device} \item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Feature Blocks / Device} \item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Error Signaling / Device} \item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Endianness / Device} @@ -360,6 +360,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \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} diff --git a/transport-msg.tex b/transport-msg.tex index d4e31d7..fec70f9 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -124,12 +124,33 @@ \subsubsection{Relationship Between Bus and Transport} \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 message to + a device number, it MAY drop the message or surface a + transport-visible failure. +\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 DEN0153: + \url{https://developer.arm.com/documentation/den0153/latest}. + \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 +166,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 +179,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 negotiated by the bus. When both the driver side and +device side expose transport feature masks, the bus instance presents only the +common subset to the virtio-msg transport. + The mechanism for obtaining these parameters is implementation-defined and can vary between bus instances. Common approaches include: \begin{itemize} @@ -177,6 +202,8 @@ \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 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. @@ -200,23 +227,26 @@ \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: \begin{tabular}{ |l|l|l|l| } \hline \field{revision} & \field{maximum size} & \field{features} & remarks \\ \hline \hline -1 & 44-65536 & & Virtio Message Revision 1 \\ +1 & 60-65535 & bit 0 optional: \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} & Virtio Message Revision 1 \\ \hline \end{tabular} +The table reflects the protocol-defined maximum size; the recommended +advertised maximum remains 272 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 +and includes the 16-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 @@ -226,9 +256,9 @@ \subsubsection{Transport Revisions and Maximum Message Size} \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. + 60 bytes. \item A bus implementation SHOULD NOT advertise a maximum message size that - exceeds 264 bytes (256-byte payload plus the common header). + exceeds 272 bytes (256-byte payload plus the common header). \end{itemize} \paragraph{Versioning and Forward Compatibility} @@ -271,8 +301,10 @@ \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 64-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 @@ -289,51 +321,88 @@ \subsubsection{Device Numbers and Enumeration} \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. + 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 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. +\subsubsection{Configuration Semantics Profiles} +\label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles} -\devicenormative{\paragraph}{Configuration Generation Count}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Generation Count / Device} +virtio-msg defines two configuration semantics profiles selected by transport +feature negotiation: \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. + \item \textbf{Baseline profile}: applies when + \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is not negotiated. + \item \textbf{Strict profile}: applies when + \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is negotiated. \end{itemize} -\drivernormative{\paragraph}{Configuration Generation Count}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Generation Count / Driver} -\begin{itemize} - \item A driver MUST track the most recent generation count observed (via - \msgref{EVENT_CONFIG} or \msgref{GET_CONFIG}) and include it in every - \msgref{SET_CONFIG} request. - \item If a \msgref{SET_CONFIG} request is rejected due to a mismatched - generation count, the driver SHOULD issue \msgref{GET_CONFIG} to obtain - the latest configuration data and generation count before retrying. +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 In baseline profile, a driver MUST set \field{generation} to 0 in + \msgref{SET_CONFIG} requests and MUST ignore \field{generation} in + \msgref{GET_CONFIG}, \msgref{SET_CONFIG}, and \msgref{EVENT_CONFIG}. + \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 offset/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 strict 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 In baseline profile, a device MUST set \field{generation} to 0 in + \msgref{GET_CONFIG}, \msgref{SET_CONFIG}, and \msgref{EVENT_CONFIG}. + \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 In baseline profile, 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 In strict profile, a device MUST increment generation count before it + makes a driver-visible configuration change and MUST ensure that each + \msgref{EVENT_CONFIG} carrying configuration data uses a unique + generation count since the most recent generation count reset. + \item In strict 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 + 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. +Rationale: defining baseline and strict semantics in a single subsection keeps +the non-strict behavior explicit, reduces duplicated conditional wording across +message definitions, and aligns baseline behavior with MMIO-like +configuration-change notification flow. \subsubsection{Feature Negotiation Blocks} \label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Feature Blocks} @@ -351,6 +420,19 @@ \subsubsection{Feature Negotiation Blocks} driver-requested) feature bits in the selected blocks. \end{itemize} +Transport-defined feature bits currently include: + +\begin{tabular}{|l|l|p{7cm}|} +\hline +Bit & Name & Meaning \\ +\hline +0 & \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} & +Select strict configuration semantics profile. When this feature is not +negotiated, the baseline profile applies. See +\ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles}. \\ +\hline +\end{tabular} + \devicenormative{\paragraph}{Feature Blocks}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Feature Blocks / Device} \begin{itemize} \item When \msgref{GET_DEVICE_FEATURES} covers blocks that extend beyond the @@ -372,17 +454,29 @@ \subsubsection{Error Signaling} \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 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. \end{itemize} +\drivernormative{\paragraph}{Error Handling}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Error Signaling / Driver} +\begin{itemize} + \item A driver-side transport implementation receiving a malformed or + unsupported transport message MUST discard it without producing further + protocol traffic. +\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-side transport 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 @@ -393,6 +487,11 @@ \subsubsection{Error Signaling} permits implementations to surface failures when silent recovery is not feasible. +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} @@ -415,7 +514,7 @@ \subsubsection{Common Message Format} \label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Common Message Format} All virtio-msg exchanges, whether \emph{bus messages} or \emph{transport -messages}, begin with an 8-byte header followed by an optional payload. The +messages}, begin with a 16-byte header followed by an optional payload. The fields below describe the wire format for that header. The header layout is: @@ -423,9 +522,10 @@ \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 token; /* bus-managed correlation identifier */ - le16 msg_size; /* total size: header (8) + payload */ + le16 msg_size; /* total size: header (16) + payload */ + le16 reserved; /* reserved, MUST be zero */ + le64 dev_num; /* target device number; bus messages MUST use 0 */ u8 payload[]; }; \end{lstlisting} @@ -443,13 +543,17 @@ \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}. - \item \field{dev_num}: For transport messages, the device number that should - receive the message. Bus messages operate on device number 0. \item \field{token}: Correlation identifier managed by the bus. Drivers and devices treat this field as opaque; the bus MAY overwrite it to track outstanding requests or maintain ordering. \item \field{msg_size}: Total size in bytes of the complete message (header plus payload). + \item \field{reserved}: Reserved for future use. Transmitters set this field + to zero, and receivers ignore it. + \item \field{dev_num}: For transport messages, the device number that should + 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{payload}: Operation-specific data. If a bus introduces extra padding bytes, those bytes are not part of the payload semantics. \end{itemize} @@ -461,6 +565,8 @@ \subsubsection{Common Message Format} \item A driver MUST ensure \field{msg_size} reflects the total message length (header plus payload) and MUST NOT exceed the maximum message size advertised by the bus instance. + \item A driver MUST set \field{reserved} to zero when transmitting and MUST + ignore the received \field{reserved} value. \item When sending a transport message, a driver MUST set \field{dev_num} to the intended device number. \item If a driver introduces padding bytes that become part of the transport @@ -475,6 +581,8 @@ \subsubsection{Common Message Format} messages and MUST ignore those bits on receive. \item A device MUST ensure \field{msg_size} reflects the total message length (header plus payload) and does not exceed the bus's advertised maximum. + \item A device MUST set \field{reserved} to zero when transmitting and MUST + ignore the received \field{reserved} value. \item When sending a transport message, a device MUST set \field{dev_num} to its own device number. \item A device MUST ignore padding bytes that are documented as bus-specific @@ -500,8 +608,14 @@ \subsubsection{Common Message Format} use is 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} @@ -509,16 +623,28 @@ \subsubsection{Message 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. +interpret the \field{token} field directly. Events are asynchronous +notifications and MAY be delivered at any time relative to request/response +traffic. Ordering is defined per device number; messages for different device +numbers MAY be interleaved by the bus. +Some response payloads repeat request parameters (for example, indices or +offsets) to support validation; these repeats are informational and do not +alter the correlation model described here. \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 forward requests from + the driver to the device in the same order that the driver sends them. \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 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 send exactly one response for each request it receives. \end{itemize} \subsection{Device Discovery}\label{sec:Virtio Transport Options / Virtio Over Messages / Device Discovery} @@ -568,8 +694,9 @@ \subsubsection{Initialization Flow Overview} updating the device status. \item \textbf{Initialize Configuration Space:} Read or write configuration data with - \msgref{GET_CONFIG}/\msgref{SET_CONFIG}, guarding updates with the - configuration generation count. + \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}. \item \textbf{Set Up Virtqueues:} Configure each virtqueue via \msgref{SET_VQUEUE} and verify the settings with \msgref{GET_VQUEUE}. @@ -602,16 +729,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. @@ -640,12 +764,12 @@ \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. + for any requested blocks that fall outside the number of feature blocks + it reports. \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}. + internal feature mask to match the acknowledged set. If the device + cannot support the requested set, it MUST clear the FEATURES\_OK bit in + the status returned by \msgref{SET_DEVICE_STATUS}. \end{itemize} \subsubsection{Device Configuration} @@ -653,28 +777,32 @@ \subsubsection{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. +configuration generation field. Writing is performed via \msgref{SET_CONFIG}, +which carries the same offset/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}. + +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. \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. + \item A driver MUST follow the active configuration semantics profile in + \ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles} + for generation-field handling in \msgref{GET_CONFIG}, + \msgref{SET_CONFIG}, and \msgref{EVENT_CONFIG}. \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}. + \item A device MUST follow the active configuration semantics profile in + \ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles} + for generation-field handling and \msgref{SET_CONFIG} mismatch behavior. \end{itemize} \subsubsection{Virtqueue Configuration} @@ -684,26 +812,41 @@ \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. +then calling \msgref{SET_VQUEUE} with the chosen size, physical addresses, and +queue-state operation in \field{flags}. \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. + size and current queue state before programming it. + \item A driver MUST set \msgref{SET_VQUEUE} \field{flags} according to the + desired queue-state operation and field-update behavior. + \item If a driver updates queue size via \msgref{SET_VQUEUE}, it MUST ensure + the requested size does not exceed the maximum reported by the device. + \item If a driver updates queue addresses via \msgref{SET_VQUEUE}, it MUST + supply valid descriptor/driver/device physical addresses for each + updated field. + \item A driver MUST reconfigure queue parameters only while the queue is + disabled. + \item If a queue is enabled and requires reconfiguration, a driver MUST issue + \msgref{RESET_VQUEUE} before reprogramming it when + VIRTIO\_F\_RING\_RESET is negotiated. + \item If a queue is enabled and VIRTIO\_F\_RING\_RESET has not been + negotiated, a driver MUST NOT attempt to reconfigure the queue via + \msgref{SET_VQUEUE}. \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). + and MUST report accurate current queue size and enabled state. + \item A device MUST persist the parameters supplied via \msgref{SET_VQUEUE} + for fields not marked ignored by \field{flags} while the queue is + disabled. + \item A device MUST update queue state according to the + \msgref{SET_VQUEUE} \field{flags} state-operation bits. + \item A device MUST NOT use \msgref{SET_VQUEUE} to perform an + enabled-to-disabled or reset transition for a queue. \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. @@ -714,8 +857,8 @@ \subsubsection{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. +\msgref{SET_DEVICE_STATUS}. Writing zero to the status field requests a device +reset, which can complete synchronously or asynchronously. \drivernormative{\paragraph}{Status Handling}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Status Information / Driver} \begin{itemize} @@ -730,8 +873,9 @@ \subsubsection{Status Information} \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. + start reset processing. The device MUST eventually invalidate existing + configuration and virtqueue settings, and MUST report status 0 only + after reset completion. \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. @@ -776,14 +920,14 @@ \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 use \msgref{EVENT_AVAIL} to notify the device of available buffers. A +bus implementation may use an out-of-band mechanism to signal these +notifications in addition to the in-band message. \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 A driver MUST use \msgref{EVENT_AVAIL} to notify the device of available + buffers. \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 @@ -792,9 +936,9 @@ \subsubsection{Driver Notifications} \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 MAY use an out-of-band notification for + \msgref{EVENT_AVAIL}, but it MUST also 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. @@ -804,29 +948,34 @@ \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 (or device-side bus) to the driver. The bus may use other +signals such as interrupts or polling to trigger delivery and then forward +the messages in-band or synthesize them. \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 (or device-side bus) MUST use \msgref{EVENT_CONFIG} to notify + the driver of configuration changes or status updates. + \item A device MUST follow the active configuration semantics profile in + \ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles} + for \msgref{EVENT_CONFIG} generation and offset/length handling. + \item A device MUST use \msgref{EVENT_USED} to notify the driver of used + buffers on a virtqueue, unless the device relies on polling or another + agreed-upon completion mechanism. \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 A driver MUST follow the active configuration semantics profile in + \ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles} + for \msgref{EVENT_CONFIG} generation and offset/length interpretation. \item Upon receiving \msgref{EVENT_USED}, a driver MUST examine the indicated virtqueue (for example, by reading the used ring) to reclaim completed buffers. @@ -834,9 +983,9 @@ \subsubsection{Device Notifications} \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 A bus implementation MUST deliver \msgref{EVENT_CONFIG} and + \msgref{EVENT_USED} to the driver by forwarding the in-band message or + by synthesizing the appropriate message based on other signals. \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. @@ -852,9 +1001,10 @@ \subsubsection{Configuration Changes During Operation} \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 A driver MAY issue \msgref{SET_CONFIG} after initialization, following + the same validation rules as during setup and the active configuration + semantics profile in + \ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles}. \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. @@ -863,31 +1013,39 @@ \subsubsection{Configuration Changes During Operation} \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. + \msgref{EVENT_CONFIG} to inform the driver of the change and MUST follow + the active configuration semantics profile in + \ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles}. \end{itemize} \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. +\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. \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. + \item A driver MAY configure additional virtqueues and update selected + virtqueue fields after initialization using \msgref{SET_VQUEUE}, + provided it follows the same validation steps and updates only disabled + queues. + \item If an enabled queue requires reconfiguration and + VIRTIO\_F\_RING\_RESET is negotiated, a driver MUST issue + \msgref{RESET_VQUEUE} before issuing \msgref{SET_VQUEUE} updates for + that queue. \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. + initialization and update queue parameters according to \field{flags} + only while the queue is disabled. + \item For a queue that is enabled, a device MUST accept only + \msgref{SET_VQUEUE} requests that do not modify queue parameters and do + not request a disable/reset transition. \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. @@ -896,43 +1054,45 @@ \subsubsection{Virtqueue Changes During Operation} \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. +Drivers request a device reset by writing 0 to the status field via +\msgref{SET_DEVICE_STATUS}. Reset completion can be synchronous or +asynchronous. A driver confirms completion from a +\msgref{SET_DEVICE_STATUS} response status of 0 or by polling +\msgref{GET_DEVICE_STATUS} until status is 0. A device may also signal that a +reset is required by setting DEVICE\_NEEDS\_RESET in its status and reporting +the updated status to the driver. \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. + \msgref{SET_DEVICE_STATUS}. If the driver intends to resume operation, + it MAY reinitialize the device after reset completion. + \item If DEVICE\_NEEDS\_RESET is reported in device status, 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. + start reset processing and eventually reset its internal state and + discard pending virtqueue operations. \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. + intervention, it SHOULD set DEVICE\_NEEDS\_RESET in its status and + ensure the updated status is reported to the driver. \end{itemize} \subsubsection{Hotplug and Removal} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / Hotplug and Removal} If the bus supports dynamic addition or removal of devices, it can advertise -those changes with \busref{EVENT_DEVICE} (READY or REMOVED). Some platforms may +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 @@ -1032,14 +1192,28 @@ \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 and MAY also be +signaled via equivalent out-of-band mechanisms. + +\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 in-band delivery, out-of-band signaling, or both. + \item If a bus implementation specifies out-of-band signaling, it MUST + document the mechanism and any required configuration to use it. + \item If a bus implementation uses out-of-band signaling, it MUST also relay + or synthesize the corresponding transport message on the virtio-msg + channel. +\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 (all bytes set to zero) indicates that no +UUID is provided. \msgref{GET_DEVICE_INFO} is the only transport message +permitted before the device transitions out of the inactive state. \begin{lstlisting} struct virtio_msg_get_device_info_req { @@ -1049,26 +1223,33 @@ \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 MAY set \field{device_uuid} to a UUID value that can be used + as a unique identifier. + \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 a nil UUID in \field{device_uuid} as indicating + that no UUID is provided. \end{itemize} \msgdef{GET_DEVICE_FEATURES} @@ -1132,15 +1313,15 @@ \subsubsection{Overview} \item After processing \msgref{SET_DRIVER_FEATURES}, a device MUST update its acknowledged feature set to match the data supplied and MUST report that set consistently in subsequent \msgref{GET_DEVICE_FEATURES} responses. - If it cannot support the requested set, it SHOULD clear the FEATURES\_OK - bit in the device status. \end{itemize} \msgdef{GET_CONFIG} \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. +the data, and includes generation. 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 +1330,7 @@ \subsubsection{Overview} }; struct virtio_msg_get_config_resp { - le32 generation; /* current configuration generation count */ + le32 generation; /* generation count, or 0 if not negotiated */ le32 offset; /* echoed offset */ le32 length; /* echoed length */ u8 data[]; /* configuration payload */ @@ -1164,8 +1345,9 @@ \subsubsection{Overview} \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 follow the active configuration semantics profile in + \ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles} + for \field{generation} in every \msgref{GET_CONFIG} response. \end{itemize} \msgdef{SET_CONFIG} @@ -1174,36 +1356,48 @@ \subsubsection{Overview} 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. +rejected. A rejected response uses \field{length}=0 and 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, or 0 if not negotiated */ le32 offset; /* byte offset being written */ le32 length; /* number of bytes written */ u8 data[]; /* configuration payload */ }; struct virtio_msg_set_config_resp { - le32 generation; /* resulting generation count */ + le32 generation; /* resulting count, or 0 if not negotiated */ le32 offset; /* echoed offset */ le32 length; /* bytes applied (0 if rejected) */ - u8 data[]; /* optional echoed data */ + u8 data[]; /* echoed data, omitted when 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 offset and length within the reported + configuration size in each \msgref{SET_CONFIG} request. + \item A driver MUST follow the active configuration semantics profile in + \ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles} + for \field{generation} handling in \msgref{SET_CONFIG}. \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 follow the active configuration semantics profile in + \ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles} + for \field{generation} handling and mismatch behavior in + \msgref{SET_CONFIG}. + \item A device MUST apply \msgref{SET_CONFIG} generation-mismatch rejection + only when strict profile is active. + \item If a device rejects a \msgref{SET_CONFIG} request, it MUST set + response \field{length} to 0 and MUST NOT include response + \field{data} bytes. \end{itemize} \msgdef{GET_DEVICE_STATUS} @@ -1233,8 +1427,11 @@ \subsubsection{Overview} \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 status value observed when the response is generated. +For a reset request (\field{status} == 0), a response status of 0 indicates +reset completion; a non-zero response status indicates that reset completion may +still be pending. The resulting status may differ from the requested status (for +example, if the device refuses FEATURES\_OK or sets DEVICE\_NEEDS\_RESET). \begin{lstlisting} struct virtio_msg_set_device_status_req { @@ -1249,8 +1446,11 @@ \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 status of 0 as completion; + otherwise it MUST poll \msgref{GET_DEVICE_STATUS} until the device + reports 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} @@ -1258,13 +1458,20 @@ \subsubsection{Overview} \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. + \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 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 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. \begin{lstlisting} struct virtio_msg_get_vqueue_req { @@ -1275,10 +1482,10 @@ \subsubsection{Overview} 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 flags; /* bit0: enabled state, bits[31:1] reserved */ + le64 desc_addr; /* descriptor area physical address */ + le64 driver_addr; /* driver area physical address */ + le64 device_addr; /* device area physical address */ }; \end{lstlisting} @@ -1287,24 +1494,26 @@ \subsubsection{Overview} \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 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,18 +1521,70 @@ \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 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 A device MUST reject \msgref{SET_VQUEUE} 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. + \item A device MUST reject \msgref{SET_VQUEUE} if \field{flags} requests state + operation value 0 for a queue that is currently enabled. + \item A device MUST process \msgref{SET_VQUEUE} updates atomically: it MUST + either apply all requested field updates and queue-state changes, or + reject the request without applying any of them. + \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 A device MUST reject \msgref{SET_VQUEUE} field updates to + \field{size}, \field{desc_addr}, \field{driver_addr}, or + \field{device_addr} when the queue is enabled. + \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} @@ -1344,24 +1605,31 @@ \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 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 If VIRTIO\_F\_RING\_RESET has not been negotiated, a device MUST reject + \msgref{RESET_VQUEUE} without changing queue state. \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. +provides the base physical address and length. A length of zero indicates that +the specified region does not exist. \begin{lstlisting} struct virtio_msg_get_shm_req { @@ -1369,33 +1637,39 @@ \subsubsection{Overview} }; struct virtio_msg_get_shm_resp { - le32 index; /* echoed index */ - le32 length; /* region length (0 if nonexistent) */ - le32 address;/* region address */ + le32 index; /* echoed index */ + 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. + does not exist and MUST report accurate physical address/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}. +The payload includes current device status, generation, and +configuration offset/length. The configuration data can be omitted; if omitted, +the driver re-fetches via \msgref{GET_CONFIG}. Generation and offset/length +semantics follow the active profile defined in +\ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles}. +If the event reports only a status change with no configuration update, the +device sets offset and length to zero. \begin{lstlisting} struct virtio_msg_event_config { le32 device_status; /* new device status value */ - le32 generation; /* configuration generation count */ + le32 generation; /* generation count, or 0 if not negotiated */ 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} @@ -1403,15 +1677,27 @@ \subsubsection{Overview} \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. + SHOULD apply it; otherwise it SHOULD re-read the affected range + indicated by offset/length via \msgref{GET_CONFIG} before proceeding. + If offset/length are both zero and no data is provided, the driver + SHOULD re-read required configuration via \msgref{GET_CONFIG}. + \item A driver MUST follow the active configuration semantics profile in + \ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles} + for generation and offset/length interpretation in + \msgref{EVENT_CONFIG}. \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. + configuration data or status in a way that is visible to the driver. + \item A device MUST follow the active configuration semantics profile in + \ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles} + for generation and offset/length handling in \msgref{EVENT_CONFIG}. + \item In baseline profile, a device MUST NOT send \msgref{EVENT_CONFIG} + solely to report a \msgref{SET_CONFIG} generation mismatch. + \item If \msgref{EVENT_CONFIG} reports only a status change, a device MUST set + the offset and length fields to zero. \end{itemize} \msgdef{EVENT_AVAIL} @@ -1457,9 +1743,9 @@ \subsubsection{Overview} \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. + \item A device MUST send \msgref{EVENT_USED} (or an equivalent notification) + when it processes buffers on a virtqueue unless the device relies on + polling or another agreed-upon completion mechanism. \end{itemize} \drivernormative{\paragraph}{EVENT\_USED}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_USED / Driver} @@ -1517,7 +1803,7 @@ \subsubsection{Overview} \end{tabular} \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 @@ -1538,24 +1824,28 @@ \subsubsection{Overview} \begin{lstlisting} struct virtio_bus_msg_get_devices_req { - le16 offset; /* starting device number */ - le16 count; /* number of device-number slots (multiple of 8) */ + le64 offset; /* starting device number */ + 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 */ + le64 offset; /* echoed starting device number */ + le64 next_offset; /* 0 or suggested start for next query */ + 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. +devices equals the number of set bits in the first \textbf{count} bitmap +positions. The bitmap size in bytes is \textbf{(count + 7) / 8}. +The response \textbf{count} MUST NOT exceed the request \textbf{count}. +Responders SHOULD return the requested \textbf{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 bitmap covers the reduced window. If no devices are present in +the requested window, returning \textbf{count}=0 and an empty bitmap is valid. Example: a request with \textbf{offset}=0, \textbf{count}=16 might produce \textbf{bitmap}=0b00100101 00000000 and \textbf{next_offset}=16. That indicates @@ -1569,16 +1859,24 @@ \subsubsection{Overview} \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 The bus-side responder MUST interpret \textbf{count} as a number of + device-number slots and MUST return a bitmap of length + \textbf{(count + 7) / 8} bytes, packed least-significant-bit first. + \item The bus-side responder MUST NOT return a \textbf{count} value greater + than the \textbf{count} value from the request. + \item If \textbf{count} is not a multiple of 8, the responder MUST set unused + bits in the last bitmap byte (positions at or above \textbf{count}) to + zero. \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. + 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}. + (e.g., by maximum message size) or when trailing parts of the requested + window contain no present device numbers; if a smaller count is + returned, the bitmap MUST still represent the window defined by the + echoed \textbf{offset} and \textbf{count}. + \item If no devices are present in the requested window, a responder MAY + return \textbf{count}=0 with a zero-length bitmap. \end{itemize} \busdef{PING} @@ -1615,7 +1913,7 @@ \subsubsection{Overview} \begin{lstlisting} struct virtio_bus_msg_event_device { - le16 device_number; + le64 device_number; le16 device_bus_state; /* see table below */ }; \end{lstlisting} @@ -1624,7 +1922,7 @@ \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. \\ @@ -1632,9 +1930,9 @@ \subsubsection{Overview} \end{tabular} \paragraph{Intended usage} -Upon receiving DEVICE\_BUS\_STATE\_READY, drivers SHOULD probe the device via +Upon receiving DEVICE\_BUS\_STATE\_ADDED, 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. +DEVICE\_BUS\_STATE\_REMOVED, drivers MUST stop queueing new work, quiesce the +device instance, tear down driver-side state, 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.