From 824618e99e1c4801643f5b396244133a64f559e6 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Tue, 18 Nov 2025 13:12:26 +0100 Subject: [PATCH 01/53] virtio-msg: rework GET_DEVICES Rework GET_DEVICES message description to prevent confusion between Number of devices and device number by using device-number for the device number identifier and renaming fields of the message. Also provide an example to illustrate the usage of the message. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 39 ++++++++++++++++++++++++++------------- 1 file changed, 26 insertions(+), 13 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index eaab0eb..c6c6a2e 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -1177,28 +1177,41 @@ \subsection{Bus Messages}\label{sec:Virtio Transport Options / Virtio Over Messa \busdef{GET_DEVICES} -This message is sent by the virtio-msg driver side bus and requires a response -from the device side bus. +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. \begin{tabular}{|l|l|l|l|} \hline Type & Offset & Size (bytes) & Content \\ \hline \hline -Request & 0 & 2 & Offset \\ - & 2 & 2 & Number of device numbers requested \\ +Request & 0 & 2 & offset: first device number in the window \\ + & 2 & 2 & count: number of consecutive device numbers covered \\ \hline -Answer & 0 & 2 & Offset \\ - & 2 & 2 & Number of device numbers in the answer \\ - & 4 & 2 & Next offset or 0 if no devices after Offset \\ - & 6 & .. & Bit[n]: Device[offset + n] not available(0)/available(1) \\ +Answer & 0 & 2 & offset (echoed) \\ + & 2 & 2 & count actually returned \\ + & 4 & 2 & next\_offset: 0 or the start of the recommended next window \\ + & 6 & count/8 & bitmap: bit $n$ ($0 \le n <$ count) describes device number $(offset + n)$ (0=absent, 1=present) \\ \hline \end{tabular} -The offset and number of device numbers requested \emph{MUST} be multiples of 8. -The next offset \emph{MUST} also be a multiple of 8. -The device available data is packed into a sequence of bytes with the first -device in the least significant bit of the first byte, the eighth device in -the most significant bit of the first byte, etc. +\textbf{offset} and \textbf{count} MUST be multiples of 8; the bitmap length is +\textbf{count/8} and is packed LSB-first (device number \textbf{offset} is the +LSB of the first byte). +\textbf{next_offset} is either 0 (no further windows) or an aligned value +$\ge offset + count$ that the responder suggests querying next. + +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 +at device number 16. \busdef{EVENT_DEVICE} From e47da75b9000267e272fc8765bedc58887b4afde Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Tue, 18 Nov 2025 13:32:35 +0100 Subject: [PATCH 02/53] virtio-msg: remove emph or textbf for MUST/MAY/SHOULD To comply with the rest of the OASIS Virtio specification removing all emph or textbf around MUST/MAY/SHOULD. Do some minor rewording to prevent using normative wording when not required. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 270 +++++++++++++++++++++++----------------------- 1 file changed, 135 insertions(+), 135 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index c6c6a2e..390422f 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -20,7 +20,7 @@ \subsubsection{Purpose} \begin{itemize} \item \textbf{Support multiple bus implementations:} - Systems may rely on various communication methods such as hypercalls, local + Systems can rely on various communication methods such as hypercalls, local IPC, network channels, or device trees for enumerating devices. virtio-msg defines a common transport interface suitable for any of these mechanisms. @@ -43,14 +43,14 @@ \subsubsection{High-Level Architecture} \begin{enumerate} \item \textbf{Bus Layer}: A \emph{bus instance} exposes zero or more virtio - devices. It can detect available devices through: + devices. It discovers available devices through mechanisms such as: \begin{itemize} \item Optional message-based queries (\busref{GET_DEVICES}), \item External data sources (e.g., device tree, ACPI tables, hypervisor firmware calls), \item Dynamic hotplug notifications (optionally via \busref{EVENT_DEVICE}). \end{itemize} - Once a device is identified, regardless of discovery method, the bus typically + Once a device is identified, regardless of discovery method, the bus uses \msgref{GET_DEVICE_INFO} to read its device ID and vendor ID, then \emph{registers} that device with the host OS so the usual virtio driver probe can occur. @@ -74,9 +74,9 @@ \subsubsection{High-Level Architecture} \subsubsection{System Topology} \begin{itemize} - \item \textbf{Bus Instances and Devices}: Each bus instance can advertise - different capabilities (e.g., transport revision, maximum message size) - and may discover devices via a message-based or external mechanism. + \item \textbf{Bus Instances and Devices}: Each bus instance advertises its + capabilities (e.g., transport revision, maximum message size) and + discovers devices via message-based queries or external data sources. Every discovered device has a unique \emph{device number}. \item \textbf{Driver}: Communicates with the bus to learn about available devices. Once a device is recognized, the driver uses the @@ -94,7 +94,7 @@ \subsubsection{Optional Bus Messages} completely message-based approach to enumeration, hotplug, and bus-wide health. However, these are \emph{not} mandatory if a bus instance already handles those functions via firmware, device tree, or other platform features. The only strict -requirement is that the bus \emph{MUST} be able to forward device-specific +requirement is that the bus MUST be able to forward device-specific \emph{transport messages} once a device is recognized, so the virtio-msg driver can manage it. @@ -122,7 +122,7 @@ \subsubsection{Transport Revisions and Maximum Message Size} optional features that are supported or not by the bus instance. \end{itemize} -These parameters \emph{MAY} vary between bus instances within the same system. +These parameters MAY vary between bus instances within the same system. The bus implementation obtains a bus's revision, maximum message size and list of features through an \emph{implementation-defined} mechanism, which could be: \begin{itemize} @@ -132,9 +132,9 @@ \subsubsection{Transport Revisions and Maximum Message Size} \item A static definition built into the driver for a known environment. \end{itemize} -After learning these parameters, the transport layer \emph{MUST} respect them -for all messages involving that bus instance. For example, it \emph{MUST NOT} -send a message exceeding the \textbf{maximum message size}, and it \emph{MUST} +After learning these parameters, the transport layer MUST respect them +for all messages involving that bus instance. For example, it MUST NOT +send a message exceeding the \textbf{maximum message size}, and it MUST avoid using advanced features or messages unavailable in the bus's advertised \textbf{transport revision}. @@ -165,7 +165,7 @@ \subsubsection{Device Numbers and Enumeration} Device Numbers} Each virtio-msg bus instance contains one or more \emph{devices}, identified -by a 16-bit \textbf{device number}. Buses \emph{MAY} discover these device +by a 16-bit \textbf{device number}. Buses MAY discover these device numbers in multiple ways: \begin{itemize} \item \textbf{Message-Based Enumeration}: Using \busref{GET_DEVICES} to query @@ -187,23 +187,23 @@ \subsubsection{Configuration Generation Count} every driver visible change it makes to its own copy of the configuration data. A configuration change is made visible to the driver via \msgref{EVENT_CONFIG} or the response to \msgref{GET_CONFIG} which also both provide the device's -current configuration count. The device may change any amount of data for one +current configuration count. The device MAY change any amount of data for one generation count increment. If the change cannot fit in one \msgref{EVENT_CONFIG} -message, the device \emph{SHOULD} send an \msgref{EVENT_CONFIG} message +message, the device SHOULD send an \msgref{EVENT_CONFIG} message with a zero data length and the new generation count to the driver. -The device \emph{MUST NOT} provide the same generation count in +The device MUST NOT provide the same generation count in multiple \msgref{EVENT_CONFIG} messages that contain non-zero length config data. The driver includes its view of the current generation count in \msgref{SET_CONFIG} requests. The configuration generation count does not -necessarily start at 0 and \emph{SHOULD NOT} reset to 0 on device reset. +necessarily start at 0 and SHOULD NOT reset to 0 on device reset. \begin{itemize} \item If the driver's generation count does not match the device's current - count, the \msgref{SET_CONFIG} request \emph{MUST} be rejected by the + count, the \msgref{SET_CONFIG} request MUST be rejected by the device. - \item The driver may have received \msgref{EVENT_CONFIG} messages + \item The driver MAY have received \msgref{EVENT_CONFIG} messages between the request and the response and will know the current - configuration data and generation count. If not it \emph{SHOULD} + configuration data and generation count. If not it SHOULD re-read the configuration and generation count via \msgref{GET_CONFIG}), and then resend the \msgref{SET_CONFIG} if still desired. \end{itemize} @@ -227,30 +227,30 @@ \subsubsection{Feature Negotiation Blocks} supported or requested feature bits. \end{itemize} -A device \emph{MUST} respond with all zero feature data for features bit +A device MUST respond with all zero feature data for features bit requested beyond those the device implements. \subsubsection{Error Signaling} \label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / ErrorSignaling} -Errors may arise from: (a) malformed or unsupported transport messages, (b) +Errors MAY arise from: (a) malformed or unsupported transport messages, (b) transmission or routing issues within a bus implementation, or (c) device-side failures while processing a valid request. Local detection and recovery are -preferred, but a virtio-msg bus \textbf{MAY} report transmission errors to the +preferred, but a virtio-msg bus MAY report transmission errors to the virtio-msg transport when it cannot deliver a request or obtain a response within a bounded policy. The following rules apply: \begin{itemize} - \item A bus implementation \textbf{MAY} surface a transport-visible failure + \item A bus implementation MAY surface a transport-visible failure (implementation-defined) after exhausting any bounded retry policy for a transmission error. - \item Malformed headers or unsupported \field{msg_id} values \textbf{SHOULD} - be discarded; the receiver \textbf{MAY} log them and \textbf{SHOULD NOT} + \item Malformed headers or unsupported \field{msg_id} values SHOULD + be discarded; the receiver MAY log them and SHOULD NOT generate further protocol traffic in response. - \item Event (one-way) messages \textbf{MUST NOT} elicit an error response. + \item Event (one-way) messages MUST NOT elicit an error response. \item Recovery actions (retry, selective reset, device removal) are - environment-specific but \textbf{MUST} comply with any normative reset + environment-specific but MUST comply with any normative reset or status handling semantics described in \ref{sec:Virtio Transport Options / Virtio Over Messages / Device Operation}. \end{itemize} @@ -272,7 +272,7 @@ \subsubsection{Bus vs. Transport Messages} These messages are \emph{optional} in environments where device discovery or state changes occur through other means (e.g., device tree). However, if a bus chooses to handle those tasks via messages, - it \emph{should} implement the appropriate bus message definitions. + it SHOULD implement the appropriate bus message definitions. \item[\textbf{Transport Messages}:] Used for device-specific operations, such as: @@ -285,7 +285,7 @@ \subsubsection{Bus vs. Transport Messages} \item Handling device status and notifications (\msgref{SET_DEVICE_STATUS}, \msgref{EVENT_USED}, etc.). \end{itemize} - The bus \emph{MUST} relay these messages to the correct device, + The bus MUST relay these messages to the correct device, regardless of how the bus discovered or enumerated that device. \end{description} @@ -296,7 +296,7 @@ \subsubsection{Bus vs. Transport Messages} \subsubsection{Endianness} \label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Endianness} -All values and fields defined in the virtio-msg messages \emph{MUST} +All values and fields defined in the virtio-msg messages MUST be encoded in little-endian. \subsubsection{Common Message Format} @@ -324,7 +324,7 @@ \subsubsection{Common Message Format} \begin{itemize} \item Bit[0]: 0=request, 1=response. \item Bit[1]: 0=Transport Message, 1=Bus Message. - \item Bits[2..7]: \textbf{MUST} be zero; receivers \textbf{MUST} ignore. + \item Bits[2..7]: MUST be zero; receivers MUST ignore. \end{itemize} \item \field{msg_id}: Message ID identifying the message definition. Ranges are defined in @@ -332,20 +332,20 @@ \subsubsection{Common Message Format} and \ref{sec:Virtio Transport Options / Virtio Over Messages / Bus Messages}. \item \field{dev_num}: For Transport Messages, the target device number; for - Bus Messages \textbf{MUST} be zero. + Bus Messages MUST be zero. \item \field{token}: Non-zero for requests (which expect a response); zero - \textbf{MUST} be used only for event (one-way) messages. Responses - \textbf{MUST} echo the request's \field{token}. + MUST be used only for event (one-way) messages. Responses + MUST echo the request's \field{token}. \item \field{msg_size}: Total size in bytes of the complete message (header + - payload). \textbf{MUST} be \(\ge 8\) and \textbf{MUST NOT} exceed the + payload). MUST be \(\ge 8\) and MUST NOT exceed the bus's maximum message size. \item \field{payload}: Operation-specific data. Unused trailing bytes (if any - introduced by a bus framing) \textbf{MUST} be zero and \textbf{MUST} be + introduced by a bus framing) MUST be zero and MUST be ignored by receivers. \end{itemize} -All reserved header bits and any unspecified header values \textbf{MUST} be -sent as zero and \textbf{MUST} be ignored on receive to preserve forward +All reserved header bits and any unspecified header values MUST be +sent as zero and MUST be ignored on receive to preserve forward compatibility. \subsubsection{Message Correlation} @@ -353,7 +353,7 @@ \subsubsection{Message Correlation} Messages are either requests or events. Requests require a response. Events are one way and do not have a response. Most requests defined today originate at the -driver side but bus message requests such as \busref{PING} may originate at +driver side but bus message requests such as \busref{PING} MAY originate at either driver side or device side. This section defines how responses are correlated to requests. An implementation @@ -370,10 +370,10 @@ \subsubsection{Message Correlation} \begin{itemize} \item The request originator assigns a non-zero \field{token} for every request such that the tuple is unique for all inflight requests. - \item Event (one-way) messages \textbf{MUST} set \field{token}=0 - \item A response \textbf{MUST} echo \field{token} and \field{dev_num}. + \item Event (one-way) messages MUST set \field{token}=0 + \item A response MUST echo \field{token} and \field{dev_num}. \item Reception of unknown or already completed correlation tuples - \textbf{SHOULD} result in discarding the response without further protocol + SHOULD result in discarding the response without further protocol action. \end{itemize} @@ -383,14 +383,14 @@ \subsection{Bus Operation} A \textbf{virtio-msg bus} is responsible for identifying available virtio devices and informing the operating system (or higher-level software environment) so that those devices can be bound to the appropriate driver. The following -subsections describe optional messaging mechanisms that a bus \emph{MAY} use to +subsections describe optional messaging mechanisms that a bus MAY use to discover or manage devices, as well as general guidelines for completing the device registration process. \subsubsection{Device Discovery} \label{sec:Virtio Transport Options / Virtio Over Messages / Bus Operation / Device Discovery} -Bus implementations \emph{MAY} discover their devices in various ways: +Bus implementations MAY discover their devices in various ways: \begin{itemize} \item By parsing platform data such as a device tree or ACPI tables, \item By receiving enumeration data from a hypervisor or firmware, @@ -400,10 +400,10 @@ \subsubsection{Device Discovery} This specification \emph{defines} \busref{GET_DEVICES} for implementations that wish to carry out discovery entirely via messages, but it does \textbf{not} -mandate use of this approach. A bus implementation \emph{MAY} skip +mandate use of this approach. A bus implementation MAY skip \busref{GET_DEVICES} altogether if it already knows which devices exist (e.g., via a device tree). In any case, once a bus has established the presence of a -device, it \emph{SHOULD} call \msgref{GET_DEVICE_INFO} to retrieve the device ID +device, it SHOULD call \msgref{GET_DEVICE_INFO} to retrieve the device ID and vendor ID. The bus can then register the device with the host OS so the appropriate virtio driver probe routine is invoked. @@ -411,7 +411,7 @@ \subsubsection{Device Hotplug} \label{sec:Virtio Transport Options / Virtio Over Messages / Bus Operation / Device Hotplug} If the bus supports dynamic addition or removal of devices at runtime, it -\emph{MAY} announce these events using messages: +MAY announce these events using messages: \begin{itemize} \item \busref{EVENT_DEVICE} with state DEVICE_BUS_STATE_READY for a newly available device, @@ -419,27 +419,27 @@ \subsubsection{Device Hotplug} that is no longer accessible. \end{itemize} -Alternatively, the bus \emph{MAY} rely on external signals (e.g., an event from +Alternatively, the bus MAY rely on external signals (e.g., an event from the platform or hypervisor) and inform the OS of hotplug changes out-of-band. This specification \emph{defines} \busref{EVENT_DEVICE} for implementations that prefer a fully message-based approach but does not require their use. In any scenario, once notified that a -device has appeared, the bus \emph{SHOULD} query the device (e.g., via +device has appeared, the bus SHOULD query the device (e.g., via \msgref{GET_DEVICE_INFO}) and register it with the OS. If a device is -removed, the bus \emph{SHOULD} prompt the OS to unbind and release resources. +removed, the bus SHOULD prompt the OS to unbind and release resources. \subsubsection{Monitoring the Bus} \label{sec:Virtio Transport Options / Virtio Over Messages / Bus Operation / Monitoring} An optional \busref{PING} message is provided for bus implementations that want to periodically verify connectivity with the other end (driver or device). -Implementations \emph{MAY} use other keepalive or health-check +Implementations MAY use other keepalive or health-check protocols instead. The general usage of \busref{PING} (if implemented) is: \begin{itemize} \item The initiator sends a 32-bit data field, \item The recipient responds by echoing this same 32-bit data, - \item If a response does not arrive in time, the initiator \emph{MAY} treat + \item If a response does not arrive in time, the initiator MAY treat the bus as unresponsive and trigger a global reset or other fallback procedure. \end{itemize} @@ -465,7 +465,7 @@ \subsubsection{Interaction with Transport Messages} messages} to the correct device for each device number. Typically the bus does not interpret or modify these transport messages; its role is simply to ensure they reach the intended device. If the bus does not rely on messages for device -enumeration or hotplug itself, it \emph{MUST} still be capable of transporting +enumeration or hotplug itself, it MUST still be capable of transporting \msgref{GET_DEVICE_INFO}, \msgref{GET_DEVICE_FEATURES}, \msgref{SET_CONFIG}, etc. once the OS driver has identified a device and is performing initialization via the virtio-msg transport. @@ -494,7 +494,7 @@ \subsubsection{Initialization Flow Overview} FEATURES_OK bit in the device status (\msgref{SET_DEVICE_STATUS}) and verifies that it is set in the return device status. \item \textbf{Initialize Configuration Space:} - The driver may read (\msgref{GET_CONFIG}) or modify (\msgref{SET_CONFIG}) + The driver MAY read (\msgref{GET_CONFIG}) or modify (\msgref{SET_CONFIG}) configuration data, using the device's \emph{Configuration Generation Count} to prevent race conditions. \item \textbf{Set Up Virtqueues:} @@ -507,13 +507,13 @@ \subsubsection{Initialization Flow Overview} "driver," or "driver OK," following Virtio conventions). \end{enumerate} -This sequence may vary slightly depending on the device's requirements, but it +This sequence MAY vary slightly depending on the device's requirements, but it serves as a common baseline for virtio-msg transport implementations. \subsubsection{Device Information} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Information} -Once the bus or driver knows a device number is present, it \emph{SHOULD} send a +Once the bus or driver knows a device number is present, it SHOULD send a \msgref{GET_DEVICE_INFO} to retrieve: \begin{itemize} @@ -553,12 +553,12 @@ \subsubsection{Feature Negotiation} feature requires the driver to set the corresponding bit(s) and send them back to the device with \msgref{SET_DRIVER_FEATURES}. Once the driver has set all desired features it tries to set the FEATURES_OK bit in the device status -via the \msgref{SET_DEVICE_STATUS} message. The device may accept or reject the +via the \msgref{SET_DEVICE_STATUS} message. The device MAY accept or reject the selected features by returning the new device status with the FEATURES_OK bit set (accepted) or cleared (rejected). If the driver requests blocks beyond the number of feature bits the device -exposes, the device \emph{MUST} respond with all zeros for the unsupported +exposes, the device MUST respond with all zeros for the unsupported features. \subsubsection{Device Configuration} @@ -588,8 +588,8 @@ \subsubsection{Device Configuration} \end{itemize} If the generation count does not match the device's current value, the device -\emph{MUST} reject the update as defined in the \msgref{SET_CONFIG} response. -The driver \emph{SHOULD} then read the updated configuration space and +MUST reject the update as defined in the \msgref{SET_CONFIG} response. +The driver SHOULD then read the updated configuration space and reattempt if necessary. \subsubsection{Virtqueue Configuration} @@ -622,7 +622,7 @@ \subsubsection{Virtqueue Configuration} \subsubsection{Status Information} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Initialization / Status Information} -During initialization, the driver \emph{MAY} query the device's status via +During initialization, the driver MAY query the device's status via \msgref{GET_DEVICE_STATUS} to check for errors or to see if the device is ready for feature negotiation or configuration changes. To advance or reset the device's state, the driver sends \msgref{SET_DEVICE_STATUS} with the desired @@ -650,25 +650,25 @@ \subsection{Device Operation} \subsubsection{Driver Notifications} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / Driver Notifications} -After setting up one or more virtqueues, the driver \emph{MUST} send notifications +After setting up one or more virtqueues, the driver MUST send notifications to signal that new buffers are available for processing. The virtio-msg transport defines the message, \msgref{EVENT_AVAIL}, that the driver will use to notify the device of pending buffers. -The driver side bus \emph{MAY} convert them to some form of +The driver side bus MAY convert them to some form of out-of-band (OoB) notification. If not using OoB notifications, the driver -side bus \emph{SHOULD} send the messages via the normal message channel. -As a final option, the bus \emph{MAY} discard the messages but only if it knows +side bus SHOULD send the messages via the normal message channel. +As a final option, the bus MAY discard the messages but only if it knows that the device will poll the virtqueues directly. \paragraph{EVENT\_AVAIL Usage} \begin{itemize} \item \textbf{Virtqueue Index}: Identifies which queue has new buffers. \item \textbf{Next Offset and Wrap}: If the VIRTIO_F_NOTIFICATION_DATA feature - has been negotiated, the driver \emph{MUST} sets these fields to + has been negotiated, the driver MUST sets these fields to indicate the next descriptor offset and wrap state so the device can jump directly to the updated buffers. - If this features has not been negotiated these fields \emph{MUST} be 0. + If this features has not been negotiated these fields MUST be 0. \item \textbf{Response}: The \msgref{EVENT_AVAIL} message does not have a direct response, but the device will subsequently process available buffers and eventually notify the driver when they are used. @@ -677,10 +677,10 @@ \subsubsection{Driver Notifications} \subsubsection{Device Notifications} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / Device Notifications} -During normal operation, the driver side bus \emph{MUST} send notifications to +During normal operation, the driver side bus MUST send notifications to the driver about configuration changes, device status changes, or the completion of buffers in virtqueues using the messages described below. -These notifications may be the result of: +These notifications MAY be the result of: \begin{itemize} \item The same messages received in-band on the message channel from the @@ -689,7 +689,7 @@ \subsubsection{Device Notifications} out-of-band (OoB) notification from the device side. Example OoB notifications include things like specific MSIX or other IRQ signals. \item Manufactured by the device side bus periodically (polling). - This option should be reserved only for situation where nothing else + This option SHOULD be reserved only for situation where nothing else will work. \end{itemize} @@ -699,7 +699,7 @@ \subsubsection{Device Notifications} at runtime. \item Includes the new \emph{Configuration Generation Count}, current device status, and optionally the updated portion of the configuration data. - \item If the data is not included, the driver \emph{SHOULD} issue + \item If the data is not included, the driver SHOULD issue \msgref{GET_CONFIG} to discover the updated configuration. \end{itemize} @@ -711,7 +711,7 @@ \subsubsection{Device Notifications} \item The driver uses normal virtio methods (e.g., reading the "used" ring) to identify which buffers are complete. \item If a device does not support sending \msgref{EVENT_USED}, the driver - \emph{MAY} rely on standard virtqueue polling mechanisms to detect + MAY rely on standard virtqueue polling mechanisms to detect completion. \end{itemize} @@ -720,42 +720,42 @@ \subsubsection{Device Notifications} \subsubsection{Configuration Changes During Operation} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / ConfigUpdates} -The driver \emph{MAY} issue new \msgref{SET_CONFIG} +The driver MAY issue new \msgref{SET_CONFIG} messages after initialization if device configuration needs to be -changed at runtime. The device \emph{MAY} also make configuration changes at -runtime and \emph{MUST} signal those changes with \msgref{EVENT_CONFIG} +changed at runtime. The device MAY also make configuration changes at +runtime and MUST signal those changes with \msgref{EVENT_CONFIG} messages. \subsubsection{Virtqueue Changes During Operation} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / VQueueUpdates} -The driver \emph{MAY} issue new \msgref{SET_VQUEUE} for virtqueues that have not +The driver MAY issue new \msgref{SET_VQUEUE} for virtqueues that have not yet be setup. If the VIRTIO_F_RING_RESET feature has been negotiated, individual virtqueues can be reset and then optionally re-configured. \subsubsection{Device Reset and Shutdown} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / Reset} -The driver \emph{MAY} reset or shut down a device at any time by writing a status +The driver MAY reset or shut down a device at any time by writing a status of 0 via \msgref{SET_DEVICE_STATUS}. This forces the device to discard its state and any pending operations on virtqueues. Once a device is reset, the driver -\emph{MAY} reinitialize the device (see +MAY reinitialize the device (see \ref{sec:Virtio Transport Options / Virtio Over Messages / Device Initialization}) if it wishes to use the device again. \paragraph{Device Side Initiated Reset} -In some circumstances, the device \emph{MAY} also trigger a reset if it +In some circumstances, the device MAY also trigger a reset if it encounters an unrecoverable error. This can be signaled to the driver by sending an \msgref{EVENT_CONFIG} with a \emph{device status} with the DEVICE_NEEDS_RESET -bit set. The driver \emph{SHOULD} reset the device by writing a status of 0 -via the \msgref{SET_DEVICE_STATUS} message. The driver \emph{MAY} reinitialize +bit set. The driver SHOULD reset the device by writing a status of 0 +via the \msgref{SET_DEVICE_STATUS} message. The driver MAY reinitialize the device if it wishes to use the device again. \subsection{Transport Messages}\label{sec:Virtio Transport Options / Virtio Over Messages / Transport Messages} Transport messages are used to configure and operate individual virtio devices. Unlike bus messages (which handle device enumeration, hotplug, or global resets), -transport messages \textbf{MUST} be implemented by any virtio-msg device and +transport messages MUST be implemented by any virtio-msg device and driver pair to enable standard virtio functionality (feature negotiation, configuration, virtqueues, etc.). The subsections below describe each message and clarify its required fields, typical usage patterns, and possible responses. @@ -819,7 +819,7 @@ \subsubsection{Overview} \paragraph{Mandatory Transport Messages} For a virtio-msg device to be fully operational, the following messages -\textbf{MUST} be supported: +MUST be supported: \begin{itemize} \item \msgref{GET_DEVICE_INFO} \item \msgref{GET_DEVICE_FEATURES} and \msgref{SET_DRIVER_FEATURES} @@ -828,7 +828,7 @@ \subsubsection{Overview} \item \msgref{GET_VQUEUE}, \msgref{SET_VQUEUE}, and \msgref{RESET_VQUEUE} \end{itemize} -The functionality of the following messages \textbf{MUST} be provided by +The functionality of the following messages MUST be provided by in-band messages, out-of-band event notification, or bus implementation based polling: \begin{itemize} @@ -860,10 +860,10 @@ \subsubsection{Overview} \hline \end{tabular} -The number of feature bits must be a multiple of 32. +The number of feature bits MUST be a multiple of 32. This is the only message allowed for an inactive device. If this message queries -an inactive device all fields in the response should be 0. +an inactive device all fields in the response SHOULD be 0. \msgdef{GET_DEVICE_FEATURES} @@ -883,7 +883,7 @@ \subsubsection{Overview} \hline \end{tabular} -A feature block is a group of 32 bits. The feature data \emph{MUST} be a +A feature block is a group of 32 bits. The feature data MUST be a multiple of 4 bytes in length. \msgdef{SET_DRIVER_FEATURES} @@ -903,11 +903,11 @@ \subsubsection{Overview} \hline \end{tabular} -A feature block is a group of 32 bits. The feature data \emph{MUST} be a +A feature block is a group of 32 bits. The feature data MUST be a multiple of 4 bytes in length. Note: As defined in \ref{sec:Basic Facilities of a Virtio Device / Feature Bits}, -if the device is not OK with the features set, it \emph{MUST} not allow +if the device is not OK with the features set, it MUST not allow the FEATURES_OK bit in the device status to be set. \msgdef{GET_CONFIG} @@ -983,8 +983,8 @@ \subsubsection{Overview} \hline \end{tabular} -The resulting device status is returned and may not match the status set. The -device may set the DEVICE_NEEDS_RESET bit if it has an issue. The device may +The resulting device status is returned and MAY not match the status set. The +device MAY set the DEVICE_NEEDS_RESET bit if it has an issue. The device MAY refuse to set the FEATURES_OK bit if it cannot operate with the features set by the driver. @@ -1010,7 +1010,7 @@ \subsubsection{Overview} \end{tabular} If the maximum virtqueue size is zero, the virtqueue is not valid and -\emph{MUST} not be used. +MUST not be used. \msgdef{SET_VQUEUE} @@ -1038,7 +1038,7 @@ \subsubsection{Overview} This message is sent by the virtio-msg transport driver and requires a response from the device. -The driver \emph{SHOULD NOT} send this message unless the VIRTIO_F_RING_RESET +The driver SHOULD NOT send this message unless the VIRTIO_F_RING_RESET feature has been negotiated. \begin{tabular}{|l|l|l|l|} @@ -1086,12 +1086,12 @@ \subsubsection{Overview} Request & 0 & 4 & Device status \\ & 4 & 4 & Configuration generation count \\ & 8 & 4 & Configuration offset \\ -& 12 & 4 & Number of bytes (\emph{MAY} be zero) \\ +& 12 & 4 & Number of bytes (MAY be zero) \\ & 16 & ... & Configuration data \\ \hline \end{tabular} -The number of bytes field \emph{MAY} be zero. If so the configuration data field +The number of bytes field MAY be zero. If so the configuration data field will also be of zero length. This is the normal case when the configuration generation count has not been changed. @@ -1113,9 +1113,9 @@ \subsubsection{Overview} \end{tabular} The \textbf{Next wrap} field is the MSB of the 32 bit value. The -\textbf{Next offset} field is the other 31 bits. These fields should be 0 if +\textbf{Next offset} field is the other 31 bits. These fields SHOULD be 0 if the VIRTIO_F_NOTIFICATION_DATA feature has not been negotiated. If the bus -implementation is using out-of-band notifications, it should prevent this +implementation is using out-of-band notifications, it SHOULD prevent this feature from being negotiated. \msgdef{EVENT_USED} @@ -1136,7 +1136,7 @@ \subsection{Bus Messages}\label{sec:Virtio Transport Options / Virtio Over Messa hotplug management, and liveness checks at the bus level. They are intended for bus implementations that wish to perform these operations \emph{via virtio-msg} rather than relying exclusively on external means (e.g., -firmware tables, device trees). Each bus instance \emph{may} use a subset of or +firmware tables, device trees). Each bus instance MAY use a subset of or all these messages according to its design. \paragraph{Messages IDs and issuers} @@ -1164,13 +1164,13 @@ \subsection{Bus Messages}\label{sec:Virtio Transport Options / Virtio Over Messa event messages. Bus message IDs 0x80 and above are bus implementation specific. Bus -implementations \emph{MAY} specify the policy that IDs below 0xC0 be used +implementations MAY specify the policy that IDs below 0xC0 be used for request/response messages and IDs 0xC0 and above are used for event messages. \paragraph{Note:} A bus implementation \textbf{is not required} to use these messages if it already provides equivalent functionality through some platform-specific mechanism. However, if a bus chooses to handle enumeration, -hotplug, etc. via virtio-msg, it \emph{should} implement the corresponding +hotplug, etc. via virtio-msg, it SHOULD implement the corresponding message definitions below. \newcommand{\busdef}[1]{\subsubsection{BUS_MSG_#1}\label{sec:Virtio Transport Options / Virtio Over Messages / Bus Messages / BUS_MSG_#1}} @@ -1237,12 +1237,12 @@ \subsection{Bus Messages}\label{sec:Virtio Transport Options / Virtio Over Messa \hline reserved & 0x3 to 0x7FFF & Reserved for standard use \\ \hline -any & 0x8000 to 0xFFFF & may be used by bus implementations \\ +any & 0x8000 to 0xFFFF & MAY be used by bus implementations \\ \hline \end{tabular} This event is sent when the bus level state of the device has changed. -It can indicate when a device is added or removed. It may also be used by +It can indicate when a device is added or removed. It MAY also be used by bus implementations to indicate other states. \busdef{PING} @@ -1263,15 +1263,15 @@ \subsection{Bus Messages}\label{sec:Virtio Transport Options / Virtio Over Messa \subsection{Compliance} \label{sec:Virtio Transport Options / Virtio Over Messages / Compliance} -This section details the requirements that an implementation \emph{MUST} meet to +This section details the requirements that an implementation MUST meet to be considered compliant with the virtio-msg transport. It distinguishes between -\emph{mandatory} behaviors that all implementations \emph{MUST} support and +\emph{mandatory} behaviors that all implementations MUST support and \emph{optional} behaviors that are permissible but not required. \subsubsection{Normative References} \label{sec:Virtio Transport Options / Virtio Over Messages / Compliance / NormativeRefs} -The terms \textbf{MUST}, \textbf{MUST NOT}, \textbf{SHOULD}, \textbf{SHOULD NOT}, -and \textbf{MAY} in this document are to be interpreted as specified by +The terms MUST, MUST NOT, SHOULD, SHOULD NOT, +and MAY in this document are to be interpreted as specified by \href{https://www.rfc-editor.org/rfc/rfc2119}{RFC 2119}. \subsubsection{Mandatory Requirements} @@ -1279,7 +1279,7 @@ \subsubsection{Mandatory Requirements} \paragraph{General Transport Requirements} \begin{itemize} - \item An implementation \textbf{MUST} correctly process or generate all + \item An implementation MUST correctly process or generate all \emph{transport messages} defined by this specification that are necessary for device operation. At minimum, this includes: \begin{itemize} @@ -1289,41 +1289,41 @@ \subsubsection{Mandatory Requirements} \item \msgref{GET_DEVICE_STATUS}, \msgref{SET_DEVICE_STATUS} \end{itemize} Failure to support these messages renders a device or driver noncompliant. - \item An implementation \textbf{MUST} adhere to the + \item An implementation MUST adhere to the \textbf{transport revision} and \textbf{maximum message size} constraints - indicated by each bus instance. For example, it \textbf{MUST NOT} exceed + indicated by each bus instance. For example, it MUST NOT exceed the \textbf{maximum message size} in any message. \end{itemize} \paragraph{Device-Side Requirements} \begin{itemize} - \item A device \textbf{MUST} provide accurate data in response to + \item A device MUST provide accurate data in response to \msgref{GET_DEVICE_INFO}, including the correct \emph{device ID}, \emph{vendor ID}, number of feature bits, and configuration size. - \item A device \textbf{MUST} accept or reject driver-requested features via - \msgref{SET_DRIVER_FEATURES} consistently with its capabilities and \textbf{MUST} + \item A device MUST accept or reject driver-requested features via + \msgref{SET_DRIVER_FEATURES} consistently with its capabilities and MUST return the final agreed-upon feature bits to the driver. - \item A device \textbf{MUST} maintain a valid \emph{Configuration Generation - Count} and \textbf{MUST} reject \msgref{SET_CONFIG} or similar operations if + \item A device MUST maintain a valid \emph{Configuration Generation + Count} and MUST reject \msgref{SET_CONFIG} or similar operations if the generation count supplied by the driver does not match. - \item A device \textbf{MUST} properly manage virtqueues configured via + \item A device MUST properly manage virtqueues configured via \msgref{SET_VQUEUE}, including storing and using the provided addresses for descriptor, driver, and device areas. - \item A device \textbf{MUST} respect \msgref{SET_DEVICE_STATUS} changes: if the - status is set to zero, the device \emph{MUST} reset its internal state and + \item A device MUST respect \msgref{SET_DEVICE_STATUS} changes: if the + status is set to zero, the device MUST reset its internal state and discard any pending operations. \end{itemize} \paragraph{Driver-Side Requirements} \begin{itemize} - \item A driver \textbf{MUST} send valid requests that do not exceed + \item A driver MUST send valid requests that do not exceed the \textbf{maximum message size}, including correct offsets and block counts in \msgref{GET_DEVICE_FEATURES}, \msgref{SET_DRIVER_FEATURES}, \msgref{GET_CONFIG}, and \msgref{SET_CONFIG}. - \item A driver \emph{MUST} handle a \msgref{SET_CONFIG} being rejected for a + \item A driver MUST handle a \msgref{SET_CONFIG} being rejected for a mismatched configuration generation count. - \item A driver \textbf{MUST} initialize each device's virtqueues (where needed) - via \msgref{SET_VQUEUE} before attempting normal I/O and \textbf{SHOULD} + \item A driver MUST initialize each device's virtqueues (where needed) + via \msgref{SET_VQUEUE} before attempting normal I/O and SHOULD query the device's status or configuration if an unexpected \msgref{EVENT_CONFIG} or error arises. \end{itemize} @@ -1333,28 +1333,28 @@ \subsubsection{Optional Requirements} \paragraph{Bus Messages for Enumeration and Hotplug} \begin{itemize} - \item Implementations \emph{MAY} use \busref{GET_DEVICES} + \item Implementations MAY use \busref{GET_DEVICES} and \busref{EVENT_DEVICE} for discovering and managing devices in a message-driven manner. However, this is not mandatory if other enumeration methods (e.g., device tree, ACPI, hypervisor firmware) are used. - \item If a bus chooses to implement these messages, it \textbf{MUST} do + \item If a bus chooses to implement these messages, it MUST do so in compliance with their defined formats and semantics (see \ref{sec:Virtio Transport Options / Virtio Over Messages / Bus Messages}). \end{itemize} \paragraph{Optional Bus-Level Messages} \begin{itemize} - \item \busref{PING} \emph{MAY} be implemented for keepalive or health checks. - If used, both sides \textbf{MUST} echo the 32-bit data field precisely. + \item \busref{PING} MAY be implemented for keepalive or health checks. + If used, both sides MUST echo the 32-bit data field precisely. \end{itemize} \paragraph{Runtime Notifications} \begin{itemize} - \item A device or the driver side bus \emph{MUST} send \msgref{EVENT_CONFIG} + \item A device or the driver side bus MUST send \msgref{EVENT_CONFIG} to inform the driver of configuration of device status changes. - \item A device or the driver side bus \emph{MUST} send \msgref{EVENT_USED} + \item A device or the driver side bus MUST send \msgref{EVENT_USED} to inform the driver of (likely) buffer completions. - \item A driver \emph{MUST} send \msgref{EVENT_AVAIL} to notify the device that + \item A driver MUST send \msgref{EVENT_AVAIL} to notify the device that new buffers are available. \end{itemize} @@ -1369,7 +1369,7 @@ \subsubsection{Compliance for Different Environments} \item It enforces the \textbf{maximum message size} and \textbf{transport revision} advertised for its instance. \item If it implements bus messages (e.g., \busref{GET_DEVICES}, \busref{PING}), - those must follow the formats in + those MUST follow the formats in \ref{sec:Virtio Transport Options / Virtio Over Messages / Bus Messages}. \end{itemize} @@ -1398,7 +1398,7 @@ \subsubsection{Compliance for Different Environments} \subsubsection{Conformance Statements} \label{sec:Virtio Transport Options / Virtio Over Messages / Compliance / Conformance} -An implementation \textbf{MUST} meet all "MUST" requirements stated in: +An implementation MUST meet all "MUST" requirements stated in: \begin{itemize} \item \ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts} (Basic Concepts) \item \ref{sec:Virtio Transport Options / Virtio Over Messages / Bus Operation} (Bus Operation) @@ -1408,8 +1408,8 @@ \subsubsection{Conformance Statements} \end{itemize} to claim compliance with the virtio-msg specification. -Implementations that do not follow these mandatory rules \emph{MUST NOT} declare -themselves conformant. Features or messages labeled as "optional" (\emph{MAY}) +Implementations that do not follow these mandatory rules MUST NOT declare +themselves conformant. Features or messages labeled as "optional" (MAY) do not invalidate compliance if omitted, provided all required behaviors are still correctly implemented. @@ -1417,9 +1417,9 @@ \subsubsection{Versioning and Forward Compatibility} \label{sec:Virtio Transport Options / Virtio Over Messages / Compliance / Versioning} A higher transport \textbf{transport revision} or additional \textbf{feature -bits} \emph{MAY} extend the protocol with new messages or capabilities. However, -to remain compliant with earlier revisions, devices and drivers \emph{SHOULD} +bits} MAY extend the protocol with new messages or capabilities. However, +to remain compliant with earlier revisions, devices and drivers SHOULD continue to honor the mandatory messages and semantics from prior revisions. If -a bus instance or device does not support an advanced feature, it \emph{SHOULD} +a bus instance or device does not support an advanced feature, it SHOULD reject or ignore those requests rather than undefined behavior. From 1a617c734e5479249cb74d399a7a117b5b32020c Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Tue, 18 Nov 2025 15:15:16 +0100 Subject: [PATCH 03/53] virtio-msg: Remove introduction as chapter To follow the organization of other transports, remove the introduction chapter by moving its content into basic concepts and just having a small introduction paragraph for the chapter instead. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 53 +++++++++++++++++++++-------------------------- 1 file changed, 24 insertions(+), 29 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 390422f..4cf5924 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -3,9 +3,8 @@ \section{Virtio Over Messages}\label{sec:Virtio Transport Options / Virtio Over \newcommand{\conceptref}[1]{\hyperref[sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / #1]{#1}} \newcommand{\msgref}[1]{\hyperref[sec:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_#1]{VIRTIO_MSG_#1}} \newcommand{\busref}[1]{\hyperref[sec:Virtio Transport Options / Virtio Over Messages / Bus Messages / BUS_MSG_#1]{BUS_MSG_#1}} - -\subsection{Introduction} -\label{sec:Virtio Transport Options / Virtio Over Messages / Introduction} +\newcommand{\msgdef}[1]{\subsubsection{VIRTIO_MSG_#1}\label{sec:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_#1}} +\newcommand{\busdef}[1]{\subsubsection{BUS_MSG_#1}\label{sec:Virtio Transport Options / Virtio Over Messages / Bus Messages / BUS_MSG_#1}} This section defines \textbf{virtio-msg}, a transport mechanism that encapsulates virtio operations as discrete message exchanges rather than relying on PCI or @@ -14,8 +13,6 @@ \subsection{Introduction} negotiation, virtqueue setup), ensuring that a single, generic transport layer can be reused across multiple bus implementations. -\subsubsection{Purpose} - virtio-msg addresses several key objectives: \begin{itemize} @@ -37,6 +34,15 @@ \subsubsection{Purpose} integrate smoothly once a device is discovered and registered. \end{itemize} +\subsection{Basic Concepts} +\label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts} + +The virtio-msg transport relies on a set of foundational concepts to ensure +reusability across different bus implementations and flexibility in device +capabilities. This section defines those concepts and clarifies how they apply, +regardless of whether the bus leverages message-based enumeration or platform +data for device discovery. + \subsubsection{High-Level Architecture} virtio-msg operates around two layers: @@ -73,6 +79,8 @@ \subsubsection{High-Level Architecture} \subsubsection{System Topology} +A virtio-msg system contains the following elements: + \begin{itemize} \item \textbf{Bus Instances and Devices}: Each bus instance advertises its capabilities (e.g., transport revision, maximum message size) and @@ -87,26 +95,6 @@ \subsubsection{System Topology} the correct device instance based on device number. \end{itemize} -\subsubsection{Optional Bus Messages} - -This specification \emph{defines} messages such as \busref{GET_DEVICES}, -\busref{EVENT_DEVICE}, and \busref{PING} for a -completely message-based approach to enumeration, hotplug, and bus-wide health. -However, these are \emph{not} mandatory if a bus instance already handles those -functions via firmware, device tree, or other platform features. The only strict -requirement is that the bus MUST be able to forward device-specific -\emph{transport messages} once a device is recognized, so the virtio-msg driver -can manage it. - -\subsection{Basic Concepts} -\label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts} - -The virtio-msg transport relies on a set of foundational concepts to ensure -reusability across different bus implementations and flexibility in device -capabilities. This section defines those concepts and clarifies how they apply, -regardless of whether the bus leverages message-based enumeration or platform -data for device discovery. - \subsubsection{Transport Revisions and Maximum Message Size} \label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Revisions} @@ -293,6 +281,17 @@ \subsubsection{Bus vs. Transport Messages} information from a device tree or firmware tables, while still supporting fully message-based enumeration and hotplug if desired. +\subsubsection{Optional Bus Messages} + +This specification \emph{defines} messages such as \busref{GET_DEVICES}, +\busref{EVENT_DEVICE}, and \busref{PING} for a +completely message-based approach to enumeration, hotplug, and bus-wide health. +However, these are \emph{not} mandatory if a bus instance already handles those +functions via firmware, device tree, or other platform features. The only strict +requirement is that the bus MUST be able to forward device-specific +\emph{transport messages} once a device is recognized, so the virtio-msg driver +can manage it. + \subsubsection{Endianness} \label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Endianness} @@ -837,8 +836,6 @@ \subsubsection{Overview} \item \msgref{EVENT_CONFIG} \end{itemize} -\newcommand{\msgdef}[1]{\subsubsection{VIRTIO_MSG_#1}\label{sec:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_#1}} - \msgdef{GET_DEVICE_INFO} This message is sent by the virtio-msg transport driver and requires a @@ -1173,8 +1170,6 @@ \subsection{Bus Messages}\label{sec:Virtio Transport Options / Virtio Over Messa hotplug, etc. via virtio-msg, it SHOULD implement the corresponding message definitions below. -\newcommand{\busdef}[1]{\subsubsection{BUS_MSG_#1}\label{sec:Virtio Transport Options / Virtio Over Messages / Bus Messages / BUS_MSG_#1}} - \busdef{GET_DEVICES} The driver-side bus uses this request to enumerate device numbers on the From 92a39c6447fdd2cdedd494981dd0f15a3b22e504 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Tue, 18 Nov 2025 15:30:58 +0100 Subject: [PATCH 04/53] virtio-msg: create a Device discovery section Create a stand-alone device discovery section to have the same organization as other transports. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 4cf5924..4dbc357 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -376,18 +376,12 @@ \subsubsection{Message Correlation} action. \end{itemize} -\subsection{Bus Operation} -\label{sec:Virtio Transport Options / Virtio Over Messages / Bus Operation} - -A \textbf{virtio-msg bus} is responsible for identifying available virtio devices -and informing the operating system (or higher-level software environment) so -that those devices can be bound to the appropriate driver. The following -subsections describe optional messaging mechanisms that a bus MAY use to -discover or manage devices, as well as general guidelines for completing the -device registration process. +\subsection{Device Discovery}\label{sec:Virtio Transport Options / Virtio Over Messages / Device Discovery} -\subsubsection{Device Discovery} -\label{sec:Virtio Transport Options / Virtio Over Messages / Bus Operation / Device Discovery} +A virtio-msg implementation can learn about devices via bus-level enumeration +(e.g., \busref{GET_DEVICES}), platform data (e.g., device tree, ACPI), or +hypervisor/firmware interfaces. The following informative text describes +typical flows; the normative obligations follow. Bus implementations MAY discover their devices in various ways: \begin{itemize} @@ -406,6 +400,16 @@ \subsubsection{Device Discovery} and vendor ID. The bus can then register the device with the host OS so the appropriate virtio driver probe routine is invoked. +\subsection{Bus Operation} +\label{sec:Virtio Transport Options / Virtio Over Messages / Bus Operation} + +A \textbf{virtio-msg bus} is responsible for identifying available virtio devices +and informing the operating system (or higher-level software environment) so +that those devices can be bound to the appropriate driver. The following +subsections describe optional messaging mechanisms that a bus MAY use to +discover or manage devices, as well as general guidelines for completing the +device registration process. + \subsubsection{Device Hotplug} \label{sec:Virtio Transport Options / Virtio Over Messages / Bus Operation / Device Hotplug} From d150afda419398bc3e7e9a3d01412c4e44844ca9 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Tue, 18 Nov 2025 18:31:52 +0100 Subject: [PATCH 05/53] virtio-msg: remove bus operation section Merge content into messages description directly by adding an intended usage paragraph or into the Basic Concepts section. This makes the transport content look more like PCI or Channel IO. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 153 ++++++++++++++++++++++------------------------ 1 file changed, 74 insertions(+), 79 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 4dbc357..2e32257 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -376,6 +376,18 @@ \subsubsection{Message Correlation} action. \end{itemize} +\subsubsection{Bus and Transport Messages} +\label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Bus and Transport Messages} + +The bus is responsible for forwarding device-specific \emph{transport +messages} to the correct device for each device number. Typically the bus does +not interpret or modify these transport messages; its role is simply to ensure +they reach the intended device. If the bus does not rely on messages for device +enumeration or hotplug itself, it MUST still be capable of transporting +\msgref{GET_DEVICE_INFO}, \msgref{GET_DEVICE_FEATURES}, \msgref{SET_CONFIG}, etc. +once the OS driver has identified a device and is performing initialization +via the virtio-msg transport. + \subsection{Device Discovery}\label{sec:Virtio Transport Options / Virtio Over Messages / Device Discovery} A virtio-msg implementation can learn about devices via bus-level enumeration @@ -400,79 +412,6 @@ \subsection{Device Discovery}\label{sec:Virtio Transport Options / Virtio Over M and vendor ID. The bus can then register the device with the host OS so the appropriate virtio driver probe routine is invoked. -\subsection{Bus Operation} -\label{sec:Virtio Transport Options / Virtio Over Messages / Bus Operation} - -A \textbf{virtio-msg bus} is responsible for identifying available virtio devices -and informing the operating system (or higher-level software environment) so -that those devices can be bound to the appropriate driver. The following -subsections describe optional messaging mechanisms that a bus MAY use to -discover or manage devices, as well as general guidelines for completing the -device registration process. - -\subsubsection{Device Hotplug} -\label{sec:Virtio Transport Options / Virtio Over Messages / Bus Operation / Device Hotplug} - -If the bus supports dynamic addition or removal of devices at runtime, it -MAY announce these events using messages: -\begin{itemize} - \item \busref{EVENT_DEVICE} with state DEVICE_BUS_STATE_READY for a newly - available device, - \item \busref{EVENT_DEVICE} with state DEVICE_BUS_STATE_REMOVED for a device - that is no longer accessible. -\end{itemize} - -Alternatively, the bus MAY rely on external signals (e.g., an event from -the platform or hypervisor) and inform the OS of hotplug changes out-of-band. -This specification \emph{defines} \busref{EVENT_DEVICE} -for implementations that prefer a fully message-based -approach but does not require their use. In any scenario, once notified that a -device has appeared, the bus SHOULD query the device (e.g., via -\msgref{GET_DEVICE_INFO}) and register it with the OS. If a device is -removed, the bus SHOULD prompt the OS to unbind and release resources. - -\subsubsection{Monitoring the Bus} -\label{sec:Virtio Transport Options / Virtio Over Messages / Bus Operation / Monitoring} - -An optional \busref{PING} message is provided for bus implementations that want -to periodically verify connectivity with the other end (driver or device). -Implementations MAY use other keepalive or health-check -protocols instead. The general usage of \busref{PING} (if implemented) is: - -\begin{itemize} - \item The initiator sends a 32-bit data field, - \item The recipient responds by echoing this same 32-bit data, - \item If a response does not arrive in time, the initiator MAY treat - the bus as unresponsive and trigger a global reset or other fallback - procedure. -\end{itemize} - -\subsubsection{Bus Specific Messages} -\label{sec:Virtio Transport Options / Virtio Over Messages / Bus Operation / 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 -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 Provide extra debug or logging information -\end{itemize} - -\subsubsection{Interaction with Transport Messages} -\label{sec:Virtio Transport Options / Virtio Over Messages / Bus Operation / Interaction with Transport} - -The bus is also responsible for forwarding device-specific \emph{transport -messages} to the correct device for each device number. Typically the bus does -not interpret or modify these transport messages; its role is simply to ensure -they reach the intended device. If the bus does not rely on messages for device -enumeration or hotplug itself, it MUST still be capable of transporting -\msgref{GET_DEVICE_INFO}, \msgref{GET_DEVICE_FEATURES}, \msgref{SET_CONFIG}, etc. -once the OS driver has identified a device and is performing initialization -via the virtio-msg transport. - \subsection{Device Initialization} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Initialization} @@ -754,6 +693,27 @@ \subsubsection{Device Reset and Shutdown} via the \msgref{SET_DEVICE_STATUS} message. The driver MAY reinitialize the device if it wishes to use the device again. +\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 at runtime, it +MAY announce these events using messages: +\begin{itemize} + \item \busref{EVENT_DEVICE} with state DEVICE_BUS_STATE_READY for a newly + available device, + \item \busref{EVENT_DEVICE} with state DEVICE_BUS_STATE_REMOVED for a device + that is no longer accessible. +\end{itemize} + +Alternatively, the bus MAY rely on external signals (e.g., an event from +the platform or hypervisor) and inform the OS of hotplug changes out-of-band. +This specification \emph{defines} \busref{EVENT_DEVICE} +for implementations that prefer a fully message-based +approach but does not require their use. In any scenario, once notified that a +device has appeared, the bus SHOULD query the device (e.g., via +\msgref{GET_DEVICE_INFO}) and register it with the OS. If a device is +removed, the bus SHOULD prompt the OS to unbind and release resources. + \subsection{Transport Messages}\label{sec:Virtio Transport Options / Virtio Over Messages / Transport Messages} Transport messages are used to configure and operate individual virtio devices. @@ -1140,6 +1100,15 @@ \subsection{Bus Messages}\label{sec:Virtio Transport Options / Virtio Over Messa firmware tables, device trees). Each bus instance MAY use a subset of or all these messages according to its design. +\subsubsection{Overview} +\label{sec:Virtio Transport Options / Virtio Over Messages / Bus Messages / Overview} + +A bus implementation \textbf{is not required} to use these +messages if it already provides equivalent functionality through some +platform-specific mechanism. However, if a bus chooses to handle enumeration, +hotplug, etc. via virtio-msg, it SHOULD implement the corresponding +message definitions below. + \paragraph{Messages IDs and issuers} \begin{tabular}{|l|l|l|} @@ -1168,11 +1137,19 @@ \subsection{Bus Messages}\label{sec:Virtio Transport Options / Virtio Over Messa implementations MAY specify the policy that IDs below 0xC0 be used for request/response messages and IDs 0xC0 and above are used for event messages. -\paragraph{Note:} A bus implementation \textbf{is not required} to use these -messages if it already provides equivalent functionality through some -platform-specific mechanism. However, if a bus chooses to handle enumeration, -hotplug, etc. via virtio-msg, it SHOULD implement the corresponding -message definitions below. +\paragraph{Bus Specific Messages} +\label{sec:Virtio Transport Options / Virtio Over Messages / Bus Operation / 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 +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 Provide extra debug or logging information +\end{itemize} \busdef{GET_DEVICES} @@ -1212,6 +1189,11 @@ \subsection{Bus Messages}\label{sec:Virtio Transport Options / Virtio Over Messa 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. + \busdef{EVENT_DEVICE} This message is sent by the virtio-msg device side bus and there is no response. @@ -1244,6 +1226,14 @@ \subsection{Bus Messages}\label{sec:Virtio Transport Options / Virtio Over Messa It can indicate when a device is added or removed. It MAY also be used by bus implementations to indicate other states. +\paragraph{Intended usage} +This message advertises device presence or removal. Upon READY, drivers SHOULD +probe the device via \msgref{GET_DEVICE_INFO} and proceed with initialization +if successful. Upon REMOVED, drivers MUST stop queueing new requests, +quiesce/reset as applicable, and release resources. Drivers SHOULD tolerate +duplicates and out-of-order events, and MAY use bus-level monitoring (see +\busref{PING}) to refine policy. + \busdef{PING} This message is sent by the virtio-msg driver side bus or device side bus and @@ -1252,13 +1242,18 @@ \subsection{Bus Messages}\label{sec:Virtio Transport Options / Virtio Over Messa \begin{tabular}{|l|l|l|l|} \hline Type & Offset & Size (bytes) & Content \\ -\hline \hline + \hline \hline Request & 0 & 4 & Data \\ \hline Answer & 0 & 4 & Request Data \\ \hline \end{tabular} +\paragraph{Intended usage} +Drivers MAY treat \busref{PING} as an optional keepalive or monitoring +mechanism. Timeouts or missing replies SHOULD trigger validation of device +state via \msgref{GET_DEVICE_STATUS} and recovery as appropriate. + \subsection{Compliance} \label{sec:Virtio Transport Options / Virtio Over Messages / Compliance} From 91a41babf93438ff655131391c547fd71fda82bb Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Wed, 19 Nov 2025 16:02:37 +0100 Subject: [PATCH 06/53] virtio-msg: merge all bus vs transport chapters in one Rework the Basic concepts to merge all chapters speaking of bus vs transport and the bus messages and transport messages into a single one to prevent repetition. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 99 ++++++++++++++++++++--------------------------- 1 file changed, 42 insertions(+), 57 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 2e32257..98798b9 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -77,6 +77,48 @@ \subsubsection{High-Level Architecture} environments. \end{enumerate} +\subsubsection{Relationship Between Bus and Transport} +\label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Relationship between bus and transport} + +This subsubsection explains the division of responsibilities: the bus layer is +the mandatory carrier that moves messages between driver and device endpoints +(e.g., over IPC, shared memory with signalling or hardware messaging), while +the virtio-msg transport defines the semantics of those messages. + +virtio-msg groups messages into two categories: + +\begin{description} + \item[\textbf{Bus Messages}:] + Intended for global bus operations such as enumerating device numbers + (\busref{GET_DEVICES}), managing device hotplug events (\busref{EVENT_DEVICE}) + or assessing bus-wide health (\busref{PING}). + These messages are \emph{optional} in environments where + device discovery or state changes occur through other means (e.g., device + tree). However, if a bus chooses to handle those tasks via messages, + it SHOULD implement the appropriate bus message definitions. + + \item[\textbf{Transport Messages}:] + Used for device-specific operations, such as: + \begin{itemize} + \item Retrieving or setting features (\msgref{GET_DEVICE_FEATURES}, + \msgref{SET_DRIVER_FEATURES}), + \item Accessing device configuration (\msgref{GET_CONFIG}, + \msgref{SET_CONFIG}), + \item Managing virtqueues (\msgref{SET_VQUEUE}, \msgref{RESET_VQUEUE}), + \item Handling device status and notifications (\msgref{SET_DEVICE_STATUS}, + \msgref{EVENT_USED}, etc.). + \end{itemize} + A bus implementation MUST relay these messages to the device number + identified in the header, regardless of how it discovered or enumerated + that device. Apart from enforcing generic transport limits (for example, + maximum message size), a bus SHOULD treat transport messages as opaque and + avoid modifying them. +\end{description} + +This separation lets a bus remain minimal if it obtains device information from +firmware tables, while still supporting fully message-based enumeration and +hotplug when desired. + \subsubsection{System Topology} A virtio-msg system contains the following elements: @@ -247,51 +289,6 @@ \subsubsection{Error Signaling} transmission failures; it only permits a virtio-msg bus to surface such failures to the virtio-msg transport when silent recovery is not feasible. -\subsubsection{Bus vs. Transport Messages} -\label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / BusVsTransport} - -virtio-msg groups messages into two categories: - -\begin{description} - \item[\textbf{Bus Messages}:] - Intended for global bus operations such as enumerating device numbers - (\busref{GET_DEVICES}), managing device hotplug events (\busref{EVENT_DEVICE}) - or assessing bus-wide health (\busref{PING}). - These messages are \emph{optional} in environments where - device discovery or state changes occur through other means (e.g., device - tree). However, if a bus chooses to handle those tasks via messages, - it SHOULD implement the appropriate bus message definitions. - - \item[\textbf{Transport Messages}:] - Used for device-specific operations, such as: - \begin{itemize} - \item Retrieving or setting features (\msgref{GET_DEVICE_FEATURES}, - \msgref{SET_DRIVER_FEATURES}), - \item Accessing device configuration (\msgref{GET_CONFIG}, - \msgref{SET_CONFIG}), - \item Managing virtqueues (\msgref{SET_VQUEUE}, \msgref{RESET_VQUEUE}), - \item Handling device status and notifications (\msgref{SET_DEVICE_STATUS}, - \msgref{EVENT_USED}, etc.). - \end{itemize} - The bus MUST relay these messages to the correct device, - regardless of how the bus discovered or enumerated that device. -\end{description} - -The resulting design allows a bus to remain minimal if it obtains device -information from a device tree or firmware tables, while still supporting -fully message-based enumeration and hotplug if desired. - -\subsubsection{Optional Bus Messages} - -This specification \emph{defines} messages such as \busref{GET_DEVICES}, -\busref{EVENT_DEVICE}, and \busref{PING} for a -completely message-based approach to enumeration, hotplug, and bus-wide health. -However, these are \emph{not} mandatory if a bus instance already handles those -functions via firmware, device tree, or other platform features. The only strict -requirement is that the bus MUST be able to forward device-specific -\emph{transport messages} once a device is recognized, so the virtio-msg driver -can manage it. - \subsubsection{Endianness} \label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Endianness} @@ -376,18 +373,6 @@ \subsubsection{Message Correlation} action. \end{itemize} -\subsubsection{Bus and Transport Messages} -\label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Bus and Transport Messages} - -The bus is responsible for forwarding device-specific \emph{transport -messages} to the correct device for each device number. Typically the bus does -not interpret or modify these transport messages; its role is simply to ensure -they reach the intended device. If the bus does not rely on messages for device -enumeration or hotplug itself, it MUST still be capable of transporting -\msgref{GET_DEVICE_INFO}, \msgref{GET_DEVICE_FEATURES}, \msgref{SET_CONFIG}, etc. -once the OS driver has identified a device and is performing initialization -via the virtio-msg transport. - \subsection{Device Discovery}\label{sec:Virtio Transport Options / Virtio Over Messages / Device Discovery} A virtio-msg implementation can learn about devices via bus-level enumeration From d81941b5d25db6eb56b742f5d1fbd34a745625bb Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Wed, 19 Nov 2025 16:34:05 +0100 Subject: [PATCH 07/53] virtio-msg: move compatibility rules in basic concepts Move version compatibility rules in a sub-chapter of transport revision in the basic concepts. This is to prepare for the removal of the compliance chapter. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 98798b9..e0c2c7b 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -190,6 +190,15 @@ \subsubsection{Transport Revisions and Maximum Message Size} This value is large enough to support a GET_CONFIG or SET_CONFIG message with a configuration data payload of 256 bytes. +\paragraph{Versioning and Forward Compatibility} + +A higher transport \textbf{transport revision} or additional \textbf{feature +bits} MAY extend the protocol with new messages or capabilities. However, +to remain compliant with earlier revisions, devices and drivers SHOULD +continue to honor the mandatory messages and semantics from prior revisions. If +a bus instance or device does not support an advanced feature, it SHOULD +reject or ignore those requests rather than undefined behavior. + \subsubsection{Device Numbers and Enumeration} \label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Device Numbers} @@ -1392,13 +1401,3 @@ \subsubsection{Conformance Statements} do not invalidate compliance if omitted, provided all required behaviors are still correctly implemented. -\subsubsection{Versioning and Forward Compatibility} -\label{sec:Virtio Transport Options / Virtio Over Messages / Compliance / Versioning} - -A higher transport \textbf{transport revision} or additional \textbf{feature -bits} MAY extend the protocol with new messages or capabilities. However, -to remain compliant with earlier revisions, devices and drivers SHOULD -continue to honor the mandatory messages and semantics from prior revisions. If -a bus instance or device does not support an advanced feature, it SHOULD -reject or ignore those requests rather than undefined behavior. - From f55c83c6ba435760a901c6685e8e146680c1fd94 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Thu, 20 Nov 2025 11:19:34 +0100 Subject: [PATCH 08/53] virtio-msg: add new command for bus normative Add a new command to have a standard way to define virtio-msg bus normative statements. Signed-off-by: Bertrand Marquis --- commands.tex | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/commands.tex b/commands.tex index 25ea8ee..122a97f 100644 --- a/commands.tex +++ b/commands.tex @@ -7,9 +7,10 @@ % How we format a field name \newcommand{\field}[1]{\emph{#1}} -% Mark a normative section (driver or device) +% Mark a normative section (driver, device, or bus) \newcommand{\drivernormative}[3]{#1{Driver Requirements: #2}\label{drivernormative:#3}} \newcommand{\devicenormative}[3]{#1{Device Requirements: #2}\label{devicenormative:#3}} +\newcommand{\busnormative}[3]{#1{Bus Requirements: #2}\label{busnormative:#3}} \newcounter{clausecounter} \newcommand{\conformance}[2]{ \stepcounter{clausecounter} From 2cae300642b2d07eed0122629bac43f76b04bf6f Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Thu, 20 Nov 2025 11:21:06 +0100 Subject: [PATCH 09/53] virtio-msg: normative in bus vs transport relationship Add bus normative statement in bus vs transport section of basic concepts. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 26 +++++++++++++++++++------- 1 file changed, 19 insertions(+), 7 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index e0c2c7b..b65b409 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -95,7 +95,8 @@ \subsubsection{Relationship Between Bus and Transport} These messages are \emph{optional} in environments where device discovery or state changes occur through other means (e.g., device tree). However, if a bus chooses to handle those tasks via messages, - it SHOULD implement the appropriate bus message definitions. + it implements the appropriate bus message definitions described in this + section. \item[\textbf{Transport Messages}:] Used for device-specific operations, such as: @@ -108,17 +109,29 @@ \subsubsection{Relationship Between Bus and Transport} \item Handling device status and notifications (\msgref{SET_DEVICE_STATUS}, \msgref{EVENT_USED}, etc.). \end{itemize} - A bus implementation MUST relay these messages to the device number - identified in the header, regardless of how it discovered or enumerated - that device. Apart from enforcing generic transport limits (for example, - maximum message size), a bus SHOULD treat transport messages as opaque and - avoid modifying them. \end{description} This separation lets a bus remain minimal if it obtains device information from firmware tables, while still supporting fully message-based enumeration and hotplug when desired. +\busnormative{\paragraph}{Bus Message Implementation}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Relationship between bus and transport / Bus Messages} +\begin{itemize} + \item A bus implementation that provides enumeration, hotplug, or bus + health handling via bus messages SHOULD implement the corresponding Bus + Message definitions described in this section. +\end{itemize} + +\busnormative{\paragraph}{Transport Message Forwarding}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Relationship between bus and transport / Transport Message Forwarding} +\begin{itemize} + \item A bus implementation MUST relay each transport message to the device + number identified in the message header, regardless of how it + discovered or enumerated that device. + \item A bus implementation SHOULD treat transport messages as opaque apart + from enforcing generic transport limits, such as the advertised maximum + message size, and SHOULD NOT modify the transport payload. +\end{itemize} + \subsubsection{System Topology} A virtio-msg system contains the following elements: @@ -1400,4 +1413,3 @@ \subsubsection{Conformance Statements} themselves conformant. Features or messages labeled as "optional" (MAY) do not invalidate compliance if omitted, provided all required behaviors are still correctly implemented. - From 00abb585bd3fd0ecda903119009cf4ddee59b741 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Thu, 20 Nov 2025 11:28:23 +0100 Subject: [PATCH 10/53] virtio-msg: rework transport revision Rework the transport revision and maximum message size section to switch to normative declarations. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 82 +++++++++++++++++++++++++++++------------------ 1 file changed, 51 insertions(+), 31 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index b65b409..5e07f8a 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -156,30 +156,49 @@ \subsubsection{Transport Revisions and Maximum Message Size} Each \textbf{virtio-msg bus instance} advertises the following to the transport layer: \begin{itemize} - \item A \textbf{transport revision} indicating the protocol version it - supports. This revision is separate from the overall Virtio - specification version. - \item A \textbf{maximum message size} representing the largest payload - (in bytes) the bus can reliably carry per request or response. - \item A \textbf{feature bits} indicating a list of revision specific - optional features that are supported or not by the bus instance. + \item \textbf{Transport revision}: the protocol version supported by the bus + instance (independent of the overall Virtio specification version). + \item \textbf{Maximum message size}: the largest payload (in bytes) that can + be carried per request or response, including the common header. + \item \textbf{Transport feature bits}: revision-specific optional features + implemented by the bus instance. \end{itemize} -These parameters MAY vary between bus instances within the same system. -The bus implementation obtains a bus's revision, maximum message size and list -of features through an \emph{implementation-defined} mechanism, which could be: +The mechanism for obtaining these parameters is implementation-defined and can +vary between bus instances. Common approaches include: \begin{itemize} - \item A device tree or firmware method providing bus configuration, - \item A message exchange during bus setup, - \item A per bus instance list of properties, - \item A static definition built into the driver for a known environment. + \item Reading firmware or device-tree data that describes each bus instance, + \item Performing a message exchange during bus setup to retrieve the values, + \item Relying on per-bus configuration structures or driver-specific defaults. \end{itemize} -After learning these parameters, the transport layer MUST respect them -for all messages involving that bus instance. For example, it MUST NOT -send a message exceeding the \textbf{maximum message size}, and it MUST -avoid using advanced features or messages unavailable in the bus's advertised -\textbf{transport revision}. +\busnormative{\paragraph}{Advertising Transport Parameters}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Revisions / Advertising Transport Parameters} +\begin{itemize} + \item Each bus instance MUST make its transport revision, maximum message + size, and transport feature bits available to the virtio-msg transport + before any transport messages are exchanged for that device. + \item A bus instance MUST apply the same limits to both driver-originated and + device-originated transport messages; if the values change, the bus + MUST inform the transport layer before accepting additional messages. +\end{itemize} + +\drivernormative{\paragraph}{Respecting Bus Limits (Driver)}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Revisions / Driver Limits} +\begin{itemize} + \item A driver MUST NOT send a transport message whose total size exceeds the + maximum message size advertised for the target bus instance. + \item A driver MUST NOT rely on transport features or messages that require a + higher transport revision than the bus instance reports. +\end{itemize} + +\devicenormative{\paragraph}{Respecting Bus Limits (Device)}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Revisions / Device Limits} +\begin{itemize} + \item A device MUST ensure its responses and device-originated messages do + not exceed the maximum message size advertised by the bus instance that + relays them. + \item A device MUST NOT require transport features or messages beyond the + transport revision reported by the bus instance, and MUST respond with + an error or ignore requests for unsupported features. +\end{itemize} \paragraph{virtio-msg revisions} @@ -196,21 +215,22 @@ \subsubsection{Transport Revisions and Maximum Message Size} Note that a change in the virtio standard does not necessarily correspond to a change in the virtio-msg revision. -The maximum message size is from the common transport level point of -view and includes the headers and payload described here. If the bus adds its -own overhead (e.x. its own header) this is not included in the maximum message -size. The maximum useful message size is currently expected to be 274. -This value is large enough to support a GET_CONFIG or SET_CONFIG message with a -configuration data payload of 256 bytes. +The maximum message size is specified from the transport-layer point of view +and includes the 8-byte common header plus payload. Any extra encapsulation +imposed by the underlying bus (for example, a framing header) does not count +against this limit. Today the maximum useful transport payload is expected to +be 274 bytes, which is sufficient for a GET_CONFIG or SET_CONFIG transfer with +256 bytes of configuration data. \paragraph{Versioning and Forward Compatibility} -A higher transport \textbf{transport revision} or additional \textbf{feature -bits} MAY extend the protocol with new messages or capabilities. However, -to remain compliant with earlier revisions, devices and drivers SHOULD -continue to honor the mandatory messages and semantics from prior revisions. If -a bus instance or device does not support an advanced feature, it SHOULD -reject or ignore those requests rather than undefined behavior. +A higher transport revision or additional transport feature bits extend the +protocol with new messages or capabilities. Implementations are expected to +remain interoperable across revisions: devices and drivers designed for a newer +revision still implement the mandatory messages and semantics defined in prior +revisions. When a bus instance, driver, or device encounters an unsupported +message or feature, it should reject the request explicitly or ignore it rather +than exhibit undefined behavior. \subsubsection{Device Numbers and Enumeration} \label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / From da563c1605dac452e01a0df94ea2c12ad07ef624 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Mon, 1 Dec 2025 16:25:16 +0100 Subject: [PATCH 11/53] virtio-msg: Add normative statement for message size Add normative statement on message size constraints in the revisions chapter. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 5e07f8a..0ca9dcd 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -218,9 +218,18 @@ \subsubsection{Transport Revisions and Maximum Message Size} 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 maximum useful transport payload is expected to -be 274 bytes, which is sufficient for a GET_CONFIG or SET_CONFIG transfer with -256 bytes of configuration data. +against this limit. Today the largest practical transport payload is 256 bytes: +messages such as GET_CONFIG and SET_CONFIG can carry up to 256 bytes of device +configuration in one transfer, and larger configuration regions can be accessed +through multiple exchanges without requiring a larger per-message limit. + +\busnormative{\paragraph}{Message Size Bounds}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Revisions / Message Size} +\begin{itemize} + \item A bus implementation MUST advertise a maximum message size of at least + 44 bytes. + \item A bus implementation SHOULD NOT advertise a maximum message size that + exceeds 264 bytes (256-byte payload plus the common header). +\end{itemize} \paragraph{Versioning and Forward Compatibility} From 963fa80b8759afe3b8861080e462ec8ec5743edb Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Mon, 1 Dec 2025 16:31:16 +0100 Subject: [PATCH 12/53] virtio-msg: Add normative statements for version compat Define some normative statements for backward compatibility rules. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 32 +++++++++++++++++++++++++++++--- 1 file changed, 29 insertions(+), 3 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 0ca9dcd..e9e0093 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -237,9 +237,35 @@ \subsubsection{Transport Revisions and Maximum Message Size} protocol with new messages or capabilities. Implementations are expected to remain interoperable across revisions: devices and drivers designed for a newer revision still implement the mandatory messages and semantics defined in prior -revisions. When a bus instance, driver, or device encounters an unsupported -message or feature, it should reject the request explicitly or ignore it rather -than exhibit undefined behavior. +revisions. + +\drivernormative{\paragraph}{Revision Compatibility}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Versioning and Forward Compatibility / Driver} +\begin{itemize} + \item A driver that negotiates transport revision $N$ MUST implement all + mandatory driver behavior defined for revisions $1$ through $N$. + \item If a driver receives a device-originated message or feature indication + that requires an unsupported revision or transport feature, it MUST + ignore the message (or treat the request as failed) and MUST NOT act on + partially understood data. +\end{itemize} + +\devicenormative{\paragraph}{Revision Compatibility}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Versioning and Forward Compatibility / Device} +\begin{itemize} + \item A device that advertises transport revision $N$ MUST implement all + mandatory device behavior defined for revisions $1$ through $N$. + \item If a device receives a driver request that relies on an unsupported + revision or transport feature, it MUST reject the request using the + message-specific error mechanism (if any) or silently ignore it. +\end{itemize} + +\busnormative{\paragraph}{Revision Compatibility}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Versioning and Forward Compatibility / Bus} +\begin{itemize} + \item A bus instance that advertises transport revision $N$ MUST satisfy every + bus requirement defined for revisions $1$ through $N$. + \item If a bus instance cannot forward a message because it requires an + unsupported revision or transport feature, it MUST surface a transport + error or drop the message without forwarding it. +\end{itemize} \subsubsection{Device Numbers and Enumeration} \label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / From 7296f149908d6b40807b063503dec9f7235515e4 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Thu, 20 Nov 2025 11:35:57 +0100 Subject: [PATCH 13/53] virtio-msg: Switch to normative in device numbers Switch to normative statement in device numbers and enumeration section. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index e9e0093..366dc79 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -272,8 +272,8 @@ \subsubsection{Device Numbers and Enumeration} Device Numbers} Each virtio-msg bus instance contains one or more \emph{devices}, identified -by a 16-bit \textbf{device number}. Buses MAY discover these device -numbers in multiple ways: +by a 16-bit \textbf{device number}. Buses discover these device numbers through +mechanisms such as: \begin{itemize} \item \textbf{Message-Based Enumeration}: Using \busref{GET_DEVICES} to query which numbers exist (optional). @@ -281,10 +281,20 @@ \subsubsection{Device Numbers and Enumeration} might inform the bus of available device numbers and their properties. \end{itemize} -Once a bus confirms that a given device number is valid (regardless of the method), -it typically issues \msgref{GET_DEVICE_INFO} to retrieve the device's Device ID -and vendor ID. The bus can then register the device with the host OS to initiate -the usual Virtio driver binding process. +Once a bus confirms that a device number is valid—regardless of the discovery +method—it normally issues \msgref{GET_DEVICE_INFO} to retrieve the device and +vendor IDs before registering the device with the host OS so the usual Virtio +driver binding process can begin. + +\busnormative{\paragraph}{Device Number Assignment}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Device Numbers / Assignment} +\begin{itemize} + \item A bus implementation MUST assign a unique device number to every + device on a given bus instance and MUST NOT forward transport messages + for a device number that has not been validated. + \item A bus implementation SHOULD provide the driver with sufficient + information—either via \busref{GET_DEVICES} or equivalent platform + data—to discover each valid device number. +\end{itemize} \subsubsection{Configuration Generation Count} \label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / ConfigGen} From 6859b5b2dee94d6b701bc88c91f2045f924256a8 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Thu, 20 Nov 2025 11:58:07 +0100 Subject: [PATCH 14/53] virtio-msg: switch generation count to normative Rework Generation Count section in basic concept to use normative statements. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 47 +++++++++++++++++++++++++++-------------------- 1 file changed, 27 insertions(+), 20 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 366dc79..a966593 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -301,28 +301,35 @@ \subsubsection{Configuration Generation Count} Each device maintains a \textbf{Configuration Generation Count} to prevent inconsistent updates. This count is incremented at least once by the device for -every driver visible change it makes to its own copy of the configuration data. -A configuration change is made visible to the driver via \msgref{EVENT_CONFIG} -or the response to \msgref{GET_CONFIG} which also both provide the device's -current configuration count. The device MAY change any amount of data for one -generation count increment. If the change cannot fit in one \msgref{EVENT_CONFIG} -message, the device SHOULD send an \msgref{EVENT_CONFIG} message -with a zero data length and the new generation count to the driver. -The device MUST NOT provide the same generation count in -multiple \msgref{EVENT_CONFIG} messages that contain non-zero length config -data. The driver includes its view of the current generation count in -\msgref{SET_CONFIG} requests. The configuration generation count does not -necessarily start at 0 and SHOULD NOT reset to 0 on device reset. +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 (Device)}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / ConfigGen / Device} \begin{itemize} - \item If the driver's generation count does not match the device's current - count, the \msgref{SET_CONFIG} request MUST be rejected by the - device. - \item The driver MAY have received \msgref{EVENT_CONFIG} messages - between the request and the response and will know the current - configuration data and generation count. If not it SHOULD - re-read the configuration and generation count via \msgref{GET_CONFIG}), - and then resend the \msgref{SET_CONFIG} if still desired. + \item A device MUST increment the generation count before it makes a change + that is visible to the driver and MUST ensure that each + \msgref{EVENT_CONFIG} carrying configuration data uses a unique + generation count. + \item If updated configuration data cannot fit in a single + \msgref{EVENT_CONFIG}, the device SHOULD send an \msgref{EVENT_CONFIG} + with zero data length to advertise the new generation count and MUST + make the updated data available via \msgref{GET_CONFIG}. + \item If a \msgref{SET_CONFIG} request includes a generation count that does + not match the device's current count, the device MUST reject the + request. +\end{itemize} + +\drivernormative{\paragraph}{Configuration Generation Count (Driver)}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / ConfigGen / Driver} +\begin{itemize} + \item A driver MUST track the most recent generation count observed (via + \msgref{EVENT_CONFIG} or \msgref{GET_CONFIG}) and include it in every + \msgref{SET_CONFIG} request. + \item If a \msgref{SET_CONFIG} request is rejected due to a mismatched + generation count, the driver SHOULD issue \msgref{GET_CONFIG} to obtain + the latest configuration data and generation count before retrying. \end{itemize} This mechanism ensures updates are not lost or overwritten due to stale From db203b98b6d71a75b53dc6085496216503f4c6e3 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Thu, 20 Nov 2025 12:01:13 +0100 Subject: [PATCH 15/53] virtio-msg: apply normative in feature blocks Signed-off-by: Bertrand Marquis --- transport-msg.tex | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index a966593..0e16f67 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -338,21 +338,25 @@ \subsubsection{Configuration Generation Count} \subsubsection{Feature Negotiation Blocks} \label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / FeatureBlocks} -The virtio-msg transport handles feature bits in one or more -\textbf{32-bits blocks}, accessed via \msgref{GET_DEVICE_FEATURES} and -\msgref{SET_DRIVER_FEATURES}. Each block corresponds to up to 32 features: +The virtio-msg transport organizes feature bits into 32-bit blocks accessed by +\msgref{GET_DEVICE_FEATURES} and \msgref{SET_DRIVER_FEATURES}. Each block +represents up to 32 feature bits: \begin{itemize} \item \textbf{Block Index}: The starting block (e.g., block 0 for features 0--31, block 1 for features 32--63, etc.). \item \textbf{Number of Blocks}: How many blocks the driver wishes to retrieve or modify in a single message. - \item \textbf{Feature Data}: The 32 bits values representing a device's - supported or requested feature bits. + \item \textbf{Feature Data}: The 32-bit values representing the supported (or + driver-requested) feature bits in the selected blocks. \end{itemize} -A device MUST respond with all zero feature data for features bit -requested beyond those the device implements. +\devicenormative{\paragraph}{Feature Blocks (Device)}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / FeatureBlocks / Device} +\begin{itemize} + \item When \msgref{GET_DEVICE_FEATURES} covers blocks that extend beyond the + features a device implements, the device MUST return zero for the + feature data in those positions. +\end{itemize} \subsubsection{Error Signaling} \label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / ErrorSignaling} From 718d1c0d96ea273fae3fca03e4d177673d4aea9c Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Thu, 20 Nov 2025 12:36:04 +0100 Subject: [PATCH 16/53] virtio-msg: Switch error signaling to normative Signed-off-by: Bertrand Marquis --- transport-msg.tex | 50 ++++++++++++++++++++++++++--------------------- 1 file changed, 28 insertions(+), 22 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 0e16f67..28a321f 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -361,31 +361,37 @@ \subsubsection{Feature Negotiation Blocks} \subsubsection{Error Signaling} \label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / ErrorSignaling} -Errors MAY arise from: (a) malformed or unsupported transport messages, (b) -transmission or routing issues within a bus implementation, or (c) device-side -failures while processing a valid request. Local detection and recovery are -preferred, but a virtio-msg bus MAY report transmission errors to the -virtio-msg transport when it cannot deliver a request or obtain a response -within a bounded policy. - -The following rules apply: +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. + +\busnormative{\paragraph}{Error Handling (Bus)}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / ErrorSignaling / 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 NOT generate error responses to event + (one-way) messages. +\end{itemize} + +\devicenormative{\paragraph}{Error Handling (Device)}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / ErrorSignaling / Device} \begin{itemize} - \item A bus implementation MAY surface a transport-visible failure - (implementation-defined) after exhausting any bounded retry policy for - a transmission error. - \item Malformed headers or unsupported \field{msg_id} values SHOULD - be discarded; the receiver MAY log them and SHOULD NOT - generate further protocol traffic in response. - \item Event (one-way) messages MUST NOT elicit an error response. - \item Recovery actions (retry, selective reset, device removal) are - environment-specific but MUST comply with any normative reset - or status handling semantics described in - \ref{sec:Virtio Transport Options / Virtio Over Messages / Device Operation}. + \item A device receiving a malformed or unsupported transport message MUST + discard it without producing further protocol traffic. + \item Recovery actions taken in response to an error (such as retries, + selective resets, or device removal) MUST follow the normative reset and + status semantics defined in + \ref{sec:Virtio Transport Options / Virtio Over Messages / Device Operation}. \end{itemize} -This specification does not mandate a specific error reporting message for -transmission failures; it only permits a virtio-msg bus to surface such -failures to the virtio-msg transport when silent recovery is not feasible. +This specification does not define a dedicated error-reporting message; it only +permits implementations to surface failures when silent recovery is not +feasible. \subsubsection{Endianness} \label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Endianness} From b804cc4d37ab30e39403a7a6a82f49be421065a0 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Thu, 20 Nov 2025 12:36:58 +0100 Subject: [PATCH 17/53] virtio-msg: switch endianness to normative Signed-off-by: Bertrand Marquis --- transport-msg.tex | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 28a321f..b4277c5 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -396,8 +396,20 @@ \subsubsection{Error Signaling} \subsubsection{Endianness} \label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Endianness} -All values and fields defined in the virtio-msg messages MUST -be encoded in little-endian. +Unless otherwise stated, all numeric fields defined for virtio-msg messages use +little-endian encoding. + +\drivernormative{\paragraph}{Endianness (Driver)}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Endianness / Driver} +\begin{itemize} + \item A driver MUST encode and decode the common header and payload fields + defined by this transport using little-endian byte order. +\end{itemize} + +\devicenormative{\paragraph}{Endianness (Device)}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Endianness / Device} +\begin{itemize} + \item A device MUST emit and consume the common header and payload fields + defined by this transport using little-endian byte order. +\end{itemize} \subsubsection{Common Message Format} \label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Common Message Format} From a971eb29c5ca46bfab3275c974d0ce89c964673d Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Thu, 20 Nov 2025 12:45:46 +0100 Subject: [PATCH 18/53] virtio-msg: convert common message format to normative Signed-off-by: Bertrand Marquis --- transport-msg.tex | 79 +++++++++++++++++++++++++++++++++++------------ 1 file changed, 60 insertions(+), 19 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index b4277c5..5336d11 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -414,9 +414,9 @@ \subsubsection{Endianness} \subsubsection{Common Message Format} \label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Common Message Format} -All virtio-msg exchanges, whether \emph{bus messages} or -\emph{transport messages}, begin with an 8 byte header followed by an optional -payload. +All virtio-msg exchanges, whether \emph{bus messages} or \emph{transport +messages}, begin with an 8-byte header followed by an optional payload. The +fields below describe the wire format for that header. The header layout is: \begin{lstlisting} @@ -435,30 +435,71 @@ \subsubsection{Common Message Format} \item \field{type}: \begin{itemize} \item Bit[0]: 0=request, 1=response. - \item Bit[1]: 0=Transport Message, 1=Bus Message. - \item Bits[2..7]: MUST be zero; receivers MUST ignore. + \item Bit[1]: 0=transport message, 1=bus message. + \item Bits[2..7]: reserved for future use. \end{itemize} \item \field{msg_id}: Message ID identifying the message definition. Ranges are defined in \ref{sec:Virtio Transport Options / Virtio Over Messages / Transport Messages} and \ref{sec:Virtio Transport Options / Virtio Over Messages / Bus Messages}. - \item \field{dev_num}: For Transport Messages, the target device number; for - Bus Messages MUST be zero. - \item \field{token}: Non-zero for requests (which expect a response); zero - MUST be used only for event (one-way) messages. Responses - MUST echo the request's \field{token}. - \item \field{msg_size}: Total size in bytes of the complete message (header + - payload). MUST be \(\ge 8\) and MUST NOT exceed the - bus's maximum message size. - \item \field{payload}: Operation-specific data. Unused trailing bytes (if any - introduced by a bus framing) MUST be zero and MUST be - ignored by receivers. + \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}: Requests use non-zero tokens so responses can be matched; + event (one-way) messages use token 0 and do not expect a response. + \item \field{msg_size}: Total size in bytes of the complete message (header + plus payload). + \item \field{payload}: Operation-specific data. If a bus introduces extra + padding bytes, those bytes are not part of the payload semantics. \end{itemize} -All reserved header bits and any unspecified header values MUST be -sent as zero and MUST be ignored on receive to preserve forward -compatibility. +\drivernormative{\paragraph}{Common Header (Driver)}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Common Message Format / Driver} +\begin{itemize} + \item A driver MUST set bits 2..7 of \field{type} to zero and MUST treat them + as reserved when parsing received headers. + \item A driver MUST ensure \field{msg_size} reflects the total message length + (header plus payload) and MUST NOT exceed the maximum message size + advertised by the bus instance. + \item A driver MUST set \field{token}=0 for event (one-way) messages and MUST + assign a non-zero \field{token} for every request that expects a + response. + \item When sending a transport message, a driver MUST set \field{dev_num} to + the intended device number. + \item If a driver introduces padding bytes that become part of the transport + payload, it MUST set those bytes to zero. +\end{itemize} + +\devicenormative{\paragraph}{Common Header (Device)}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Common Message Format / Device} +\begin{itemize} + \item A device MUST set bits 2..7 of \field{type} to zero in transmitted + messages and MUST ignore those bits on receive. + \item A device MUST ensure \field{msg_size} reflects the total message length + (header plus payload) and does not exceed the bus's advertised maximum. + \item A device MUST set \field{token}=0 for event (one-way) messages it + originates and MUST echo the \field{token} received in requests when + producing responses. + \item When sending a transport message, a device MUST set \field{dev_num} to + its own device number. + \item A device MUST ignore padding bytes that are documented as bus-specific + and MUST zero any such bytes it introduces into the transport payload. +\end{itemize} + +\busnormative{\paragraph}{Common Header (Bus)}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Common Message Format / Bus} +\begin{itemize} + \item A bus implementation MUST deliver bus messages with \field{dev_num}=0 + and MUST NOT alter \field{dev_num} for transport messages beyond the + routing needed to reach the addressed device. + \item A bus implementation MUST set bits 2..7 of \field{type} to zero when + generating bus messages and MUST ignore those bits when forwarding + transport messages. + \item If the bus adds framing or padding bytes around the common header or + payload, it MUST set those bytes to zero before delivering the message + to the opposite side and MUST present the same zero padding when the + opposite side reads a message. +\end{itemize} + +Reserved header bits and unspecified header values MUST be transmitted as zero +and ignored on receive to preserve forward compatibility. \subsubsection{Message Correlation} \label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Correlation} From 231b768591122b4ac8fdfca4cd7a2f871d8a957d Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Thu, 20 Nov 2025 12:48:19 +0100 Subject: [PATCH 19/53] virtio-msg: convert correlation to normative Signed-off-by: Bertrand Marquis --- transport-msg.tex | 36 +++++++++++++++++------------------- 1 file changed, 17 insertions(+), 19 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 5336d11..d458a11 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -504,30 +504,28 @@ \subsubsection{Common Message Format} \subsubsection{Message Correlation} \label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Correlation} -Messages are either requests or events. Requests require a response. Events are -one way and do not have a response. Most requests defined today originate at the -driver side but bus message requests such as \busref{PING} MAY originate at -either driver side or device side. +Requests expect responses, whereas events are one-way and do not. Correlation is +based on the tuple (\field{dev_num}, \field{token}) from the message header. -This section defines how responses are correlated to requests. An implementation -does not need to support sending multiple requests in parallel but these rules -allow for that possibility. - -The token field in the message header is part of a tuple that is unique during -a request to response interval. +\drivernormative{\paragraph}{Message Correlation (Driver)}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Correlation / Driver} \begin{itemize} - \item Message tuple: ( \field{dev_num}, \field{token} ). + \item A driver MUST assign a non-zero \field{token} for each outstanding + request so that the (\field{dev_num}, \field{token}) tuple remains + unique among inflight requests. + \item A driver MUST set \field{token}=0 when sending event (one-way) messages + and MUST ignore any error responses purportedly referencing such events. + \item When processing responses, a driver SHOULD discard any response whose + correlation tuple does not match an outstanding request. \end{itemize} -Rules: +\devicenormative{\paragraph}{Message Correlation (Device)}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Correlation / Device} \begin{itemize} - \item The request originator assigns a non-zero \field{token} for every - request such that the tuple is unique for all inflight requests. - \item Event (one-way) messages MUST set \field{token}=0 - \item A response MUST echo \field{token} and \field{dev_num}. - \item Reception of unknown or already completed correlation tuples - SHOULD result in discarding the response without further protocol - action. + \item A device MUST echo the \field{token} and \field{dev_num} from the + corresponding request when generating a response. + \item A device MUST set \field{token}=0 when generating event (one-way) + messages and MUST NOT send error responses referencing those events. + \item A device SHOULD discard responses from the other side that reference a + correlation tuple that is unknown or already completed. \end{itemize} \subsection{Device Discovery}\label{sec:Virtio Transport Options / Virtio Over Messages / Device Discovery} From 6a1f55012b2634238eb9cc372f8f352b9e6b405d Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Thu, 20 Nov 2025 12:49:35 +0100 Subject: [PATCH 20/53] virtio-msg: convert device discovery to normative Signed-off-by: Bertrand Marquis --- transport-msg.tex | 30 ++++++++++++++++-------------- 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index d458a11..50a71e5 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -535,23 +535,25 @@ \subsection{Device Discovery}\label{sec:Virtio Transport Options / Virtio Over M hypervisor/firmware interfaces. The following informative text describes typical flows; the normative obligations follow. -Bus implementations MAY discover their devices in various ways: +Bus implementations discover their devices through a mix of platform data, +hypervisor-provided enumeration, or message-based queries such as +\busref{GET_DEVICES}. This specification defines \busref{GET_DEVICES} for +environments that prefer message-driven enumeration, but it does not require +its use when equivalent information is already known out-of-band. + +\busnormative{\paragraph}{Device Discovery (Bus)}{Virtio Transport Options / Virtio Over Messages / Device Discovery / Bus} \begin{itemize} - \item By parsing platform data such as a device tree or ACPI tables, - \item By receiving enumeration data from a hypervisor or firmware, - \item By using \busref{GET_DEVICES} messages - to query which device numbers are present on this bus instance. + \item A bus implementation MUST ensure that every device number it exposes to + the driver has been validated via either platform data or a successful + query such as \busref{GET_DEVICES}. + \item Once a device number is deemed present, the bus implementation SHOULD + invoke \msgref{GET_DEVICE_INFO} so it can register the device with the + host OS and allow the appropriate virtio driver to bind. + \item If a bus implementation provides an alternative enumeration mechanism + (e.g., ACPI, device tree), it MAY omit \busref{GET_DEVICES} provided the + alternative delivers equivalent information to the driver. \end{itemize} -This specification \emph{defines} \busref{GET_DEVICES} for implementations that -wish to carry out discovery entirely via messages, but it does \textbf{not} -mandate use of this approach. A bus implementation MAY skip -\busref{GET_DEVICES} altogether if it already knows which devices exist (e.g., -via a device tree). In any case, once a bus has established the presence of a -device, it SHOULD call \msgref{GET_DEVICE_INFO} to retrieve the device ID -and vendor ID. The bus can then register the device with the host OS -so the appropriate virtio driver probe routine is invoked. - \subsection{Device Initialization} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Initialization} From 9c8806515ea811ea1165f20bf886c55c6cc5a3c8 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Thu, 20 Nov 2025 15:09:50 +0100 Subject: [PATCH 21/53] virtio-msg: convert flow overview to normative Signed-off-by: Bertrand Marquis --- transport-msg.tex | 58 +++++++++++++++++++++++++++-------------------- 1 file changed, 34 insertions(+), 24 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 50a71e5..68087db 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -567,32 +567,42 @@ \subsubsection{Initialization Flow Overview} A typical device initialization flow includes: \begin{enumerate} - \item \textbf{Obtain Device Information:} - The driver queries the device's Device ID, vendor ID, feature block count, - configuration size, and other static parameters of the device using - \msgref{GET_DEVICE_INFO}. - \item \textbf{Negotiate Features:} - The driver retrieves the device's feature bits (\msgref{GET_DEVICE_FEATURES}), - determines which features it wants to enable, and writes the desired set - with (\msgref{SET_DRIVER_FEATURES}). It then attempts to set the - FEATURES_OK bit in the device status (\msgref{SET_DEVICE_STATUS}) and - verifies that it is set in the return device status. - \item \textbf{Initialize Configuration Space:} - The driver MAY read (\msgref{GET_CONFIG}) or modify (\msgref{SET_CONFIG}) - configuration data, using the device's \emph{Configuration Generation Count} - to prevent race conditions. - \item \textbf{Set Up Virtqueues:} - The driver configures each virtqueue (e.g., number of descriptors, base - addresses) via \msgref{SET_VQUEUE} and verifies each queue's readiness - (\msgref{GET_VQUEUE}). - \item \textbf{Set Device Status:} - The driver updates the device's status with \msgref{SET_DEVICE_STATUS} to - indicate initialization progress (e.g., from "reset" to "acknowledge," - "driver," or "driver OK," following Virtio conventions). + \item \textbf{Obtain Device Information:} + Query static parameters with \msgref{GET_DEVICE_INFO}. + \item \textbf{Negotiate Features:} + Read feature blocks via \msgref{GET_DEVICE_FEATURES}, decide which to + enable, and write them back with \msgref{SET_DRIVER_FEATURES} before + updating the device status. + \item \textbf{Initialize Configuration Space:} + Read or write configuration data with + \msgref{GET_CONFIG}/\msgref{SET_CONFIG}, guarding updates with the + configuration generation count. + \item \textbf{Set Up Virtqueues:} + Configure each virtqueue via \msgref{SET_VQUEUE} and verify the settings + with \msgref{GET_VQUEUE}. + \item \textbf{Set Device Status:} + Use \msgref{SET_DEVICE_STATUS} to drive the device through the standard + virtio status states. \end{enumerate} -This sequence MAY vary slightly depending on the device's requirements, but it -serves as a common baseline for virtio-msg transport implementations. +The exact order may vary slightly across implementations, but these steps form +the baseline for virtio-msg initialization. + +\drivernormative{\paragraph}{Initialization Flow (Driver)}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Overview / Driver} +\begin{itemize} + \item A driver MUST issue \msgref{GET_DEVICE_INFO} before attempting feature + negotiation or queue setup. + \item A driver MUST complete feature negotiation via + \msgref{GET_DEVICE_FEATURES}/\msgref{SET_DRIVER_FEATURES} + and confirm the FEATURES\_OK state via \msgref{SET_DEVICE_STATUS} before + enabling virtqueues. + \item A driver MUST configure each virtqueue via \msgref{SET_VQUEUE} and + confirm its parameters (e.g., with \msgref{GET_VQUEUE}) before marking + the queue ready for I/O. + \item A driver MUST drive the device status transitions using + \msgref{SET_DEVICE_STATUS}, ensuring the device reaches DRIVER\_OK + before issuing normal I/O. +\end{itemize} \subsubsection{Device Information} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Information} From 3a942a14be34d544bc82bed04ae9724922c40984 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Thu, 20 Nov 2025 15:11:00 +0100 Subject: [PATCH 22/53] virtio-msg: convert device information to normative Signed-off-by: Bertrand Marquis --- transport-msg.tex | 39 ++++++++++++++------------------------- 1 file changed, 14 insertions(+), 25 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 68087db..23eb100 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -607,34 +607,23 @@ \subsubsection{Initialization Flow Overview} \subsubsection{Device Information} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Information} -Once the bus or driver knows a device number is present, it SHOULD send a -\msgref{GET_DEVICE_INFO} to retrieve: - +Once a device number is confirmed, the driver uses \msgref{GET_DEVICE_INFO} to +retrieve static identification data (device ID, vendor ID), the number of +feature bits, configuration space size, maximum virtqueues, shared memory +segments, and any admin virtqueue details. This information determines which +virtio driver should bind to the device, how many feature blocks to query, and +how much configuration space is valid. + +\drivernormative{\paragraph}{Device Information (Driver)}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Information / Driver} \begin{itemize} - \item \textbf{Device ID}: Identifies the type of Virtio device (e.g., network, - block, console). - \item \textbf{Vendor ID}: Identifies the vendor or implementation source. - \item \textbf{Number of Feature Bits}: Indicates how many bits (organized in - 32-bit blocks) the device uses for feature negotiation. - \item \textbf{Configuration Size}: The total size (in bytes) of the device's - configuration space. - \item \textbf{Number of virtqueues}: The maximum number of virtqueues the - device supports. - \item \textbf{Number of SHM segments}: The number of device owned - shared memory segments this device has. - \item \textbf{Admin virtqueue starting index}: The virtqueue index for the - first admin virtqueue supported by the device. - \item \textbf{Admin virtqueue count}: The number of admin virtqueues - supported by the device. + \item A driver MUST issue \msgref{GET_DEVICE_INFO} before attempting feature + negotiation or queue setup so it can discover the device ID, vendor ID, + feature count, configuration size, and virtqueue limits. + \item A driver MUST use the configuration size reported via + \msgref{GET_DEVICE_INFO} to bound any offsets and lengths supplied in + \msgref{GET_CONFIG} and \msgref{SET_CONFIG} requests. \end{itemize} -Armed with these details, the driver knows how many feature blocks to query, -what portion of the configuration space is valid, and which OS-level virtio -driver might bind to this device based on the Device ID. - -It also knows of any device owned shared memory segments and any admin -virtqueues supported by the device. - \subsubsection{Feature Negotiation} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Features} From 891388597eb9fe27983874981fb24e456e256a0e Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Thu, 20 Nov 2025 15:11:47 +0100 Subject: [PATCH 23/53] virtio-msg: convert feature negotiation to normative Signed-off-by: Bertrand Marquis --- transport-msg.tex | 43 +++++++++++++++++++++++++++---------------- 1 file changed, 27 insertions(+), 16 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 23eb100..b62f044 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -627,22 +627,33 @@ \subsubsection{Device Information} \subsubsection{Feature Negotiation} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Features} -The driver reads the device's available features in \textbf{blocks of 32 bits} -using \msgref{GET_DEVICE_FEATURES}, supplying a \emph{block index} and -\emph{number of blocks} to retrieve. The device responds with the feature bits -in that range, filling any out-of-range blocks with zero. - -The driver then determines which features it can or wants to enable. Enabling a -feature requires the driver to set the corresponding bit(s) and send -them back to the device with \msgref{SET_DRIVER_FEATURES}. Once the driver has -set all desired features it tries to set the FEATURES_OK bit in the device status -via the \msgref{SET_DEVICE_STATUS} message. The device MAY accept or reject the -selected features by returning the new device status with the FEATURES_OK bit -set (accepted) or cleared (rejected). - -If the driver requests blocks beyond the number of feature bits the device -exposes, the device MUST respond with all zeros for the unsupported -features. +Drivers read available features in 32-bit blocks using +\msgref{GET_DEVICE_FEATURES}; the device returns the requested bitfields, +padding with zeros for any out-of-range blocks. To enable selected features, the +driver writes them back with \msgref{SET_DRIVER_FEATURES} and then updates the +device status via \msgref{SET_DEVICE_STATUS}, checking whether the FEATURES\_OK +bit remains set. + +\drivernormative{\paragraph}{Feature Negotiation (Driver)}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Features / Driver} +\begin{itemize} + \item A driver MUST use \msgref{GET_DEVICE_FEATURES} to discover the feature + bits offered by the device and MUST write back only the features it + intends to enable via \msgref{SET_DRIVER_FEATURES}. + \item After writing the desired features, the driver MUST attempt to set the + FEATURES\_OK bit using \msgref{SET_DEVICE_STATUS} and MUST check the + returned status to ensure the device accepted the set. +\end{itemize} + +\devicenormative{\paragraph}{Feature Negotiation (Device)}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Features / Device} +\begin{itemize} + \item When handling \msgref{GET_DEVICE_FEATURES}, a device MUST return zero + for any requested bits that fall outside the number of feature bits it + implements. + \item After receiving \msgref{SET_DRIVER_FEATURES}, a device MUST update its + internal feature mask to match the acknowledged set and MUST reflect + acceptance or rejection by leaving the FEATURES\_OK bit set or clearing + it in the status returned by \msgref{SET_DEVICE_STATUS}. +\end{itemize} \subsubsection{Device Configuration} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Configuration} From 3646c297f4ce1adc3d129de55a3a8ea409ab47fd Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Thu, 20 Nov 2025 15:12:55 +0100 Subject: [PATCH 24/53] virtio-msg: switch device configuration to normative Signed-off-by: Bertrand Marquis --- transport-msg.tex | 40 +++++++++++++++++++--------------------- 1 file changed, 19 insertions(+), 21 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index b62f044..e567894 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -658,34 +658,32 @@ \subsubsection{Feature Negotiation} \subsubsection{Device Configuration} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Configuration} -\paragraph{Reading Configuration} +Drivers use \msgref{GET_CONFIG} to read portions of the configuration space by +supplying an offset and length; the device returns the requested data plus the +current configuration generation count. Writing is performed via +\msgref{SET_CONFIG}, which carries the same offset/length along with the +driver's notion of the generation count and the new data. -The driver can read portions of the device's configuration space using -\msgref{GET_CONFIG}. It supplies: +\drivernormative{\paragraph}{Device Configuration (Driver)}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Configuration / Driver} \begin{itemize} - \item \textbf{Offset}: The byte offset from the start of the configuration - space, - \item \textbf{Number of bytes}: How many bytes to retrieve. + \item A driver MUST ensure that the offset and length in each + \msgref{GET_CONFIG} or \msgref{SET_CONFIG} request stay within the + configuration size reported by \msgref{GET_DEVICE_INFO}. + \item A driver MUST include its most recently observed configuration + generation count in a \msgref{SET_CONFIG} request and SHOULD re-read the + configuration (via \msgref{GET_CONFIG}) if the request is rejected for a + generation mismatch. \end{itemize} -The device returns the requested data along with the current \emph{Configuration -Generation Count}, which changes each time the device updates its configuration -internally. -\paragraph{Writing Configuration} - -To write a portion of the configuration space, the driver uses -\msgref{SET_CONFIG}, providing: +\devicenormative{\paragraph}{Device Configuration (Device)}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Configuration / Device} \begin{itemize} - \item \textbf{Offset} and \textbf{Number of bytes}, - \item \textbf{Configuration generation count} as read earlier, - \item The \textbf{new configuration data} to be written. + \item A device MUST reject a \msgref{SET_CONFIG} request whose generation + count does not match its current value and MUST indicate the rejection + in the response. + \item A device MUST return the current configuration generation count + alongside any data returned via \msgref{GET_CONFIG}. \end{itemize} -If the generation count does not match the device's current value, the device -MUST reject the update as defined in the \msgref{SET_CONFIG} response. -The driver SHOULD then read the updated configuration space and -reattempt if necessary. - \subsubsection{Virtqueue Configuration} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Initialization / Virtqueue Configuration} From 5ee179dd4eb9813cb96b835850d8489d68fc966f Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Thu, 20 Nov 2025 15:13:35 +0100 Subject: [PATCH 25/53] virtio-msg: Switch virqueue config to normative Signed-off-by: Bertrand Marquis --- transport-msg.tex | 45 +++++++++++++++++++++++++-------------------- 1 file changed, 25 insertions(+), 20 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index e567894..74b9859 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -687,29 +687,34 @@ \subsubsection{Device Configuration} \subsubsection{Virtqueue Configuration} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Initialization / Virtqueue Configuration} -Virtqueues are configured via a set of transport messages: - +Drivers query virtqueue parameters with \msgref{GET_VQUEUE}, configure them via +\msgref{SET_VQUEUE}, and optionally reset them using \msgref{RESET_VQUEUE} (if +VIRTIO\_F\_RING\_RESET is negotiated). Each queue is typically configured by +reading its maximum size, provisioning descriptor/available/used buffers, and +then calling \msgref{SET_VQUEUE} with the chosen size and guest-physical +addresses. + +\drivernormative{\paragraph}{Virtqueue Configuration (Driver)}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Virtqueue Configuration / Driver} \begin{itemize} - \item \msgref{GET_VQUEUE} obtains information about a specific virtqueue, - including its maximum size (e.g., number of descriptors) and current - configuration if already set. - \item \msgref{SET_VQUEUE} sets or updates the virtqueue parameters (e.g., - queue size, descriptor area addresses, driver address, device address). - \item \msgref{RESET_VQUEUE} disables and resets the virtqueue, freeing its - resources on the device side. The use of this message is dependent on the - VIRTIO_F_RING_RESET feature being negotiated. + \item A driver MUST use \msgref{GET_VQUEUE} to determine the maximum queue + size and confirm that a queue is inactive before programming it. + \item A driver MUST ensure the queue size provided in \msgref{SET_VQUEUE} does + not exceed the maximum reported by the device and MUST supply valid + descriptor/driver/device addresses before enabling the queue. + \item If VIRTIO\_F\_RING\_RESET has been negotiated and a queue requires + reinitialization, the driver SHOULD use \msgref{RESET_VQUEUE} before + reprogramming it. \end{itemize} -A typical approach is: -\begin{enumerate} - \item \textbf{GET\_VQUEUE}: Determine maximum size and confirm that the queue - is inactive or empty. - \item \textbf{SET\_VQUEUE}: Specify the number of descriptors (not exceeding - the maximum) and the addresses for the descriptor table, driver area, - and device area. -\end{enumerate} - -The driver repeats these steps for each queue the device supports. +\devicenormative{\paragraph}{Virtqueue Configuration (Device)}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Virtqueue Configuration / Device} +\begin{itemize} + \item A device MUST report accurate maximum queue sizes in \msgref{GET_VQUEUE} + and MUST persist the parameters supplied via \msgref{SET_VQUEUE} (size, + descriptor, driver, and device addresses). + \item When \msgref{RESET_VQUEUE} is issued (and VIRTIO\_F\_RING\_RESET is + negotiated), the device MUST quiesce the queue, release any resources + associated with it, and allow the driver to reconfigure it. +\end{itemize} \subsubsection{Status Information} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Initialization / Status Information} From 59ac96c901dde96dae064c64973aedb42fa23070 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Thu, 20 Nov 2025 15:14:09 +0100 Subject: [PATCH 26/53] virtio-msg: switch status information to normative Signed-off-by: Bertrand Marquis --- transport-msg.tex | 31 ++++++++++++++++++++++++------- 1 file changed, 24 insertions(+), 7 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 74b9859..07ac04e 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -719,13 +719,30 @@ \subsubsection{Virtqueue Configuration} \subsubsection{Status Information} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Initialization / Status Information} -During initialization, the driver MAY query the device's status via -\msgref{GET_DEVICE_STATUS} to check for errors or to see if the device is ready -for feature negotiation or configuration changes. To advance or reset the -device's state, the driver sends \msgref{SET_DEVICE_STATUS} with the desired -status bits (e.g., "ACKNOWLEDGE," "DRIVER," "DRIVER OK"). Setting the device's -status to 0 triggers a device reset, invalidating configuration and -virtqueues. +Drivers query the device status via \msgref{GET_DEVICE_STATUS} to observe +progress or detect errors, and they drive the Virtio status transitions via +\msgref{SET_DEVICE_STATUS}. Writing zero to the status field resets the device, +invalidating any configuration or virtqueue state. + +\drivernormative{\paragraph}{Status Handling (Driver)}{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 (Device)}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Status Information / Device} +\begin{itemize} + \item Upon receiving a \msgref{SET_DEVICE_STATUS} write of 0, a device MUST + reset its internal state, invalidate existing configuration and + virtqueue settings, and present the status field as 0. + \item A device MUST report its current status accurately via + \msgref{GET_DEVICE_STATUS}, including whether the FEATURES\_OK bit has + been accepted or cleared. +\end{itemize} \subsubsection{Finalizing Initialization} From f87efe21e0494676feef4ab3d6ffde5884dddf6e Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Thu, 20 Nov 2025 15:14:29 +0100 Subject: [PATCH 27/53] virtio-msg: switch finalize init to normative Signed-off-by: Bertrand Marquis --- transport-msg.tex | 27 +++++++++++++++++++++++---- 1 file changed, 23 insertions(+), 4 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 07ac04e..4fc63af 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -746,10 +746,29 @@ \subsubsection{Status Information} \subsubsection{Finalizing Initialization} -Once all virtqueues are configured and any required features have been enabled, -the driver typically sets the final status bits (e.g., "DRIVER OK") via -\msgref{SET_DEVICE_STATUS}. At this point, the device is considered fully -initialized, and normal I/O operations can begin using virtio queues. +After configuring virtqueues and agreeing on features, the driver transitions +the device to DRIVER\_OK (and any other required status bits) via +\msgref{SET_DEVICE_STATUS}. At that point, the device is considered ready for +normal virtqueue I/O. + +\drivernormative{\paragraph}{Final Status (Driver)}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Finalizing Initialization / Driver} +\begin{itemize} + \item A driver MUST set DRIVER\_OK via \msgref{SET_DEVICE_STATUS} only after + it has completed feature negotiation and initialized all required + virtqueues. + \item A driver MUST NOT queue normal I/O until the device reports a status + that includes DRIVER\_OK. + \item A driver MUST NOT supply buffers or send driver notifications for a + virtqueue until that queue has been configured via \msgref{SET_VQUEUE}. +\end{itemize} + +\devicenormative{\paragraph}{Final Status (Device)}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Finalizing Initialization / Device} +\begin{itemize} + \item A device MUST NOT process normal virtqueue I/O until the driver has set + DRIVER\_OK. + \item Once DRIVER\_OK is set, the device MUST begin processing virtqueue + requests subject to the negotiated features and queue configurations. +\end{itemize} \subsection{Device Operation} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Operation} From 983b7763b5fd7d9f6f085bb76faad7d5a80d2d2e Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Thu, 20 Nov 2025 15:24:27 +0100 Subject: [PATCH 28/53] virtio-msg: convert driver notifications to normative Signed-off-by: Bertrand Marquis --- transport-msg.tex | 42 +++++++++++++++++++++--------------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 4fc63af..b09fe8d 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -783,28 +783,28 @@ \subsection{Device Operation} \subsubsection{Driver Notifications} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / Driver Notifications} -After setting up one or more virtqueues, the driver MUST send notifications -to signal that new buffers are available for processing. The virtio-msg transport -defines the message, \msgref{EVENT_AVAIL}, that the driver will use to -notify the device of pending buffers. - -The driver side bus MAY convert them to some form of -out-of-band (OoB) notification. If not using OoB notifications, the driver -side bus SHOULD send the messages via the normal message channel. -As a final option, the bus MAY discard the messages but only if it knows -that the device will poll the virtqueues directly. - -\paragraph{EVENT\_AVAIL Usage} +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. + +\drivernormative{\paragraph}{Driver Notifications (Driver)}{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 (Bus)}{Virtio Transport Options / Virtio Over Messages / Device Operation / Driver Notifications / Bus} \begin{itemize} - \item \textbf{Virtqueue Index}: Identifies which queue has new buffers. - \item \textbf{Next Offset and Wrap}: If the VIRTIO_F_NOTIFICATION_DATA feature - has been negotiated, the driver MUST sets these fields to - indicate the next descriptor offset and wrap state - so the device can jump directly to the updated buffers. - If this features has not been negotiated these fields MUST be 0. - \item \textbf{Response}: The \msgref{EVENT_AVAIL} message does not have a - direct response, but the device will subsequently process available - buffers and eventually notify the driver when they are used. + \item A bus implementation MAY convert \msgref{EVENT_AVAIL} into an + out-of-band notification but, if it does not, it MUST relay the message + over the virtio-msg channel. + \item A bus implementation MUST NOT drop \msgref{EVENT_AVAIL} unless it has + arranged for the device to detect new buffers through polling or an + equivalent mechanism. \end{itemize} \subsubsection{Device Notifications} From 299d5e38f0b3ab5e578f1cb877c4bd23005e8373 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Thu, 20 Nov 2025 15:27:43 +0100 Subject: [PATCH 29/53] virtio-msg: switch device notifications to normative Signed-off-by: Bertrand Marquis --- transport-msg.tex | 63 +++++++++++++++++++++++------------------------ 1 file changed, 31 insertions(+), 32 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index b09fe8d..34fdf5f 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -810,45 +810,44 @@ \subsubsection{Driver Notifications} \subsubsection{Device Notifications} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / Device Notifications} -During normal operation, the driver side bus MUST send notifications to -the driver about configuration changes, device status changes, or the -completion of buffers in virtqueues using the messages described below. -These notifications MAY be the result of: +\msgref{EVENT_CONFIG} and \msgref{EVENT_USED} provide asynchronous notifications +from the device (or device-side bus) to the driver. The bus may forward these +messages in-band or synthesize them based on other signals such as interrupts +or polling. +\devicenormative{\paragraph}{Device Notifications (Device)}{Virtio Transport Options / Virtio Over Messages / Device Operation / Device Notifications / Device} \begin{itemize} - \item The same messages received in-band on the message channel from the - device side bus. - \item Manufactured by the driver side bus based on reception of an - out-of-band (OoB) notification from the device side. Example OoB - notifications include things like specific MSIX or other IRQ signals. - \item Manufactured by the device side bus periodically (polling). - This option SHOULD be reserved only for situation where nothing else - will work. - \end{itemize} - -\paragraph{EVENT\_CONFIG} -\begin{itemize} - \item Sent by the device when a configuration field or device status changes - at runtime. - \item Includes the new \emph{Configuration Generation Count}, current device - status, and optionally the updated portion of the configuration data. - \item If the data is not included, the driver SHOULD issue - \msgref{GET_CONFIG} to discover the updated configuration. + \item A device (or device-side bus) MUST send \msgref{EVENT_CONFIG} whenever + it makes a configuration change or status update that becomes visible to + the driver. The message MUST include the new configuration generation + count and MAY include the updated configuration data. + \item If the configuration data is omitted from \msgref{EVENT_CONFIG}, the + device SHOULD include the relevant offsets/lengths so the driver can + re-fetch the data via \msgref{GET_CONFIG}. + \item A device SHOULD send \msgref{EVENT_USED} to inform the driver when + buffers on a virtqueue have been consumed, unless the device relies on + an alternative, agreed-upon completion mechanism. \end{itemize} -\paragraph{EVENT\_USED} +\drivernormative{\paragraph}{Device Notifications (Driver)}{Virtio Transport Options / Virtio Over Messages / Device Operation / Device Notifications / Driver} \begin{itemize} - \item Signifies that one or more buffers in a specific virtqueue have been - processed or consumed by the device and the buffer has been added to the - used ring of the virtqueue. - \item The driver uses normal virtio methods (e.g., reading the "used" ring) to - identify which buffers are complete. - \item If a device does not support sending \msgref{EVENT_USED}, the driver - MAY rely on standard virtqueue polling mechanisms to detect - completion. + \item Upon receiving \msgref{EVENT_CONFIG}, a driver SHOULD update its view of + the configuration using the provided data (or by issuing + \msgref{GET_CONFIG} if necessary) before resuming normal I/O. + \item Upon receiving \msgref{EVENT_USED}, a driver MUST examine the indicated + virtqueue (for example, by reading the used ring) to reclaim completed + buffers. \end{itemize} -These messages enable asynchronous updates from the device. +\busnormative{\paragraph}{Device Notifications (Bus)}{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. +\end{itemize} \subsubsection{Configuration Changes During Operation} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / ConfigUpdates} From da771b30d58345b85ffc33544d083aa6fbf6a34f Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Thu, 20 Nov 2025 15:29:37 +0100 Subject: [PATCH 30/53] virtio-msg: convert config changes to normative Signed-off-by: Bertrand Marquis --- transport-msg.tex | 26 +++++++++++++++++++++----- 1 file changed, 21 insertions(+), 5 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 34fdf5f..cd513c4 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -852,11 +852,27 @@ \subsubsection{Device Notifications} \subsubsection{Configuration Changes During Operation} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / ConfigUpdates} -The driver MAY issue new \msgref{SET_CONFIG} -messages after initialization if device configuration needs to be -changed at runtime. The device MAY also make configuration changes at -runtime and MUST signal those changes with \msgref{EVENT_CONFIG} -messages. +Drivers may update configuration fields at runtime using \msgref{SET_CONFIG} +when features such as device modes or limits need to change. Devices can also +update configuration data autonomously but must signal those changes via +\msgref{EVENT_CONFIG}. + +\drivernormative{\paragraph}{Runtime Configuration (Driver)}{Virtio Transport Options / Virtio Over Messages / Device Operation / ConfigUpdates / 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 (Device)}{Virtio Transport Options / Virtio Over Messages / Device Operation / ConfigUpdates / Device} +\begin{itemize} + \item If a device updates its configuration after initialization, it MUST send + \msgref{EVENT_CONFIG} to inform the driver of the change and provide the + new configuration generation count. +\end{itemize} \subsubsection{Virtqueue Changes During Operation} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / VQueueUpdates} From a7efbcafa1af80caac0a0095422981f1ccb13862 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Thu, 20 Nov 2025 15:31:46 +0100 Subject: [PATCH 31/53] virtio-msg: convert virtqueue change to normative Signed-off-by: Bertrand Marquis --- transport-msg.tex | 25 ++++++++++++++++++++++--- 1 file changed, 22 insertions(+), 3 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index cd513c4..a24dca8 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -877,9 +877,28 @@ \subsubsection{Configuration Changes During Operation} \subsubsection{Virtqueue Changes During Operation} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / VQueueUpdates} -The driver MAY issue new \msgref{SET_VQUEUE} for virtqueues that have not -yet be setup. If the VIRTIO_F_RING_RESET feature has been negotiated, -individual virtqueues can be reset and then optionally re-configured. +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 (Driver)}{Virtio Transport Options / Virtio Over Messages / Device Operation / VQueueUpdates / 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 (Device)}{Virtio Transport Options / Virtio Over Messages / Device Operation / VQueueUpdates / Device} +\begin{itemize} + \item A device MUST honor \msgref{SET_VQUEUE} requests issued after + initialization and update the queue parameters accordingly. + \item When \msgref{RESET_VQUEUE} is received (and VIRTIO\_F\_RING\_RESET is + negotiated), the device MUST quiesce the queue and allow the driver to + reconfigure it without processing stale data. +\end{itemize} \subsubsection{Device Reset and Shutdown} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / Reset} From d08bd5c4679080e6e0b01f1b223b66e07dbe845f Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Thu, 20 Nov 2025 15:33:50 +0100 Subject: [PATCH 32/53] virtio-msg: convert reset and shutdown to normative Signed-off-by: Bertrand Marquis --- transport-msg.tex | 39 +++++++++++++++++++++++++-------------- 1 file changed, 25 insertions(+), 14 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index a24dca8..ae4153f 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -903,20 +903,31 @@ \subsubsection{Virtqueue Changes During Operation} \subsubsection{Device Reset and Shutdown} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / Reset} -The driver MAY reset or shut down a device at any time by writing a status -of 0 via \msgref{SET_DEVICE_STATUS}. This forces the device to discard its state -and any pending operations on virtqueues. Once a device is reset, the driver -MAY reinitialize the device (see -\ref{sec:Virtio Transport Options / Virtio Over Messages / Device Initialization}) -if it wishes to use the device again. - -\paragraph{Device Side Initiated Reset} -In some circumstances, the device MAY also trigger a reset if it -encounters an unrecoverable error. This can be signaled to the driver by sending -an \msgref{EVENT_CONFIG} with a \emph{device status} with the DEVICE_NEEDS_RESET -bit set. The driver SHOULD reset the device by writing a status of 0 -via the \msgref{SET_DEVICE_STATUS} message. The driver MAY reinitialize -the device if it wishes to use the device again. +Drivers reset a device by writing 0 to the status field via \msgref{SET_DEVICE_STATUS}, +which forces the device to discard pending operations and return to the initial state. +A device may also signal that a reset is required by sending \msgref{EVENT_CONFIG} +with the DEVICE\_NEEDS\_RESET bit set. + +\drivernormative{\paragraph}{Reset and Shutdown (Driver)}{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 (Device)}{Virtio Transport Options / Virtio Over Messages / Device Operation / Reset / Device} +\begin{itemize} + \item Upon receiving a \msgref{SET_DEVICE_STATUS} write of 0, a device MUST + reset its internal state, discard pending virtqueue operations, and + present the status field as 0. + \item If the device encounters an unrecoverable error that requires driver + intervention, it SHOULD signal DEVICE\_NEEDS\_RESET (such as via + \msgref{EVENT_CONFIG}) so the driver can initiate a reset. +\end{itemize} \subsubsection{Hotplug and Removal} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / Hotplug and Removal} From 1002f30a3957cd196102c7d814cb2002a7329d5f Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Thu, 20 Nov 2025 15:35:28 +0100 Subject: [PATCH 33/53] virtio-msg: convert hotplug and removal to normative Signed-off-by: Bertrand Marquis --- transport-msg.tex | 32 +++++++++++++++----------------- 1 file changed, 15 insertions(+), 17 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index ae4153f..f4a48ad 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -932,23 +932,21 @@ \subsubsection{Device Reset and Shutdown} \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 at runtime, it -MAY announce these events using messages: -\begin{itemize} - \item \busref{EVENT_DEVICE} with state DEVICE_BUS_STATE_READY for a newly - available device, - \item \busref{EVENT_DEVICE} with state DEVICE_BUS_STATE_REMOVED for a device - that is no longer accessible. -\end{itemize} - -Alternatively, the bus MAY rely on external signals (e.g., an event from -the platform or hypervisor) and inform the OS of hotplug changes out-of-band. -This specification \emph{defines} \busref{EVENT_DEVICE} -for implementations that prefer a fully message-based -approach but does not require their use. In any scenario, once notified that a -device has appeared, the bus SHOULD query the device (e.g., via -\msgref{GET_DEVICE_INFO}) and register it with the OS. If a device is -removed, the bus SHOULD prompt the OS to unbind and release resources. +If the bus supports dynamic addition or removal of devices, it can advertise +those changes with \busref{EVENT_DEVICE} (READY or REMOVED). Some platforms may +instead rely on external signals such as ACPI, device tree updates, or +hypervisor events; virtio-msg does not mandate a specific mechanism. + +\busnormative{\paragraph}{Hotplug and Removal (Bus)}{Virtio Transport Options / Virtio Over Messages / Device Operation / Hotplug and Removal / Bus} +\begin{itemize} + \item A bus implementation that uses \busref{EVENT_DEVICE} MUST send the READY + event when a device becomes accessible and the REMOVED event when it is + no longer available. + \item Regardless of how hotplug information is delivered, once a new device is + reported the bus SHOULD query it (e.g., via \msgref{GET_DEVICE_INFO}) + and register it with the host OS. When a device is removed, the bus + SHOULD prompt the OS to quiesce and release the associated driver. +\end{itemize} \subsection{Transport Messages}\label{sec:Virtio Transport Options / Virtio Over Messages / Transport Messages} From 2060d08290fec526ed3abe7abda6a4de8cc2d67b Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Thu, 20 Nov 2025 15:51:08 +0100 Subject: [PATCH 34/53] virtio-msg: convert transport messages intro to normative Also convert the overview Signed-off-by: Bertrand Marquis --- transport-msg.tex | 60 +++++++++++++++++++++++------------------------ 1 file changed, 29 insertions(+), 31 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index f4a48ad..d3c3acd 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -950,24 +950,20 @@ \subsubsection{Hotplug and Removal} \subsection{Transport Messages}\label{sec:Virtio Transport Options / Virtio Over Messages / Transport Messages} -Transport messages are used to configure and operate individual virtio devices. -Unlike bus messages (which handle device enumeration, hotplug, or global resets), -transport messages MUST be implemented by any virtio-msg device and -driver pair to enable standard virtio functionality (feature negotiation, -configuration, virtqueues, etc.). The subsections below describe each message -and clarify its required fields, typical usage patterns, and possible responses. +Transport messages configure and operate virtio devices once they have been +discovered. Unlike bus messages (which cover enumeration or hotplug), transport +messages focus on feature negotiation, configuration access, virtqueue setup, +and runtime notifications. The subsections below describe each message and how +it is used in the virtio-msg transport. \subsubsection{Overview} \label{sec:Virtio Transport Options / Virtio Over Messages / Transport Messages / Overview} -A driver typically sends these messages to a known device number, -and the virtio-msg device responds or notifies as appropriate. The -bus \emph{forwards} these messages but does not interpret or modify them beyond -basic checks (e.g., ensuring the size does not exceed the maximum size -supported, verifying the target device number exists). - -Most transport messages adopt a \emph{request/response} pattern, but some are -unidirectional (e.g., asynchronous notifications). +Drivers send transport messages to a specific device number, and the virtio-msg +device replies or emits events accordingly. The bus simply forwards these +messages after enforcing generic checks such as maximum size or verifying that +the target device exists. Most transport messages are request/response pairs, +with events reserved for asynchronous notifications. \paragraph{Messages IDs and issuers} @@ -1010,30 +1006,32 @@ \subsubsection{Overview} \hline \end{tabular} -Transport message IDs 0x00 to 0x3F are used for messages that require a response -and IDs 0x40 to 0x7F are used for event messages. Transport message IDs 0x80 -and above are reserved by this specification. +IDs 0x00–0x3F are reserved for request/response messages and 0x40–0x7F for +events. IDs 0x80 and above are reserved for future extensions. -\paragraph{Mandatory Transport Messages} -For a virtio-msg device to be fully operational, the following messages -MUST be supported: +\devicenormative{\paragraph}{Core Messages (Device)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / Mandatory / Device} \begin{itemize} - \item \msgref{GET_DEVICE_INFO} - \item \msgref{GET_DEVICE_FEATURES} and \msgref{SET_DRIVER_FEATURES} - \item \msgref{GET_CONFIG} and \msgref{SET_CONFIG} - \item \msgref{GET_DEVICE_STATUS} and \msgref{SET_DEVICE_STATUS} - \item \msgref{GET_VQUEUE}, \msgref{SET_VQUEUE}, and \msgref{RESET_VQUEUE} + \item A device MUST implement \msgref{GET_DEVICE_INFO}, + \msgref{GET_DEVICE_FEATURES}, \msgref{SET_DRIVER_FEATURES}, + \msgref{GET_CONFIG}, \msgref{SET_CONFIG}, \msgref{GET_DEVICE_STATUS}, + \msgref{SET_DEVICE_STATUS}, \msgref{GET_VQUEUE}, \msgref{SET_VQUEUE}, + and \msgref{RESET_VQUEUE}. \end{itemize} -The functionality of the following messages MUST be provided by -in-band messages, out-of-band event notification, or bus implementation based -polling: +\drivernormative{\paragraph}{Core Messages (Driver)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / Mandatory / Driver} \begin{itemize} - \item \msgref{EVENT_AVAIL} - \item \msgref{EVENT_USED} - \item \msgref{EVENT_CONFIG} + \item A driver MUST support sending and interpreting the messages listed + above in order to initialize and operate a virtio-msg device. \end{itemize} +As described in Sections +\ref{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / Driver Notifications} +and +\ref{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / Device Notifications}, +runtime notifications (\msgref{EVENT_AVAIL}, \msgref{EVENT_USED}, and +\msgref{EVENT_CONFIG}) may be delivered in-band or via equivalent out-of-band +mechanisms. + \msgdef{GET_DEVICE_INFO} This message is sent by the virtio-msg transport driver and requires a From 770f3404493240fa0cffad57df8a396a87603e18 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Thu, 20 Nov 2025 15:51:54 +0100 Subject: [PATCH 35/53] virtio-msg: convert GET_DEVICE_INFO to normative Signed-off-by: Bertrand Marquis --- transport-msg.tex | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index d3c3acd..35d5214 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -1034,8 +1034,9 @@ \subsubsection{Overview} \msgdef{GET_DEVICE_INFO} -This message is sent by the virtio-msg transport driver and requires a -response from the device. +The driver issues \msgref{GET_DEVICE_INFO} to discover static identification +data and limits for a device. It is the only transport message permitted before +the device transitions out of the inactive state. \begin{tabular}{|l|l|l|l|} \hline @@ -1053,10 +1054,19 @@ \subsubsection{Overview} \hline \end{tabular} -The number of feature bits MUST be a multiple of 32. +\devicenormative{\paragraph}{GET\_DEVICE\_INFO (Device)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_DEVICE_INFO / Device} +\begin{itemize} + \item A device MUST respond to \msgref{GET_DEVICE_INFO} while inactive and + MUST supply consistent values for device ID, vendor ID, feature count (a + multiple of 32 bits), configuration size, and virtqueue limits. +\end{itemize} -This is the only message allowed for an inactive device. If this message queries -an inactive device all fields in the response SHOULD be 0. +\drivernormative{\paragraph}{GET\_DEVICE\_INFO (Driver)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_DEVICE_INFO / Driver} +\begin{itemize} + \item A driver SHOULD treat the response as the authoritative source for + feature count, configuration size, and virtqueue limits before + proceeding with initialization. +\end{itemize} \msgdef{GET_DEVICE_FEATURES} From d17f18f1106a16df25e08796ce8e2d137159caca Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Thu, 20 Nov 2025 15:55:31 +0100 Subject: [PATCH 36/53] virtio-msg: convert get_features to normative Signed-off-by: Bertrand Marquis --- transport-msg.tex | 27 +++++++++++++++++++-------- 1 file changed, 19 insertions(+), 8 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 35d5214..cfaf9d8 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -1070,24 +1070,35 @@ \subsubsection{Overview} \msgdef{GET_DEVICE_FEATURES} -This message is sent by the virtio-msg transport driver and requires a -response from the device. +Drivers retrieve device feature bits in 32-bit blocks via +\msgref{GET_DEVICE_FEATURES}; the response echoes the requested block index and +returns one or more 32-bit values with the feature bits in that range. \begin{tabular}{|l|l|l|l|} \hline Type & Offset & Size (bytes) & Content \\ \hline \hline Request & 0 & 4 & Feature block index \\ -& 4 & 4 & Number of feature blocks \\ + & 4 & 4 & Number of feature blocks \\ \hline -Answer & 0 & 4 & Feature block index \\ -& 4 & 4 & Number of feature blocks \\ -& 8 & ... & Feature data \\ +Answer & 0 & 4 & Feature block index (echoed) \\ + & 4 & 4 & Number of feature blocks (echoed) \\ + & 8 & ... & Feature data (multiples of 32 bits) \\ \hline \end{tabular} -A feature block is a group of 32 bits. The feature data MUST be a -multiple of 4 bytes in length. +\devicenormative{\paragraph}{GET\_DEVICE\_FEATURES (Device)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_DEVICE_FEATURES / Device} +\begin{itemize} + \item A device MUST return zero for any feature bits beyond those it + implements when responding to \msgref{GET_DEVICE_FEATURES}. +\end{itemize} + +\drivernormative{\paragraph}{GET\_DEVICE\_FEATURES (Driver)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_DEVICE_FEATURES / Driver} +\begin{itemize} + \item A driver MUST treat the returned data as 32-bit feature blocks starting + at the requested index, padding with zeros as needed, before deciding + which features to enable. +\end{itemize} \msgdef{SET_DRIVER_FEATURES} From f3633569c6d5d4962615f756d5b0747e9dbfe5ba Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Thu, 20 Nov 2025 15:57:34 +0100 Subject: [PATCH 37/53] virtio-msg: convert set_features to normative Signed-off-by: Bertrand Marquis --- transport-msg.tex | 29 +++++++++++++++++++---------- 1 file changed, 19 insertions(+), 10 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index cfaf9d8..8d861ff 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -1102,27 +1102,36 @@ \subsubsection{Overview} \msgdef{SET_DRIVER_FEATURES} -This message is sent by the virtio-msg transport driver and requires a -response from the device. +Drivers use \msgref{SET_DRIVER_FEATURES} to acknowledge the subset of feature +bits they wish to enable. The payload mirrors \msgref{GET_DEVICE_FEATURES}, +supplying an index, count, and 32-bit feature data for the selected blocks. \begin{tabular}{|l|l|l|l|} \hline Type & Offset & Size (bytes) & Content \\ \hline \hline Request & 0 & 4 & Feature block index \\ -& 4 & 4 & Number of feature blocks \\ -& 8 & ... & Feature data \\ + & 4 & 4 & Number of feature blocks \\ + & 8 & ... & Feature data \\ \hline -Answer & 0 & 0 & no extra data \\ +Answer & 0 & 0 & No additional data \\ \hline \end{tabular} -A feature block is a group of 32 bits. The feature data MUST be a -multiple of 4 bytes in length. +\drivernormative{\paragraph}{SET\_DRIVER\_FEATURES (Driver)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_DRIVER_FEATURES / Driver} +\begin{itemize} + \item A driver MUST set only the feature bits it intends to enable in the + blocks supplied to \msgref{SET_DRIVER_FEATURES}. +\end{itemize} -Note: As defined in \ref{sec:Basic Facilities of a Virtio Device / Feature Bits}, -if the device is not OK with the features set, it MUST not allow -the FEATURES_OK bit in the device status to be set. +\devicenormative{\paragraph}{SET\_DRIVER\_FEATURES (Device)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_DRIVER_FEATURES / Device} +\begin{itemize} + \item After processing \msgref{SET_DRIVER_FEATURES}, a device MUST update its + acknowledged feature set to match the data supplied and MUST report that + set consistently in subsequent \msgref{GET_DEVICE_FEATURES} responses. + If it cannot support the requested set, it SHOULD clear the FEATURES\_OK + bit in the device status. +\end{itemize} \msgdef{GET_CONFIG} From e55a0c3421df8737e110a7e1344fa325c73a3442 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Thu, 20 Nov 2025 16:30:52 +0100 Subject: [PATCH 38/53] virtio-msg: convert get/set config to normative Signed-off-by: Bertrand Marquis --- transport-msg.tex | 65 +++++++++++++++++++++++++++++++++-------------- 1 file changed, 46 insertions(+), 19 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 8d861ff..5dc83f6 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -1135,46 +1135,73 @@ \subsubsection{Overview} \msgdef{GET_CONFIG} -This message is sent by the virtio-msg transport driver and requires a -response from the device. +\msgref{GET_CONFIG} reads a portion of the configuration space. The request +specifies the byte offset and length; the response echoes those values, returns +the data, and includes the current configuration generation count. \begin{tabular}{|l|l|l|l|} \hline Type & Offset & Size (bytes) & Content \\ \hline \hline -Request & 0 & 4 & Configuration offset in bytes \\ -& 4 & 4 & Number of bytes \\ +Request & 0 & 4 & Configuration offset \\ + & 4 & 4 & Number of bytes \\ \hline -Answer & 0 & 4 & Configuration generation count \\ -& 4 & 4 & Configuration offset in bytes \\ \\ -& 8 & 4 & Number of bytes \\ -& 12 & ... & Configuration data \\ +Answer & 0 & 4 & Configuration generation count \\ + & 4 & 4 & Configuration offset (echoed) \\ + & 8 & 4 & Number of bytes (echoed) \\ + & 12 & ... & Configuration data \\ \hline \end{tabular} +\drivernormative{\paragraph}{GET\_CONFIG (Driver)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_CONFIG / Driver} +\begin{itemize} + \item A driver MUST ensure the requested offset and length in \msgref{GET_CONFIG} + stay within the configuration size reported by \msgref{GET_DEVICE_INFO}. +\end{itemize} + +\devicenormative{\paragraph}{GET\_CONFIG (Device)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_CONFIG / Device} +\begin{itemize} + \item A device MUST return the current configuration generation count with + every \msgref{GET_CONFIG} response. +\end{itemize} + \msgdef{SET_CONFIG} -This message is sent by the virtio-msg transport driver and requires a -response from the device. +\msgref{SET_CONFIG} writes a portion of configuration space, supplying the +offset, length, the driver's view of the generation count, and the new data. +The device echoes the offset/length, returns the resulting generation count, +and may mirror the applied data or set the length to zero if the write was +rejected. \begin{tabular}{|l|l|l|l|} \hline Type & Offset & Size (bytes) & Content \\ \hline \hline Request & 0 & 4 & Configuration generation count \\ -& 4 & 4 & Configuration offset in bytes \\ -& 8 & 4 & Number of bytes \\ -& 12 & ... & Configuration data \\ + & 4 & 4 & Configuration offset \\ + & 8 & 4 & Number of bytes \\ + & 12 & ... & Configuration data \\ \hline -Answer & 0 & 4 & New Configuration generation count \\ -& 4 & 4 & Configuration offset in bytes \\ -& 8 & 4 & Number of bytes, or 0 if rejected \\ -& 12 & ... & Configuration data \\ +Answer & 0 & 4 & Updated configuration generation count \\ + & 4 & 4 & Configuration offset (echoed) \\ + & 8 & 4 & Number of bytes applied (0 if rejected) \\ + & 12 & ... & Configuration data (optional) \\ \hline \end{tabular} -See \ref{sec:Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Configuration} -for details about rejection and for new data not equal to written data. +\drivernormative{\paragraph}{SET\_CONFIG (Driver)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_CONFIG / Driver} +\begin{itemize} + \item A driver MUST include its most recent configuration generation count in + each \msgref{SET_CONFIG} request and MUST keep the offset and length + within the reported configuration size. +\end{itemize} + +\devicenormative{\paragraph}{SET\_CONFIG (Device)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_CONFIG / Device} +\begin{itemize} + \item A device MUST reject a \msgref{SET_CONFIG} request if the supplied + generation count does not match its current value and MUST report that + rejection in the response. +\end{itemize} \msgdef{GET_DEVICE_STATUS} From 42b70ab8f5bd10b89e7c58b499e82288d5175546 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Thu, 20 Nov 2025 16:35:47 +0100 Subject: [PATCH 39/53] virtio-msg: convert get/set status to normative Signed-off-by: Bertrand Marquis --- transport-msg.tex | 41 ++++++++++++++++++++++++++++++----------- 1 file changed, 30 insertions(+), 11 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 5dc83f6..8ac8da8 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -1205,8 +1205,9 @@ \subsubsection{Overview} \msgdef{GET_DEVICE_STATUS} -This message is sent by the virtio-msg transport driver and requires a -response from the device. +\msgref{GET_DEVICE_STATUS} reads the current device status (e.g., ACKNOWLEDGE, +DRIVER, DRIVER\_OK, FEATURES\_OK, or DEVICE\_NEEDS\_RESET bits). The request has +no payload; the response returns the 32-bit status value. \begin{tabular}{|l|l|l|l|} \hline @@ -1214,29 +1215,47 @@ \subsubsection{Overview} \hline \hline Request & 0 & 0 & None \\ \hline -Answer & 0 & 4 & Device status \\ +Answer & 0 & 4 & Device status \\ \hline \end{tabular} +\devicenormative{\paragraph}{GET\_DEVICE\_STATUS (Device)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_DEVICE_STATUS / Device} +\begin{itemize} + \item A device MUST report its current status accurately via + \msgref{GET_DEVICE_STATUS}, including whether FEATURES\_OK or + DEVICE\_NEEDS\_RESET are set. +\end{itemize} + \msgdef{SET_DEVICE_STATUS} -This message is sent by the virtio-msg transport driver and requires a -response from the device. +\msgref{SET_DEVICE_STATUS} writes a new device status value. Drivers use it to +progress through the virtio-defined states or to request a reset by writing 0. +The device responds with its resulting status, which may differ (for example, +if it refuses FEATURES\_OK or sets DEVICE\_NEEDS\_RESET). \begin{tabular}{|l|l|l|l|} \hline Type & Offset & Size (bytes) & Content \\ \hline \hline -Request & 0 & 4 & Device status \\ +Request & 0 & 4 & Device status value \\ \hline -Answer & 0 & 4 & New device status \\ +Answer & 0 & 4 & Resulting device status \\ \hline \end{tabular} -The resulting device status is returned and MAY not match the status set. The -device MAY set the DEVICE_NEEDS_RESET bit if it has an issue. The device MAY -refuse to set the FEATURES_OK bit if it cannot operate with the features set -by the driver. +\drivernormative{\paragraph}{SET\_DEVICE\_STATUS (Driver)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_DEVICE_STATUS / Driver} +\begin{itemize} + \item A driver MUST write 0 via \msgref{SET_DEVICE_STATUS} to request a device + reset and MUST re-read the status (e.g., via \msgref{GET_DEVICE_STATUS}) + if it needs to confirm acceptance. +\end{itemize} + +\devicenormative{\paragraph}{SET\_DEVICE\_STATUS (Device)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_DEVICE_STATUS / Device} +\begin{itemize} + \item A device MAY clear FEATURES\_OK or set DEVICE\_NEEDS\_RESET in its + response if it cannot accept the requested status, but it MUST report + the resulting status accurately. +\end{itemize} \msgdef{GET_VQUEUE} From e2b3e9f57346039570ac24f6a7251e62a6a26da1 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Thu, 20 Nov 2025 16:39:49 +0100 Subject: [PATCH 40/53] virtio-msg: convert vqueue messages to normative Signed-off-by: Bertrand Marquis --- transport-msg.tex | 85 ++++++++++++++++++++++++++++++++--------------- 1 file changed, 59 insertions(+), 26 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 8ac8da8..c5758c3 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -1259,8 +1259,9 @@ \subsubsection{Overview} \msgdef{GET_VQUEUE} -This message is sent by the virtio-msg transport driver and requires a -response from the device. +\msgref{GET_VQUEUE} returns information about a specific virtqueue, including +its maximum size, current size, and, if already configured, the descriptor, +driver, and device area addresses. \begin{tabular}{|l|l|l|l|} \hline @@ -1268,47 +1269,65 @@ \subsubsection{Overview} \hline \hline Request & 0 & 4 & Virtqueue index \\ \hline -Answer & 0 & 4 & Virtqueue index \\ -& 4 & 4 & Maximum virtqueue size \\ -& 8 & 4 & Current virtqueue size \\ -& 12 & 4 & Reserved (Must Be Zero - MBZ) \\ -& 16 & 8 & Descriptor address \\ -& 24 & 8 & Driver address \\ -& 32 & 8 & Device address \\ +Answer & 0 & 4 & Virtqueue index (echoed) \\ + & 4 & 4 & Maximum virtqueue size \\ + & 8 & 4 & Current virtqueue size (0 if unused) \\ + & 12 & 4 & Reserved (must be zero) \\ + & 16 & 8 & Descriptor area address \\ + & 24 & 8 & Driver area address \\ + & 32 & 8 & Device area address \\ \hline \end{tabular} -If the maximum virtqueue size is zero, the virtqueue is not valid and -MUST not be used. +\devicenormative{\paragraph}{GET\_VQUEUE (Device)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_VQUEUE / Device} +\begin{itemize} + \item A device MUST report accurate maxima and current queue sizes for each + virtqueue and MUST return zero as the current size if the queue has not + yet been configured. +\end{itemize} \msgdef{SET_VQUEUE} -This message is sent by the virtio-msg transport driver and requires a -response from the device. +\msgref{SET_VQUEUE} programs a virtqueue's size and buffer addresses. The driver +selects a queue index, supplies the desired size (not exceeding the maximum +reported via \msgref{GET_VQUEUE}), and provides guest-physical addresses for the +descriptor, driver, and device areas. \begin{tabular}{|l|l|l|l|} \hline Type & Offset & Size (bytes) & Content \\ \hline \hline Request & 0 & 4 & Virtqueue index \\ -& 4 & 4 & Reserved (Must Be Zero - MBZ) \\ -& 8 & 4 & Current virtqueue size \\ -& 12 & 4 & Reserved (Must Be Zero - MBZ) \\ -& 16 & 8 & Descriptor address \\ -& 24 & 8 & Driver address \\ -& 32 & 8 & Device address \\ + & 4 & 4 & Reserved (must be zero) \\ + & 8 & 4 & Virtqueue size \\ + & 12 & 4 & Reserved (must be zero) \\ + & 16 & 8 & Descriptor address \\ + & 24 & 8 & Driver address \\ + & 32 & 8 & Device address \\ \hline -Answer & 0 & 0 & no extra data \\ +Answer & 0 & 0 & No additional data \\ \hline \end{tabular} -\msgdef{RESET_VQUEUE} +\drivernormative{\paragraph}{SET\_VQUEUE (Driver)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_VQUEUE / Driver} +\begin{itemize} + \item A driver MUST set the virtqueue size field to a value not exceeding the + maximum reported by \msgref{GET_VQUEUE} and MUST ensure the supplied + addresses point to properly aligned memory. +\end{itemize} -This message is sent by the virtio-msg transport driver and requires a -response from the device. +\devicenormative{\paragraph}{SET\_VQUEUE (Device)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_VQUEUE / Device} +\begin{itemize} + \item A device MUST configure the queue using the parameters provided via + \msgref{SET_VQUEUE} and treat the queue as inactive until + \msgref{SET_VQUEUE} has successfully completed. +\end{itemize} + +\msgdef{RESET_VQUEUE} -The driver SHOULD NOT send this message unless the VIRTIO_F_RING_RESET -feature has been negotiated. +\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. \begin{tabular}{|l|l|l|l|} \hline @@ -1316,10 +1335,24 @@ \subsubsection{Overview} \hline \hline Request & 0 & 4 & Virtqueue index \\ \hline -Answer & 0 & 0 & no extra data \\ +Answer & 0 & 0 & No additional data \\ \hline \end{tabular} +\drivernormative{\paragraph}{RESET\_VQUEUE (Driver)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_RESET_VQUEUE / Driver} +\begin{itemize} + \item A driver SHOULD issue \msgref{RESET_VQUEUE} only if + VIRTIO\_F\_RING\_RESET has been negotiated and it needs to reconfigure + or recover a specific queue. +\end{itemize} + +\devicenormative{\paragraph}{RESET\_VQUEUE (Device)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_RESET_VQUEUE / Device} +\begin{itemize} + \item Upon receiving \msgref{RESET_VQUEUE}, a device MUST stop processing the + indicated queue, reset its internal state for that queue, and allow the + driver to reconfigure it via \msgref{SET_VQUEUE}. +\end{itemize} + \msgdef{GET_SHM} This message is sent by the virtio-msg transport driver and requires a From bd256d6ab0d7bca71baa6898b37d42d49aa225ee Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Thu, 20 Nov 2025 16:42:56 +0100 Subject: [PATCH 41/53] virtio-msg: convert get_shm to normative Signed-off-by: Bertrand Marquis --- transport-msg.tex | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index c5758c3..f410310 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -1355,8 +1355,10 @@ \subsubsection{Overview} \msgdef{GET_SHM} -This message is sent by the virtio-msg transport driver and requires a -response from the device. +\msgref{GET_SHM} returns the location and size of a device-owned shared memory +region. The request carries the region index; the response echoes the index and +provides the base address and length. A length of zero indicates that the +specified region does not exist. \begin{tabular}{|l|l|l|l|} \hline @@ -1364,18 +1366,18 @@ \subsubsection{Overview} \hline \hline Request & 0 & 4 & Shared memory region index \\ \hline -Answer & 0 & 4 & Shared memory region index \\ -& 4 & 4 & Shared memory region length \\ -& 8 & 4 & Shared memory region address \\ +Answer & 0 & 4 & Shared memory region index (echoed) \\ + & 4 & 4 & Shared memory region length \\ + & 8 & 4 & Shared memory region address \\ \hline \end{tabular} -If the returned shared memory region length is zero, the memory region does not -exist. - -Note: these shared memory regions are device owned and supported on other virtio -transports since virtio v1.3. These shared memory regions are separate and -distinct from any shared memory regions defined by the bus implementation. +\devicenormative{\paragraph}{GET\_SHM (Device)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_SHM / Device} +\begin{itemize} + \item A device MUST return zero length if the requested shared memory region + does not exist and MUST report accurate address/length information for + regions it supports. +\end{itemize} \msgdef{EVENT_CONFIG} From 9d097f34752f359f140914d05db4a52f785ddc17 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Thu, 20 Nov 2025 16:46:55 +0100 Subject: [PATCH 42/53] virtio-msg: convert event messages to normative Signed-off-by: Bertrand Marquis --- transport-msg.tex | 76 +++++++++++++++++++++++++++++++++++------------ 1 file changed, 57 insertions(+), 19 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index f410310..e5a7fcd 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -1381,50 +1381,74 @@ \subsubsection{Overview} \msgdef{EVENT_CONFIG} -This message is sent by the virtio-msg device and there is no response. +\msgref{EVENT_CONFIG} notifies the driver about configuration or status changes. +The payload includes the current device status, configuration generation count, +and optionally the updated configuration data (offset plus length). A length of +zero indicates that the driver should re-fetch the affected range via +\msgref{GET_CONFIG}. \begin{tabular}{|l|l|l|l|} \hline Type & Offset & Size (bytes) & Content \\ \hline \hline Request & 0 & 4 & Device status \\ -& 4 & 4 & Configuration generation count \\ -& 8 & 4 & Configuration offset \\ -& 12 & 4 & Number of bytes (MAY be zero) \\ -& 16 & ... & Configuration data \\ + & 4 & 4 & Configuration generation count \\ + & 8 & 4 & Configuration offset \\ + & 12 & 4 & Number of bytes (may be zero) \\ + & 16 & ... & Configuration data (optional) \\ \hline \end{tabular} -The number of bytes field MAY be zero. If so the configuration data field -will also be of zero length. This is the normal case when the configuration -generation count has not been changed. +\drivernormative{\paragraph}{EVENT\_CONFIG (Driver)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_CONFIG / Driver} +\begin{itemize} + \item When \msgref{EVENT_CONFIG} provides configuration data, the driver + SHOULD apply it; otherwise it SHOULD re-read the affected range via + \msgref{GET_CONFIG} before proceeding. +\end{itemize} -If the number of bytes field is zero and the configuration generation count is -changed, then the driver is responsible for discovering any changed -configuration data via \msgref{GET_CONFIG} messages. +\devicenormative{\paragraph}{EVENT\_CONFIG (Device)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_CONFIG / Device} +\begin{itemize} + \item A device MUST send \msgref{EVENT_CONFIG} whenever it changes + configuration data or status in a way that is visible to the driver, + including the new configuration generation count. +\end{itemize} \msgdef{EVENT_AVAIL} -This message is sent by the virtio-msg driver and there is no response. +\msgref{EVENT_AVAIL} notifies the device that a virtqueue has new buffers. The +message includes the queue index and, if VIRTIO\_F\_NOTIFICATION\_DATA is +negotiated, a combined next-offset/next-wrap field so the device can jump +directly to the updated position. Otherwise that field is zero. \begin{tabular}{|l|l|l|l|} \hline Type & Offset & Size (bytes) & Content \\ \hline \hline Request & 0 & 4 & Virtqueue index \\ -& 4 & 4 & Next offset and Next wrap \\ + & 4 & 4 & Next offset (31 bits) and wrap (MSB) \\ \hline \end{tabular} -The \textbf{Next wrap} field is the MSB of the 32 bit value. The -\textbf{Next offset} field is the other 31 bits. These fields SHOULD be 0 if -the VIRTIO_F_NOTIFICATION_DATA feature has not been negotiated. If the bus -implementation is using out-of-band notifications, it SHOULD prevent this -feature from being negotiated. +\drivernormative{\paragraph}{EVENT\_AVAIL (Driver)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_AVAIL / Driver} +\begin{itemize} + \item If VIRTIO\_F\_NOTIFICATION\_DATA has not been negotiated, a driver MUST + set the next offset/wrap field to zero in \msgref{EVENT_AVAIL} messages. + If it has been negotiated, the driver MUST fill in the field with the + current available ring position. +\end{itemize} + +\busnormative{\paragraph}{EVENT\_AVAIL (Bus)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_AVAIL / Bus} +\begin{itemize} + \item A bus implementation that uses out-of-band notifications SHOULD prevent + negotiation of VIRTIO\_F\_NOTIFICATION\_DATA so that devices do not + expect in-band offset/wrap values. +\end{itemize} \msgdef{EVENT_USED} -This message is sent by the virtio-msg device and there is no response. +\msgref{EVENT_USED} notifies the driver that buffers on a particular virtqueue +have been consumed. The payload carries only the queue index; the driver uses +its used ring to determine which descriptors completed. \begin{tabular}{|l|l|l|l|} \hline @@ -1434,6 +1458,20 @@ \subsubsection{Overview} \hline \end{tabular} +\devicenormative{\paragraph}{EVENT\_USED (Device)}{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 (Driver)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_USED / Driver} +\begin{itemize} + \item Upon receiving \msgref{EVENT_USED}, a driver MUST examine the indicated + virtqueue (for example, by reading the used ring) to reclaim completed + buffers. +\end{itemize} + \subsection{Bus Messages}\label{sec:Virtio Transport Options / Virtio Over Messages / Bus Messages} The bus messages defined in this specification facilitate device discovery, From c85ef0de0213885b792c61a004d471c677bede71 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Thu, 20 Nov 2025 16:49:05 +0100 Subject: [PATCH 43/53] virtio-msg: reword bus message intro and overview Signed-off-by: Bertrand Marquis --- transport-msg.tex | 31 ++++++++++++------------------- 1 file changed, 12 insertions(+), 19 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index e5a7fcd..073a46e 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -1474,21 +1474,18 @@ \subsubsection{Overview} \subsection{Bus Messages}\label{sec:Virtio Transport Options / Virtio Over Messages / Bus Messages} -The bus messages defined in this specification facilitate device discovery, -hotplug management, and liveness checks at the bus level. -They are intended for bus implementations that wish to perform these operations -\emph{via virtio-msg} rather than relying exclusively on external means (e.g., -firmware tables, device trees). Each bus instance MAY use a subset of or -all these messages according to its design. +Bus messages cover device discovery, hotplug notifications, and bus-level +liveness checks. Implementations that already provide equivalent functionality +through platform mechanisms (e.g., ACPI, device tree, hypervisor events) may +reuse that infrastructure instead of the messages defined here. The following +subsections describe standardized bus messages that virtio-msg supports today. \subsubsection{Overview} \label{sec:Virtio Transport Options / Virtio Over Messages / Bus Messages / Overview} -A bus implementation \textbf{is not required} to use these -messages if it already provides equivalent functionality through some -platform-specific mechanism. However, if a bus chooses to handle enumeration, -hotplug, etc. via virtio-msg, it SHOULD implement the corresponding -message definitions below. +Each bus implementation chooses which of these messages to support. Some may +implement all of them for a fully message-based workflow, while others may rely +on out-of-band enumeration and use only the subset that fits their needs. \paragraph{Messages IDs and issuers} @@ -1509,14 +1506,10 @@ \subsubsection{Overview} \hline \end{tabular} -Bus message IDs below 0x80 are reserved for standardized (but optional) bus -messages. A few are used here and more are expected in the future. Bus message -IDs below 0x40 are used for request/response messages and 0x40 and above for -event messages. - -Bus message IDs 0x80 and above are bus implementation specific. Bus -implementations MAY specify the policy that IDs below 0xC0 be used -for request/response messages and IDs 0xC0 and above are used for event messages. +Bus message IDs below 0x40 cover request/response messages and 0x40–0x7F cover +events. IDs 0x80 and above are reserved for bus-specific extensions; some +implementations further subdivide that range (for example, IDs below 0xC0 for +requests and IDs 0xC0 and above for events). \paragraph{Bus Specific Messages} \label{sec:Virtio Transport Options / Virtio Over Messages / Bus Operation / Bus Specific Messages} From a4b41009a9ae84dd4557592c172528f8bbd0703c Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Thu, 20 Nov 2025 17:01:43 +0100 Subject: [PATCH 44/53] virtio-msg: convert get_devices to normative Signed-off-by: Bertrand Marquis --- transport-msg.tex | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 073a46e..817d29c 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -1545,12 +1545,6 @@ \subsubsection{Overview} \hline \end{tabular} -\textbf{offset} and \textbf{count} MUST be multiples of 8; the bitmap length is -\textbf{count/8} and is packed LSB-first (device number \textbf{offset} is the -LSB of the first byte). -\textbf{next_offset} is either 0 (no further windows) or an aligned value -$\ge offset + count$ that the responder suggests querying next. - 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 @@ -1568,6 +1562,20 @@ \subsubsection{Overview} a snapshot, advance using \textbf{next_offset}, and confirm candidates via \msgref{GET_DEVICE_INFO} before issuing other transport messages. +\busnormative{\paragraph}{GET\_DEVICES (Bus)}{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}. +\end{itemize} + \busdef{EVENT_DEVICE} This message is sent by the virtio-msg device side bus and there is no response. From 17d1729cb2dfafbd88e8f92c178c523e2d48120f Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Thu, 20 Nov 2025 17:05:08 +0100 Subject: [PATCH 45/53] virtio-msg: convert event dev and ping to normative Signed-off-by: Bertrand Marquis --- transport-msg.tex | 63 ++++++++++++++++++++--------------------------- 1 file changed, 27 insertions(+), 36 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 817d29c..47776cc 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -1578,63 +1578,54 @@ \subsubsection{Overview} \busdef{EVENT_DEVICE} -This message is sent by the virtio-msg device side bus and there is no response. +\busref{EVENT_DEVICE} signals device-level hotplug changes. The driver-side bus +receives these indications from the device-side bus; READY announces that a +device is present and REMOVED indicates that it is no longer accessible. Standard +states use values 0x1–0x2, while higher values (0x3 and above) are reserved for +future or implementation-specific meanings. \begin{tabular}{|l|l|l|l|} \hline Type & Offset & Size (bytes) & Content \\ \hline \hline -Request & 0 & 2 & Device Number \\ - & 2 & 2 & Device Bus State \\ +Request & 0 & 2 & Device number \\ + & 2 & 2 & Device bus state \\ \hline \end{tabular} -\begin{tabular}{|l|l|l|} -\hline -Device Bus State & Value & Meaning \\ -\hline -\hline -DEVICE_BUS_STATE_READY & 0x1 & Device is present and ready \\ -\hline -DEVICE_BUS_STATE_REMOVED & 0x2 & Device is no longer present \\ -\hline -reserved & 0x3 to 0x7FFF & Reserved for standard use \\ -\hline -any & 0x8000 to 0xFFFF & MAY be used by bus implementations \\ -\hline -\end{tabular} - -This event is sent when the bus level state of the device has changed. -It can indicate when a device is added or removed. It MAY also be used by -bus implementations to indicate other states. - \paragraph{Intended usage} -This message advertises device presence or removal. Upon READY, drivers SHOULD -probe the device via \msgref{GET_DEVICE_INFO} and proceed with initialization -if successful. Upon REMOVED, drivers MUST stop queueing new requests, -quiesce/reset as applicable, and release resources. Drivers SHOULD tolerate -duplicates and out-of-order events, and MAY use bus-level monitoring (see -\busref{PING}) to refine policy. +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. \busdef{PING} -This message is sent by the virtio-msg driver side bus or device side bus and -requires a response. +\busref{PING} is a simple liveness check that can be sent by either side of the +bus; the response echoes the 32-bit data value from the request. \begin{tabular}{|l|l|l|l|} \hline Type & Offset & Size (bytes) & Content \\ - \hline \hline -Request & 0 & 4 & Data \\ +\hline \hline +Request & 0 & 4 & Data (arbitrary 32-bit value) \\ \hline -Answer & 0 & 4 & Request Data \\ +Answer & 0 & 4 & Echoed request data \\ \hline \end{tabular} \paragraph{Intended usage} -Drivers MAY treat \busref{PING} as an optional keepalive or monitoring -mechanism. Timeouts or missing replies SHOULD trigger validation of device -state via \msgref{GET_DEVICE_STATUS} and recovery as appropriate. +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. + +\busnormative{\paragraph}{PING (Bus)}{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. +\end{itemize} \subsection{Compliance} \label{sec:Virtio Transport Options / Virtio Over Messages / Compliance} From 433d538155cdbde9f44bb91e21c2ed5eec33b718 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Thu, 20 Nov 2025 17:12:02 +0100 Subject: [PATCH 46/53] virtio-msg: remove compliance chapter All the content of the chapter is now present in normative statements in the required sections. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 155 +--------------------------------------------- 1 file changed, 1 insertion(+), 154 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 47776cc..a611a5e 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -1625,157 +1625,4 @@ \subsubsection{Overview} \begin{itemize} \item The bus-side responder MUST echo the 32-bit data field from the request exactly in the \busref{PING} response. -\end{itemize} - -\subsection{Compliance} -\label{sec:Virtio Transport Options / Virtio Over Messages / Compliance} - -This section details the requirements that an implementation MUST meet to -be considered compliant with the virtio-msg transport. It distinguishes between -\emph{mandatory} behaviors that all implementations MUST support and -\emph{optional} behaviors that are permissible but not required. - -\subsubsection{Normative References} -\label{sec:Virtio Transport Options / Virtio Over Messages / Compliance / NormativeRefs} -The terms MUST, MUST NOT, SHOULD, SHOULD NOT, -and MAY in this document are to be interpreted as specified by -\href{https://www.rfc-editor.org/rfc/rfc2119}{RFC 2119}. - -\subsubsection{Mandatory Requirements} -\label{sec:Virtio Transport Options / Virtio Over Messages / Compliance / Mandatory} - -\paragraph{General Transport Requirements} -\begin{itemize} - \item An implementation MUST correctly process or generate all - \emph{transport messages} defined by this specification that are necessary - for device operation. At minimum, this includes: - \begin{itemize} - \item \msgref{GET_DEVICE_INFO}, \msgref{GET_DEVICE_FEATURES}, \msgref{SET_DRIVER_FEATURES} - \item \msgref{GET_CONFIG}, \msgref{SET_CONFIG} - \item \msgref{GET_VQUEUE}, \msgref{SET_VQUEUE}, \msgref{RESET_VQUEUE} - \item \msgref{GET_DEVICE_STATUS}, \msgref{SET_DEVICE_STATUS} - \end{itemize} - Failure to support these messages renders a device or driver noncompliant. - \item An implementation MUST adhere to the - \textbf{transport revision} and \textbf{maximum message size} constraints - indicated by each bus instance. For example, it MUST NOT exceed - the \textbf{maximum message size} in any message. -\end{itemize} - -\paragraph{Device-Side Requirements} -\begin{itemize} - \item A device MUST provide accurate data in response to - \msgref{GET_DEVICE_INFO}, including the correct \emph{device ID}, \emph{vendor ID}, - number of feature bits, and configuration size. - \item A device MUST accept or reject driver-requested features via - \msgref{SET_DRIVER_FEATURES} consistently with its capabilities and MUST - return the final agreed-upon feature bits to the driver. - \item A device MUST maintain a valid \emph{Configuration Generation - Count} and MUST reject \msgref{SET_CONFIG} or similar operations if - the generation count supplied by the driver does not match. - \item A device MUST properly manage virtqueues configured via - \msgref{SET_VQUEUE}, including storing and using the provided addresses for - descriptor, driver, and device areas. - \item A device MUST respect \msgref{SET_DEVICE_STATUS} changes: if the - status is set to zero, the device MUST reset its internal state and - discard any pending operations. -\end{itemize} - -\paragraph{Driver-Side Requirements} -\begin{itemize} - \item A driver MUST send valid requests that do not exceed - the \textbf{maximum message size}, including correct offsets and block - counts in \msgref{GET_DEVICE_FEATURES}, \msgref{SET_DRIVER_FEATURES}, \msgref{GET_CONFIG}, - and \msgref{SET_CONFIG}. - \item A driver MUST handle a \msgref{SET_CONFIG} being rejected for a - mismatched configuration generation count. - \item A driver MUST initialize each device's virtqueues (where needed) - via \msgref{SET_VQUEUE} before attempting normal I/O and SHOULD - query the device's status or configuration if an unexpected - \msgref{EVENT_CONFIG} or error arises. -\end{itemize} - -\subsubsection{Optional Requirements} -\label{sec:Virtio Transport Options / Virtio Over Messages / Compliance / Optional} - -\paragraph{Bus Messages for Enumeration and Hotplug} -\begin{itemize} - \item Implementations MAY use \busref{GET_DEVICES} - and \busref{EVENT_DEVICE} for discovering and managing devices in a - message-driven manner. However, this is not mandatory if other enumeration - methods (e.g., device tree, ACPI, hypervisor firmware) are used. - \item If a bus chooses to implement these messages, it MUST do - so in compliance with their defined formats and semantics (see - \ref{sec:Virtio Transport Options / Virtio Over Messages / Bus Messages}). -\end{itemize} - -\paragraph{Optional Bus-Level Messages} -\begin{itemize} - \item \busref{PING} MAY be implemented for keepalive or health checks. - If used, both sides MUST echo the 32-bit data field precisely. -\end{itemize} - -\paragraph{Runtime Notifications} -\begin{itemize} - \item A device or the driver side bus MUST send \msgref{EVENT_CONFIG} - to inform the driver of configuration of device status changes. - \item A device or the driver side bus MUST send \msgref{EVENT_USED} - to inform the driver of (likely) buffer completions. - \item A driver MUST send \msgref{EVENT_AVAIL} to notify the device that - new buffers are available. -\end{itemize} - -\subsubsection{Compliance for Different Environments} -\label{sec:Virtio Transport Options / Virtio Over Messages / Compliance / DifferentEnvs} - -\paragraph{Bus Implementation} -A \emph{bus implementation} is compliant if: -\begin{itemize} - \item It forwards \textbf{transport messages} to the appropriate device - without altering or discarding valid requests. - \item It enforces the \textbf{maximum message size} and \textbf{transport - revision} advertised for its instance. - \item If it implements bus messages (e.g., \busref{GET_DEVICES}, \busref{PING}), - those MUST follow the formats in - \ref{sec:Virtio Transport Options / Virtio Over Messages / Bus Messages}. -\end{itemize} - -\paragraph{Driver Implementation} -A \emph{driver} is compliant if: -\begin{itemize} - \item It correctly sends and interprets all required transport messages - (\msgref{GET_DEVICE_INFO}, \msgref{SET_DRIVER_FEATURES}, \msgref{SET_CONFIG}, etc.). - \item It respects the bus \textbf{transport revision} and \textbf{maximum - message size} limits for each bus instance. - \item It properly handles device resets, ensuring that any - subsequent re-initialization follows - \ref{sec:Virtio Transport Options / Virtio Over Messages / Device Initialization}. -\end{itemize} - -\paragraph{Device Implementation} -A \emph{device} is compliant if: -\begin{itemize} - \item It supports the core transport messages and enforces the - \emph{Configuration Generation Count}. - \item It implements feature negotiation correctly - \item It respects \msgref{SET_DEVICE_STATUS} changes, resetting or shutting - down if the status is cleared. -\end{itemize} - -\subsubsection{Conformance Statements} -\label{sec:Virtio Transport Options / Virtio Over Messages / Compliance / Conformance} - -An implementation MUST meet all "MUST" requirements stated in: -\begin{itemize} - \item \ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts} (Basic Concepts) - \item \ref{sec:Virtio Transport Options / Virtio Over Messages / Bus Operation} (Bus Operation) - \item \ref{sec:Virtio Transport Options / Virtio Over Messages / Device Initialization} (Device Initialization) - \item \ref{sec:Virtio Transport Options / Virtio Over Messages / Device Operation} (Device Operation) - \item This \ref{sec:Virtio Transport Options / Virtio Over Messages / Compliance} (Compliance) section -\end{itemize} -to claim compliance with the virtio-msg specification. - -Implementations that do not follow these mandatory rules MUST NOT declare -themselves conformant. Features or messages labeled as "optional" (MAY) -do not invalidate compliance if omitted, provided all required behaviors are -still correctly implemented. +\end{itemize} \ No newline at end of file From 518d845512bdad880215323a7241e4ed647715c9 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Thu, 20 Nov 2025 17:37:01 +0100 Subject: [PATCH 47/53] virtio-msg: Simplify correlation handling Rework the correlation handling: - fully delegate correlation to the bus - only enforce for answers to be received in the order of the requests - remove restriction to set token to 0 for events - enforce for the device to not make any assumption on the token value Signed-off-by: Bertrand Marquis --- transport-msg.tex | 57 +++++++++++++++++++++-------------------------- 1 file changed, 25 insertions(+), 32 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index a611a5e..b99f47f 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -424,7 +424,7 @@ \subsubsection{Common Message Format} u8 type; /* request/response + bus/transport */ u8 msg_id; /* message id */ le16 dev_num; /* device number (0 for bus messages) */ - le16 token; /* correlation identifier (0 for events) */ + le16 token; /* bus-managed correlation identifier */ le16 msg_size; /* total size: header (8) + payload */ u8 payload[]; }; @@ -445,8 +445,9 @@ \subsubsection{Common Message Format} \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}: Requests use non-zero tokens so responses can be matched; - event (one-way) messages use token 0 and do not expect a response. + \item \field{token}: Correlation identifier managed by the bus. Drivers and + devices treat this field as opaque; the bus MAY overwrite it to track + outstanding requests or maintain ordering. \item \field{msg_size}: Total size in bytes of the complete message (header plus payload). \item \field{payload}: Operation-specific data. If a bus introduces extra @@ -460,13 +461,12 @@ \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{token}=0 for event (one-way) messages and MUST - assign a non-zero \field{token} for every request that expects a - response. \item When sending a transport message, a driver MUST set \field{dev_num} to the intended device number. \item If a driver introduces padding bytes that become part of the transport payload, it MUST set those bytes to zero. + \item A driver MUST treat the \field{token} field as opaque and MUST NOT rely + on its value when processing received messages. \end{itemize} \devicenormative{\paragraph}{Common Header (Device)}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Common Message Format / Device} @@ -475,13 +475,12 @@ \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{token}=0 for event (one-way) messages it - originates and MUST echo the \field{token} received in requests when - producing responses. \item When sending a transport message, a device MUST set \field{dev_num} to its own device number. \item A device MUST ignore padding bytes that are documented as bus-specific and MUST zero any such bytes it introduces into the transport payload. + \item A device MUST treat the \field{token} field as opaque and MUST NOT rely + on its value when processing received messages. \end{itemize} \busnormative{\paragraph}{Common Header (Bus)}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Common Message Format / Bus} @@ -496,36 +495,30 @@ \subsubsection{Common Message Format} payload, it MUST set those bytes to zero before delivering the message to the opposite side and MUST present the same zero padding when the opposite side reads a message. + \item A bus implementation owns the \field{token} field; it MAY insert or + overwrite values for correlation purposes and MUST ensure that any such + use is transparent to drivers and devices. \end{itemize} Reserved header bits and unspecified header values MUST be transmitted as zero and ignored on receive to preserve forward compatibility. -\subsubsection{Message Correlation} -\label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Correlation} +\subsubsection{Message Ordering} +\label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Ordering} -Requests expect responses, whereas events are one-way and do not. Correlation is -based on the tuple (\field{dev_num}, \field{token}) from the message header. +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. -\drivernormative{\paragraph}{Message Correlation (Driver)}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Correlation / Driver} +\busnormative{\paragraph}{Message Ordering (Bus)}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Ordering / Bus} \begin{itemize} - \item A driver MUST assign a non-zero \field{token} for each outstanding - request so that the (\field{dev_num}, \field{token}) tuple remains - unique among inflight requests. - \item A driver MUST set \field{token}=0 when sending event (one-way) messages - and MUST ignore any error responses purportedly referencing such events. - \item When processing responses, a driver SHOULD discard any response whose - correlation tuple does not match an outstanding request. -\end{itemize} - -\devicenormative{\paragraph}{Message Correlation (Device)}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Correlation / Device} -\begin{itemize} - \item A device MUST echo the \field{token} and \field{dev_num} from the - corresponding request when generating a response. - \item A device MUST set \field{token}=0 when generating event (one-way) - messages and MUST NOT send error responses referencing those events. - \item A device SHOULD discard responses from the other side that reference a - correlation tuple that is unknown or already completed. + \item For each device number, a bus implementation MUST deliver responses to + the driver in the same order that it forwarded the corresponding + requests to the device. + \item A bus implementation MUST ensure that every request forwarded to a + device results in exactly one response delivered to the driver (unless + the request is defined as an event). \end{itemize} \subsection{Device Discovery}\label{sec:Virtio Transport Options / Virtio Over Messages / Device Discovery} @@ -1625,4 +1618,4 @@ \subsubsection{Overview} \begin{itemize} \item The bus-side responder MUST echo the 32-bit data field from the request exactly in the \busref{PING} response. -\end{itemize} \ No newline at end of file +\end{itemize} From b67346b2eff574b4c3ee0e1f12ac2de81909a998 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Thu, 20 Nov 2025 17:40:34 +0100 Subject: [PATCH 48/53] virtio-msg: Remove (xx) in normative Remove (Driver), (Device) or (Bus) as those are repeating the requirement title. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 134 +++++++++++++++++++++++----------------------- 1 file changed, 67 insertions(+), 67 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index b99f47f..c8515a9 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -182,7 +182,7 @@ \subsubsection{Transport Revisions and Maximum Message Size} MUST inform the transport layer before accepting additional messages. \end{itemize} -\drivernormative{\paragraph}{Respecting Bus Limits (Driver)}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Revisions / Driver Limits} +\drivernormative{\paragraph}{Respecting Bus Limits}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Revisions / Driver Limits} \begin{itemize} \item A driver MUST NOT send a transport message whose total size exceeds the maximum message size advertised for the target bus instance. @@ -190,7 +190,7 @@ \subsubsection{Transport Revisions and Maximum Message Size} higher transport revision than the bus instance reports. \end{itemize} -\devicenormative{\paragraph}{Respecting Bus Limits (Device)}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Revisions / Device Limits} +\devicenormative{\paragraph}{Respecting Bus Limits}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Revisions / Device Limits} \begin{itemize} \item A device MUST ensure its responses and device-originated messages do not exceed the maximum message size advertised by the bus instance that @@ -307,7 +307,7 @@ \subsubsection{Configuration Generation Count} count does not necessarily start at zero and is not automatically reset when the device resets. -\devicenormative{\paragraph}{Configuration Generation Count (Device)}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / ConfigGen / Device} +\devicenormative{\paragraph}{Configuration Generation Count}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / ConfigGen / 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 @@ -322,7 +322,7 @@ \subsubsection{Configuration Generation Count} request. \end{itemize} -\drivernormative{\paragraph}{Configuration Generation Count (Driver)}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / ConfigGen / Driver} +\drivernormative{\paragraph}{Configuration Generation Count}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / ConfigGen / 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 @@ -351,7 +351,7 @@ \subsubsection{Feature Negotiation Blocks} driver-requested) feature bits in the selected blocks. \end{itemize} -\devicenormative{\paragraph}{Feature Blocks (Device)}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / FeatureBlocks / Device} +\devicenormative{\paragraph}{Feature Blocks}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / FeatureBlocks / 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 @@ -367,7 +367,7 @@ \subsubsection{Error Signaling} surface an error to the virtio-msg transport if it cannot deliver a request or obtain a response within its policy. -\busnormative{\paragraph}{Error Handling (Bus)}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / ErrorSignaling / Bus} +\busnormative{\paragraph}{Error Handling}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / ErrorSignaling / 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 @@ -379,7 +379,7 @@ \subsubsection{Error Signaling} (one-way) messages. \end{itemize} -\devicenormative{\paragraph}{Error Handling (Device)}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / ErrorSignaling / Device} +\devicenormative{\paragraph}{Error Handling}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / ErrorSignaling / Device} \begin{itemize} \item A device receiving a malformed or unsupported transport message MUST discard it without producing further protocol traffic. @@ -399,13 +399,13 @@ \subsubsection{Endianness} Unless otherwise stated, all numeric fields defined for virtio-msg messages use little-endian encoding. -\drivernormative{\paragraph}{Endianness (Driver)}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Endianness / Driver} +\drivernormative{\paragraph}{Endianness}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Endianness / Driver} \begin{itemize} \item A driver MUST encode and decode the common header and payload fields defined by this transport using little-endian byte order. \end{itemize} -\devicenormative{\paragraph}{Endianness (Device)}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Endianness / Device} +\devicenormative{\paragraph}{Endianness}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Endianness / Device} \begin{itemize} \item A device MUST emit and consume the common header and payload fields defined by this transport using little-endian byte order. @@ -454,7 +454,7 @@ \subsubsection{Common Message Format} padding bytes, those bytes are not part of the payload semantics. \end{itemize} -\drivernormative{\paragraph}{Common Header (Driver)}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Common Message Format / Driver} +\drivernormative{\paragraph}{Common Header}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Common Message Format / Driver} \begin{itemize} \item A driver MUST set bits 2..7 of \field{type} to zero and MUST treat them as reserved when parsing received headers. @@ -469,7 +469,7 @@ \subsubsection{Common Message Format} on its value when processing received messages. \end{itemize} -\devicenormative{\paragraph}{Common Header (Device)}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Common Message Format / Device} +\devicenormative{\paragraph}{Common Header}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Common Message Format / Device} \begin{itemize} \item A device MUST set bits 2..7 of \field{type} to zero in transmitted messages and MUST ignore those bits on receive. @@ -483,7 +483,7 @@ \subsubsection{Common Message Format} on its value when processing received messages. \end{itemize} -\busnormative{\paragraph}{Common Header (Bus)}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Common Message Format / Bus} +\busnormative{\paragraph}{Common Header}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Common Message Format / Bus} \begin{itemize} \item A bus implementation MUST deliver bus messages with \field{dev_num}=0 and MUST NOT alter \field{dev_num} for transport messages beyond the @@ -511,7 +511,7 @@ \subsubsection{Message Ordering} relative ordering of request/response pairs for each device number; they do not interpret the \field{token} field directly. -\busnormative{\paragraph}{Message Ordering (Bus)}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Ordering / Bus} +\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 @@ -534,7 +534,7 @@ \subsection{Device Discovery}\label{sec:Virtio Transport Options / Virtio Over M environments that prefer message-driven enumeration, but it does not require its use when equivalent information is already known out-of-band. -\busnormative{\paragraph}{Device Discovery (Bus)}{Virtio Transport Options / Virtio Over Messages / Device Discovery / Bus} +\busnormative{\paragraph}{Device Discovery}{Virtio Transport Options / Virtio Over Messages / Device Discovery / Bus} \begin{itemize} \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 @@ -581,7 +581,7 @@ \subsubsection{Initialization Flow Overview} The exact order may vary slightly across implementations, but these steps form the baseline for virtio-msg initialization. -\drivernormative{\paragraph}{Initialization Flow (Driver)}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Overview / Driver} +\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. @@ -607,7 +607,7 @@ \subsubsection{Device Information} virtio driver should bind to the device, how many feature blocks to query, and how much configuration space is valid. -\drivernormative{\paragraph}{Device Information (Driver)}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Information / Driver} +\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, @@ -627,7 +627,7 @@ \subsubsection{Feature Negotiation} device status via \msgref{SET_DEVICE_STATUS}, checking whether the FEATURES\_OK bit remains set. -\drivernormative{\paragraph}{Feature Negotiation (Driver)}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Features / Driver} +\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 @@ -637,7 +637,7 @@ \subsubsection{Feature Negotiation} returned status to ensure the device accepted the set. \end{itemize} -\devicenormative{\paragraph}{Feature Negotiation (Device)}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Features / Device} +\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 @@ -657,7 +657,7 @@ \subsubsection{Device Configuration} \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 (Driver)}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Configuration / Driver} +\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 @@ -668,7 +668,7 @@ \subsubsection{Device Configuration} generation mismatch. \end{itemize} -\devicenormative{\paragraph}{Device Configuration (Device)}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Configuration / Device} +\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 @@ -687,7 +687,7 @@ \subsubsection{Virtqueue Configuration} then calling \msgref{SET_VQUEUE} with the chosen size and guest-physical addresses. -\drivernormative{\paragraph}{Virtqueue Configuration (Driver)}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Virtqueue Configuration / Driver} +\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. @@ -699,7 +699,7 @@ \subsubsection{Virtqueue Configuration} reprogramming it. \end{itemize} -\devicenormative{\paragraph}{Virtqueue Configuration (Device)}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Virtqueue Configuration / Device} +\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, @@ -717,7 +717,7 @@ \subsubsection{Status Information} \msgref{SET_DEVICE_STATUS}. Writing zero to the status field resets the device, invalidating any configuration or virtqueue state. -\drivernormative{\paragraph}{Status Handling (Driver)}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Status Information / Driver} +\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 @@ -727,7 +727,7 @@ \subsubsection{Status Information} reset when needed. \end{itemize} -\devicenormative{\paragraph}{Status Handling (Device)}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Status Information / Device} +\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 @@ -744,7 +744,7 @@ \subsubsection{Finalizing Initialization} \msgref{SET_DEVICE_STATUS}. At that point, the device is considered ready for normal virtqueue I/O. -\drivernormative{\paragraph}{Final Status (Driver)}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Finalizing Initialization / Driver} +\drivernormative{\paragraph}{Final Status}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Finalizing Initialization / Driver} \begin{itemize} \item A driver MUST set DRIVER\_OK via \msgref{SET_DEVICE_STATUS} only after it has completed feature negotiation and initialized all required @@ -755,7 +755,7 @@ \subsubsection{Finalizing Initialization} virtqueue until that queue has been configured via \msgref{SET_VQUEUE}. \end{itemize} -\devicenormative{\paragraph}{Final Status (Device)}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Finalizing Initialization / Device} +\devicenormative{\paragraph}{Final Status}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Finalizing Initialization / Device} \begin{itemize} \item A device MUST NOT process normal virtqueue I/O until the driver has set DRIVER\_OK. @@ -780,7 +780,7 @@ \subsubsection{Driver Notifications} \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. -\drivernormative{\paragraph}{Driver Notifications (Driver)}{Virtio Transport Options / Virtio Over Messages / Device Operation / Driver Notifications / Driver} +\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. @@ -790,7 +790,7 @@ \subsubsection{Driver Notifications} head of the updated ring; otherwise those fields MUST be zero. \end{itemize} -\busnormative{\paragraph}{Driver Notifications (Bus)}{Virtio Transport Options / Virtio Over Messages / Device Operation / Driver Notifications / Bus} +\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 @@ -808,7 +808,7 @@ \subsubsection{Device Notifications} messages in-band or synthesize them based on other signals such as interrupts or polling. -\devicenormative{\paragraph}{Device Notifications (Device)}{Virtio Transport Options / Virtio Over Messages / Device Operation / Device Notifications / Device} +\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 @@ -822,7 +822,7 @@ \subsubsection{Device Notifications} an alternative, agreed-upon completion mechanism. \end{itemize} -\drivernormative{\paragraph}{Device Notifications (Driver)}{Virtio Transport Options / Virtio Over Messages / Device Operation / Device Notifications / Driver} +\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 @@ -832,7 +832,7 @@ \subsubsection{Device Notifications} buffers. \end{itemize} -\busnormative{\paragraph}{Device Notifications (Bus)}{Virtio Transport Options / Virtio Over Messages / Device Operation / Device Notifications / Bus} +\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, @@ -850,7 +850,7 @@ \subsubsection{Configuration Changes During Operation} update configuration data autonomously but must signal those changes via \msgref{EVENT_CONFIG}. -\drivernormative{\paragraph}{Runtime Configuration (Driver)}{Virtio Transport Options / Virtio Over Messages / Device Operation / ConfigUpdates / Driver} +\drivernormative{\paragraph}{Runtime Configuration}{Virtio Transport Options / Virtio Over Messages / Device Operation / ConfigUpdates / 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 @@ -860,7 +860,7 @@ \subsubsection{Configuration Changes During Operation} \msgref{GET_CONFIG}) before relying on the updated values. \end{itemize} -\devicenormative{\paragraph}{Runtime Configuration (Device)}{Virtio Transport Options / Virtio Over Messages / Device Operation / ConfigUpdates / Device} +\devicenormative{\paragraph}{Runtime Configuration}{Virtio Transport Options / Virtio Over Messages / Device Operation / ConfigUpdates / 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 @@ -874,7 +874,7 @@ \subsubsection{Virtqueue Changes During Operation} \msgref{SET_VQUEUE}, and they may reconfigure existing queues if the VIRTIO\_F\_RING\_RESET feature has been negotiated. -\drivernormative{\paragraph}{Runtime Virtqueue Changes (Driver)}{Virtio Transport Options / Virtio Over Messages / Device Operation / VQueueUpdates / Driver} +\drivernormative{\paragraph}{Runtime Virtqueue Changes}{Virtio Transport Options / Virtio Over Messages / Device Operation / VQueueUpdates / Driver} \begin{itemize} \item A driver MAY configure additional virtqueues after initialization using \msgref{SET_VQUEUE}, provided it follows the same validation steps @@ -884,7 +884,7 @@ \subsubsection{Virtqueue Changes During Operation} the device. \end{itemize} -\devicenormative{\paragraph}{Runtime Virtqueue Changes (Device)}{Virtio Transport Options / Virtio Over Messages / Device Operation / VQueueUpdates / Device} +\devicenormative{\paragraph}{Runtime Virtqueue Changes}{Virtio Transport Options / Virtio Over Messages / Device Operation / VQueueUpdates / Device} \begin{itemize} \item A device MUST honor \msgref{SET_VQUEUE} requests issued after initialization and update the queue parameters accordingly. @@ -901,7 +901,7 @@ \subsubsection{Device Reset and Shutdown} 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 (Driver)}{Virtio Transport Options / Virtio Over Messages / Device Operation / Reset / 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 @@ -912,7 +912,7 @@ \subsubsection{Device Reset and Shutdown} I/O. \end{itemize} -\devicenormative{\paragraph}{Reset and Shutdown (Device)}{Virtio Transport Options / Virtio Over Messages / Device Operation / Reset / Device} +\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 @@ -930,7 +930,7 @@ \subsubsection{Hotplug and Removal} 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 (Bus)}{Virtio Transport Options / Virtio Over Messages / Device Operation / Hotplug and Removal / Bus} +\busnormative{\paragraph}{Hotplug and Removal}{Virtio Transport Options / Virtio Over Messages / Device Operation / Hotplug and Removal / Bus} \begin{itemize} \item A bus implementation that uses \busref{EVENT_DEVICE} MUST send the READY event when a device becomes accessible and the REMOVED event when it is @@ -1002,7 +1002,7 @@ \subsubsection{Overview} IDs 0x00–0x3F are reserved for request/response messages and 0x40–0x7F for events. IDs 0x80 and above are reserved for future extensions. -\devicenormative{\paragraph}{Core Messages (Device)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / Mandatory / Device} +\devicenormative{\paragraph}{Core Messages}{Virtio Transport Options / Virtio Over Messages / Transport Messages / Mandatory / Device} \begin{itemize} \item A device MUST implement \msgref{GET_DEVICE_INFO}, \msgref{GET_DEVICE_FEATURES}, \msgref{SET_DRIVER_FEATURES}, @@ -1011,7 +1011,7 @@ \subsubsection{Overview} and \msgref{RESET_VQUEUE}. \end{itemize} -\drivernormative{\paragraph}{Core Messages (Driver)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / Mandatory / Driver} +\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. @@ -1047,14 +1047,14 @@ \subsubsection{Overview} \hline \end{tabular} -\devicenormative{\paragraph}{GET\_DEVICE\_INFO (Device)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_DEVICE_INFO / Device} +\devicenormative{\paragraph}{GET\_DEVICE\_INFO}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_DEVICE_INFO / Device} \begin{itemize} \item A device MUST respond to \msgref{GET_DEVICE_INFO} while inactive and MUST supply consistent values for device ID, vendor ID, feature count (a multiple of 32 bits), configuration size, and virtqueue limits. \end{itemize} -\drivernormative{\paragraph}{GET\_DEVICE\_INFO (Driver)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_DEVICE_INFO / Driver} +\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 @@ -1080,13 +1080,13 @@ \subsubsection{Overview} \hline \end{tabular} -\devicenormative{\paragraph}{GET\_DEVICE\_FEATURES (Device)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_DEVICE_FEATURES / Device} +\devicenormative{\paragraph}{GET\_DEVICE\_FEATURES}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_DEVICE_FEATURES / Device} \begin{itemize} \item A device MUST return zero for any feature bits beyond those it implements when responding to \msgref{GET_DEVICE_FEATURES}. \end{itemize} -\drivernormative{\paragraph}{GET\_DEVICE\_FEATURES (Driver)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_DEVICE_FEATURES / Driver} +\drivernormative{\paragraph}{GET\_DEVICE\_FEATURES}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_DEVICE_FEATURES / Driver} \begin{itemize} \item A driver MUST treat the returned data as 32-bit feature blocks starting at the requested index, padding with zeros as needed, before deciding @@ -1111,13 +1111,13 @@ \subsubsection{Overview} \hline \end{tabular} -\drivernormative{\paragraph}{SET\_DRIVER\_FEATURES (Driver)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_DRIVER_FEATURES / Driver} +\drivernormative{\paragraph}{SET\_DRIVER\_FEATURES}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_DRIVER_FEATURES / Driver} \begin{itemize} \item A driver MUST set only the feature bits it intends to enable in the blocks supplied to \msgref{SET_DRIVER_FEATURES}. \end{itemize} -\devicenormative{\paragraph}{SET\_DRIVER\_FEATURES (Device)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_DRIVER_FEATURES / Device} +\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 @@ -1146,13 +1146,13 @@ \subsubsection{Overview} \hline \end{tabular} -\drivernormative{\paragraph}{GET\_CONFIG (Driver)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_CONFIG / Driver} +\drivernormative{\paragraph}{GET\_CONFIG}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_CONFIG / Driver} \begin{itemize} \item A driver MUST ensure the requested offset and length in \msgref{GET_CONFIG} stay within the configuration size reported by \msgref{GET_DEVICE_INFO}. \end{itemize} -\devicenormative{\paragraph}{GET\_CONFIG (Device)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_CONFIG / Device} +\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. @@ -1182,14 +1182,14 @@ \subsubsection{Overview} \hline \end{tabular} -\drivernormative{\paragraph}{SET\_CONFIG (Driver)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_CONFIG / Driver} +\drivernormative{\paragraph}{SET\_CONFIG}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_CONFIG / Driver} \begin{itemize} \item A driver MUST include its most recent configuration generation count in each \msgref{SET_CONFIG} request and MUST keep the offset and length within the reported configuration size. \end{itemize} -\devicenormative{\paragraph}{SET\_CONFIG (Device)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_CONFIG / Device} +\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 @@ -1212,7 +1212,7 @@ \subsubsection{Overview} \hline \end{tabular} -\devicenormative{\paragraph}{GET\_DEVICE\_STATUS (Device)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_DEVICE_STATUS / Device} +\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 @@ -1236,14 +1236,14 @@ \subsubsection{Overview} \hline \end{tabular} -\drivernormative{\paragraph}{SET\_DEVICE\_STATUS (Driver)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_DEVICE_STATUS / Driver} +\drivernormative{\paragraph}{SET\_DEVICE\_STATUS}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_DEVICE_STATUS / Driver} \begin{itemize} \item A driver MUST write 0 via \msgref{SET_DEVICE_STATUS} to request a device reset and MUST re-read the status (e.g., via \msgref{GET_DEVICE_STATUS}) if it needs to confirm acceptance. \end{itemize} -\devicenormative{\paragraph}{SET\_DEVICE\_STATUS (Device)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_DEVICE_STATUS / Device} +\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 @@ -1272,7 +1272,7 @@ \subsubsection{Overview} \hline \end{tabular} -\devicenormative{\paragraph}{GET\_VQUEUE (Device)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_VQUEUE / Device} +\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 @@ -1302,14 +1302,14 @@ \subsubsection{Overview} \hline \end{tabular} -\drivernormative{\paragraph}{SET\_VQUEUE (Driver)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_VQUEUE / Driver} +\drivernormative{\paragraph}{SET\_VQUEUE}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_VQUEUE / Driver} \begin{itemize} \item A driver MUST set the virtqueue size field to a value not exceeding the maximum reported by \msgref{GET_VQUEUE} and MUST ensure the supplied addresses point to properly aligned memory. \end{itemize} -\devicenormative{\paragraph}{SET\_VQUEUE (Device)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_VQUEUE / Device} +\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 @@ -1332,14 +1332,14 @@ \subsubsection{Overview} \hline \end{tabular} -\drivernormative{\paragraph}{RESET\_VQUEUE (Driver)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_RESET_VQUEUE / Driver} +\drivernormative{\paragraph}{RESET\_VQUEUE}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_RESET_VQUEUE / Driver} \begin{itemize} \item A driver SHOULD issue \msgref{RESET_VQUEUE} only if VIRTIO\_F\_RING\_RESET has been negotiated and it needs to reconfigure or recover a specific queue. \end{itemize} -\devicenormative{\paragraph}{RESET\_VQUEUE (Device)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_RESET_VQUEUE / Device} +\devicenormative{\paragraph}{RESET\_VQUEUE}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_RESET_VQUEUE / Device} \begin{itemize} \item Upon receiving \msgref{RESET_VQUEUE}, a device MUST stop processing the indicated queue, reset its internal state for that queue, and allow the @@ -1365,7 +1365,7 @@ \subsubsection{Overview} \hline \end{tabular} -\devicenormative{\paragraph}{GET\_SHM (Device)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_SHM / Device} +\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 @@ -1392,14 +1392,14 @@ \subsubsection{Overview} \hline \end{tabular} -\drivernormative{\paragraph}{EVENT\_CONFIG (Driver)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_CONFIG / Driver} +\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 (Device)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_CONFIG / Device} +\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, @@ -1422,7 +1422,7 @@ \subsubsection{Overview} \hline \end{tabular} -\drivernormative{\paragraph}{EVENT\_AVAIL (Driver)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_AVAIL / Driver} +\drivernormative{\paragraph}{EVENT\_AVAIL}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_AVAIL / Driver} \begin{itemize} \item If VIRTIO\_F\_NOTIFICATION\_DATA has not been negotiated, a driver MUST set the next offset/wrap field to zero in \msgref{EVENT_AVAIL} messages. @@ -1430,7 +1430,7 @@ \subsubsection{Overview} current available ring position. \end{itemize} -\busnormative{\paragraph}{EVENT\_AVAIL (Bus)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_AVAIL / Bus} +\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 @@ -1451,14 +1451,14 @@ \subsubsection{Overview} \hline \end{tabular} -\devicenormative{\paragraph}{EVENT\_USED (Device)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_USED / Device} +\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 (Driver)}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_USED / Driver} +\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 @@ -1555,7 +1555,7 @@ \subsubsection{Overview} a snapshot, advance using \textbf{next_offset}, and confirm candidates via \msgref{GET_DEVICE_INFO} before issuing other transport messages. -\busnormative{\paragraph}{GET\_DEVICES (Bus)}{Virtio Transport Options / Virtio Over Messages / Bus Messages / GET_DEVICES / Bus} +\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 @@ -1614,7 +1614,7 @@ \subsubsection{Overview} 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. -\busnormative{\paragraph}{PING (Bus)}{Virtio Transport Options / Virtio Over Messages / Bus Messages / PING / Bus} +\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. From 3688857e66718675e012c030cb0658e14194a328 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Thu, 20 Nov 2025 17:49:56 +0100 Subject: [PATCH 49/53] virtio-msg: add conformance entries in conformance chapter Add entries for conformance of Virtio over Message for Driver, Device and bus. Signed-off-by: Bertrand Marquis --- conformance.tex | 100 +++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 98 insertions(+), 2 deletions(-) diff --git a/conformance.tex b/conformance.tex index d92a236..8797008 100644 --- a/conformance.tex +++ b/conformance.tex @@ -14,7 +14,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \item[Driver] A driver MUST conform to four conformance clauses: \begin{itemize} \item Clause \ref{sec:Conformance / Driver Conformance}. - \item One of clauses \ref{sec:Conformance / Driver Conformance / PCI Driver Conformance}, \ref{sec:Conformance / Driver Conformance / MMIO Driver Conformance} or \ref{sec:Conformance / Driver Conformance / Channel I/O Driver Conformance}. + \item One of clauses \ref{sec:Conformance / Driver Conformance / PCI Driver Conformance}, \ref{sec:Conformance / Driver Conformance / MMIO Driver Conformance}, \ref{sec:Conformance / Driver Conformance / Channel I/O Driver Conformance} or \ref{sec:Conformance / Driver Conformance / Virtio Over Messages Driver Conformance}. \item One of clauses \ref{sec:Conformance / Driver Conformance / Network Driver Conformance}, \ref{sec:Conformance / Driver Conformance / Block Driver Conformance}, @@ -42,7 +42,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \item[Device] A device MUST conform to four conformance clauses: \begin{itemize} \item Clause \ref{sec:Conformance / Device Conformance}. - \item One of clauses \ref{sec:Conformance / Device Conformance / PCI Device Conformance}, \ref{sec:Conformance / Device Conformance / MMIO Device Conformance} or \ref{sec:Conformance / Device Conformance / Channel I/O Device Conformance}. + \item One of clauses \ref{sec:Conformance / Device Conformance / PCI Device Conformance}, \ref{sec:Conformance / Device Conformance / MMIO Device Conformance}, \ref{sec:Conformance / Device Conformance / Channel I/O Device Conformance} or \ref{sec:Conformance / Device Conformance / Virtio Over Messages Device Conformance}. \item One of clauses \ref{sec:Conformance / Device Conformance / Network Device Conformance}, \ref{sec:Conformance / Device Conformance / Block Device Conformance}, @@ -68,6 +68,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \item Clause \ref{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance}. \end{itemize} +\item[Bus] A bus implementation MUST conform to clause \ref{sec:Conformance / Bus Conformance / Virtio Over Messages Bus Conformance} when providing Virtio Over Messages. \end{description} \conformance{\section}{Driver Conformance}\label{sec:Conformance / Driver Conformance} @@ -142,6 +143,41 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \item \ref{drivernormative:Virtio Transport Options / Virtio over channel I/O / Device Operation / Resetting Devices} \end{itemize} +\conformance{\subsection}{Virtio Over Messages Driver Conformance}\label{sec:Conformance / Driver Conformance / Virtio Over Messages Driver Conformance} + +A Virtio Over Messages driver MUST conform to the following normative statements: + +\begin{itemize} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Revisions / Driver Limits} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / ConfigGen / 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 / ConfigUpdates / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Device Operation / VQueueUpdates / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Device Operation / Reset / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / Mandatory / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_DEVICE_INFO / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_DEVICE_FEATURES / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_DRIVER_FEATURES / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_CONFIG / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_CONFIG / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_DEVICE_STATUS / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_VQUEUE / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_RESET_VQUEUE / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_CONFIG / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_AVAIL / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_USED / Driver} +\end{itemize} + \input{device-types/net/driver-conformance.tex} \input{device-types/blk/driver-conformance.tex} \input{device-types/console/driver-conformance.tex} @@ -233,6 +269,42 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \item \ref{devicenormative:Virtio Transport Options / Virtio over channel I/O / Device Operation / Resetting Devices} \end{itemize} +\conformance{\subsection}{Virtio Over Messages Device Conformance}\label{sec:Conformance / Device Conformance / Virtio Over Messages Device Conformance} + +A Virtio Over Messages device MUST conform to the following normative statements: + +\begin{itemize} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Revisions / Device Limits} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / ConfigGen / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / FeatureBlocks / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / ErrorSignaling / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Endianness / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Common Message Format / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Features / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Configuration / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Device Initialization / Virtqueue Configuration / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Device Initialization / Status Information / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Device Initialization / Finalizing Initialization / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Device Operation / Device Notifications / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Device Operation / ConfigUpdates / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Device Operation / VQueueUpdates / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Device Operation / Reset / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / Mandatory / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_DEVICE_INFO / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_DEVICE_FEATURES / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_DRIVER_FEATURES / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_CONFIG / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_CONFIG / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_DEVICE_STATUS / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_DEVICE_STATUS / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_VQUEUE / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_VQUEUE / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_RESET_VQUEUE / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_SHM / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_CONFIG / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_USED / Device} +\end{itemize} + \input{device-types/net/device-conformance.tex} \input{device-types/blk/device-conformance.tex} \input{device-types/console/device-conformance.tex} @@ -255,6 +327,30 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \input{device-types/can/device-conformance.tex} \input{device-types/spi/device-conformance.tex} +\conformance{\section}{Bus Conformance}\label{sec:Conformance / Bus Conformance} + +A bus implementation MUST conform to the relevant bus normative statements. + +\conformance{\subsection}{Virtio Over Messages Bus Conformance}\label{sec:Conformance / Bus Conformance / Virtio Over Messages Bus Conformance} + +A Virtio Over Messages bus implementation MUST conform to the following normative statements: + +\begin{itemize} +\item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Relationship between bus and transport / Transport Message Forwarding} +\item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Revisions / Advertising Transport Parameters} +\item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Device Numbers / Assignment} +\item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / ErrorSignaling / Bus} +\item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Common Message Format / Bus} +\item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Ordering / Bus} +\item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Device Discovery / Bus} +\item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Device Operation / Driver Notifications / Bus} +\item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Device Operation / Device Notifications / Bus} +\item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Device Operation / Hotplug and Removal / Bus} +\item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_AVAIL / Bus} +\item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Bus Messages / GET_DEVICES / Bus} +\item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Bus Messages / PING / Bus} +\end{itemize} + \conformance{\section}{Legacy Interface: Transitional Device and Transitional Driver Conformance}\label{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance} A conformant implementation MUST be either transitional or non-transitional, see \ref{intro:Legacy From 3851e6e7fe84b6376cb8d16177c3baad4ee6bc03 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Mon, 1 Dec 2025 15:44:46 +0100 Subject: [PATCH 50/53] virtio-msg: Improve message ID specification Use a table to properly define the message IDs area reserved for specific usage. Use the same format and fully specify also the message IDs area for bus messages. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 30 ++++++++++++++++++++++++------ 1 file changed, 24 insertions(+), 6 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index c8515a9..4b47703 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -999,8 +999,18 @@ \subsubsection{Overview} \hline \end{tabular} -IDs 0x00–0x3F are reserved for request/response messages and 0x40–0x7F for -events. IDs 0x80 and above are reserved for future extensions. +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} \devicenormative{\paragraph}{Core Messages}{Virtio Transport Options / Virtio Over Messages / Transport Messages / Mandatory / Device} \begin{itemize} @@ -1499,10 +1509,18 @@ \subsubsection{Overview} \hline \end{tabular} -Bus message IDs below 0x40 cover request/response messages and 0x40–0x7F cover -events. IDs 0x80 and above are reserved for bus-specific extensions; some -implementations further subdivide that range (for example, IDs below 0xC0 for -requests and IDs 0xC0 and above for events). +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} \paragraph{Bus Specific Messages} \label{sec:Virtio Transport Options / Virtio Over Messages / Bus Operation / Bus Specific Messages} From 1f2e4d95e58f28f1a38649c193adea3ea5395bd0 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Mon, 1 Dec 2025 15:45:55 +0100 Subject: [PATCH 51/53] virtio-msg: Use struct instead of tables for messages Define the messages format using structures instead of using table to be more coherent with other transports and the rest of virtio specification. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 383 +++++++++++++++++++++++----------------------- 1 file changed, 192 insertions(+), 191 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 4b47703..f2d9cde 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -1041,21 +1041,21 @@ \subsubsection{Overview} data and limits for a device. It is the only transport message permitted before the device transitions out of the inactive state. -\begin{tabular}{|l|l|l|l|} -\hline -Type & Offset & Size (bytes) & Content \\ -\hline \hline -Request & 0 & 0 & None \\ -\hline -Answer & 0 & 4 & Device ID \\ -& 4 & 4 & Vendor ID \\ -& 8 & 4 & Number of feature bits \\ -& 12 & 4 & Configuration size in bytes \\ -& 16 & 4 & Maximum number of virtqueues \\ -& 20 & 2 & Admin virtqueue start index \\ -& 22 & 2 & Admin virtqueue count \\ -\hline -\end{tabular} +\begin{lstlisting} +struct virtio_msg_get_device_info_req { + /* no payload */ +}; + +struct virtio_msg_get_device_info_resp { + le32 device_id; /* virtio device type */ + le32 vendor_id; /* implementation-defined vendor ID */ + le32 num_feature_bits; /* total feature bits (multiples of 32) */ + le32 config_size; /* bytes in the device configuration space */ + le32 max_virtqueues; /* maximum virtqueues supported */ + le16 admin_vq_start; /* index of the first admin virtqueue */ + le16 admin_vq_count; /* number of admin virtqueues */ +}; +\end{lstlisting} \devicenormative{\paragraph}{GET\_DEVICE\_INFO}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_DEVICE_INFO / Device} \begin{itemize} @@ -1077,18 +1077,18 @@ \subsubsection{Overview} \msgref{GET_DEVICE_FEATURES}; the response echoes the requested block index and returns one or more 32-bit values with the feature bits in that range. -\begin{tabular}{|l|l|l|l|} -\hline -Type & Offset & Size (bytes) & Content \\ -\hline \hline -Request & 0 & 4 & Feature block index \\ - & 4 & 4 & Number of feature blocks \\ -\hline -Answer & 0 & 4 & Feature block index (echoed) \\ - & 4 & 4 & Number of feature blocks (echoed) \\ - & 8 & ... & Feature data (multiples of 32 bits) \\ -\hline -\end{tabular} +\begin{lstlisting} +struct virtio_msg_get_device_features_req { + le32 block_index; /* starting block (0 == bits 0-31) */ + le32 num_blocks; /* number of 32-bit blocks requested */ +}; + +struct virtio_msg_get_device_features_resp { + le32 block_index; /* echoed starting block */ + le32 num_blocks; /* echoed number of blocks */ + le32 features[]; /* num_blocks entries, zero-padded if needed */ +}; +\end{lstlisting} \devicenormative{\paragraph}{GET\_DEVICE\_FEATURES}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_DEVICE_FEATURES / Device} \begin{itemize} @@ -1109,17 +1109,17 @@ \subsubsection{Overview} bits they wish to enable. The payload mirrors \msgref{GET_DEVICE_FEATURES}, supplying an index, count, and 32-bit feature data for the selected blocks. -\begin{tabular}{|l|l|l|l|} -\hline -Type & Offset & Size (bytes) & Content \\ -\hline \hline -Request & 0 & 4 & Feature block index \\ - & 4 & 4 & Number of feature blocks \\ - & 8 & ... & Feature data \\ -\hline -Answer & 0 & 0 & No additional data \\ -\hline -\end{tabular} +\begin{lstlisting} +struct virtio_msg_set_driver_features_req { + le32 block_index; /* starting block being acknowledged */ + le32 num_blocks; /* number of blocks provided */ + le32 features[]; /* num_blocks entries with desired bits */ +}; + +struct virtio_msg_set_driver_features_resp { + /* no payload */ +}; +\end{lstlisting} \drivernormative{\paragraph}{SET\_DRIVER\_FEATURES}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_DRIVER_FEATURES / Driver} \begin{itemize} @@ -1142,19 +1142,19 @@ \subsubsection{Overview} specifies the byte offset and length; the response echoes those values, returns the data, and includes the current configuration generation count. -\begin{tabular}{|l|l|l|l|} -\hline -Type & Offset & Size (bytes) & Content \\ -\hline \hline -Request & 0 & 4 & Configuration offset \\ - & 4 & 4 & Number of bytes \\ -\hline -Answer & 0 & 4 & Configuration generation count \\ - & 4 & 4 & Configuration offset (echoed) \\ - & 8 & 4 & Number of bytes (echoed) \\ - & 12 & ... & Configuration data \\ -\hline -\end{tabular} +\begin{lstlisting} +struct virtio_msg_get_config_req { + le32 offset; /* byte offset into configuration space */ + le32 length; /* number of bytes requested */ +}; + +struct virtio_msg_get_config_resp { + le32 generation; /* current configuration generation count */ + le32 offset; /* echoed offset */ + le32 length; /* echoed length */ + u8 data[]; /* configuration payload */ +}; +\end{lstlisting} \drivernormative{\paragraph}{GET\_CONFIG}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_CONFIG / Driver} \begin{itemize} @@ -1176,21 +1176,21 @@ \subsubsection{Overview} and may mirror the applied data or set the length to zero if the write was rejected. -\begin{tabular}{|l|l|l|l|} -\hline -Type & Offset & Size (bytes) & Content \\ -\hline \hline -Request & 0 & 4 & Configuration generation count \\ - & 4 & 4 & Configuration offset \\ - & 8 & 4 & Number of bytes \\ - & 12 & ... & Configuration data \\ -\hline -Answer & 0 & 4 & Updated configuration generation count \\ - & 4 & 4 & Configuration offset (echoed) \\ - & 8 & 4 & Number of bytes applied (0 if rejected) \\ - & 12 & ... & Configuration data (optional) \\ -\hline -\end{tabular} +\begin{lstlisting} +struct virtio_msg_set_config_req { + le32 generation; /* driver's view of generation count */ + le32 offset; /* byte offset being written */ + le32 length; /* number of bytes written */ + u8 data[]; /* configuration payload */ +}; + +struct virtio_msg_set_config_resp { + le32 generation; /* resulting generation count */ + le32 offset; /* echoed offset */ + le32 length; /* bytes applied (0 if rejected) */ + u8 data[]; /* optional echoed data */ +}; +\end{lstlisting} \drivernormative{\paragraph}{SET\_CONFIG}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_CONFIG / Driver} \begin{itemize} @@ -1212,15 +1212,15 @@ \subsubsection{Overview} DRIVER, DRIVER\_OK, FEATURES\_OK, or DEVICE\_NEEDS\_RESET bits). The request has no payload; the response returns the 32-bit status value. -\begin{tabular}{|l|l|l|l|} -\hline -Type & Offset & Size (bytes) & Content \\ -\hline \hline -Request & 0 & 0 & None \\ -\hline -Answer & 0 & 4 & Device status \\ -\hline -\end{tabular} +\begin{lstlisting} +struct virtio_msg_get_device_status_req { + /* no payload */ +}; + +struct virtio_msg_get_device_status_resp { + le32 status; /* current device status bits */ +}; +\end{lstlisting} \devicenormative{\paragraph}{GET\_DEVICE\_STATUS}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_DEVICE_STATUS / Device} \begin{itemize} @@ -1236,15 +1236,15 @@ \subsubsection{Overview} The device responds with its resulting status, which may differ (for example, if it refuses FEATURES\_OK or sets DEVICE\_NEEDS\_RESET). -\begin{tabular}{|l|l|l|l|} -\hline -Type & Offset & Size (bytes) & Content \\ -\hline \hline -Request & 0 & 4 & Device status value \\ -\hline -Answer & 0 & 4 & Resulting device status \\ -\hline -\end{tabular} +\begin{lstlisting} +struct virtio_msg_set_device_status_req { + le32 status; /* desired device status value */ +}; + +struct virtio_msg_set_device_status_resp { + le32 status; /* resulting device status */ +}; +\end{lstlisting} \drivernormative{\paragraph}{SET\_DEVICE\_STATUS}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_DEVICE_STATUS / Driver} \begin{itemize} @@ -1266,21 +1266,21 @@ \subsubsection{Overview} its maximum size, current size, and, if already configured, the descriptor, driver, and device area addresses. -\begin{tabular}{|l|l|l|l|} -\hline -Type & Offset & Size (bytes) & Content \\ -\hline \hline -Request & 0 & 4 & Virtqueue index \\ -\hline -Answer & 0 & 4 & Virtqueue index (echoed) \\ - & 4 & 4 & Maximum virtqueue size \\ - & 8 & 4 & Current virtqueue size (0 if unused) \\ - & 12 & 4 & Reserved (must be zero) \\ - & 16 & 8 & Descriptor area address \\ - & 24 & 8 & Driver area address \\ - & 32 & 8 & Device area address \\ -\hline -\end{tabular} +\begin{lstlisting} +struct virtio_msg_get_vqueue_req { + le32 index; /* virtqueue index */ +}; + +struct virtio_msg_get_vqueue_resp { + le32 index; /* echoed virtqueue index */ + le32 max_size; /* maximum queue size */ + le32 cur_size; /* current size (0 if unconfigured) */ + le32 reserved; /* must be zero */ + le64 desc_addr; /* descriptor area address */ + le64 driver_addr; /* driver area address */ + le64 device_addr; /* device area address */ +}; +\end{lstlisting} \devicenormative{\paragraph}{GET\_VQUEUE}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_VQUEUE / Device} \begin{itemize} @@ -1296,21 +1296,21 @@ \subsubsection{Overview} reported via \msgref{GET_VQUEUE}), and provides guest-physical addresses for the descriptor, driver, and device areas. -\begin{tabular}{|l|l|l|l|} -\hline -Type & Offset & Size (bytes) & Content \\ -\hline \hline -Request & 0 & 4 & Virtqueue index \\ - & 4 & 4 & Reserved (must be zero) \\ - & 8 & 4 & Virtqueue size \\ - & 12 & 4 & Reserved (must be zero) \\ - & 16 & 8 & Descriptor address \\ - & 24 & 8 & Driver address \\ - & 32 & 8 & Device address \\ -\hline -Answer & 0 & 0 & No additional data \\ -\hline -\end{tabular} +\begin{lstlisting} +struct virtio_msg_set_vqueue_req { + le32 index; /* virtqueue index */ + le32 reserved0; /* must be zero */ + le32 size; /* number of descriptors */ + le32 reserved1; /* must be zero */ + le64 desc_addr; /* descriptor area address */ + le64 driver_addr; /* driver area address */ + le64 device_addr; /* device area address */ +}; + +struct virtio_msg_set_vqueue_resp { + /* no payload */ +}; +\end{lstlisting} \drivernormative{\paragraph}{SET\_VQUEUE}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_VQUEUE / Driver} \begin{itemize} @@ -1332,15 +1332,15 @@ \subsubsection{Overview} has been negotiated). It requires only the queue index; the device responds after the queue has been quiesced. -\begin{tabular}{|l|l|l|l|} -\hline -Type & Offset & Size (bytes) & Content \\ -\hline \hline -Request & 0 & 4 & Virtqueue index \\ -\hline -Answer & 0 & 0 & No additional data \\ -\hline -\end{tabular} +\begin{lstlisting} +struct virtio_msg_reset_vqueue_req { + le32 index; /* virtqueue index */ +}; + +struct virtio_msg_reset_vqueue_resp { + /* no payload */ +}; +\end{lstlisting} \drivernormative{\paragraph}{RESET\_VQUEUE}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_RESET_VQUEUE / Driver} \begin{itemize} @@ -1363,17 +1363,17 @@ \subsubsection{Overview} provides the base address and length. A length of zero indicates that the specified region does not exist. -\begin{tabular}{|l|l|l|l|} -\hline -Type & Offset & Size (bytes) & Content \\ -\hline \hline -Request & 0 & 4 & Shared memory region index \\ -\hline -Answer & 0 & 4 & Shared memory region index (echoed) \\ - & 4 & 4 & Shared memory region length \\ - & 8 & 4 & Shared memory region address \\ -\hline -\end{tabular} +\begin{lstlisting} +struct virtio_msg_get_shm_req { + le32 index; /* shared memory region index */ +}; + +struct virtio_msg_get_shm_resp { + le32 index; /* echoed index */ + le32 length; /* region length (0 if nonexistent) */ + le32 address;/* region address */ +}; +\end{lstlisting} \devicenormative{\paragraph}{GET\_SHM}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_SHM / Device} \begin{itemize} @@ -1390,17 +1390,15 @@ \subsubsection{Overview} zero indicates that the driver should re-fetch the affected range via \msgref{GET_CONFIG}. -\begin{tabular}{|l|l|l|l|} -\hline -Type & Offset & Size (bytes) & Content \\ -\hline \hline -Request & 0 & 4 & Device status \\ - & 4 & 4 & Configuration generation count \\ - & 8 & 4 & Configuration offset \\ - & 12 & 4 & Number of bytes (may be zero) \\ - & 16 & ... & Configuration data (optional) \\ -\hline -\end{tabular} +\begin{lstlisting} +struct virtio_msg_event_config { + le32 device_status; /* new device status value */ + le32 generation; /* configuration generation count */ + le32 offset; /* configuration offset */ + le32 length; /* number of bytes (may be zero) */ + u8 data[]; /* optional configuration data */ +}; +\end{lstlisting} \drivernormative{\paragraph}{EVENT\_CONFIG}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_CONFIG / Driver} \begin{itemize} @@ -1423,14 +1421,12 @@ \subsubsection{Overview} negotiated, a combined next-offset/next-wrap field so the device can jump directly to the updated position. Otherwise that field is zero. -\begin{tabular}{|l|l|l|l|} -\hline -Type & Offset & Size (bytes) & Content \\ -\hline \hline -Request & 0 & 4 & Virtqueue index \\ - & 4 & 4 & Next offset (31 bits) and wrap (MSB) \\ -\hline -\end{tabular} +\begin{lstlisting} +struct virtio_msg_event_avail { + le32 vq_index; /* virtqueue index */ + le32 next_offset; /* bits[30:0] offset, bit[31] wrap; zero if unused */ +}; +\end{lstlisting} \drivernormative{\paragraph}{EVENT\_AVAIL}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_AVAIL / Driver} \begin{itemize} @@ -1453,13 +1449,11 @@ \subsubsection{Overview} have been consumed. The payload carries only the queue index; the driver uses its used ring to determine which descriptors completed. -\begin{tabular}{|l|l|l|l|} -\hline -Type & Offset & Size (bytes) & Content \\ -\hline \hline -Request & 0 & 4 & Virtqueue index \\ -\hline -\end{tabular} +\begin{lstlisting} +struct virtio_msg_event_used { + le32 vq_index; /* virtqueue index */ +}; +\end{lstlisting} \devicenormative{\paragraph}{EVENT\_USED}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_USED / Device} \begin{itemize} @@ -1542,19 +1536,19 @@ \subsubsection{Overview} device-side bus. The response describes a “window” of device numbers and signals which entries are present. -\begin{tabular}{|l|l|l|l|} -\hline -Type & Offset & Size (bytes) & Content \\ -\hline \hline -Request & 0 & 2 & offset: first device number in the window \\ - & 2 & 2 & count: number of consecutive device numbers covered \\ -\hline -Answer & 0 & 2 & offset (echoed) \\ - & 2 & 2 & count actually returned \\ - & 4 & 2 & next\_offset: 0 or the start of the recommended next window \\ - & 6 & count/8 & bitmap: bit $n$ ($0 \le n <$ count) describes device number $(offset + n)$ (0=absent, 1=present) \\ -\hline -\end{tabular} +\begin{lstlisting} +struct virtio_bus_msg_get_devices_req { + le16 offset; /* starting device number */ + le16 count; /* number of device-number slots (multiple of 8) */ +}; + +struct virtio_bus_msg_get_devices_resp { + le16 offset; /* echoed starting device number */ + le16 count; /* window length actually returned */ + le16 next_offset; /* 0 or suggested start for next query */ + u8 bitmap[]; /* count/8 bytes, LSB-first packing */ +}; +\end{lstlisting} The \textbf{(offset, count)} tuple defines a window of \textbf{count} consecutive device numbers beginning at \textbf{offset}. The number of present @@ -1590,17 +1584,24 @@ \subsubsection{Overview} \busdef{EVENT_DEVICE} \busref{EVENT_DEVICE} signals device-level hotplug changes. The driver-side bus -receives these indications from the device-side bus; READY announces that a -device is present and REMOVED indicates that it is no longer accessible. Standard -states use values 0x1–0x2, while higher values (0x3 and above) are reserved for -future or implementation-specific meanings. +receives these indications from the device-side bus; the table below lists the +defined device bus states. + +\begin{lstlisting} +struct virtio_bus_msg_event_device { + le16 device_number; + le16 device_bus_state; /* see table below */ +}; +\end{lstlisting} -\begin{tabular}{|l|l|l|l|} +\begin{tabular}{|l|l|p{7cm}|} \hline -Type & Offset & Size (bytes) & Content \\ -\hline \hline -Request & 0 & 2 & Device number \\ - & 2 & 2 & Device bus state \\ +Constant & Value & Meaning \\ +\hline +DEVICE\_BUS\_STATE\_READY & 0x0001 & Device is present and ready. \\ +DEVICE\_BUS\_STATE\_REMOVED & 0x0002 & Device is no longer present. \\ +Reserved & 0x0003–0x7FFF & Reserved for standard use. \\ +Implementation-defined & 0x8000–0xFFFF & MAY be used by the bus implementation. \\ \hline \end{tabular} @@ -1617,15 +1618,15 @@ \subsubsection{Overview} \busref{PING} is a simple liveness check that can be sent by either side of the bus; the response echoes the 32-bit data value from the request. -\begin{tabular}{|l|l|l|l|} -\hline -Type & Offset & Size (bytes) & Content \\ -\hline \hline -Request & 0 & 4 & Data (arbitrary 32-bit value) \\ -\hline -Answer & 0 & 4 & Echoed request data \\ -\hline -\end{tabular} +\begin{lstlisting} +struct virtio_bus_msg_ping_req { + le32 data; /* arbitrary value chosen by the sender */ +}; + +struct virtio_bus_msg_ping_resp { + le32 data; /* echoed request data */ +}; +\end{lstlisting} \paragraph{Intended usage} Drivers or bus implementations MAY use \busref{PING} as a keepalive. If a reply From c25b9bdf0b2d8efb1f21b20f2ceafdd31c9c2193 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Mon, 1 Dec 2025 17:22:35 +0100 Subject: [PATCH 52/53] virtio-msg: Remove compressed chapter lable/normative Replace compressed forms of labels or normative with long forms (for example FeatureBlocks to Feature Blocks). While there update conformance chapter. Signed-off-by: Bertrand Marquis --- conformance.tex | 23 ++++++++++++++--------- transport-msg.tex | 28 ++++++++++++++-------------- 2 files changed, 28 insertions(+), 23 deletions(-) diff --git a/conformance.tex b/conformance.tex index 8797008..4ebcf9d 100644 --- a/conformance.tex +++ b/conformance.tex @@ -149,7 +149,8 @@ \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 / ConfigGen / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Versioning and Forward Compatibility / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Generation Count / Driver} \item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Endianness / Driver} \item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Common Message Format / Driver} \item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Device Initialization / Overview / Driver} @@ -161,8 +162,8 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \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 / ConfigUpdates / Driver} -\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Device Operation / VQueueUpdates / 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} @@ -275,9 +276,10 @@ \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 / ConfigGen / Device} -\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / FeatureBlocks / Device} -\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / ErrorSignaling / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Versioning and Forward Compatibility / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Generation Count / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Feature Blocks / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Error Signaling / Device} \item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Endianness / Device} \item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Common Message Format / Device} \item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Features / Device} @@ -286,8 +288,8 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \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 / ConfigUpdates / Device} -\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Device Operation / VQueueUpdates / 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} @@ -336,10 +338,13 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} A Virtio Over Messages bus implementation MUST conform to the following normative statements: \begin{itemize} +\item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Relationship between bus and transport / Bus Messages} \item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Relationship between bus and transport / Transport Message Forwarding} \item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Revisions / Advertising Transport Parameters} +\item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Revisions / Message Size} +\item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Versioning and Forward Compatibility / Bus} \item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Device Numbers / Assignment} -\item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / ErrorSignaling / Bus} +\item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Error Signaling / Bus} \item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Common Message Format / Bus} \item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Ordering / Bus} \item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Device Discovery / Bus} diff --git a/transport-msg.tex b/transport-msg.tex index f2d9cde..99686de 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -297,7 +297,7 @@ \subsubsection{Device Numbers and Enumeration} \end{itemize} \subsubsection{Configuration Generation Count} -\label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / ConfigGen} +\label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Generation Count} Each device maintains a \textbf{Configuration Generation Count} to prevent inconsistent updates. This count is incremented at least once by the device for @@ -307,7 +307,7 @@ \subsubsection{Configuration Generation Count} 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 / ConfigGen / Device} +\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 @@ -322,7 +322,7 @@ \subsubsection{Configuration Generation Count} request. \end{itemize} -\drivernormative{\paragraph}{Configuration Generation Count}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / ConfigGen / Driver} +\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 @@ -336,7 +336,7 @@ \subsubsection{Configuration Generation Count} information. \subsubsection{Feature Negotiation Blocks} -\label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / FeatureBlocks} +\label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Feature Blocks} The virtio-msg transport organizes feature bits into 32-bit blocks accessed by \msgref{GET_DEVICE_FEATURES} and \msgref{SET_DRIVER_FEATURES}. Each block @@ -351,7 +351,7 @@ \subsubsection{Feature Negotiation Blocks} driver-requested) feature bits in the selected blocks. \end{itemize} -\devicenormative{\paragraph}{Feature Blocks}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / FeatureBlocks / Device} +\devicenormative{\paragraph}{Feature Blocks}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Feature Blocks / Device} \begin{itemize} \item When \msgref{GET_DEVICE_FEATURES} covers blocks that extend beyond the features a device implements, the device MUST return zero for the @@ -359,7 +359,7 @@ \subsubsection{Feature Negotiation Blocks} \end{itemize} \subsubsection{Error Signaling} -\label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / ErrorSignaling} +\label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Error Signaling} Transport errors can arise from malformed messages, routing failures inside a bus implementation, or device-side faults while processing a valid request. @@ -367,7 +367,7 @@ \subsubsection{Error Signaling} surface an error to the virtio-msg transport if it cannot deliver a request or obtain a response within its policy. -\busnormative{\paragraph}{Error Handling}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / ErrorSignaling / Bus} +\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 @@ -379,7 +379,7 @@ \subsubsection{Error Signaling} (one-way) messages. \end{itemize} -\devicenormative{\paragraph}{Error Handling}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / ErrorSignaling / Device} +\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. @@ -843,14 +843,14 @@ \subsubsection{Device Notifications} \end{itemize} \subsubsection{Configuration Changes During Operation} -\label{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / ConfigUpdates} +\label{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / Configuration Changes During Operation} 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 / ConfigUpdates / Driver} +\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 @@ -860,7 +860,7 @@ \subsubsection{Configuration Changes During Operation} \msgref{GET_CONFIG}) before relying on the updated values. \end{itemize} -\devicenormative{\paragraph}{Runtime Configuration}{Virtio Transport Options / Virtio Over Messages / Device Operation / ConfigUpdates / Device} +\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 @@ -868,13 +868,13 @@ \subsubsection{Configuration Changes During Operation} \end{itemize} \subsubsection{Virtqueue Changes During Operation} -\label{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / VQueueUpdates} +\label{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / Virtqueue Changes During Operation} Drivers may provision unused virtqueues later in the device lifetime by issuing \msgref{SET_VQUEUE}, and they may reconfigure existing queues if the VIRTIO\_F\_RING\_RESET feature has been negotiated. -\drivernormative{\paragraph}{Runtime Virtqueue Changes}{Virtio Transport Options / Virtio Over Messages / Device Operation / VQueueUpdates / Driver} +\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 @@ -884,7 +884,7 @@ \subsubsection{Virtqueue Changes During Operation} the device. \end{itemize} -\devicenormative{\paragraph}{Runtime Virtqueue Changes}{Virtio Transport Options / Virtio Over Messages / Device Operation / VQueueUpdates / Device} +\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. From 7891b6b4a1d438aa1b3961888492fd6ee1b80e70 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Mon, 1 Dec 2025 17:43:25 +0100 Subject: [PATCH 53/53] virtio-msg: move ping before event_device To keep messages in the order of the table of IDs, move ping definition before event_device. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 52 +++++++++++++++++++++++------------------------ 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 99686de..d4e31d7 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -1581,6 +1581,32 @@ \subsubsection{Overview} \textbf{offset} and \textbf{count}. \end{itemize} +\busdef{PING} + +\busref{PING} is a simple liveness check that can be sent by either side of the +bus; the response echoes the 32-bit data value from the request. + +\begin{lstlisting} +struct virtio_bus_msg_ping_req { + le32 data; /* arbitrary value chosen by the sender */ +}; + +struct virtio_bus_msg_ping_resp { + le32 data; /* echoed request data */ +}; +\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. + +\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. +\end{itemize} + \busdef{EVENT_DEVICE} \busref{EVENT_DEVICE} signals device-level hotplug changes. The driver-side bus @@ -1612,29 +1638,3 @@ \subsubsection{Overview} 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. - -\busdef{PING} - -\busref{PING} is a simple liveness check that can be sent by either side of the -bus; the response echoes the 32-bit data value from the request. - -\begin{lstlisting} -struct virtio_bus_msg_ping_req { - le32 data; /* arbitrary value chosen by the sender */ -}; - -struct virtio_bus_msg_ping_resp { - le32 data; /* echoed request data */ -}; -\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. - -\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. -\end{itemize}