From 52ffe641810d26860fbdbb45e7437c8df9360f6a Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Fri, 20 Feb 2026 11:18:31 +0100 Subject: [PATCH 01/56] virtio-msg: clarify device number vs device ID (Peter Hilber) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Peter noted inconsistent use of “device number” vs “device ID”. I did not find other ambiguous occurrences in transport-msg, so I added a sentence explicitly distinguishing the bus-assigned device number from the virtio device ID returned by GET_DEVICE_INFO. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/transport-msg.tex b/transport-msg.tex index d4e31d7..573cb76 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -272,7 +272,9 @@ \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 discover these device numbers through +by a 16-bit \textbf{device number}. The device number is a bus-assigned +identifier and is distinct from the virtio device ID (device type) returned by +\msgref{GET_DEVICE_INFO}. Buses discover these device numbers through mechanisms such as: \begin{itemize} \item \textbf{Message-Based Enumeration}: Using \busref{GET_DEVICES} to query From 3a70c3ad6a277cf08931a4efb86b3a41fd29eb7b Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Fri, 20 Feb 2026 11:21:22 +0100 Subject: [PATCH 02/56] virtio-msg: fix minor grammar in device topology (Peter Hilber) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Peter noted minor editorial issues (“Implement”/“respond”). Update the Device bullet to “Implements” and “responds”. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 573cb76..ecec4b6 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -145,8 +145,8 @@ \subsubsection{System Topology} available devices. Once a device is recognized, the driver uses the common transport messages to perform feature negotiation, configuration, and virtqueue setup. - \item \textbf{Device}: Implement virtio device functionality and - respond to the transport messages. The bus forwards these messages to + \item \textbf{Device}: Implements virtio device functionality and + responds to the transport messages. The bus forwards these messages to the correct device instance based on device number. \end{itemize} From d677fc8c1717320416460d911143fa243b8f4eb8 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Fri, 20 Feb 2026 11:25:15 +0100 Subject: [PATCH 03/56] =?UTF-8?q?virtio-msg:=20use=20=E2=80=9Ctransport=20?= =?UTF-8?q?revision=E2=80=9D=20consistently=20(Peter=20Hilber)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Peter noted inconsistent naming. Update the virtio-msg revision wording and paragraph title to consistently use “transport revision”. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index ecec4b6..abb78e8 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -200,9 +200,9 @@ \subsubsection{Transport Revisions and Maximum Message Size} an error or ignore requests for unsupported features. \end{itemize} -\paragraph{virtio-msg revisions} +\paragraph{virtio-msg transport revisions} -The following table lists the currently defined virtio-msg revisions: +The following table lists the currently defined virtio-msg transport revisions: \begin{tabular}{ |l|l|l|l| } \hline @@ -213,7 +213,7 @@ \subsubsection{Transport Revisions and Maximum Message Size} \end{tabular} Note that a change in the virtio standard does not necessarily -correspond to a change in the virtio-msg revision. +correspond to a change in the virtio-msg transport revision. The maximum message size is specified from the transport-layer point of view and includes the 8-byte common header plus payload. Any extra encapsulation From c0020f12b985b25c66e3afcf348c1b7aaa81fb78 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Fri, 20 Feb 2026 11:29:02 +0100 Subject: [PATCH 04/56] virtio-msg: use active voice for reserved header bits (Peter Hilber) Peter requested active-voice wording for the reserved header bits requirement. Rephrase to make the bus implementation the subject. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index abb78e8..4cbefa8 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -502,8 +502,9 @@ \subsubsection{Common Message Format} use is transparent to drivers and devices. \end{itemize} -Reserved header bits and unspecified header values MUST be transmitted as zero -and ignored on receive to preserve forward compatibility. +A bus implementation MUST transmit reserved header bits and unspecified header +values as zero, and drivers and devices MUST ignore those bits on receive to +preserve forward compatibility. \subsubsection{Message Ordering} \label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Ordering} From 7eafee2d67d847862f6ff7a9a2899fb5b081b217 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Fri, 20 Feb 2026 11:33:20 +0100 Subject: [PATCH 05/56] virtio-msg: drop duplicate GET_DEVICE_INFO requirement (Peter Hilber) Peter noted this requirement was already stated in the Initialization Flow driver requirements. Remove the duplicate from the Device Information driver requirements to avoid repetition. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 3 --- 1 file changed, 3 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 4cbefa8..26c3755 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -612,9 +612,6 @@ \subsubsection{Device Information} \drivernormative{\paragraph}{Device Information}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Information / Driver} \begin{itemize} - \item A driver MUST issue \msgref{GET_DEVICE_INFO} before attempting feature - negotiation or queue setup so it can discover the device ID, vendor ID, - feature count, configuration size, and virtqueue limits. \item A driver MUST use the configuration size reported via \msgref{GET_DEVICE_INFO} to bound any offsets and lengths supplied in \msgref{GET_CONFIG} and \msgref{SET_CONFIG} requests. From 623334cf0ae1c2289d23c3b47bdd7f2cfa801ed7 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Fri, 20 Feb 2026 11:38:03 +0100 Subject: [PATCH 06/56] virtio-msg: clarify removal handling (Peter Hilber) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Peter questioned “reset” on DEVICE_BUS_STATE_REMOVED. Rephrase the intended-usage text to avoid implying a device reset after removal and to focus on driver-side teardown. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 26c3755..44de96f 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -1634,7 +1634,7 @@ \subsubsection{Overview} \paragraph{Intended usage} Upon receiving DEVICE\_BUS\_STATE\_READY, drivers SHOULD probe the device via \msgref{GET_DEVICE_INFO} and proceed with initialization if successful. Upon -DEVICE\_BUS\_STATE\_REMOVED, drivers MUST stop queueing new work, quiesce and -reset as applicable, and release resources. Drivers SHOULD tolerate duplicate or -out-of-order events and MAY rely on additional bus-level monitoring (e.g., -\busref{PING}) if needed. +DEVICE\_BUS\_STATE\_REMOVED, drivers MUST stop queueing new work, quiesce the +device instance, tear down driver-side state, and release resources. Drivers +SHOULD tolerate duplicate or out-of-order events and MAY rely on additional +bus-level monitoring (e.g., \busref{PING}) if needed. From 4c75e07c29f4aa2dbdccfcde8c89d7d9953f28f6 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Fri, 20 Feb 2026 11:42:32 +0100 Subject: [PATCH 07/56] virtio-msg: allow zero devices per bus instance (Peter Hilber) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Peter noted the spec implied “one or more” devices. Update the device numbering section to allow zero devices, matching the earlier bus-layer statement and hotplug use cases. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/transport-msg.tex b/transport-msg.tex index 44de96f..2c45149 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -271,7 +271,7 @@ \subsubsection{Device Numbers and Enumeration} \label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Device Numbers} -Each virtio-msg bus instance contains one or more \emph{devices}, identified +Each virtio-msg bus instance contains zero or more \emph{devices}, identified by a 16-bit \textbf{device number}. The device number is a bus-assigned identifier and is distinct from the virtio device ID (device type) returned by \msgref{GET_DEVICE_INFO}. Buses discover these device numbers through From 2bbad994805f216755ba6abfe3a1b844e41f30aa Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Fri, 20 Feb 2026 11:50:50 +0100 Subject: [PATCH 08/56] virtio-msg: add note on config vs virtqueue data (Demi Marie Obenour) Demi suggested a non-normative note discouraging configuration space for bulk data when a virtqueue can be used. Add a short explanatory note in Device Configuration. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/transport-msg.tex b/transport-msg.tex index 2c45149..bee0015 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -657,6 +657,11 @@ \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. +Configuration space is intended for device control and configuration data. +When a device can instead expose data through a virtqueue, that mechanism is +preferred; configuration reads and writes are asynchronous in virtio-msg and +may require the driver to wait for a response. + \drivernormative{\paragraph}{Device Configuration}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Configuration / Driver} \begin{itemize} \item A driver MUST ensure that the offset and length in each From 094111b9d9e019c9cc4e50d31bf1c27ea5c8d3dc Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Fri, 20 Feb 2026 12:06:35 +0100 Subject: [PATCH 09/56] virtio-msg: rename READY to ADDED in bus device events (Parav Pandit) Parav requested symmetric naming for device hotplug events. Rename the READY state to ADDED throughout the EVENT_DEVICE definition and related text; values remain unchanged. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index bee0015..8dea0c8 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -931,13 +931,13 @@ \subsubsection{Hotplug and Removal} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / Hotplug and Removal} If the bus supports dynamic addition or removal of devices, it can advertise -those changes with \busref{EVENT_DEVICE} (READY or REMOVED). Some platforms may +those changes with \busref{EVENT_DEVICE} (ADDED or REMOVED). Some platforms may instead rely on external signals such as ACPI, device tree updates, or hypervisor events; virtio-msg does not mandate a specific mechanism. \busnormative{\paragraph}{Hotplug and Removal}{Virtio Transport Options / Virtio Over Messages / Device Operation / Hotplug and Removal / Bus} \begin{itemize} - \item A bus implementation that uses \busref{EVENT_DEVICE} MUST send the READY + \item A bus implementation that uses \busref{EVENT_DEVICE} MUST send the ADDED event when a device becomes accessible and the REMOVED event when it is no longer available. \item Regardless of how hotplug information is delivered, once a new device is @@ -1629,7 +1629,7 @@ \subsubsection{Overview} \hline Constant & Value & Meaning \\ \hline -DEVICE\_BUS\_STATE\_READY & 0x0001 & Device is present and ready. \\ +DEVICE\_BUS\_STATE\_ADDED & 0x0001 & Device is present and ready. \\ DEVICE\_BUS\_STATE\_REMOVED & 0x0002 & Device is no longer present. \\ Reserved & 0x0003–0x7FFF & Reserved for standard use. \\ Implementation-defined & 0x8000–0xFFFF & MAY be used by the bus implementation. \\ @@ -1637,7 +1637,7 @@ \subsubsection{Overview} \end{tabular} \paragraph{Intended usage} -Upon receiving DEVICE\_BUS\_STATE\_READY, drivers SHOULD probe the device via +Upon receiving DEVICE\_BUS\_STATE\_ADDED, drivers SHOULD probe the device via \msgref{GET_DEVICE_INFO} and proceed with initialization if successful. Upon DEVICE\_BUS\_STATE\_REMOVED, drivers MUST stop queueing new work, quiesce the device instance, tear down driver-side state, and release resources. Drivers From 1e1e81778404d596f1216385a8c8945cf6dbdbdc Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Fri, 20 Feb 2026 12:28:32 +0100 Subject: [PATCH 10/56] virtio-msg: clarify transport feature negotiation (Peter Hilber) Peter asked whether transport feature bits are negotiated. Clarify that the bus presents only the common subset and add a bus requirement to advertise only mutually supported bits. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/transport-msg.tex b/transport-msg.tex index 8dea0c8..15c4bc1 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -164,6 +164,10 @@ \subsubsection{Transport Revisions and Maximum Message Size} implemented by the bus instance. \end{itemize} +Transport feature bits are negotiated by the bus. When both the driver side and +device side expose transport feature masks, the bus instance presents only the +common subset to the virtio-msg transport. + The mechanism for obtaining these parameters is implementation-defined and can vary between bus instances. Common approaches include: \begin{itemize} @@ -177,6 +181,8 @@ \subsubsection{Transport Revisions and Maximum Message Size} \item Each bus instance MUST make its transport revision, maximum message size, and transport feature bits available to the virtio-msg transport before any transport messages are exchanged for that device. + \item A bus instance MUST advertise only the transport feature bits supported + by both sides of that bus instance. \item A bus instance MUST apply the same limits to both driver-originated and device-originated transport messages; if the values change, the bus MUST inform the transport layer before accepting additional messages. From f50fe3c985bd6061449f7ab50b45a045bbe15aa7 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Fri, 20 Feb 2026 14:22:06 +0100 Subject: [PATCH 11/56] virtio-msg: clarify generation count reset semantics (Peter Hilber) Peter asked whether devices may reset the configuration generation count. Allow reset (including on device reset) and require drivers to avoid assuming monotonic or persistent values. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 15c4bc1..e4448f4 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -312,8 +312,8 @@ \subsubsection{Configuration Generation Count} 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. +count does not necessarily start at zero and MAY be reset when the device +resets or at other device-defined times. \devicenormative{\paragraph}{Configuration Generation Count}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Generation Count / Device} \begin{itemize} @@ -321,6 +321,8 @@ \subsubsection{Configuration Generation Count} that is visible to the driver and MUST ensure that each \msgref{EVENT_CONFIG} carrying configuration data uses a unique generation count. + \item A device MAY reset the generation count, including when it resets its + internal state. \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 @@ -335,6 +337,8 @@ \subsubsection{Configuration Generation Count} \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 A driver MUST NOT assume the generation count is monotonic or preserved + across device resets. \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. From f462169090b0907b59b14ed0b6ee952c67934df1 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Fri, 20 Feb 2026 16:22:06 +0100 Subject: [PATCH 12/56] virtio-msg: clarify notification wording (Peter Hilber) Rephrase driver and device notification text to focus on which messages are used, avoiding timing-specific requirements for EVENT_AVAIL, EVENT_CONFIG, and EVENT_USED. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index e4448f4..6769c2c 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -791,14 +791,14 @@ \subsection{Device Operation} \subsubsection{Driver Notifications} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / Driver Notifications} -After buffers are made available to a virtqueue, the driver issues -\msgref{EVENT_AVAIL} to notify the device. A bus implementation may translate -these notifications into an out-of-band mechanism or deliver them in-band. +Drivers use \msgref{EVENT_AVAIL} to notify the device of available buffers. A +bus implementation may translate these notifications into an out-of-band +mechanism or deliver them in-band. \drivernormative{\paragraph}{Driver Notifications}{Virtio Transport Options / Virtio Over Messages / Device Operation / Driver Notifications / Driver} \begin{itemize} - \item A driver MUST send \msgref{EVENT_AVAIL} when it places new buffers on a - virtqueue. + \item A driver MUST use \msgref{EVENT_AVAIL} to notify the device of available + buffers. \item Each \msgref{EVENT_AVAIL} MUST identify the target virtqueue index. \item If VIRTIO\_F\_NOTIFICATION\_DATA has been negotiated, the driver MUST populate the “next offset and wrap” fields so the device can locate the @@ -825,16 +825,16 @@ \subsubsection{Device Notifications} \devicenormative{\paragraph}{Device Notifications}{Virtio Transport Options / Virtio Over Messages / Device Operation / Device Notifications / Device} \begin{itemize} - \item A device (or device-side bus) MUST send \msgref{EVENT_CONFIG} whenever - it makes a configuration change or status update that becomes visible to - the driver. The message MUST include the new configuration generation - count and MAY include the updated configuration data. + \item A device (or device-side bus) MUST use \msgref{EVENT_CONFIG} to notify + the driver of configuration changes or status updates. The message MUST + include the new configuration generation count and MAY include the + updated configuration data. \item If the configuration data is omitted from \msgref{EVENT_CONFIG}, the device SHOULD include the relevant offsets/lengths so the driver can re-fetch the data via \msgref{GET_CONFIG}. - \item A device SHOULD send \msgref{EVENT_USED} to inform the driver when - buffers on a virtqueue have been consumed, unless the device relies on - an alternative, agreed-upon completion mechanism. + \item A device SHOULD use \msgref{EVENT_USED} to notify the driver of used + buffers on a virtqueue, unless the device relies on an alternative, + agreed-upon completion mechanism. \end{itemize} \drivernormative{\paragraph}{Device Notifications}{Virtio Transport Options / Virtio Over Messages / Device Operation / Device Notifications / Driver} From 2d8c9952035cf72331de5b22ea13aacd9b2c5a29 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Fri, 20 Feb 2026 16:31:49 +0100 Subject: [PATCH 13/56] virtio-msg: require EVENT_USED unless polling (Peter Hilber) Strengthen EVENT_USED requirements to MUST, with explicit exceptions for polling or other agreed-upon completion mechanisms. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 6769c2c..b9064ac 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -832,8 +832,8 @@ \subsubsection{Device Notifications} \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 use \msgref{EVENT_USED} to notify the driver of used - buffers on a virtqueue, unless the device relies on an alternative, + \item A device MUST use \msgref{EVENT_USED} to notify the driver of used + buffers on a virtqueue, unless the device relies on polling or another agreed-upon completion mechanism. \end{itemize} @@ -1472,9 +1472,10 @@ \subsubsection{Overview} \devicenormative{\paragraph}{EVENT\_USED}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_USED / Device} \begin{itemize} - \item A device SHOULD send \msgref{EVENT_USED} (or an equivalent notification) + \item A device MUST send \msgref{EVENT_USED} (or an equivalent notification) when it processes buffers on a virtqueue unless the driver has - explicitly disabled such notifications. + explicitly disabled such notifications, or the device relies on polling + or another agreed-upon completion mechanism. \end{itemize} \drivernormative{\paragraph}{EVENT\_USED}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_USED / Driver} From 4b8c483c79709a509a5961309435a941a8e17110 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Fri, 20 Feb 2026 16:36:44 +0100 Subject: [PATCH 14/56] virtio-msg: drop RESET_VQUEUE-before-reprogramming (Peter Hilber) Remove the runtime requirement to issue RESET_VQUEUE before reprogramming a queue, since it does not avoid races. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 3 --- 1 file changed, 3 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index b9064ac..48dccb8 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -894,9 +894,6 @@ \subsubsection{Virtqueue Changes During Operation} \item A driver MAY configure additional virtqueues after initialization using \msgref{SET_VQUEUE}, provided it follows the same validation steps (e.g., checking the maximum queue size). - \item If VIRTIO\_F\_RING\_RESET is negotiated, the driver SHOULD use - \msgref{RESET_VQUEUE} before reprogramming a queue to avoid races with - the device. \end{itemize} \devicenormative{\paragraph}{Runtime Virtqueue Changes}{Virtio Transport Options / Virtio Over Messages / Device Operation / Virtqueue Changes During Operation / Device} From b783fc534d8973167770515d12a5fd22703ba331 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Fri, 20 Feb 2026 16:42:08 +0100 Subject: [PATCH 15/56] virtio-msg: align admin vq field widths (Peter Hilber) Use le32 for admin_vq_start and admin_vq_count to match max_virtqueues. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 48dccb8..6f5687d 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -1064,8 +1064,8 @@ \subsubsection{Overview} 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 */ + le32 admin_vq_start; /* index of the first admin virtqueue */ + le32 admin_vq_count; /* number of admin virtqueues */ }; \end{lstlisting} From 818142ed4c8612645a46ed211a0a172267684d35 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Fri, 20 Feb 2026 17:09:43 +0100 Subject: [PATCH 16/56] virtio-msg: proposal: clarify echoed fields (Peter Hilber) PROPOSAL: Clarify that echoed request parameters in responses are informational and do not change the ordering-based correlation model. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/transport-msg.tex b/transport-msg.tex index 6f5687d..8e6ed64 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -522,7 +522,10 @@ \subsubsection{Message Ordering} Transport messages fall into two classes: requests (which expect responses) and events (which are one-way). Drivers and devices rely on the bus to preserve the relative ordering of request/response pairs for each device number; they do not -interpret the \field{token} field directly. +interpret the \field{token} field directly. Some response payloads repeat +request parameters (for example, indices or offsets) to support validation; +these repeats are informational and do not alter the correlation model +described here. \busnormative{\paragraph}{Message Ordering}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Ordering / Bus} \begin{itemize} From 6ba8c708335f9068c0045f74714f9258b8faf488 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Fri, 20 Feb 2026 17:13:46 +0100 Subject: [PATCH 17/56] virtio-msg: require clearing FEATURES_OK (Peter Hilber) Make device requirements explicit: if features are unsupported, the device MUST clear FEATURES_OK in the status response. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 8e6ed64..84740a2 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -656,9 +656,9 @@ \subsubsection{Feature Negotiation} 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}. + internal feature mask to match the acknowledged set. If the device + cannot support the requested set, it MUST clear the FEATURES\_OK bit in + the status returned by \msgref{SET_DEVICE_STATUS}. \end{itemize} \subsubsection{Device Configuration} @@ -1147,7 +1147,7 @@ \subsubsection{Overview} \item After processing \msgref{SET_DRIVER_FEATURES}, a device MUST update its acknowledged feature set to match the data supplied and MUST report that set consistently in subsequent \msgref{GET_DEVICE_FEATURES} responses. - If it cannot support the requested set, it SHOULD clear the FEATURES\_OK + If it cannot support the requested set, it MUST clear the FEATURES\_OK bit in the device status. \end{itemize} From 21aeb4982be32a80ea2a4852cef9dae8f552786d Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Fri, 20 Feb 2026 17:23:02 +0100 Subject: [PATCH 18/56] virtio-msg: widen GET_SHM fields (Peter Hilber) Use le64 for shared memory length and address, and add a reserved padding field aligned with existing message layouts. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 84740a2..45fc919 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -1384,9 +1384,10 @@ \subsubsection{Overview} }; struct virtio_msg_get_shm_resp { - le32 index; /* echoed index */ - le32 length; /* region length (0 if nonexistent) */ - le32 address;/* region address */ + le32 index; /* echoed index */ + le32 reserved; /* must be zero */ + le64 length; /* region length (0 if nonexistent) */ + le64 address; /* region address */ }; \end{lstlisting} @@ -1395,6 +1396,8 @@ \subsubsection{Overview} \item A device MUST return zero length if the requested shared memory region does not exist and MUST report accurate address/length information for regions it supports. + \item A device MUST set the \field{reserved} field in \msgref{GET_SHM} + responses to zero. \end{itemize} \msgdef{EVENT_CONFIG} From 3e007fdbc75eadb931c2cb4eaf4954255f51e419 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Fri, 20 Feb 2026 17:28:28 +0100 Subject: [PATCH 19/56] virtio-msg: clarify EVENT_CONFIG ranges (Peter Hilber) Require EVENT_CONFIG to carry the affected offset/length even when data is omitted, and update related guidance. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 45fc919..745e701 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -325,8 +325,9 @@ \subsubsection{Configuration Generation Count} internal state. \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}. + without configuration data for the affected range (with offset/length + set to that range), 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. @@ -830,11 +831,8 @@ \subsubsection{Device Notifications} \begin{itemize} \item A device (or device-side bus) MUST use \msgref{EVENT_CONFIG} to notify the driver of configuration changes or status updates. 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}. + include the new configuration generation count and the affected + offset/length, and MAY include the updated configuration data. \item A device MUST use \msgref{EVENT_USED} to notify the driver of used buffers on a virtqueue, unless the device relies on polling or another agreed-upon completion mechanism. @@ -1404,8 +1402,8 @@ \subsubsection{Overview} \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 +and the affected configuration offset/length. The configuration data MAY be +omitted; if it is omitted, the driver should re-fetch the affected range via \msgref{GET_CONFIG}. \begin{lstlisting} @@ -1413,7 +1411,7 @@ \subsubsection{Overview} le32 device_status; /* new device status value */ le32 generation; /* configuration generation count */ le32 offset; /* configuration offset */ - le32 length; /* number of bytes (may be zero) */ + le32 length; /* number of bytes in affected range */ u8 data[]; /* optional configuration data */ }; \end{lstlisting} @@ -1421,8 +1419,9 @@ \subsubsection{Overview} \drivernormative{\paragraph}{EVENT\_CONFIG}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_CONFIG / Driver} \begin{itemize} \item When \msgref{EVENT_CONFIG} provides configuration data, the driver - SHOULD apply it; otherwise it SHOULD re-read the affected range via - \msgref{GET_CONFIG} before proceeding. + SHOULD apply it; otherwise it SHOULD re-read the affected range + indicated by the offset/length via \msgref{GET_CONFIG} before + proceeding. \end{itemize} \devicenormative{\paragraph}{EVENT\_CONFIG}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_CONFIG / Device} @@ -1430,6 +1429,8 @@ \subsubsection{Overview} \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. + \item A device MUST set the offset/length fields to describe the affected + configuration range, whether or not the configuration data is included. \end{itemize} \msgdef{EVENT_AVAIL} From f1095590057baff76976d371a1ecd95357ca3f35 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Fri, 20 Feb 2026 17:33:53 +0100 Subject: [PATCH 20/56] virtio-msg: streamline DEVICE_NEEDS_RESET text (Peter Hilber) Clarify that DEVICE_NEEDS_RESET is reported via status updates without repeating EVENT_CONFIG-specific requirements. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 745e701..dc60c1a 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -911,18 +911,17 @@ \subsubsection{Device Reset and Shutdown} 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. +A device may also signal that a reset is required by setting DEVICE\_NEEDS\_RESET +in its status and reporting the updated status to the driver. \drivernormative{\paragraph}{Reset and Shutdown}{Virtio Transport Options / Virtio Over Messages / Device Operation / Reset / Driver} \begin{itemize} \item A driver MAY request a device reset at any time by writing 0 through \msgref{SET_DEVICE_STATUS} and MAY reinitialize the device afterwards if it intends to resume operation. - \item If a device signals DEVICE\_NEEDS\_RESET (for example, via - \msgref{EVENT_CONFIG}), the driver SHOULD write 0 to - \msgref{SET_DEVICE_STATUS} and reinitialize the device before resuming - I/O. + \item If DEVICE\_NEEDS\_RESET is reported in device status, the driver SHOULD + write 0 to \msgref{SET_DEVICE_STATUS} and reinitialize the device before + resuming I/O. \end{itemize} \devicenormative{\paragraph}{Reset and Shutdown}{Virtio Transport Options / Virtio Over Messages / Device Operation / Reset / Device} @@ -931,8 +930,8 @@ \subsubsection{Device Reset and Shutdown} 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. + intervention, it SHOULD set DEVICE\_NEEDS\_RESET in its status and + ensure the updated status is reported to the driver. \end{itemize} \subsubsection{Hotplug and Removal} From 835ef718e432d7b8df08cf0e25f59f89a0a0bdc6 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Fri, 20 Feb 2026 17:43:14 +0100 Subject: [PATCH 21/56] virtio-msg: scope msg_id validation (Peter Hilber) Require the bus to discard invalid bus msg_ids and leave transport msg_id validation to the transport endpoints. NOTE: I am unsure whether the explicit "MUST NOT validate transport msg_id" line is necessary; please comment if a softer requirement is preferred. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index dc60c1a..b02dc0d 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -385,17 +385,29 @@ \subsubsection{Error Signaling} \item A bus implementation MAY report a transport-visible failure (for example, after exhausting a bounded retry policy) when it cannot deliver a request or obtain a response. - \item A bus implementation MUST treat malformed headers or unsupported - \field{msg_id} values as invalid, MUST discard them without generating - additional protocol traffic, and MAY log the condition for diagnostics. + \item A bus implementation MUST treat malformed headers or unsupported bus + \field{msg_id} values in bus messages as invalid, MUST discard them + without generating additional protocol traffic, and MAY log the + condition for diagnostics. + \item A bus implementation MUST NOT validate transport \field{msg_id} values; + unsupported transport \field{msg_id} handling is performed by the + transport layer. \item A bus implementation MUST NOT generate error responses to event (one-way) messages. \end{itemize} +\drivernormative{\paragraph}{Error Handling}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Error Signaling / Driver} +\begin{itemize} + \item A driver-side transport implementation receiving a malformed or + unsupported transport message MUST discard it without producing further + protocol traffic. +\end{itemize} + \devicenormative{\paragraph}{Error Handling}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Error Signaling / Device} \begin{itemize} - \item A device receiving a malformed or unsupported transport message MUST - discard it without producing further protocol traffic. + \item A device-side transport implementation receiving a malformed or + unsupported transport message MUST discard it without producing further + protocol traffic. \item Recovery actions taken in response to an error (such as retries, selective resets, or device removal) MUST follow the normative reset and status semantics defined in From 07b0d08d12c9038d59f07a627dbf408ec7424435 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Fri, 20 Feb 2026 17:57:29 +0100 Subject: [PATCH 22/56] virtio-msg: drop FEATURES_OK sentence (Peter Hilber) Remove the redundant sentence in SET_DRIVER_FEATURES device requirements. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 2 -- 1 file changed, 2 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index b02dc0d..3cb7a2d 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -1156,8 +1156,6 @@ \subsubsection{Overview} \item After processing \msgref{SET_DRIVER_FEATURES}, a device MUST update its acknowledged feature set to match the data supplied and MUST report that set consistently in subsequent \msgref{GET_DEVICE_FEATURES} responses. - If it cannot support the requested set, it MUST clear the FEATURES\_OK - bit in the device status. \end{itemize} \msgdef{GET_CONFIG} From ba844e93dd1a685fae0d0c04eb216784962a91e1 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Fri, 20 Feb 2026 18:13:55 +0100 Subject: [PATCH 23/56] virtio-msg: note bus-level errors (Demi Marie Obenour) Add a non-normative description of bus-level rejection for forbidden requests and how it can be surfaced to the driver. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/transport-msg.tex b/transport-msg.tex index 3cb7a2d..f021b4e 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -418,6 +418,11 @@ \subsubsection{Error Signaling} permits implementations to surface failures when silent recovery is not feasible. +Some bus implementations may reject requests that violate their local policy +or that are not valid for the current device state. In such cases, the bus may +return a bus-specific error indication to the transport, which can then surface +that failure to the driver. + \subsubsection{Endianness} \label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Endianness} From 3c685b6d5facca7ff01cce29869893c077153209 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Mon, 23 Feb 2026 09:24:02 +0100 Subject: [PATCH 24/56] virtio-msg: reframe ordering responses (Demi Marie Obenour) Rephrase the Message Ordering requirements so the device, not the bus, MUST send exactly one response per request. The bus ordering guarantee remains unchanged. Signed-off-by: Bertrand Marquis Signed-off-by: Bertrand Marquis --- transport-msg.tex | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index f021b4e..569fc56 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -550,9 +550,11 @@ \subsubsection{Message Ordering} \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} + +\devicenormative{\paragraph}{Message Ordering}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Ordering / Device} +\begin{itemize} + \item A device MUST send exactly one response for each request it receives. \end{itemize} \subsection{Device Discovery}\label{sec:Virtio Transport Options / Virtio Over Messages / Device Discovery} From 8a529c0a6bd261ef0bdda92b1715bfb5e5e8e034 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Mon, 23 Feb 2026 09:25:51 +0100 Subject: [PATCH 25/56] virtio-msg: clarify virtqueue data path (Demi Marie Obenour) Add an explicit note that virtqueue descriptors and buffer data are exchanged via shared memory or other DMA-accessible memory. Transport messages remain control-plane only. Signed-off-by: Bertrand Marquis Signed-off-by: Bertrand Marquis --- transport-msg.tex | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/transport-msg.tex b/transport-msg.tex index 569fc56..e7c36a3 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -534,6 +534,11 @@ \subsubsection{Common Message Format} values as zero, and drivers and devices MUST ignore those bits on receive to preserve forward compatibility. +Virtqueue descriptors and buffer data are exchanged via shared memory or other +DMA-accessible memory, as with other virtio transports. Transport messages are +used for control operations, configuration, and notifications, not for +virtqueue data transfer. + \subsubsection{Message Ordering} \label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Ordering} From 0df8574759c0685e802a99c34ef09e0d7cef3af2 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Mon, 23 Feb 2026 09:29:49 +0100 Subject: [PATCH 26/56] virtio-msg: allow out-of-order events (Demi Marie Obenour) Clarify that event notifications are independent and may be delivered out of order with respect to other events, while request/response ordering remains unchanged. Signed-off-by: Bertrand Marquis Signed-off-by: Bertrand Marquis --- transport-msg.tex | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index e7c36a3..19f7dbf 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -545,10 +545,11 @@ \subsubsection{Message Ordering} Transport messages fall into two classes: requests (which expect responses) and events (which are one-way). Drivers and devices rely on the bus to preserve the relative ordering of request/response pairs for each device number; they do not -interpret the \field{token} field directly. Some response payloads repeat -request parameters (for example, indices or offsets) to support validation; -these repeats are informational and do not alter the correlation model -described here. +interpret the \field{token} field directly. Events are independent +notifications and may be delivered out of order with respect to other events. +Some response payloads repeat request parameters (for example, indices or +offsets) to support validation; these repeats are informational and do not +alter the correlation model described here. \busnormative{\paragraph}{Message Ordering}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Ordering / Bus} \begin{itemize} From 773970f939facdba7ba7f2ff70838d0133e6cd58 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Mon, 23 Feb 2026 09:38:34 +0100 Subject: [PATCH 27/56] virtio-msg: use physical address terminology (Demi Marie Obenour) Align virtqueue and shared-memory address wording with mmio/pci by consistently referring to physical addresses throughout the virtio-msg transport text and message definitions. Signed-off-by: Bertrand Marquis Signed-off-by: Bertrand Marquis --- transport-msg.tex | 40 ++++++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 19f7dbf..3b30302 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -728,7 +728,7 @@ \subsubsection{Virtqueue Configuration} \msgref{SET_VQUEUE}, and optionally reset them using \msgref{RESET_VQUEUE} (if VIRTIO\_F\_RING\_RESET is negotiated). Each queue is typically configured by reading its maximum size, provisioning descriptor/available/used buffers, and -then calling \msgref{SET_VQUEUE} with the chosen size and guest-physical +then calling \msgref{SET_VQUEUE} with the chosen size and physical addresses. \drivernormative{\paragraph}{Virtqueue Configuration}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Virtqueue Configuration / Driver} @@ -737,7 +737,7 @@ \subsubsection{Virtqueue Configuration} 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. + descriptor/driver/device physical 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. @@ -747,7 +747,7 @@ \subsubsection{Virtqueue Configuration} \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). + descriptor, driver, and device physical 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. @@ -1299,7 +1299,7 @@ \subsubsection{Overview} \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. +driver, and device area physical addresses. \begin{lstlisting} struct virtio_msg_get_vqueue_req { @@ -1311,9 +1311,9 @@ \subsubsection{Overview} 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 */ + le64 desc_addr; /* descriptor area physical address */ + le64 driver_addr; /* driver area physical address */ + le64 device_addr; /* device area physical address */ }; \end{lstlisting} @@ -1326,10 +1326,10 @@ \subsubsection{Overview} \msgdef{SET_VQUEUE} -\msgref{SET_VQUEUE} programs a virtqueue's size and buffer addresses. The driver -selects a queue index, supplies the desired size (not exceeding the maximum -reported via \msgref{GET_VQUEUE}), and provides guest-physical addresses for the -descriptor, driver, and device areas. +\msgref{SET_VQUEUE} programs a virtqueue's size and physical addresses. The +driver selects a queue index, supplies the desired size (not exceeding the +maximum reported via \msgref{GET_VQUEUE}), and provides physical addresses for +the descriptor, driver, and device areas. \begin{lstlisting} struct virtio_msg_set_vqueue_req { @@ -1337,9 +1337,9 @@ \subsubsection{Overview} 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 */ + le64 desc_addr; /* descriptor area physical address */ + le64 driver_addr; /* driver area physical address */ + le64 device_addr; /* device area physical address */ }; struct virtio_msg_set_vqueue_resp { @@ -1351,7 +1351,7 @@ \subsubsection{Overview} \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. + physical addresses point to properly aligned memory. \end{itemize} \devicenormative{\paragraph}{SET\_VQUEUE}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_VQUEUE / Device} @@ -1395,8 +1395,8 @@ \subsubsection{Overview} \msgref{GET_SHM} returns the location and size of a device-owned shared memory region. The request carries the region index; the response echoes the index and -provides the base address and length. A length of zero indicates that the -specified region does not exist. +provides the base physical address and length. A length of zero indicates that +the specified region does not exist. \begin{lstlisting} struct virtio_msg_get_shm_req { @@ -1407,15 +1407,15 @@ \subsubsection{Overview} le32 index; /* echoed index */ le32 reserved; /* must be zero */ le64 length; /* region length (0 if nonexistent) */ - le64 address; /* region address */ + le64 address; /* region physical address */ }; \end{lstlisting} \devicenormative{\paragraph}{GET\_SHM}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_SHM / Device} \begin{itemize} \item A device MUST return zero length if the requested shared memory region - does not exist and MUST report accurate address/length information for - regions it supports. + does not exist and MUST report accurate physical address/length + information for regions it supports. \item A device MUST set the \field{reserved} field in \msgref{GET_SHM} responses to zero. \end{itemize} From 95fdde934531694f1f21fad60abddcb477d4741e Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Mon, 23 Feb 2026 11:19:43 +0100 Subject: [PATCH 28/56] virtio-msg: scope generation count uniqueness to resets The configuration generation count is now allowed to reset, but the normative text still required unique values for EVENT_CONFIG across the entire device lifetime. Scope the uniqueness requirement to the period since the last generation-count reset to remove the contradiction while preserving the intended sequencing guarantee. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/transport-msg.tex b/transport-msg.tex index 3b30302..b26226e 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -320,7 +320,7 @@ \subsubsection{Configuration Generation Count} \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. + generation count since the most recent generation count reset. \item A device MAY reset the generation count, including when it resets its internal state. \item If updated configuration data cannot fit in a single From 6e78b47e9bfbcfa0b778f40ffe48326c7cdd6240 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Mon, 23 Feb 2026 14:02:02 +0100 Subject: [PATCH 29/56] virtio-msg: define EVENT_CONFIG offset/length for status-only updates EVENT_CONFIG is used for both configuration changes and status updates, but the offset/length fields only describe configuration ranges. Define that status-only updates set offset and length to zero, removing the ambiguity while keeping range reporting for configuration updates. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/transport-msg.tex b/transport-msg.tex index b26226e..045692b 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -1426,7 +1426,8 @@ \subsubsection{Overview} The payload includes the current device status, configuration generation count, and the affected configuration offset/length. The configuration data MAY be omitted; if it is omitted, the driver should re-fetch the affected range via -\msgref{GET_CONFIG}. +\msgref{GET_CONFIG}. If the event reports only a status change with no +configuration update, the device sets the offset and length fields to zero. \begin{lstlisting} struct virtio_msg_event_config { @@ -1453,6 +1454,8 @@ \subsubsection{Overview} including the new configuration generation count. \item A device MUST set the offset/length fields to describe the affected configuration range, whether or not the configuration data is included. + \item If \msgref{EVENT_CONFIG} reports only a status change, a device MUST set + the offset and length fields to zero. \end{itemize} \msgdef{EVENT_AVAIL} From d56ac789b4ff8ab4c0d13d813f122d38fe91c1b4 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Mon, 23 Feb 2026 14:03:49 +0100 Subject: [PATCH 30/56] virtio-msg: align EVENT_USED omission criteria The Device Notifications section only allows EVENT_USED omission when polling or another completion mechanism is used. Drop the extra "driver explicitly disabled" clause from the message definition to match the normative text and keep the rules consistent. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 045692b..aab2c8a 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -1502,9 +1502,8 @@ \subsubsection{Overview} \devicenormative{\paragraph}{EVENT\_USED}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_USED / Device} \begin{itemize} \item A device MUST send \msgref{EVENT_USED} (or an equivalent notification) - when it processes buffers on a virtqueue unless the driver has - explicitly disabled such notifications, or the device relies on polling - or another agreed-upon completion mechanism. + when it processes buffers on a virtqueue unless the device relies on + polling or another agreed-upon completion mechanism. \end{itemize} \drivernormative{\paragraph}{EVENT\_USED}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_USED / Driver} From fd5cb94db8188ac13056bd250078ca2a4590ff4c Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Mon, 23 Feb 2026 14:05:46 +0100 Subject: [PATCH 31/56] virtio-msg: clarify reserved header bits rule The common header section implied the bus must sanitize reserved bits when forwarding transport messages. Rephrase the rule to apply to the message originator and receivers, preserving forward-compatibility requirements without conflicting with bus forwarding behavior. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index aab2c8a..f737a05 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -530,9 +530,9 @@ \subsubsection{Common Message Format} use is transparent to drivers and devices. \end{itemize} -A bus implementation MUST transmit reserved header bits and unspecified header -values as zero, and drivers and devices MUST ignore those bits on receive to -preserve forward compatibility. +A message originator MUST transmit reserved header bits and unspecified header +values as zero, and receivers MUST ignore those bits on receive to preserve +forward compatibility. Virtqueue descriptors and buffer data are exchanged via shared memory or other DMA-accessible memory, as with other virtio transports. Transport messages are From d2761027b0c4425bf7c13ee97460c9614f49362a Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Mon, 23 Feb 2026 14:18:37 +0100 Subject: [PATCH 32/56] virtio-msg: raise minimum max message size to 48 bytes Mandatory messages such as GET_VQUEUE/SET_VQUEUE are 40-byte payloads plus the 8-byte header. Update the revision table and the normative minimum to 48 bytes so the minimum advertised size can carry all mandatory messages. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index f737a05..2ff9e0c 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -214,7 +214,7 @@ \subsubsection{Transport Revisions and Maximum Message Size} \hline \field{revision} & \field{maximum size} & \field{features} & remarks \\ \hline \hline -1 & 44-65536 & & Virtio Message Revision 1 \\ +1 & 48-65536 & & Virtio Message Revision 1 \\ \hline \end{tabular} @@ -232,7 +232,7 @@ \subsubsection{Transport Revisions and Maximum Message Size} \busnormative{\paragraph}{Message Size Bounds}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Revisions / Message Size} \begin{itemize} \item A bus implementation MUST advertise a maximum message size of at least - 44 bytes. + 48 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} From b87c319a31484a5f603af0acd2facd12d924db79 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Mon, 23 Feb 2026 14:24:43 +0100 Subject: [PATCH 33/56] virtio-msg: relax bus device-number validation The bus is not responsible for validating device numbers. Drop the "MUST NOT forward" clause from device-number assignment and clarify that routing failures may be dropped or surfaced as a transport error. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 2ff9e0c..a73828d 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -130,6 +130,8 @@ \subsubsection{Relationship Between Bus and Transport} \item A bus implementation SHOULD treat transport messages as opaque apart from enforcing generic transport limits, such as the advertised maximum message size, and SHOULD NOT modify the transport payload. + \item If a bus implementation cannot route a transport message to a device + number, it MAY drop the message or surface a transport-visible failure. \end{itemize} \subsubsection{System Topology} @@ -297,8 +299,7 @@ \subsubsection{Device Numbers and Enumeration} \busnormative{\paragraph}{Device Number Assignment}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Device Numbers / Assignment} \begin{itemize} \item A bus implementation MUST assign a unique device number to every - device on a given bus instance and MUST NOT forward transport messages - for a device number that has not been validated. + device on a given bus instance. \item A bus implementation SHOULD provide the driver with sufficient information—either via \busref{GET_DEVICES} or equivalent platform data—to discover each valid device number. From 20306168ef081619c4dd90e39784366b0fc1ba4b Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Mon, 23 Feb 2026 14:25:45 +0100 Subject: [PATCH 34/56] virtio-msg: trim GET_DEVICE_INFO description GET_DEVICE_INFO does not report shared memory segments. Update the Device Information description to mention admin virtqueues only and remove the shared-memory reference. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index a73828d..038964a 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -645,10 +645,10 @@ \subsubsection{Device Information} Once a device number is confirmed, the driver uses \msgref{GET_DEVICE_INFO} to retrieve static identification data (device ID, vendor ID), the number of -feature bits, configuration space size, maximum virtqueues, shared memory -segments, and any admin virtqueue details. This information determines which -virtio driver should bind to the device, how many feature blocks to query, and -how much configuration space is valid. +feature bits, configuration space size, maximum virtqueues, and any admin +virtqueue details. This information determines which virtio driver should bind +to the device, how many feature blocks to query, and how much configuration +space is valid. \drivernormative{\paragraph}{Device Information}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Information / Driver} \begin{itemize} From e3e634f54c256fe7bf76b45de4e1a076947882cb Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Mon, 23 Feb 2026 14:27:15 +0100 Subject: [PATCH 35/56] virtio-msg: clarify max size table vs recommended cap The revision table shows the protocol-defined maximum message size, while the text recommends advertising no more than 264 bytes. Add a sentence to distinguish the protocol maximum from the recommended advertised maximum. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 3 +++ 1 file changed, 3 insertions(+) diff --git a/transport-msg.tex b/transport-msg.tex index 038964a..97bb6bd 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -220,6 +220,9 @@ \subsubsection{Transport Revisions and Maximum Message Size} \hline \end{tabular} +The table reflects the protocol-defined maximum size; the recommended +advertised maximum remains 264 bytes for interoperability. + Note that a change in the virtio standard does not necessarily correspond to a change in the virtio-msg transport revision. From b33da369f94c441f8073e0e3db50feaaac923703 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Mon, 23 Feb 2026 14:28:21 +0100 Subject: [PATCH 36/56] virtio-msg: fix Bus Specific Messages label path Update the label path for "Bus Specific Messages" to match the Bus Messages section hierarchy, keeping labels consistent with the document structure. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/transport-msg.tex b/transport-msg.tex index 97bb6bd..57766c6 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -1565,7 +1565,7 @@ \subsubsection{Overview} \end{tabular} \paragraph{Bus Specific Messages} -\label{sec:Virtio Transport Options / Virtio Over Messages / Bus Operation / Bus Specific Messages} +\label{sec:Virtio Transport Options / Virtio Over Messages / Bus Messages / Bus Specific Messages} A range of message IDs are reserved for use by the specific bus implementation. These messages can be used for any implementation specific From 1a5cf20233036a40195d2cd8dfb33443ca81369d Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Wed, 25 Feb 2026 09:22:04 +0100 Subject: [PATCH 37/56] virtio-msg: keep EVENT_* messages with OOB signaling (Demi Marie Obenour) Clarify that buses may signal runtime notifications out-of-band but MUST still relay or synthesize the corresponding EVENT_* transport message so the transport always receives events uniformly. Signed-off-by: Bertrand Marquis --- conformance.tex | 1 + transport-msg.tex | 38 +++++++++++++++++++++++++------------- 2 files changed, 26 insertions(+), 13 deletions(-) diff --git a/conformance.tex b/conformance.tex index 7d5d00f..12c65c0 100644 --- a/conformance.tex +++ b/conformance.tex @@ -360,6 +360,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Device Discovery / Bus} \item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Device Operation / Driver Notifications / Bus} \item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Device Operation / Device Notifications / Bus} +\item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / Runtime Notifications / Bus} \item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Device Operation / Hotplug and Removal / Bus} \item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_AVAIL / Bus} \item \ref{busnormative:Virtio Transport Options / Virtio Over Messages / Bus Messages / GET_DEVICES / Bus} diff --git a/transport-msg.tex b/transport-msg.tex index 57766c6..2701756 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -825,8 +825,8 @@ \subsubsection{Driver Notifications} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / Driver Notifications} Drivers use \msgref{EVENT_AVAIL} to notify the device of available buffers. A -bus implementation may translate these notifications into an out-of-band -mechanism or deliver them in-band. +bus implementation may use an out-of-band mechanism to signal these +notifications in addition to the in-band message. \drivernormative{\paragraph}{Driver Notifications}{Virtio Transport Options / Virtio Over Messages / Device Operation / Driver Notifications / Driver} \begin{itemize} @@ -840,9 +840,9 @@ \subsubsection{Driver Notifications} \busnormative{\paragraph}{Driver Notifications}{Virtio Transport Options / Virtio Over Messages / Device Operation / Driver Notifications / Bus} \begin{itemize} - \item A bus implementation MAY convert \msgref{EVENT_AVAIL} into an - out-of-band notification but, if it does not, it MUST relay the message - over the virtio-msg channel. + \item A bus implementation MAY use an out-of-band notification for + \msgref{EVENT_AVAIL}, but it MUST also relay the message over the + virtio-msg channel. \item A bus implementation MUST NOT drop \msgref{EVENT_AVAIL} unless it has arranged for the device to detect new buffers through polling or an equivalent mechanism. @@ -852,9 +852,9 @@ \subsubsection{Device Notifications} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / Device Notifications} \msgref{EVENT_CONFIG} and \msgref{EVENT_USED} provide asynchronous notifications -from the device (or device-side bus) to the driver. The bus may forward these -messages in-band or synthesize them based on other signals such as interrupts -or polling. +from the device (or device-side bus) to the driver. The bus may use other +signals such as interrupts or polling to trigger delivery and then forward +the messages in-band or synthesize them. \devicenormative{\paragraph}{Device Notifications}{Virtio Transport Options / Virtio Over Messages / Device Operation / Device Notifications / Device} \begin{itemize} @@ -879,9 +879,9 @@ \subsubsection{Device Notifications} \busnormative{\paragraph}{Device Notifications}{Virtio Transport Options / Virtio Over Messages / Device Operation / Device Notifications / Bus} \begin{itemize} - \item A bus implementation MUST forward \msgref{EVENT_CONFIG} and - \msgref{EVENT_USED} notifications (or their equivalents) to the driver, - either in-band or by synthesizing the appropriate message. + \item A bus implementation MUST deliver \msgref{EVENT_CONFIG} and + \msgref{EVENT_USED} to the driver by forwarding the in-band message or + by synthesizing the appropriate message based on other signals. \item If a bus implementation relies on polling or other mechanisms instead of direct notifications, it SHOULD limit that mode to scenarios where no other notification method is available. @@ -1073,8 +1073,20 @@ \subsubsection{Overview} and \ref{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / Device Notifications}, runtime notifications (\msgref{EVENT_AVAIL}, \msgref{EVENT_USED}, and -\msgref{EVENT_CONFIG}) may be delivered in-band or via equivalent out-of-band -mechanisms. +\msgref{EVENT_CONFIG}) are defined as transport messages and MAY also be +signaled via equivalent out-of-band mechanisms. + +\busnormative{\paragraph}{Runtime Notifications}{Virtio Transport Options / Virtio Over Messages / Transport Messages / Runtime Notifications / Bus} +\begin{itemize} + \item A bus implementation MUST specify whether runtime notifications + (\msgref{EVENT_AVAIL}, \msgref{EVENT_USED}, and \msgref{EVENT_CONFIG}) + use in-band delivery, out-of-band signaling, or both. + \item If a bus implementation specifies out-of-band signaling, it MUST + document the mechanism and any required configuration to use it. + \item If a bus implementation uses out-of-band signaling, it MUST also relay + or synthesize the corresponding transport message on the virtio-msg + channel. +\end{itemize} \msgdef{GET_DEVICE_INFO} From 2359b9191c8caedc8e002c19b95f85854a6a147b Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Wed, 25 Feb 2026 11:56:11 +0100 Subject: [PATCH 38/56] virtio-msg: propose UUID in GET_DEVICE_INFO (Parav Pandit) Proposal: extend GET_DEVICE_INFO with a 16-byte device_uuid field so a device can provide a unique identifier when available. If UUID reporting is not supported, or the device has no identifier, the device returns the nil UUID (all-zero value). Drivers interpret the nil UUID as "no UUID provided". Because this increases the fixed GET_DEVICE_INFO response size, raise the transport minimum advertised message size from 48 to 52 bytes and update the revision size table accordingly. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 2701756..1f67d55 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -216,7 +216,7 @@ \subsubsection{Transport Revisions and Maximum Message Size} \hline \field{revision} & \field{maximum size} & \field{features} & remarks \\ \hline \hline -1 & 48-65536 & & Virtio Message Revision 1 \\ +1 & 52-65536 & & Virtio Message Revision 1 \\ \hline \end{tabular} @@ -237,7 +237,7 @@ \subsubsection{Transport Revisions and Maximum Message Size} \busnormative{\paragraph}{Message Size Bounds}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Revisions / Message Size} \begin{itemize} \item A bus implementation MUST advertise a maximum message size of at least - 48 bytes. + 52 bytes. \item A bus implementation SHOULD NOT advertise a maximum message size that exceeds 264 bytes (256-byte payload plus the common header). \end{itemize} @@ -1091,8 +1091,10 @@ \subsubsection{Overview} \msgdef{GET_DEVICE_INFO} The driver issues \msgref{GET_DEVICE_INFO} to discover static identification -data and limits for a device. It is the only transport message permitted before -the device transitions out of the inactive state. +data and limits for a device. The response includes \field{device_uuid}, a +16-byte UUID value. The nil UUID (all bytes set to zero) indicates that no +UUID is provided. \msgref{GET_DEVICE_INFO} is the only transport message +permitted before the device transitions out of the inactive state. \begin{lstlisting} struct virtio_msg_get_device_info_req { @@ -1102,6 +1104,7 @@ \subsubsection{Overview} struct virtio_msg_get_device_info_resp { le32 device_id; /* virtio device type */ le32 vendor_id; /* implementation-defined vendor ID */ + u8 device_uuid[16]; /* UUID, or nil UUID if unavailable */ 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 */ @@ -1115,6 +1118,10 @@ \subsubsection{Overview} \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. + \item A device MAY set \field{device_uuid} to a UUID value that can be used + as a unique identifier. + \item If a device does not support UUID reporting or does not have an + identifier, it MUST set \field{device_uuid} to the nil UUID. \end{itemize} \drivernormative{\paragraph}{GET\_DEVICE\_INFO}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_DEVICE_INFO / Driver} @@ -1122,6 +1129,8 @@ \subsubsection{Overview} \item A driver SHOULD treat the response as the authoritative source for feature count, configuration size, and virtqueue limits before proceeding with initialization. + \item A driver MUST interpret a nil UUID in \field{device_uuid} as indicating + that no UUID is provided. \end{itemize} \msgdef{GET_DEVICE_FEATURES} From 1cc53be9607e43129b971d85bcf23be3a44fce04 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Wed, 25 Feb 2026 13:10:07 +0100 Subject: [PATCH 39/56] virtio-msg: widen header msg_size and dev_num fields Proposal: update the common virtio-msg header to use `le32 msg_size` and `le64 dev_num`, and move `dev_num` to the end of the header so the new 16-byte layout keeps fields naturally aligned. This updates header semantics and size-related limits accordingly, and propagates 64-bit device numbers into bus message payloads that carry device numbers (GET_DEVICES and EVENT_DEVICE). GET_DEVICES response field order is adjusted to keep 64-bit fields aligned. Related review discussion in mail threads: - Parav Pandit (device-number width and msg_size concerns) - Demi Marie Obenour (larger unique device identifiers) - Peter Hilber (device-number reuse/race concerns) Signed-off-by: Bertrand Marquis --- transport-msg.tex | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 1f67d55..ef940f5 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -160,8 +160,8 @@ \subsubsection{Transport Revisions and Maximum Message Size} \begin{itemize} \item \textbf{Transport revision}: the protocol version supported by the bus instance (independent of the overall Virtio specification version). - \item \textbf{Maximum message size}: the largest payload (in bytes) that can - be carried per request or response, including the common header. + \item \textbf{Maximum message size}: the largest message size (in bytes) that + can be carried per request or response, including the common header. \item \textbf{Transport feature bits}: revision-specific optional features implemented by the bus instance. \end{itemize} @@ -216,18 +216,18 @@ \subsubsection{Transport Revisions and Maximum Message Size} \hline \field{revision} & \field{maximum size} & \field{features} & remarks \\ \hline \hline -1 & 52-65536 & & Virtio Message Revision 1 \\ +1 & 60-65536 & & Virtio Message Revision 1 \\ \hline \end{tabular} The table reflects the protocol-defined maximum size; the recommended -advertised maximum remains 264 bytes for interoperability. +advertised maximum remains 272 bytes for interoperability. Note that a change in the virtio standard does not necessarily correspond to a change in the virtio-msg transport revision. The maximum message size is specified from the transport-layer point of view -and includes the 8-byte common header plus payload. Any extra encapsulation +and includes the 16-byte common header plus payload. Any extra encapsulation imposed by the underlying bus (for example, a framing header) does not count against this limit. Today the largest practical transport payload is 256 bytes: messages such as GET_CONFIG and SET_CONFIG can carry up to 256 bytes of device @@ -237,9 +237,9 @@ \subsubsection{Transport Revisions and Maximum Message Size} \busnormative{\paragraph}{Message Size Bounds}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Revisions / Message Size} \begin{itemize} \item A bus implementation MUST advertise a maximum message size of at least - 52 bytes. + 60 bytes. \item A bus implementation SHOULD NOT advertise a maximum message size that - exceeds 264 bytes (256-byte payload plus the common header). + exceeds 272 bytes (256-byte payload plus the common header). \end{itemize} \paragraph{Versioning and Forward Compatibility} @@ -283,7 +283,7 @@ \subsubsection{Device Numbers and Enumeration} Device Numbers} Each virtio-msg bus instance contains zero or more \emph{devices}, identified -by a 16-bit \textbf{device number}. The device number is a bus-assigned +by a 64-bit \textbf{device number}. The device number is a bus-assigned identifier and is distinct from the virtio device ID (device type) returned by \msgref{GET_DEVICE_INFO}. Buses discover these device numbers through mechanisms such as: @@ -449,7 +449,7 @@ \subsubsection{Common Message Format} \label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Common Message Format} All virtio-msg exchanges, whether \emph{bus messages} or \emph{transport -messages}, begin with an 8-byte header followed by an optional payload. The +messages}, begin with a 16-byte header followed by an optional payload. The fields below describe the wire format for that header. The header layout is: @@ -457,9 +457,9 @@ \subsubsection{Common Message Format} struct virtio_msg_header { u8 type; /* request/response + bus/transport */ u8 msg_id; /* message id */ - le16 dev_num; /* device number (0 for bus messages) */ le16 token; /* bus-managed correlation identifier */ - le16 msg_size; /* total size: header (8) + payload */ + le32 msg_size; /* total size: header (16) + payload */ + le64 dev_num; /* device number (0 for bus messages) */ u8 payload[]; }; \end{lstlisting} @@ -477,13 +477,13 @@ \subsubsection{Common Message Format} \ref{sec:Virtio Transport Options / Virtio Over Messages / Transport Messages} and \ref{sec:Virtio Transport Options / Virtio Over Messages / Bus Messages}. - \item \field{dev_num}: For transport messages, the device number that should - receive the message. Bus messages operate on device number 0. \item \field{token}: Correlation identifier managed by the bus. Drivers and devices treat this field as opaque; the bus MAY overwrite it to track outstanding requests or maintain ordering. \item \field{msg_size}: Total size in bytes of the complete message (header plus payload). + \item \field{dev_num}: For transport messages, the device number that should + receive the message. Bus messages operate on device number 0. \item \field{payload}: Operation-specific data. If a bus introduces extra padding bytes, those bytes are not part of the payload semantics. \end{itemize} @@ -1607,14 +1607,14 @@ \subsubsection{Overview} \begin{lstlisting} struct virtio_bus_msg_get_devices_req { - le16 offset; /* starting device number */ + le64 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 */ + le64 offset; /* echoed starting device number */ + le64 next_offset; /* 0 or suggested start for next query */ 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} @@ -1684,7 +1684,7 @@ \subsubsection{Overview} \begin{lstlisting} struct virtio_bus_msg_event_device { - le16 device_number; + le64 device_number; le16 device_bus_state; /* see table below */ }; \end{lstlisting} From ab4b48d3bcbe0f7f2372bb798fddaafb592c8f41 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Wed, 25 Feb 2026 13:32:53 +0100 Subject: [PATCH 40/56] virtio-msg: recommend delaying device-number reuse (Peter Hilber) Add a bus-level recommendation in Device Number Assignment to prevent immediate reuse of a device number after device removal. This is specified as SHOULD (not MUST) to avoid hard policy requirements while still reducing race conditions with delayed messages associated with the removed device. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 3 +++ 1 file changed, 3 insertions(+) diff --git a/transport-msg.tex b/transport-msg.tex index ef940f5..3ffb17f 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -303,6 +303,9 @@ \subsubsection{Device Numbers and Enumeration} \begin{itemize} \item A bus implementation MUST assign a unique device number to every device on a given bus instance. + \item A bus implementation SHOULD prevent reuse of a device number + immediately after a device is removed, to reduce race conditions with + delayed messages associated with the removed device. \item A bus implementation SHOULD provide the driver with sufficient information—either via \busref{GET_DEVICES} or equivalent platform data—to discover each valid device number. From bf520b5ed8c3306211dc4cd1bc25c35f1e342673 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Wed, 25 Feb 2026 14:10:27 +0100 Subject: [PATCH 41/56] virtio-msg: add flags-based SET_VQUEUE updates and queue state (Peter Hilber) Extend GET_VQUEUE and SET_VQUEUE to carry queue state and update control via a flags field. For GET_VQUEUE, replace the reserved field with flags bit0 to report the queue enabled state (bits[31:1] reserved zero). For SET_VQUEUE, replace reserved0 with flags: - bits[1:0]: queue state operation (disable, enable, keep, reserved) - bits[5:2]: per-field ignore bits for size/desc_addr/driver_addr/device_addr - bits[31:6]: reserved zero Define flags==0 as legacy behavior (disable + apply all queue fields). Add normative rules for valid flag values, atomic apply-or-reject processing, and driver-side verification through GET_VQUEUE when confirmation is required (SET_VQUEUE response has no payload). Signed-off-by: Bertrand Marquis --- transport-msg.tex | 106 ++++++++++++++++++++++++++++++++++------------ 1 file changed, 78 insertions(+), 28 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 3ffb17f..8a5657f 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -735,16 +735,20 @@ \subsubsection{Virtqueue Configuration} \msgref{SET_VQUEUE}, and optionally reset them using \msgref{RESET_VQUEUE} (if VIRTIO\_F\_RING\_RESET is negotiated). Each queue is typically configured by reading its maximum size, provisioning descriptor/available/used buffers, and -then calling \msgref{SET_VQUEUE} with the chosen size and physical -addresses. +then calling \msgref{SET_VQUEUE} with the chosen size, physical addresses, and +queue-state operation in \field{flags}. \drivernormative{\paragraph}{Virtqueue Configuration}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Virtqueue Configuration / Driver} \begin{itemize} \item A driver MUST use \msgref{GET_VQUEUE} to determine the maximum queue - size and confirm that a queue is inactive before programming it. - \item A driver MUST ensure the queue size provided in \msgref{SET_VQUEUE} does - not exceed the maximum reported by the device and MUST supply valid - descriptor/driver/device physical addresses before enabling the queue. + size and current queue state before programming it. + \item A driver MUST set \msgref{SET_VQUEUE} \field{flags} according to the + desired queue-state operation and field-update behavior. + \item If a driver updates queue size via \msgref{SET_VQUEUE}, it MUST ensure + the requested size does not exceed the maximum reported by the device. + \item If a driver updates queue addresses via \msgref{SET_VQUEUE}, it MUST + supply valid descriptor/driver/device physical addresses for each + updated field. \item If VIRTIO\_F\_RING\_RESET has been negotiated and a queue requires reinitialization, the driver SHOULD use \msgref{RESET_VQUEUE} before reprogramming it. @@ -753,8 +757,11 @@ \subsubsection{Virtqueue Configuration} \devicenormative{\paragraph}{Virtqueue Configuration}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Virtqueue Configuration / Device} \begin{itemize} \item A device MUST report accurate maximum queue sizes in \msgref{GET_VQUEUE} - and MUST persist the parameters supplied via \msgref{SET_VQUEUE} (size, - descriptor, driver, and device physical addresses). + and MUST report accurate current queue size and enabled state. + \item A device MUST persist the parameters supplied via \msgref{SET_VQUEUE} + for fields not marked ignored by \field{flags}. + \item A device MUST update queue state according to the + \msgref{SET_VQUEUE} \field{flags} state-operation bits. \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. @@ -919,20 +926,22 @@ \subsubsection{Virtqueue Changes During Operation} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / Virtqueue Changes During Operation} Drivers may provision unused virtqueues later in the device lifetime by issuing -\msgref{SET_VQUEUE}, and they may reconfigure existing queues if the +\msgref{SET_VQUEUE}, and they may reconfigure existing queues or update queue +state if the VIRTIO\_F\_RING\_RESET feature has been negotiated. \drivernormative{\paragraph}{Runtime Virtqueue Changes}{Virtio Transport Options / Virtio Over Messages / Device Operation / Virtqueue Changes During Operation / Driver} \begin{itemize} - \item A driver MAY configure additional virtqueues after initialization using - \msgref{SET_VQUEUE}, provided it follows the same validation steps - (e.g., checking the maximum queue size). + \item A driver MAY configure additional virtqueues and update selected + virtqueue fields after initialization using \msgref{SET_VQUEUE}, + provided it follows the same validation steps. \end{itemize} \devicenormative{\paragraph}{Runtime Virtqueue Changes}{Virtio Transport Options / Virtio Over Messages / Device Operation / Virtqueue Changes During Operation / Device} \begin{itemize} \item A device MUST honor \msgref{SET_VQUEUE} requests issued after - initialization and update the queue parameters accordingly. + initialization and update queue parameters and queue state according to + \field{flags}. \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. @@ -1326,8 +1335,8 @@ \subsubsection{Overview} \msgdef{GET_VQUEUE} \msgref{GET_VQUEUE} returns information about a specific virtqueue, including -its maximum size, current size, and, if already configured, the descriptor, -driver, and device area physical addresses. +its maximum size, current size, enabled state, and, if already configured, the +descriptor, driver, and device area physical addresses. \begin{lstlisting} struct virtio_msg_get_vqueue_req { @@ -1338,7 +1347,7 @@ \subsubsection{Overview} le32 index; /* echoed virtqueue index */ le32 max_size; /* maximum queue size */ le32 cur_size; /* current size (0 if unconfigured) */ - le32 reserved; /* must be zero */ + le32 flags; /* bit0: enabled state, bits[31:1] reserved */ le64 desc_addr; /* descriptor area physical address */ le64 driver_addr; /* driver area physical address */ le64 device_addr; /* device area physical address */ @@ -1350,21 +1359,23 @@ \subsubsection{Overview} \item A device MUST report accurate maxima and current queue sizes for each virtqueue and MUST return zero as the current size if the queue has not yet been configured. + \item A device MUST report queue enabled state in \field{flags} bit 0 and + MUST set \field{flags} bits 31:1 to zero. \end{itemize} \msgdef{SET_VQUEUE} -\msgref{SET_VQUEUE} programs a virtqueue's size and physical addresses. The -driver selects a queue index, supplies the desired size (not exceeding the -maximum reported via \msgref{GET_VQUEUE}), and provides physical addresses for -the descriptor, driver, and device areas. +\msgref{SET_VQUEUE} updates a virtqueue's parameters and queue state. The +driver selects a queue index and uses \field{flags} to indicate whether queue +state should be enabled, disabled, or kept unchanged, and which queue fields +should be ignored versus updated. \begin{lstlisting} struct virtio_msg_set_vqueue_req { le32 index; /* virtqueue index */ - le32 reserved0; /* must be zero */ + le32 flags; /* state op + ignore bits */ le32 size; /* number of descriptors */ - le32 reserved1; /* must be zero */ + le32 reserved; /* must be zero */ le64 desc_addr; /* descriptor area physical address */ le64 driver_addr; /* driver area physical address */ le64 device_addr; /* device area physical address */ @@ -1375,18 +1386,57 @@ \subsubsection{Overview} }; \end{lstlisting} +\field{flags} is defined as: +\begin{itemize} + \item Bits [1:0] (\textbf{State Operation}): + \begin{itemize} + \item 0: disable queue. + \item 1: enable queue. + \item 2: keep current queue state. + \item 3: reserved. + \end{itemize} + \item Bit 2 (\textbf{size\_ignore}): 0=apply \field{size}, 1=ignore. + \item Bit 3 (\textbf{desc\_addr\_ignore}): 0=apply \field{desc_addr}, + 1=ignore. + \item Bit 4 (\textbf{driver\_addr\_ignore}): 0=apply \field{driver_addr}, + 1=ignore. + \item Bit 5 (\textbf{device\_addr\_ignore}): 0=apply \field{device_addr}, + 1=ignore. + \item Bits [31:6]: reserved, MUST be zero. +\end{itemize} + +When \field{flags} is zero, \msgref{SET_VQUEUE} uses current behavior: +the queue is disabled and all queue fields in the request are applied. + \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 - physical addresses point to properly aligned memory. + \item A driver MUST set \field{reserved} to zero and MUST set \field{flags} + bits [31:6] to zero. + \item A driver MUST NOT use state operation value 3 in \field{flags} bits + [1:0]. + \item If \field{size\_ignore} is 0, a driver MUST set \field{size} to a value + not exceeding the maximum reported by \msgref{GET_VQUEUE}. + \item If any address ignore bit is 0, a driver MUST ensure the corresponding + physical address points to properly aligned memory. + \item Because \msgref{SET_VQUEUE} has no response payload, a driver that + needs confirmation of acceptance MUST verify the resulting queue + parameters and state via \msgref{GET_VQUEUE} before relying on the + requested updates. \end{itemize} \devicenormative{\paragraph}{SET\_VQUEUE}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_VQUEUE / Device} \begin{itemize} - \item A device MUST configure the queue using the parameters provided via - \msgref{SET_VQUEUE} and treat the queue as inactive until - \msgref{SET_VQUEUE} has successfully completed. + \item A device MUST reject \msgref{SET_VQUEUE} if \field{reserved} is nonzero, + if \field{flags} bits [31:6] are nonzero, or if \field{flags} bits [1:0] + use state operation value 3. + \item A device MUST process \msgref{SET_VQUEUE} updates atomically: it MUST + either apply all requested field updates and queue-state changes, or + reject the request without applying any of them. + \item If an ignore bit is 0, a device MUST apply the corresponding field from + \msgref{SET_VQUEUE}; if an ignore bit is 1, a device MUST keep the + current value for that field unchanged. + \item A device MUST apply queue state according to \field{flags} bits [1:0] + after processing requested field updates. \end{itemize} \msgdef{RESET_VQUEUE} From d201a320af5b209c3d8f006059010b54428417cc Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Wed, 25 Feb 2026 14:39:50 +0100 Subject: [PATCH 42/56] virtio-msg: clarify reset completion checks for SET_DEVICE_STATUS (Peter Hilber) Clarify reset semantics so SET_DEVICE_STATUS(0) supports both synchronous and asynchronous completion without ambiguity. Define that a SET_DEVICE_STATUS response with status==0 indicates reset completion, while a non-zero status may mean completion is still pending. Require drivers that need confirmation to poll GET_DEVICE_STATUS until status==0 before reinitialization, and require devices to report status 0 only after reset completion. Align the Status Information and Device Reset/Shutdown sections with the same completion model to avoid contradictory immediate-reset wording. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 49 +++++++++++++++++++++++++++++++---------------- 1 file changed, 33 insertions(+), 16 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 8a5657f..537964d 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -772,8 +772,8 @@ \subsubsection{Status Information} Drivers query the device status via \msgref{GET_DEVICE_STATUS} to observe progress or detect errors, and they drive the Virtio status transitions via -\msgref{SET_DEVICE_STATUS}. Writing zero to the status field resets the device, -invalidating any configuration or virtqueue state. +\msgref{SET_DEVICE_STATUS}. Writing zero to the status field requests a device +reset, which can complete synchronously or asynchronously. \drivernormative{\paragraph}{Status Handling}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Status Information / Driver} \begin{itemize} @@ -788,8 +788,9 @@ \subsubsection{Status Information} \devicenormative{\paragraph}{Status Handling}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Status Information / Device} \begin{itemize} \item Upon receiving a \msgref{SET_DEVICE_STATUS} write of 0, a device MUST - reset its internal state, invalidate existing configuration and - virtqueue settings, and present the status field as 0. + start reset processing. The device MUST eventually invalidate existing + configuration and virtqueue settings, and MUST report status 0 only + after reset completion. \item A device MUST report its current status accurately via \msgref{GET_DEVICE_STATUS}, including whether the FEATURES\_OK bit has been accepted or cleared. @@ -950,16 +951,19 @@ \subsubsection{Virtqueue Changes During Operation} \subsubsection{Device Reset and Shutdown} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / Reset} -Drivers reset a device by writing 0 to the status field via \msgref{SET_DEVICE_STATUS}, -which forces the device to discard pending operations and return to the initial state. -A device may also signal that a reset is required by setting DEVICE\_NEEDS\_RESET -in its status and reporting the updated status to the driver. +Drivers request a device reset by writing 0 to the status field via +\msgref{SET_DEVICE_STATUS}. Reset completion can be synchronous or +asynchronous. A driver confirms completion from a +\msgref{SET_DEVICE_STATUS} response status of 0 or by polling +\msgref{GET_DEVICE_STATUS} until status is 0. A device may also signal that a +reset is required by setting DEVICE\_NEEDS\_RESET in its status and reporting +the updated status to the driver. \drivernormative{\paragraph}{Reset and Shutdown}{Virtio Transport Options / Virtio Over Messages / Device Operation / Reset / Driver} \begin{itemize} \item A driver MAY request a device reset at any time by writing 0 through - \msgref{SET_DEVICE_STATUS} and MAY reinitialize the device afterwards if - it intends to resume operation. + \msgref{SET_DEVICE_STATUS}. If the driver intends to resume operation, + it MAY reinitialize the device after reset completion. \item If DEVICE\_NEEDS\_RESET is reported in device status, the driver SHOULD write 0 to \msgref{SET_DEVICE_STATUS} and reinitialize the device before resuming I/O. @@ -968,8 +972,8 @@ \subsubsection{Device Reset and Shutdown} \devicenormative{\paragraph}{Reset and Shutdown}{Virtio Transport Options / Virtio Over Messages / Device Operation / Reset / Device} \begin{itemize} \item Upon receiving a \msgref{SET_DEVICE_STATUS} write of 0, a device MUST - reset its internal state, discard pending virtqueue operations, and - present the status field as 0. + start reset processing and eventually reset its internal state and + discard pending virtqueue operations. \item If the device encounters an unrecoverable error that requires driver intervention, it SHOULD set DEVICE\_NEEDS\_RESET in its status and ensure the updated status is reported to the driver. @@ -1305,8 +1309,11 @@ \subsubsection{Overview} \msgref{SET_DEVICE_STATUS} writes a new device status value. Drivers use it to progress through the virtio-defined states or to request a reset by writing 0. -The device responds with its resulting status, which may differ (for example, -if it refuses FEATURES\_OK or sets DEVICE\_NEEDS\_RESET). +The response reports the status value observed when the response is generated. +For a reset request (\field{status} == 0), a response status of 0 indicates +reset completion; a non-zero response status indicates that reset completion may +still be pending. The resulting status may differ from the requested status (for +example, if the device refuses FEATURES\_OK or sets DEVICE\_NEEDS\_RESET). \begin{lstlisting} struct virtio_msg_set_device_status_req { @@ -1321,8 +1328,11 @@ \subsubsection{Overview} \drivernormative{\paragraph}{SET\_DEVICE\_STATUS}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_DEVICE_STATUS / Driver} \begin{itemize} \item A driver MUST write 0 via \msgref{SET_DEVICE_STATUS} to request a device - reset and MUST re-read the status (e.g., via \msgref{GET_DEVICE_STATUS}) - if it needs to confirm acceptance. + reset. + \item A driver that needs to confirm reset completion MUST treat a + \msgref{SET_DEVICE_STATUS} response status of 0 as completion; + otherwise it MUST poll \msgref{GET_DEVICE_STATUS} until the device + reports status 0 before reinitializing the device. \end{itemize} \devicenormative{\paragraph}{SET\_DEVICE\_STATUS}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_DEVICE_STATUS / Device} @@ -1330,6 +1340,13 @@ \subsubsection{Overview} \item A device MAY clear FEATURES\_OK or set DEVICE\_NEEDS\_RESET in its response if it cannot accept the requested status, but it MUST report the resulting status accurately. + \item Upon receiving \msgref{SET_DEVICE_STATUS} with \field{status} set to 0, + a device MUST start reset processing and MUST eventually complete reset + by reporting status 0. + \item A device MAY complete reset before sending the + \msgref{SET_DEVICE_STATUS} response (synchronous completion) or after + sending it (asynchronous completion). + \item A device MUST NOT report status 0 until reset completion. \end{itemize} \msgdef{GET_VQUEUE} From 477c04abbc48665dc6c27c82ab445e9202db3f9c Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Wed, 25 Feb 2026 15:20:50 +0100 Subject: [PATCH 43/56] virtio-msg: make strict config generation optional (Peter Hilber) Proposal: gate strict configuration generation semantics behind a transport feature bit (VIRTIO_MSG_F_STRICT_CONFIG_GENERATION). When the feature is negotiated, keep strict generation behavior for GET_CONFIG/SET_CONFIG/EVENT_CONFIG. When it is not negotiated, generation fields are reserved: senders set them to 0 and receivers ignore them, and SET_CONFIG generation mismatch must not cause rejection. Keep EVENT_CONFIG as the required configuration/status change notification path, while allowing a simplified MMIO-like mode when strict generation is not negotiated (including generic offset/length=0 notifications). Signed-off-by: Bertrand Marquis --- transport-msg.tex | 228 +++++++++++++++++++++++++++++++--------------- 1 file changed, 154 insertions(+), 74 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 537964d..7e865a4 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -216,7 +216,7 @@ \subsubsection{Transport Revisions and Maximum Message Size} \hline \field{revision} & \field{maximum size} & \field{features} & remarks \\ \hline \hline -1 & 60-65536 & & Virtio Message Revision 1 \\ +1 & 60-65536 & bit 0 optional: \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} & Virtio Message Revision 1 \\ \hline \end{tabular} @@ -314,46 +314,62 @@ \subsubsection{Device Numbers and Enumeration} \subsubsection{Configuration Generation Count} \label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Generation Count} -Each device maintains a \textbf{Configuration Generation Count} to prevent -inconsistent updates. This count is incremented at least once by the device for -every driver-visible change it makes to its configuration data. The current -count is exposed in \msgref{EVENT_CONFIG} and \msgref{GET_CONFIG} responses so -the driver can determine whether its view of the configuration is current. The -count does not necessarily start at zero and MAY be reset when the device -resets or at other device-defined times. +Configuration generation behavior depends on transport feature negotiation. +When \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is negotiated, generation +count provides stale-write detection for configuration updates. When the +feature is not negotiated, generation fields in \msgref{GET_CONFIG}, +\msgref{SET_CONFIG}, and \msgref{EVENT_CONFIG} are reserved: senders set them +to 0 and receivers ignore them. \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 + \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is negotiated, a + device MUST increment generation count before it makes a + driver-visible configuration change and MUST ensure that each \msgref{EVENT_CONFIG} carrying configuration data uses a unique generation count since the most recent generation count reset. - \item A device MAY reset the generation count, including when it resets its - internal state. + \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is negotiated, a + device MAY reset generation count, including when it resets internal + state. \item If updated configuration data cannot fit in a single \msgref{EVENT_CONFIG}, the device SHOULD send an \msgref{EVENT_CONFIG} - without configuration data for the affected range (with offset/length - set to that range), 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. + without configuration data. If + \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is negotiated, the + device SHOULD set offset/length to the affected range; otherwise it MAY + set offset/length to zero. The device MUST make updated data available + via \msgref{GET_CONFIG}. + \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is negotiated and + a \msgref{SET_CONFIG} request includes a generation count that does not + match the device's current count, the device MUST reject the request. + \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is not negotiated, + a device MUST set generation to 0 in \msgref{GET_CONFIG} responses, + \msgref{SET_CONFIG} responses, and \msgref{EVENT_CONFIG} messages. + \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is not negotiated, + a device MUST ignore request generation in \msgref{SET_CONFIG} and MUST + NOT reject \msgref{SET_CONFIG} because of generation mismatch. \end{itemize} \drivernormative{\paragraph}{Configuration Generation Count}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Generation Count / Driver} \begin{itemize} - \item A driver MUST track the most recent generation count observed (via + \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is negotiated, 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 A driver MUST NOT assume the generation count is monotonic or preserved + \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is negotiated, a + driver MUST NOT assume generation count is monotonic or preserved across device resets. - \item If a \msgref{SET_CONFIG} request is rejected due to a mismatched - generation count, the driver SHOULD issue \msgref{GET_CONFIG} to obtain - the latest configuration data and generation count before retrying. + \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is negotiated and + a \msgref{SET_CONFIG} request is rejected due to a mismatched generation + count, the driver SHOULD issue \msgref{GET_CONFIG} to obtain the latest + configuration data and generation count before retrying. + \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is not negotiated, + a driver MUST set request generation to 0 in \msgref{SET_CONFIG} and + MUST ignore generation fields in \msgref{GET_CONFIG}, + \msgref{SET_CONFIG}, and \msgref{EVENT_CONFIG}. \end{itemize} -This mechanism ensures updates are not lost or overwritten due to stale -information. +This provides strict stale-write detection when negotiated while preserving a +simpler MMIO-like notification flow when not negotiated. \subsubsection{Feature Negotiation Blocks} \label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Feature Blocks} @@ -371,6 +387,20 @@ \subsubsection{Feature Negotiation Blocks} driver-requested) feature bits in the selected blocks. \end{itemize} +Transport-defined feature bits currently include: + +\begin{tabular}{|l|l|p{7cm}|} +\hline +Bit & Name & Meaning \\ +\hline +0 & \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} & +Enable strict configuration generation validation for +\msgref{GET_CONFIG}, \msgref{SET_CONFIG}, and \msgref{EVENT_CONFIG}. When this +feature is not negotiated, generation fields are reserved and MUST be sent as 0 +and ignored on receive. \\ +\hline +\end{tabular} + \devicenormative{\paragraph}{Feature Blocks}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Feature Blocks / Device} \begin{itemize} \item When \msgref{GET_DEVICE_FEATURES} covers blocks that extend beyond the @@ -617,8 +647,8 @@ \subsubsection{Initialization Flow Overview} updating the device status. \item \textbf{Initialize Configuration Space:} Read or write configuration data with - \msgref{GET_CONFIG}/\msgref{SET_CONFIG}, guarding updates with the - configuration generation count. + \msgref{GET_CONFIG}/\msgref{SET_CONFIG}, using generation validation when + \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is negotiated. \item \textbf{Set Up Virtqueues:} Configure each virtqueue via \msgref{SET_VQUEUE} and verify the settings with \msgref{GET_VQUEUE}. @@ -699,9 +729,10 @@ \subsubsection{Device Configuration} Drivers use \msgref{GET_CONFIG} to read portions of the configuration space by supplying an offset and length; the device returns the requested data plus the -current configuration generation count. Writing is performed via -\msgref{SET_CONFIG}, which carries the same offset/length along with the -driver's notion of the generation count and the new data. +configuration generation field. Writing is performed via \msgref{SET_CONFIG}, +which carries the same offset/length plus generation and new data. Generation +validation applies only when +\texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is negotiated. Configuration space is intended for device control and configuration data. When a device can instead expose data through a virtqueue, that mechanism is @@ -713,19 +744,30 @@ \subsubsection{Device Configuration} \item A driver MUST ensure that the offset and length in each \msgref{GET_CONFIG} or \msgref{SET_CONFIG} request stay within the configuration size reported by \msgref{GET_DEVICE_INFO}. - \item A driver MUST include its most recently observed configuration - generation count in a \msgref{SET_CONFIG} request and SHOULD re-read the - configuration (via \msgref{GET_CONFIG}) if the request is rejected for a - generation mismatch. + \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is negotiated, a + driver MUST include its most recently observed configuration generation + count in \msgref{SET_CONFIG} and SHOULD re-read configuration (via + \msgref{GET_CONFIG}) if the request is rejected for generation + mismatch. + \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is not negotiated, + a driver MUST set \field{generation} to 0 in \msgref{SET_CONFIG}. \end{itemize} \devicenormative{\paragraph}{Device Configuration}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Configuration / Device} \begin{itemize} - \item A device MUST reject a \msgref{SET_CONFIG} request whose generation - count does not match its current value and MUST indicate the rejection - in the response. - \item A device MUST return the current configuration generation count - alongside any data returned via \msgref{GET_CONFIG}. + \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is negotiated, a + device MUST reject a \msgref{SET_CONFIG} request whose generation count + does not match its current value and MUST indicate rejection in the + response. + \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is not negotiated, + a device MUST ignore request generation and MUST NOT reject + \msgref{SET_CONFIG} because of generation mismatch. + \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is negotiated, a + device MUST return current configuration generation in + \msgref{GET_CONFIG} and \msgref{SET_CONFIG} responses. + \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is not negotiated, + a device MUST return generation as 0 in \msgref{GET_CONFIG} and + \msgref{SET_CONFIG} responses. \end{itemize} \subsubsection{Virtqueue Configuration} @@ -870,9 +912,15 @@ \subsubsection{Device Notifications} \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 use \msgref{EVENT_CONFIG} to notify - the driver of configuration changes or status updates. The message MUST - include the new configuration generation count and the affected - offset/length, and MAY include the updated configuration data. + the driver of configuration changes or status updates. + \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is negotiated, + \msgref{EVENT_CONFIG} MUST include the new configuration generation + count and the affected offset/length, and MAY include updated + configuration data. + \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is not negotiated, + \msgref{EVENT_CONFIG} generation MUST be 0. The device MAY set + offset/length to 0 to indicate a generic configuration-change + notification and MAY include updated configuration data. \item A device MUST use \msgref{EVENT_USED} to notify the driver of used buffers on a virtqueue, unless the device relies on polling or another agreed-upon completion mechanism. @@ -881,8 +929,10 @@ \subsubsection{Device Notifications} \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 - \msgref{GET_CONFIG} if necessary) before resuming normal I/O. + the configuration using provided data. If data is not provided, the + driver SHOULD re-read the affected range via \msgref{GET_CONFIG}; if + offset/length are both zero, the driver SHOULD re-read the required + configuration via \msgref{GET_CONFIG} 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. @@ -908,9 +958,11 @@ \subsubsection{Configuration Changes During Operation} \drivernormative{\paragraph}{Runtime Configuration}{Virtio Transport Options / Virtio Over Messages / Device Operation / Configuration Changes During Operation / Driver} \begin{itemize} - \item A driver MAY issue \msgref{SET_CONFIG} after initialization, provided it - includes the current configuration generation count and follows the same - validation rules as during setup. + \item A driver MAY issue \msgref{SET_CONFIG} after initialization, following + the same validation rules as during setup. If + \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is negotiated, the + driver includes current generation count; otherwise it sets generation + to 0. \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. @@ -919,8 +971,10 @@ \subsubsection{Configuration Changes During Operation} \devicenormative{\paragraph}{Runtime Configuration}{Virtio Transport Options / Virtio Over Messages / Device Operation / Configuration Changes During Operation / Device} \begin{itemize} \item If a device updates its configuration after initialization, it MUST send - \msgref{EVENT_CONFIG} to inform the driver of the change and provide the - new configuration generation count. + \msgref{EVENT_CONFIG} to inform the driver of the change. If + \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is negotiated, the + message MUST provide new configuration generation count; otherwise it + MUST set generation to 0. \end{itemize} \subsubsection{Virtqueue Changes During Operation} @@ -1216,7 +1270,9 @@ \subsubsection{Overview} \msgref{GET_CONFIG} reads a portion of the configuration space. The request specifies the byte offset and length; the response echoes those values, returns -the data, and includes the current configuration generation count. +the data, and includes generation. If +\texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is not negotiated, generation +is reserved and MUST be 0. \begin{lstlisting} struct virtio_msg_get_config_req { @@ -1225,7 +1281,7 @@ \subsubsection{Overview} }; struct virtio_msg_get_config_resp { - le32 generation; /* current configuration generation count */ + le32 generation; /* generation count, or 0 if not negotiated */ le32 offset; /* echoed offset */ le32 length; /* echoed length */ u8 data[]; /* configuration payload */ @@ -1240,8 +1296,12 @@ \subsubsection{Overview} \devicenormative{\paragraph}{GET\_CONFIG}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_CONFIG / Device} \begin{itemize} - \item A device MUST return the current configuration generation count with - every \msgref{GET_CONFIG} response. + \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is negotiated, a + device MUST return current configuration generation count with every + \msgref{GET_CONFIG} response. + \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is not negotiated, + a device MUST return \field{generation} as 0 in every + \msgref{GET_CONFIG} response. \end{itemize} \msgdef{SET_CONFIG} @@ -1250,18 +1310,19 @@ \subsubsection{Overview} offset, length, the driver's view of the generation count, and the new data. The device echoes the offset/length, returns the resulting generation count, and may mirror the applied data or set the length to zero if the write was -rejected. +rejected. If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is not +negotiated, generation is reserved and MUST be 0. \begin{lstlisting} struct virtio_msg_set_config_req { - le32 generation; /* driver's view of generation count */ + le32 generation; /* driver's view, or 0 if not negotiated */ le32 offset; /* byte offset being written */ le32 length; /* number of bytes written */ u8 data[]; /* configuration payload */ }; struct virtio_msg_set_config_resp { - le32 generation; /* resulting generation count */ + le32 generation; /* resulting count, or 0 if not negotiated */ le32 offset; /* echoed offset */ le32 length; /* bytes applied (0 if rejected) */ u8 data[]; /* optional echoed data */ @@ -1270,16 +1331,28 @@ \subsubsection{Overview} \drivernormative{\paragraph}{SET\_CONFIG}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_CONFIG / Driver} \begin{itemize} - \item A driver MUST include its most recent configuration generation count in - each \msgref{SET_CONFIG} request and MUST keep the offset and length - within the reported configuration size. + \item A driver MUST keep the offset and length within the reported + configuration size in each \msgref{SET_CONFIG} request. + \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is negotiated, a + driver MUST include its most recent configuration generation count in + each \msgref{SET_CONFIG} request. + \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is not negotiated, + a driver MUST set \field{generation} to 0 in each \msgref{SET_CONFIG} + request. \end{itemize} \devicenormative{\paragraph}{SET\_CONFIG}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_CONFIG / Device} \begin{itemize} - \item A device MUST reject a \msgref{SET_CONFIG} request if the supplied - generation count does not match its current value and MUST report that - rejection in the response. + \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is negotiated, a + device MUST reject a \msgref{SET_CONFIG} request if supplied generation + does not match its current value and MUST report rejection in the + response. + \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is not negotiated, + a device MUST ignore supplied generation and MUST NOT reject + \msgref{SET_CONFIG} due to generation mismatch. + \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is not negotiated, + a device MUST return \field{generation} as 0 in + \msgref{SET_CONFIG} responses. \end{itemize} \msgdef{GET_DEVICE_STATUS} @@ -1518,16 +1591,17 @@ \subsubsection{Overview} \msgdef{EVENT_CONFIG} \msgref{EVENT_CONFIG} notifies the driver about configuration or status changes. -The payload includes the current device status, configuration generation count, -and the affected configuration offset/length. The configuration data MAY be -omitted; if it is omitted, the driver should re-fetch the affected range via -\msgref{GET_CONFIG}. If the event reports only a status change with no -configuration update, the device sets the offset and length fields to zero. +The payload includes current device status, generation, and +configuration offset/length. The configuration data MAY be omitted; if omitted, +the driver re-fetches via \msgref{GET_CONFIG}. If +\texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is not negotiated, generation +is reserved and MUST be 0. If the event reports only a status change with no +configuration update, the device sets offset and length to zero. \begin{lstlisting} struct virtio_msg_event_config { le32 device_status; /* new device status value */ - le32 generation; /* configuration generation count */ + le32 generation; /* generation count, or 0 if not negotiated */ le32 offset; /* configuration offset */ le32 length; /* number of bytes in affected range */ u8 data[]; /* optional configuration data */ @@ -1538,17 +1612,23 @@ \subsubsection{Overview} \begin{itemize} \item When \msgref{EVENT_CONFIG} provides configuration data, the driver SHOULD apply it; otherwise it SHOULD re-read the affected range - indicated by the offset/length via \msgref{GET_CONFIG} before - proceeding. + indicated by offset/length via \msgref{GET_CONFIG}. If offset/length + are both zero, the driver SHOULD re-read required configuration via + \msgref{GET_CONFIG} before proceeding. + \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is not negotiated, + a driver MUST ignore \field{generation} in \msgref{EVENT_CONFIG}. \end{itemize} \devicenormative{\paragraph}{EVENT\_CONFIG}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_CONFIG / Device} \begin{itemize} \item A device MUST send \msgref{EVENT_CONFIG} whenever it changes - configuration data or status in a way that is visible to the driver, - including the new configuration generation count. - \item A device MUST set the offset/length fields to describe the affected - configuration range, whether or not the configuration data is included. + configuration data or status in a way that is visible to the driver. + \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is negotiated, a + device MUST include the new configuration generation count and MUST set + offset/length to describe the affected configuration range. + \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is not negotiated, + a device MUST set \field{generation} to 0 and MAY set offset/length to + zero for generic configuration-change notifications. \item If \msgref{EVENT_CONFIG} reports only a status change, a device MUST set the offset and length fields to zero. \end{itemize} From e990c04119785751eb5114772e84082ed90c6c59 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Wed, 25 Feb 2026 15:35:10 +0100 Subject: [PATCH 44/56] virtio-msg: centralize config semantics profiles (Peter Hilber) Proposal: describe baseline and strict configuration-generation behavior in one dedicated "Configuration Semantics Profiles" subsection and reference it from GET_CONFIG/SET_CONFIG/EVENT_CONFIG and related runtime sections. This keeps the non-strict (baseline) behavior explicit, reduces repeated conditional wording across message definitions, and makes it clearer why the baseline model matches MMIO-like config-change notification flow. Signed-off-by: Bertrand Marquis --- conformance.tex | 4 +- transport-msg.tex | 261 +++++++++++++++++++++------------------------- 2 files changed, 120 insertions(+), 145 deletions(-) diff --git a/conformance.tex b/conformance.tex index 12c65c0..7fb57ee 100644 --- a/conformance.tex +++ b/conformance.tex @@ -155,7 +155,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \begin{itemize} \item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Revisions / Driver Limits} \item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Versioning and Forward Compatibility / Driver} -\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Generation Count / Driver} +\item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles / Driver} \item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Endianness / Driver} \item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Common Message Format / Driver} \item \ref{drivernormative:Virtio Transport Options / Virtio Over Messages / Device Initialization / Overview / Driver} @@ -285,7 +285,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \begin{itemize} \item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Revisions / Device Limits} \item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Versioning and Forward Compatibility / Device} -\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Generation Count / Device} +\item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles / Device} \item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Feature Blocks / Device} \item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Error Signaling / Device} \item \ref{devicenormative:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Endianness / Device} diff --git a/transport-msg.tex b/transport-msg.tex index 7e865a4..08d5a93 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -311,65 +311,72 @@ \subsubsection{Device Numbers and Enumeration} data—to discover each valid device number. \end{itemize} -\subsubsection{Configuration Generation Count} -\label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Generation Count} +\subsubsection{Configuration Semantics Profiles} +\label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles} -Configuration generation behavior depends on transport feature negotiation. -When \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is negotiated, generation -count provides stale-write detection for configuration updates. When the -feature is not negotiated, generation fields in \msgref{GET_CONFIG}, -\msgref{SET_CONFIG}, and \msgref{EVENT_CONFIG} are reserved: senders set them -to 0 and receivers ignore them. - -\devicenormative{\paragraph}{Configuration Generation Count}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Generation Count / Device} +virtio-msg defines two configuration semantics profiles selected by transport +feature negotiation: \begin{itemize} - \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is negotiated, a - device MUST increment generation count before it makes a - driver-visible configuration change and MUST ensure that each + \item \textbf{Baseline profile}: applies when + \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is not negotiated. + \item \textbf{Strict profile}: applies when + \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is negotiated. +\end{itemize} + +The profiles apply to \msgref{GET_CONFIG}, \msgref{SET_CONFIG}, and +\msgref{EVENT_CONFIG}. + +\drivernormative{\paragraph}{Configuration Semantics Profiles}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles / Driver} +\begin{itemize} + \item A driver MUST determine the active profile before issuing + \msgref{SET_CONFIG}. + \item In baseline profile, a driver MUST set \field{generation} to 0 in + \msgref{SET_CONFIG} requests and MUST ignore \field{generation} in + \msgref{GET_CONFIG}, \msgref{SET_CONFIG}, and \msgref{EVENT_CONFIG}. + \item In baseline profile, upon \msgref{EVENT_CONFIG}, a driver SHOULD refresh + required configuration via \msgref{GET_CONFIG} when event data is + omitted or when offset/length are zero. + \item In strict profile, a driver MUST track generation values from + \msgref{GET_CONFIG}/\msgref{EVENT_CONFIG} and MUST include its most + recent generation value in \msgref{SET_CONFIG}. + \item In strict profile, if a \msgref{SET_CONFIG} request is rejected due to a + mismatched generation count, a driver SHOULD issue \msgref{GET_CONFIG} + to obtain the latest configuration data and generation count before + retrying. + \item In strict profile, a driver MUST NOT assume generation count is + monotonic or preserved across device resets. +\end{itemize} + +\devicenormative{\paragraph}{Configuration Semantics Profiles}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles / Device} +\begin{itemize} + \item In baseline profile, a device MUST set \field{generation} to 0 in + \msgref{GET_CONFIG}, \msgref{SET_CONFIG}, and \msgref{EVENT_CONFIG}. + \item In baseline profile, a device MUST ignore request \field{generation} in + \msgref{SET_CONFIG} and MUST NOT reject \msgref{SET_CONFIG} due to + generation mismatch. + \item In baseline profile, a device MAY set \field{offset}/\field{length} to + zero in \msgref{EVENT_CONFIG} to indicate a generic + configuration-change notification. + \item In strict profile, a device MUST increment generation count before it + makes a driver-visible configuration change and MUST ensure that each \msgref{EVENT_CONFIG} carrying configuration data uses a unique generation count since the most recent generation count reset. - \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is negotiated, a - device MAY reset generation count, including when it resets internal - state. + \item In strict profile, a device MAY reset generation count, including when + it resets internal state. + \item In strict profile, if a \msgref{SET_CONFIG} request includes a + generation count that does not match the device's current count, the + device MUST reject the request. \item If updated configuration data cannot fit in a single - \msgref{EVENT_CONFIG}, the device SHOULD send an \msgref{EVENT_CONFIG} - without configuration data. If - \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is negotiated, the - device SHOULD set offset/length to the affected range; otherwise it MAY - set offset/length to zero. The device MUST make updated data available - via \msgref{GET_CONFIG}. - \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is negotiated and - a \msgref{SET_CONFIG} request includes a generation count that does not - match the device's current count, the device MUST reject the request. - \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is not negotiated, - a device MUST set generation to 0 in \msgref{GET_CONFIG} responses, - \msgref{SET_CONFIG} responses, and \msgref{EVENT_CONFIG} messages. - \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is not negotiated, - a device MUST ignore request generation in \msgref{SET_CONFIG} and MUST - NOT reject \msgref{SET_CONFIG} because of generation mismatch. -\end{itemize} - -\drivernormative{\paragraph}{Configuration Generation Count}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Generation Count / Driver} -\begin{itemize} - \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is negotiated, 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 \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is negotiated, a - driver MUST NOT assume generation count is monotonic or preserved - across device resets. - \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is negotiated and - a \msgref{SET_CONFIG} request is rejected due to a mismatched generation - count, the driver SHOULD issue \msgref{GET_CONFIG} to obtain the latest - configuration data and generation count before retrying. - \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is not negotiated, - a driver MUST set request generation to 0 in \msgref{SET_CONFIG} and - MUST ignore generation fields in \msgref{GET_CONFIG}, - \msgref{SET_CONFIG}, and \msgref{EVENT_CONFIG}. + \msgref{EVENT_CONFIG}, a device SHOULD send an \msgref{EVENT_CONFIG} + without configuration data and MUST make updated data available via + \msgref{GET_CONFIG}. In strict profile, the device SHOULD set + \field{offset}/\field{length} to the affected range. \end{itemize} -This provides strict stale-write detection when negotiated while preserving a -simpler MMIO-like notification flow when not negotiated. +Rationale: defining baseline and strict semantics in a single subsection keeps +the non-strict behavior explicit, reduces duplicated conditional wording across +message definitions, and aligns baseline behavior with MMIO-like +configuration-change notification flow. \subsubsection{Feature Negotiation Blocks} \label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Feature Blocks} @@ -394,10 +401,9 @@ \subsubsection{Feature Negotiation Blocks} Bit & Name & Meaning \\ \hline 0 & \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} & -Enable strict configuration generation validation for -\msgref{GET_CONFIG}, \msgref{SET_CONFIG}, and \msgref{EVENT_CONFIG}. When this -feature is not negotiated, generation fields are reserved and MUST be sent as 0 -and ignored on receive. \\ +Select strict configuration semantics profile. When this feature is not +negotiated, the baseline profile applies. See +\ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles}. \\ \hline \end{tabular} @@ -647,8 +653,9 @@ \subsubsection{Initialization Flow Overview} updating the device status. \item \textbf{Initialize Configuration Space:} Read or write configuration data with - \msgref{GET_CONFIG}/\msgref{SET_CONFIG}, using generation validation when - \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is negotiated. + \msgref{GET_CONFIG}/\msgref{SET_CONFIG} using the active configuration + semantics profile defined in + \ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles}. \item \textbf{Set Up Virtqueues:} Configure each virtqueue via \msgref{SET_VQUEUE} and verify the settings with \msgref{GET_VQUEUE}. @@ -730,9 +737,9 @@ \subsubsection{Device Configuration} Drivers use \msgref{GET_CONFIG} to read portions of the configuration space by supplying an offset and length; the device returns the requested data plus the configuration generation field. Writing is performed via \msgref{SET_CONFIG}, -which carries the same offset/length plus generation and new data. Generation -validation applies only when -\texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is negotiated. +which carries the same offset/length plus generation and new data. +Generation-field handling follows the active profile defined in +\ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles}. Configuration space is intended for device control and configuration data. When a device can instead expose data through a virtqueue, that mechanism is @@ -744,30 +751,17 @@ \subsubsection{Device Configuration} \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 If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is negotiated, a - driver MUST include its most recently observed configuration generation - count in \msgref{SET_CONFIG} and SHOULD re-read configuration (via - \msgref{GET_CONFIG}) if the request is rejected for generation - mismatch. - \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is not negotiated, - a driver MUST set \field{generation} to 0 in \msgref{SET_CONFIG}. + \item A driver MUST follow the active configuration semantics profile in + \ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles} + for generation-field handling in \msgref{GET_CONFIG}, + \msgref{SET_CONFIG}, and \msgref{EVENT_CONFIG}. \end{itemize} \devicenormative{\paragraph}{Device Configuration}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Configuration / Device} \begin{itemize} - \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is negotiated, a - device MUST reject a \msgref{SET_CONFIG} request whose generation count - does not match its current value and MUST indicate rejection in the - response. - \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is not negotiated, - a device MUST ignore request generation and MUST NOT reject - \msgref{SET_CONFIG} because of generation mismatch. - \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is negotiated, a - device MUST return current configuration generation in - \msgref{GET_CONFIG} and \msgref{SET_CONFIG} responses. - \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is not negotiated, - a device MUST return generation as 0 in \msgref{GET_CONFIG} and - \msgref{SET_CONFIG} responses. + \item A device MUST follow the active configuration semantics profile in + \ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles} + for generation-field handling and \msgref{SET_CONFIG} mismatch behavior. \end{itemize} \subsubsection{Virtqueue Configuration} @@ -913,14 +907,9 @@ \subsubsection{Device Notifications} \begin{itemize} \item A device (or device-side bus) MUST use \msgref{EVENT_CONFIG} to notify the driver of configuration changes or status updates. - \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is negotiated, - \msgref{EVENT_CONFIG} MUST include the new configuration generation - count and the affected offset/length, and MAY include updated - configuration data. - \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is not negotiated, - \msgref{EVENT_CONFIG} generation MUST be 0. The device MAY set - offset/length to 0 to indicate a generic configuration-change - notification and MAY include updated configuration data. + \item A device MUST follow the active configuration semantics profile in + \ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles} + for \msgref{EVENT_CONFIG} generation and offset/length handling. \item A device MUST use \msgref{EVENT_USED} to notify the driver of used buffers on a virtqueue, unless the device relies on polling or another agreed-upon completion mechanism. @@ -929,10 +918,11 @@ \subsubsection{Device Notifications} \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 provided data. If data is not provided, the - driver SHOULD re-read the affected range via \msgref{GET_CONFIG}; if - offset/length are both zero, the driver SHOULD re-read the required - configuration via \msgref{GET_CONFIG} before resuming normal I/O. + the configuration using provided data (or by issuing + \msgref{GET_CONFIG} if necessary) before resuming normal I/O. + \item A driver MUST follow the active configuration semantics profile in + \ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles} + for \msgref{EVENT_CONFIG} generation and offset/length interpretation. \item Upon receiving \msgref{EVENT_USED}, a driver MUST examine the indicated virtqueue (for example, by reading the used ring) to reclaim completed buffers. @@ -959,10 +949,9 @@ \subsubsection{Configuration Changes During Operation} \drivernormative{\paragraph}{Runtime Configuration}{Virtio Transport Options / Virtio Over Messages / Device Operation / Configuration Changes During Operation / Driver} \begin{itemize} \item A driver MAY issue \msgref{SET_CONFIG} after initialization, following - the same validation rules as during setup. If - \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is negotiated, the - driver includes current generation count; otherwise it sets generation - to 0. + the same validation rules as during setup and the active configuration + semantics profile in + \ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles}. \item Upon receiving an \msgref{EVENT_CONFIG}, the driver SHOULD refresh its view of the configuration (via the data provided or by reissuing \msgref{GET_CONFIG}) before relying on the updated values. @@ -971,10 +960,9 @@ \subsubsection{Configuration Changes During Operation} \devicenormative{\paragraph}{Runtime Configuration}{Virtio Transport Options / Virtio Over Messages / Device Operation / Configuration Changes During Operation / Device} \begin{itemize} \item If a device updates its configuration after initialization, it MUST send - \msgref{EVENT_CONFIG} to inform the driver of the change. If - \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is negotiated, the - message MUST provide new configuration generation count; otherwise it - MUST set generation to 0. + \msgref{EVENT_CONFIG} to inform the driver of the change and MUST follow + the active configuration semantics profile in + \ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles}. \end{itemize} \subsubsection{Virtqueue Changes During Operation} @@ -1270,9 +1258,9 @@ \subsubsection{Overview} \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 generation. If -\texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is not negotiated, generation -is reserved and MUST be 0. +the data, and includes generation. Generation semantics follow the active +configuration profile defined in +\ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles}. \begin{lstlisting} struct virtio_msg_get_config_req { @@ -1296,12 +1284,9 @@ \subsubsection{Overview} \devicenormative{\paragraph}{GET\_CONFIG}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_CONFIG / Device} \begin{itemize} - \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is negotiated, a - device MUST return current configuration generation count with every - \msgref{GET_CONFIG} response. - \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is not negotiated, - a device MUST return \field{generation} as 0 in every - \msgref{GET_CONFIG} response. + \item A device MUST follow the active configuration semantics profile in + \ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles} + for \field{generation} in every \msgref{GET_CONFIG} response. \end{itemize} \msgdef{SET_CONFIG} @@ -1310,8 +1295,9 @@ \subsubsection{Overview} offset, length, the driver's view of the generation count, and the new data. The device echoes the offset/length, returns the resulting generation count, and may mirror the applied data or set the length to zero if the write was -rejected. If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is not -negotiated, generation is reserved and MUST be 0. +rejected. Generation semantics follow the active configuration profile defined +in +\ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles}. \begin{lstlisting} struct virtio_msg_set_config_req { @@ -1333,26 +1319,17 @@ \subsubsection{Overview} \begin{itemize} \item A driver MUST keep the offset and length within the reported configuration size in each \msgref{SET_CONFIG} request. - \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is negotiated, a - driver MUST include its most recent configuration generation count in - each \msgref{SET_CONFIG} request. - \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is not negotiated, - a driver MUST set \field{generation} to 0 in each \msgref{SET_CONFIG} - request. + \item A driver MUST follow the active configuration semantics profile in + \ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles} + for \field{generation} handling in \msgref{SET_CONFIG}. \end{itemize} \devicenormative{\paragraph}{SET\_CONFIG}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_CONFIG / Device} \begin{itemize} - \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is negotiated, a - device MUST reject a \msgref{SET_CONFIG} request if supplied generation - does not match its current value and MUST report rejection in the - response. - \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is not negotiated, - a device MUST ignore supplied generation and MUST NOT reject - \msgref{SET_CONFIG} due to generation mismatch. - \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is not negotiated, - a device MUST return \field{generation} as 0 in - \msgref{SET_CONFIG} responses. + \item A device MUST follow the active configuration semantics profile in + \ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles} + for \field{generation} handling and mismatch behavior in + \msgref{SET_CONFIG}. \end{itemize} \msgdef{GET_DEVICE_STATUS} @@ -1593,10 +1570,11 @@ \subsubsection{Overview} \msgref{EVENT_CONFIG} notifies the driver about configuration or status changes. The payload includes current device status, generation, and configuration offset/length. The configuration data MAY be omitted; if omitted, -the driver re-fetches via \msgref{GET_CONFIG}. If -\texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is not negotiated, generation -is reserved and MUST be 0. If the event reports only a status change with no -configuration update, the device sets offset and length to zero. +the driver re-fetches via \msgref{GET_CONFIG}. Generation and offset/length +semantics follow the active profile defined in +\ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles}. +If the event reports only a status change with no configuration update, the +device sets offset and length to zero. \begin{lstlisting} struct virtio_msg_event_config { @@ -1612,23 +1590,20 @@ \subsubsection{Overview} \begin{itemize} \item When \msgref{EVENT_CONFIG} provides configuration data, the driver SHOULD apply it; otherwise it SHOULD re-read the affected range - indicated by offset/length via \msgref{GET_CONFIG}. If offset/length - are both zero, the driver SHOULD re-read required configuration via - \msgref{GET_CONFIG} before proceeding. - \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is not negotiated, - a driver MUST ignore \field{generation} in \msgref{EVENT_CONFIG}. + indicated by offset/length via \msgref{GET_CONFIG} before proceeding. + \item A driver MUST follow the active configuration semantics profile in + \ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles} + for generation and offset/length interpretation in + \msgref{EVENT_CONFIG}. \end{itemize} \devicenormative{\paragraph}{EVENT\_CONFIG}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_EVENT_CONFIG / Device} \begin{itemize} \item A device MUST send \msgref{EVENT_CONFIG} whenever it changes configuration data or status in a way that is visible to the driver. - \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is negotiated, a - device MUST include the new configuration generation count and MUST set - offset/length to describe the affected configuration range. - \item If \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} is not negotiated, - a device MUST set \field{generation} to 0 and MAY set offset/length to - zero for generic configuration-change notifications. + \item A device MUST follow the active configuration semantics profile in + \ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles} + for generation and offset/length handling in \msgref{EVENT_CONFIG}. \item If \msgref{EVENT_CONFIG} reports only a status change, a device MUST set the offset and length fields to zero. \end{itemize} From 909445a83f0208858e1ef1c91c612ea2609a7394 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Wed, 25 Feb 2026 15:52:15 +0100 Subject: [PATCH 45/56] virtio-msg: keep EVENT_CONFIG affected range optional (Demi Marie Obenour) Allow EVENT_CONFIG to use offset=0, length=0, and no data as a generic configuration-change notification when the device cannot express a bounded affected range. Rationale: this keeps an interoperable notification path for changes where only an equivalent out-of-band notification is available without affected-range details, while making driver behavior explicit through GET_CONFIG refresh. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 08d5a93..4b3d0e3 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -354,9 +354,12 @@ \subsubsection{Configuration Semantics Profiles} \item In baseline profile, a device MUST ignore request \field{generation} in \msgref{SET_CONFIG} and MUST NOT reject \msgref{SET_CONFIG} due to generation mismatch. - \item In baseline profile, a device MAY set \field{offset}/\field{length} to - zero in \msgref{EVENT_CONFIG} to indicate a generic - configuration-change notification. + \item In any profile, a device MAY send a generic + \msgref{EVENT_CONFIG} notification with \field{offset} and + \field{length} set to 0 and no \field{data} when the affected + configuration change cannot be represented as a bounded range + (for example, when only an equivalent out-of-band notification is + available without affected-range details). \item In strict profile, a device MUST increment generation count before it makes a driver-visible configuration change and MUST ensure that each \msgref{EVENT_CONFIG} carrying configuration data uses a unique @@ -920,6 +923,10 @@ \subsubsection{Device Notifications} \item Upon receiving \msgref{EVENT_CONFIG}, a driver SHOULD update its view of the configuration using provided data (or by issuing \msgref{GET_CONFIG} if necessary) before resuming normal I/O. + \item If \msgref{EVENT_CONFIG} provides no data and has + \field{offset} and \field{length} set to 0, a driver SHOULD treat it as + a generic configuration-change notification and refresh required + configuration via \msgref{GET_CONFIG}. \item A driver MUST follow the active configuration semantics profile in \ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles} for \msgref{EVENT_CONFIG} generation and offset/length interpretation. @@ -1569,7 +1576,7 @@ \subsubsection{Overview} \msgref{EVENT_CONFIG} notifies the driver about configuration or status changes. The payload includes current device status, generation, and -configuration offset/length. The configuration data MAY be omitted; if omitted, +configuration offset/length. The configuration data can be omitted; if omitted, the driver re-fetches via \msgref{GET_CONFIG}. Generation and offset/length semantics follow the active profile defined in \ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles}. @@ -1591,6 +1598,8 @@ \subsubsection{Overview} \item When \msgref{EVENT_CONFIG} provides configuration data, the driver SHOULD apply it; otherwise it SHOULD re-read the affected range indicated by offset/length via \msgref{GET_CONFIG} before proceeding. + If offset/length are both zero and no data is provided, the driver + SHOULD re-read required configuration via \msgref{GET_CONFIG}. \item A driver MUST follow the active configuration semantics profile in \ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles} for generation and offset/length interpretation in From 84e84d3820e22d324461dfbf63f1576d7b123ebe Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Fri, 6 Mar 2026 10:19:22 +0100 Subject: [PATCH 46/56] virtio-msg: restore 16-bit msg_size header field (HVAC group discussion) HVAC group discussion requested reverting the common header size field change that moved msg_size to 32 bits. Restore the common header to use a 16-bit msg_size plus a 16-bit reserved field, and update common-header normative text to define reserved-field transmit/receive behavior. This supersedes the earlier 32-bit msg_size direction and aligns the protocol maximum-size value with a 16-bit size field. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 4b3d0e3..fc8772b 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -216,7 +216,7 @@ \subsubsection{Transport Revisions and Maximum Message Size} \hline \field{revision} & \field{maximum size} & \field{features} & remarks \\ \hline \hline -1 & 60-65536 & bit 0 optional: \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} & Virtio Message Revision 1 \\ +1 & 60-65535 & bit 0 optional: \texttt{VIRTIO\_MSG\_F\_STRICT\_CONFIG\_GENERATION} & Virtio Message Revision 1 \\ \hline \end{tabular} @@ -500,7 +500,8 @@ \subsubsection{Common Message Format} u8 type; /* request/response + bus/transport */ u8 msg_id; /* message id */ le16 token; /* bus-managed correlation identifier */ - le32 msg_size; /* total size: header (16) + payload */ + le16 msg_size; /* total size: header (16) + payload */ + le16 reserved; /* reserved, MUST be zero */ le64 dev_num; /* device number (0 for bus messages) */ u8 payload[]; }; @@ -524,6 +525,8 @@ \subsubsection{Common Message Format} outstanding requests or maintain ordering. \item \field{msg_size}: Total size in bytes of the complete message (header plus payload). + \item \field{reserved}: Reserved for future use. Transmitters set this field + to zero, and receivers ignore it. \item \field{dev_num}: For transport messages, the device number that should receive the message. Bus messages operate on device number 0. \item \field{payload}: Operation-specific data. If a bus introduces extra @@ -537,6 +540,8 @@ \subsubsection{Common Message Format} \item A driver MUST ensure \field{msg_size} reflects the total message length (header plus payload) and MUST NOT exceed the maximum message size advertised by the bus instance. + \item A driver MUST set \field{reserved} to zero when transmitting and MUST + ignore the received \field{reserved} value. \item When sending a transport message, a driver MUST set \field{dev_num} to the intended device number. \item If a driver introduces padding bytes that become part of the transport @@ -551,6 +556,8 @@ \subsubsection{Common Message Format} messages and MUST ignore those bits on receive. \item A device MUST ensure \field{msg_size} reflects the total message length (header plus payload) and does not exceed the bus's advertised maximum. + \item A device MUST set \field{reserved} to zero when transmitting and MUST + ignore the received \field{reserved} value. \item When sending a transport message, a device MUST set \field{dev_num} to its own device number. \item A device MUST ignore padding bytes that are documented as bus-specific From 75f6433c6e0f8461d23045eb64323ab6a90f287e Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Fri, 6 Mar 2026 10:23:48 +0100 Subject: [PATCH 47/56] virtio-msg: gate SET_CONFIG mismatch refusal to strict profile (HVAC group discussion) HVAC group discussion identified that wrong generation count in SET_CONFIG should not cause write refusal unless strict profile semantics are negotiated. Update configuration profile and message-specific normative text so generation-mismatch rejection is strict-profile-only, baseline accepts otherwise-valid writes, and baseline does not emit mismatch-only EVENT_CONFIG notifications. 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 fc8772b..3d01f65 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -352,8 +352,12 @@ \subsubsection{Configuration Semantics Profiles} \item In baseline profile, a device MUST set \field{generation} to 0 in \msgref{GET_CONFIG}, \msgref{SET_CONFIG}, and \msgref{EVENT_CONFIG}. \item In baseline profile, a device MUST ignore request \field{generation} in - \msgref{SET_CONFIG} and MUST NOT reject \msgref{SET_CONFIG} due to - generation mismatch. + \msgref{SET_CONFIG}. For requests that are otherwise valid, the device + MUST apply the write regardless of request \field{generation} and MUST + NOT reject \msgref{SET_CONFIG} due solely to generation mismatch. + \item In baseline profile, a device MUST NOT send \msgref{EVENT_CONFIG} + solely because a \msgref{SET_CONFIG} request carried a mismatched + \field{generation} value. \item In any profile, a device MAY send a generic \msgref{EVENT_CONFIG} notification with \field{offset} and \field{length} set to 0 and no \field{data} when the affected @@ -1309,7 +1313,8 @@ \subsubsection{Overview} offset, length, the driver's view of the generation count, and the new data. The device echoes the offset/length, returns the resulting generation count, and may mirror the applied data or set the length to zero if the write was -rejected. Generation semantics follow the active configuration profile defined +rejected. Generation-mismatch rejection is defined only for strict profile. +Generation semantics follow the active configuration profile defined in \ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles}. @@ -1344,6 +1349,8 @@ \subsubsection{Overview} \ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles} for \field{generation} handling and mismatch behavior in \msgref{SET_CONFIG}. + \item A device MUST apply \msgref{SET_CONFIG} generation-mismatch rejection + only when strict profile is active. \end{itemize} \msgdef{GET_DEVICE_STATUS} @@ -1620,6 +1627,8 @@ \subsubsection{Overview} \item A device MUST follow the active configuration semantics profile in \ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles} for generation and offset/length handling in \msgref{EVENT_CONFIG}. + \item In baseline profile, a device MUST NOT send \msgref{EVENT_CONFIG} + solely to report a \msgref{SET_CONFIG} generation mismatch. \item If \msgref{EVENT_CONFIG} reports only a status change, a device MUST set the offset and length fields to zero. \end{itemize} From 51d0e643064d7e3d4b40f3ed3f7ded0f0f5badec Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Fri, 6 Mar 2026 10:30:00 +0100 Subject: [PATCH 48/56] virtio-msg: clarify per-device request/response ordering baseline (HVAC group discussion) HVAC group discussion kept baseline ordering strict for request/response handling while preserving asynchronous events. Define per-device in-order forwarding for requests and in-order delivery for corresponding responses, and state that events may be delivered at any time relative to request/response traffic without bus- imposed delay to enforce response-first ordering. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 3d01f65..9053792 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -602,17 +602,23 @@ \subsubsection{Message Ordering} Transport messages fall into two classes: requests (which expect responses) and events (which are one-way). Drivers and devices rely on the bus to preserve the relative ordering of request/response pairs for each device number; they do not -interpret the \field{token} field directly. Events are independent -notifications and may be delivered out of order with respect to other events. +interpret the \field{token} field directly. Events are asynchronous +notifications and MAY be delivered at any time relative to request/response +traffic. Ordering is defined per device number; messages for different device +numbers MAY be interleaved by the bus. Some response payloads repeat request parameters (for example, indices or offsets) to support validation; these repeats are informational and do not alter the correlation model described here. \busnormative{\paragraph}{Message Ordering}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Ordering / Bus} \begin{itemize} + \item For each device number, a bus implementation MUST forward requests from + the driver to the device in the same order that the driver sends them. \item For each device number, a bus implementation MUST deliver responses to the driver in the same order that it forwarded the corresponding requests to the device. + \item A bus implementation MUST NOT delay an event solely to preserve a + request-before-event or response-before-event ordering rule. \end{itemize} \devicenormative{\paragraph}{Message Ordering}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Ordering / Device} From 9ecc00f5ebbb25b5056bf5653dea0466d858e516 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Fri, 6 Mar 2026 10:39:40 +0100 Subject: [PATCH 49/56] virtio-msg: constrain virtqueue reconfiguration transitions (HVAC group discussion) HVAC group discussion requested explicit virtqueue state-transition rules so reconfiguration happens only while a queue is disabled. Update SET_VQUEUE and RESET_VQUEUE semantics to prevent enabled-to-disabled/reset transitions through SET_VQUEUE, require RESET_VQUEUE before reconfiguring enabled queues when VIRTIO_F_RING_RESET is negotiated, and tighten corresponding driver/device normative behavior using explicit enabled/disabled queue-state wording. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 70 +++++++++++++++++++++++++++++++++++------------ 1 file changed, 53 insertions(+), 17 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 9053792..466b9cc 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -805,9 +805,14 @@ \subsubsection{Virtqueue Configuration} \item If a driver updates queue addresses via \msgref{SET_VQUEUE}, it MUST supply valid descriptor/driver/device physical addresses for each updated field. - \item If VIRTIO\_F\_RING\_RESET has been negotiated and a queue requires - reinitialization, the driver SHOULD use \msgref{RESET_VQUEUE} before - reprogramming it. + \item A driver MUST reconfigure queue parameters only while the queue is + disabled. + \item If a queue is enabled and requires reconfiguration, a driver MUST issue + \msgref{RESET_VQUEUE} before reprogramming it when + VIRTIO\_F\_RING\_RESET is negotiated. + \item If a queue is enabled and VIRTIO\_F\_RING\_RESET has not been + negotiated, a driver MUST NOT attempt to reconfigure the queue via + \msgref{SET_VQUEUE}. \end{itemize} \devicenormative{\paragraph}{Virtqueue Configuration}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Virtqueue Configuration / Device} @@ -815,9 +820,12 @@ \subsubsection{Virtqueue Configuration} \item A device MUST report accurate maximum queue sizes in \msgref{GET_VQUEUE} and MUST report accurate current queue size and enabled state. \item A device MUST persist the parameters supplied via \msgref{SET_VQUEUE} - for fields not marked ignored by \field{flags}. + for fields not marked ignored by \field{flags} while the queue is + disabled. \item A device MUST update queue state according to the \msgref{SET_VQUEUE} \field{flags} state-operation bits. + \item A device MUST NOT use \msgref{SET_VQUEUE} to perform an + enabled-to-disabled or reset transition for a queue. \item When \msgref{RESET_VQUEUE} is issued (and VIRTIO\_F\_RING\_RESET is negotiated), the device MUST quiesce the queue, release any resources associated with it, and allow the driver to reconfigure it. @@ -993,22 +1001,30 @@ \subsubsection{Virtqueue Changes During Operation} \label{sec:Virtio Transport Options / Virtio Over Messages / Device Operation / Virtqueue Changes During Operation} Drivers may provision unused virtqueues later in the device lifetime by issuing -\msgref{SET_VQUEUE}, and they may reconfigure existing queues or update queue -state if the -VIRTIO\_F\_RING\_RESET feature has been negotiated. +\msgref{SET_VQUEUE}. Queue reconfiguration remains constrained to disabled +queues. If a queue is enabled, the driver first resets that queue via +\msgref{RESET_VQUEUE} when VIRTIO\_F\_RING\_RESET is negotiated. \drivernormative{\paragraph}{Runtime Virtqueue Changes}{Virtio Transport Options / Virtio Over Messages / Device Operation / Virtqueue Changes During Operation / Driver} \begin{itemize} \item A driver MAY configure additional virtqueues and update selected virtqueue fields after initialization using \msgref{SET_VQUEUE}, - provided it follows the same validation steps. + provided it follows the same validation steps and updates only disabled + queues. + \item If an enabled queue requires reconfiguration and + VIRTIO\_F\_RING\_RESET is negotiated, a driver MUST issue + \msgref{RESET_VQUEUE} before issuing \msgref{SET_VQUEUE} updates for + that queue. \end{itemize} \devicenormative{\paragraph}{Runtime Virtqueue Changes}{Virtio Transport Options / Virtio Over Messages / Device Operation / Virtqueue Changes During Operation / Device} \begin{itemize} \item A device MUST honor \msgref{SET_VQUEUE} requests issued after - initialization and update queue parameters and queue state according to - \field{flags}. + initialization and update queue parameters according to \field{flags} + only while the queue is disabled. + \item For a queue that is enabled, a device MUST accept only + \msgref{SET_VQUEUE} requests that do not modify queue parameters and do + not request a disable/reset transition. \item When \msgref{RESET_VQUEUE} is received (and VIRTIO\_F\_RING\_RESET is negotiated), the device MUST quiesce the queue and allow the driver to reconfigure it without processing stale data. @@ -1461,8 +1477,8 @@ \subsubsection{Overview} \msgref{SET_VQUEUE} updates a virtqueue's parameters and queue state. The driver selects a queue index and uses \field{flags} to indicate whether queue -state should be enabled, disabled, or kept unchanged, and which queue fields -should be ignored versus updated. +state should be enabled, kept disabled, or kept unchanged, and which queue +fields should be ignored versus updated. \begin{lstlisting} struct virtio_msg_set_vqueue_req { @@ -1484,7 +1500,7 @@ \subsubsection{Overview} \begin{itemize} \item Bits [1:0] (\textbf{State Operation}): \begin{itemize} - \item 0: disable queue. + \item 0: keep queue disabled. \item 1: enable queue. \item 2: keep current queue state. \item 3: reserved. @@ -1500,7 +1516,8 @@ \subsubsection{Overview} \end{itemize} When \field{flags} is zero, \msgref{SET_VQUEUE} uses current behavior: -the queue is disabled and all queue fields in the request are applied. +if the queue is disabled, all queue fields in the request are applied and the +queue remains disabled. \drivernormative{\paragraph}{SET\_VQUEUE}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_SET_VQUEUE / Driver} \begin{itemize} @@ -1508,10 +1525,16 @@ \subsubsection{Overview} bits [31:6] to zero. \item A driver MUST NOT use state operation value 3 in \field{flags} bits [1:0]. + \item A driver MUST NOT use state operation value 0 as a request to disable an + already enabled queue. \item If \field{size\_ignore} is 0, a driver MUST set \field{size} to a value not exceeding the maximum reported by \msgref{GET_VQUEUE}. \item If any address ignore bit is 0, a driver MUST ensure the corresponding physical address points to properly aligned memory. + \item A driver MUST NOT attempt to update queue size or queue addresses via + \msgref{SET_VQUEUE} while the queue is enabled. + \item If a driver needs to reconfigure an enabled queue, it MUST issue + \msgref{RESET_VQUEUE} first when VIRTIO\_F\_RING\_RESET is negotiated. \item Because \msgref{SET_VQUEUE} has no response payload, a driver that needs confirmation of acceptance MUST verify the resulting queue parameters and state via \msgref{GET_VQUEUE} before relying on the @@ -1523,14 +1546,20 @@ \subsubsection{Overview} \item A device MUST reject \msgref{SET_VQUEUE} if \field{reserved} is nonzero, if \field{flags} bits [31:6] are nonzero, or if \field{flags} bits [1:0] use state operation value 3. + \item A device MUST reject \msgref{SET_VQUEUE} if \field{flags} requests state + operation value 0 for a queue that is currently enabled. \item A device MUST process \msgref{SET_VQUEUE} updates atomically: it MUST either apply all requested field updates and queue-state changes, or reject the request without applying any of them. \item If an ignore bit is 0, a device MUST apply the corresponding field from \msgref{SET_VQUEUE}; if an ignore bit is 1, a device MUST keep the current value for that field unchanged. + \item A device MUST reject \msgref{SET_VQUEUE} field updates to + \field{size}, \field{desc_addr}, \field{driver_addr}, or + \field{device_addr} when the queue is enabled. \item A device MUST apply queue state according to \field{flags} bits [1:0] - after processing requested field updates. + after processing requested field updates, and MUST NOT perform an + enabled-to-disabled transition via \msgref{SET_VQUEUE}. \end{itemize} \msgdef{RESET_VQUEUE} @@ -1551,16 +1580,23 @@ \subsubsection{Overview} \drivernormative{\paragraph}{RESET\_VQUEUE}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_RESET_VQUEUE / Driver} \begin{itemize} - \item A driver SHOULD issue \msgref{RESET_VQUEUE} only if + \item A driver MUST issue \msgref{RESET_VQUEUE} only if VIRTIO\_F\_RING\_RESET has been negotiated and it needs to reconfigure or recover a specific queue. + \item If an enabled queue requires reconfiguration and + VIRTIO\_F\_RING\_RESET is negotiated, a driver MUST wait for + \msgref{RESET_VQUEUE} completion before issuing \msgref{SET_VQUEUE} + updates for that queue. \end{itemize} \devicenormative{\paragraph}{RESET\_VQUEUE}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_RESET_VQUEUE / Device} \begin{itemize} + \item If VIRTIO\_F\_RING\_RESET has not been negotiated, a device MUST reject + \msgref{RESET_VQUEUE} without changing queue state. \item Upon receiving \msgref{RESET_VQUEUE}, a device MUST stop processing the indicated queue, reset its internal state for that queue, and allow the - driver to reconfigure it via \msgref{SET_VQUEUE}. + driver to reconfigure it via \msgref{SET_VQUEUE} while the queue is + disabled. \end{itemize} \msgdef{GET_SHM} From f1ed24f66b1f6d9a26aecaa13d25072bbe91cb1d Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Fri, 6 Mar 2026 10:43:18 +0100 Subject: [PATCH 50/56] virtio-msg: use feature-block count in GET_DEVICE_INFO (Andrei Homescu) Andrei Homescu noted that feature capacity should use 32-bit block semantics rather than bit-count semantics for consistency. Rename the GET_DEVICE_INFO feature count field to num_feature_blocks and align related GET_DEVICE_INFO/feature-negotiation prose to describe 32-bit block units consistently. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 466b9cc..e077937 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -708,7 +708,7 @@ \subsubsection{Device Information} Once a device number is confirmed, the driver uses \msgref{GET_DEVICE_INFO} to retrieve static identification data (device ID, vendor ID), the number of -feature bits, configuration space size, maximum virtqueues, and any admin +feature blocks, configuration space size, maximum virtqueues, and any admin virtqueue details. This information determines which virtio driver should bind to the device, how many feature blocks to query, and how much configuration space is valid. @@ -743,8 +743,8 @@ \subsubsection{Feature Negotiation} \devicenormative{\paragraph}{Feature Negotiation}{Virtio Transport Options / Virtio Over Messages / Device Initialization / Device Features / Device} \begin{itemize} \item When handling \msgref{GET_DEVICE_FEATURES}, a device MUST return zero - for any requested bits that fall outside the number of feature bits it - implements. + for any requested blocks that fall outside the number of feature blocks + it reports. \item After receiving \msgref{SET_DRIVER_FEATURES}, a device MUST update its internal feature mask to match the acknowledged set. If the device cannot support the requested set, it MUST clear the FEATURES\_OK bit in @@ -1203,7 +1203,7 @@ \subsubsection{Overview} le32 device_id; /* virtio device type */ le32 vendor_id; /* implementation-defined vendor ID */ u8 device_uuid[16]; /* UUID, or nil UUID if unavailable */ - le32 num_feature_bits; /* total feature bits (multiples of 32) */ + le32 num_feature_blocks; /* total number of 32-bit feature blocks */ le32 config_size; /* bytes in the device configuration space */ le32 max_virtqueues; /* maximum virtqueues supported */ le32 admin_vq_start; /* index of the first admin virtqueue */ @@ -1214,8 +1214,8 @@ \subsubsection{Overview} \devicenormative{\paragraph}{GET\_DEVICE\_INFO}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_DEVICE_INFO / Device} \begin{itemize} \item A device MUST respond to \msgref{GET_DEVICE_INFO} while inactive and - MUST supply consistent values for device ID, vendor ID, feature count (a - multiple of 32 bits), configuration size, and virtqueue limits. + MUST supply consistent values for device ID, vendor ID, feature-block + count, configuration size, and virtqueue limits. \item A device MAY set \field{device_uuid} to a UUID value that can be used as a unique identifier. \item If a device does not support UUID reporting or does not have an @@ -1225,7 +1225,7 @@ \subsubsection{Overview} \drivernormative{\paragraph}{GET\_DEVICE\_INFO}{Virtio Transport Options / Virtio Over Messages / Transport Messages / VIRTIO_MSG_GET_DEVICE_INFO / Driver} \begin{itemize} \item A driver SHOULD treat the response as the authoritative source for - feature count, configuration size, and virtqueue limits before + feature-block count, configuration size, and virtqueue limits before proceeding with initialization. \item A driver MUST interpret a nil UUID in \field{device_uuid} as indicating that no UUID is provided. From 722a05780ce1e0bdf4ab5c557ccd3e90a345402f Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Fri, 6 Mar 2026 10:47:01 +0100 Subject: [PATCH 51/56] virtio-msg: define empty payload for rejected SET_CONFIG (Andrei Homescu) Andrei Homescu requested explicit rejected-response behavior for SET_CONFIG to avoid ambiguity about returned payload bytes. Specify that rejected SET_CONFIG responses MUST use length 0 and MUST NOT include response data bytes, and align the message description/comments with that requirement. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index e077937..586af8a 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -1335,7 +1335,8 @@ \subsubsection{Overview} offset, length, the driver's view of the generation count, and the new data. The device echoes the offset/length, returns the resulting generation count, and may mirror the applied data or set the length to zero if the write was -rejected. Generation-mismatch rejection is defined only for strict profile. +rejected. A rejected response uses \field{length}=0 and no payload bytes. +Generation-mismatch rejection is defined only for strict profile. Generation semantics follow the active configuration profile defined in \ref{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Configuration Semantics Profiles}. @@ -1352,7 +1353,7 @@ \subsubsection{Overview} le32 generation; /* resulting count, or 0 if not negotiated */ le32 offset; /* echoed offset */ le32 length; /* bytes applied (0 if rejected) */ - u8 data[]; /* optional echoed data */ + u8 data[]; /* echoed data, omitted when length is 0 */ }; \end{lstlisting} @@ -1373,6 +1374,9 @@ \subsubsection{Overview} \msgref{SET_CONFIG}. \item A device MUST apply \msgref{SET_CONFIG} generation-mismatch rejection only when strict profile is active. + \item If a device rejects a \msgref{SET_CONFIG} request, it MUST set + response \field{length} to 0 and MUST NOT include response + \field{data} bytes. \end{itemize} \msgdef{GET_DEVICE_STATUS} From 4cc756b0cce12067316d02780cf3279c9385f0db Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Fri, 6 Mar 2026 10:49:18 +0100 Subject: [PATCH 52/56] virtio-msg: use direct slot/byte units in GET_DEVICES (Andrei Homescu) Andrei Homescu requested replacing bit-multiple wording in GET_DEVICES with direct slot/byte semantics for simpler validation. Update GET_DEVICES request/response descriptions and normative text to define count in slots, bitmap size in bytes as (count + 7) / 8, and explicit handling of unused bits in the final bitmap byte. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 586af8a..5afe872 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -1804,23 +1804,24 @@ \subsubsection{Overview} \begin{lstlisting} struct virtio_bus_msg_get_devices_req { le64 offset; /* starting device number */ - le16 count; /* number of device-number slots (multiple of 8) */ + le16 count; /* number of device-number slots requested */ }; struct virtio_bus_msg_get_devices_resp { le64 offset; /* echoed starting device number */ le64 next_offset; /* 0 or suggested start for next query */ - le16 count; /* window length actually returned */ - u8 bitmap[]; /* count/8 bytes, LSB-first packing */ + le16 count; /* number of slots returned */ + u8 bitmap[]; /* ((count + 7) / 8) bytes, LSB-first packing */ }; \end{lstlisting} The \textbf{(offset, count)} tuple defines a window of \textbf{count} consecutive device numbers beginning at \textbf{offset}. The number of present -devices equals the number of 1-bits in the bitmap. Responders SHOULD return the -requested \textbf{count} unless constrained (e.g., by maximum message size); -otherwise they MAY return a smaller value, in which case the bitmap covers the -reduced window. +devices equals the number of set bits in the first \textbf{count} bitmap +positions. The bitmap size in bytes is \textbf{(count + 7) / 8}. +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 @@ -1834,12 +1835,15 @@ \subsubsection{Overview} \busnormative{\paragraph}{GET\_DEVICES}{Virtio Transport Options / Virtio Over Messages / Bus Messages / GET_DEVICES / Bus} \begin{itemize} - \item The bus-side responder MUST enforce that \textbf{offset} and - \textbf{count} are multiples of 8, and it MUST return a bitmap of length - \textbf{count/8} packed least-significant-bit first. + \item The bus-side responder MUST interpret \textbf{count} as a number of + device-number slots and MUST return a bitmap of length + \textbf{(count + 7) / 8} bytes, packed least-significant-bit first. + \item If \textbf{count} is not a multiple of 8, the responder MUST set unused + bits in the last bitmap byte (positions at or above \textbf{count}) to + zero. \item \textbf{next\_offset} MUST be 0 (indicating no further windows) or an - aligned value $\ge \textbf{offset} + \textbf{count}$ recommending where - the driver should query next. + value $\ge \textbf{offset} + \textbf{count}$ recommending where the + driver should query next. \item Responders SHOULD return the requested \textbf{count} unless constrained (e.g., by maximum message size); if a smaller count is returned, the bitmap MUST still represent the window defined by the echoed From 0930c92b0021dcf5311f27d54b4cd324b20593e4 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Fri, 6 Mar 2026 10:59:39 +0100 Subject: [PATCH 53/56] virtio-msg: add known bus implementation examples section (Michael S. Tsirkin) On-list review discussion requested including FF-A as a concrete reference point for virtio-msg bus implementations. Add a non-normative "Known Bus Implementation Examples" subsection with references for virtio message bus over FF-A and PCI-for-AMP PoC, and note Xen grant-table/event based bus work as under discussion. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/transport-msg.tex b/transport-msg.tex index 5afe872..4ca6703 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -134,6 +134,22 @@ \subsubsection{Relationship Between Bus and Transport} number, it MAY drop the message or surface a transport-visible failure. \end{itemize} +\subsubsection{Known Bus Implementation Examples} +\label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Known Bus Implementation Examples} + +This subsubsection lists informative examples of bus implementations and related +work for virtio-msg. + +\begin{itemize} + \item \textbf{Virtio Message Bus over FF-A}: specified by Arm DEN0153: + \url{https://developer.arm.com/documentation/den0153/latest}. + \item \textbf{Virtio Message Bus over PCI for AMP}: under development; proof + of concept: + \url{https://github.com/wmamills/hvac-demo}. + \item \textbf{Virtio Message Bus over Xen grant tables and events}: under + discussion. +\end{itemize} + \subsubsection{System Topology} A virtio-msg system contains the following elements: From f81d6121372d188e318291d809053bdcca0cd625 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Fri, 6 Mar 2026 11:20:58 +0100 Subject: [PATCH 54/56] virtio-msg: cap GET_DEVICES response count to request (Andrei Homescu) Andrei Homescu asked how drivers should handle GET_DEVICES responses that return more entries than requested. Define that GET_DEVICES responders MUST NOT return a count greater than the request count. Keep smaller responses allowed when constrained by message size or when requested ranges contain no present devices, including count=0 with an empty bitmap when no devices are present in the requested window. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 4ca6703..7f5f5b3 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -1835,9 +1835,12 @@ \subsubsection{Overview} consecutive device numbers beginning at \textbf{offset}. The number of present devices equals the number of set bits in the first \textbf{count} bitmap positions. The bitmap size in bytes is \textbf{(count + 7) / 8}. +The response \textbf{count} MUST NOT exceed the request \textbf{count}. Responders SHOULD return the requested \textbf{count} unless constrained -(e.g., by maximum message size); otherwise they MAY return a smaller value, in -which case the bitmap covers the reduced window. +(e.g., by maximum message size) or when trailing parts of the requested window +contain no present device numbers; in those cases they MAY return a smaller +value, and the bitmap covers the reduced window. If no devices are present in +the requested window, returning \textbf{count}=0 and an empty bitmap is valid. Example: a request with \textbf{offset}=0, \textbf{count}=16 might produce \textbf{bitmap}=0b00100101 00000000 and \textbf{next_offset}=16. That indicates @@ -1854,6 +1857,8 @@ \subsubsection{Overview} \item The bus-side responder MUST interpret \textbf{count} as a number of device-number slots and MUST return a bitmap of length \textbf{(count + 7) / 8} bytes, packed least-significant-bit first. + \item The bus-side responder MUST NOT return a \textbf{count} value greater + than the \textbf{count} value from the request. \item If \textbf{count} is not a multiple of 8, the responder MUST set unused bits in the last bitmap byte (positions at or above \textbf{count}) to zero. @@ -1861,9 +1866,12 @@ \subsubsection{Overview} value $\ge \textbf{offset} + \textbf{count}$ recommending where the driver should query next. \item Responders SHOULD return the requested \textbf{count} unless constrained - (e.g., by maximum message size); if a smaller count is returned, the - bitmap MUST still represent the window defined by the echoed - \textbf{offset} and \textbf{count}. + (e.g., by maximum message size) or when trailing parts of the requested + window contain no present device numbers; if a smaller count is + returned, the bitmap MUST still represent the window defined by the + echoed \textbf{offset} and \textbf{count}. + \item If no devices are present in the requested window, a responder MAY + return \textbf{count}=0 with a zero-length bitmap. \end{itemize} \busdef{PING} From 7a2d5e2a7741cd6633db035db019ceebe4573c88 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Fri, 6 Mar 2026 12:10:07 +0100 Subject: [PATCH 55/56] email: adjust cover letter for PATCH v2 - Replace old "Changes since RFC2" section with "Changes since v1 (virtio-msg-patch1)" - Summarize key v2 spec deltas with rationale tied to review feedback - Add open-topics sectionfor ongoing discussions - Move virtio-msg over virtqueues/admin-vq topic out of anticipated bus implementations into ongoing discussion - Update FF-A reference to DEN0153 1.0 ALP1 link and mention it as the second draft aligned with the virtio-msg v1 proposal - Reword series status text to reflect v2 Signed-off-by: Bertrand Marquis --- .prjinfo/sendmail/cover.txt | 96 ++++++++++++++++++++++++++----------- 1 file changed, 68 insertions(+), 28 deletions(-) diff --git a/.prjinfo/sendmail/cover.txt b/.prjinfo/sendmail/cover.txt index b6c4755..0fc684a 100644 --- a/.prjinfo/sendmail/cover.txt +++ b/.prjinfo/sendmail/cover.txt @@ -61,41 +61,81 @@ We also anticipate a few more: * Usable on any Xen system (including x86 where FF-A does not exist) * Using Xen events and page grants -* virtio-msg over admin virtqueues - * This allows any virtio-pci device that supports admin virtqueues to also - support a virtio-msg bus that supports sub devices - * [We are looking for collaborators for this work] - -Changes since RFC2: - -Spec Functional: -* Made the common message header 8 bytes and added a token for optional use - when parallel outstanding requests are possible -* Made the 8 byte fields align to 8 byte offsets. - This effects the {SET,GET}_VQUEUE messages -* Many conformance cases have been tightened. - -Spec Editorial: -* Major restructure to better align with virtio spec - * Conformance model now matches other transports - * Use C structures to define messages instead of tables -* Added a section to describe how responses are matched to requests - This includes the use of the new token field -* Redefined / better described error handling between transport and bus - layers to eliminate the need for the bus to generate fake response messages -* Included editorial feedback from RFC2 +Changes since v1 (virtio-msg-patch1): + +First, thank you for the detailed comments and broad interest on v1. +We tried to address most review feedback in this revision. + +Spec Functional / Behavioral: +* Finalized the common header and addressing model: + * Keep a 16-byte common header + * Use 64-bit device numbers + * Use 16-bit msg_size plus 16-bit reserved + Rationale: support larger device-number spaces while keeping the transport + control-plane focused and limiting payload-transfer misuse. +* Clarified device-number lifecycle guidance so bus implementations should avoid + immediate reuse of removed device numbers. + Rationale: reduce races with delayed messages when devices are removed and + added again. +* Added explicit configuration semantics profiles (baseline vs strict) and + gated generation-mismatch refusal to strict-profile negotiation. + Rationale: preserve compatibility in baseline mode while allowing stricter + behavior when both sides opt in. +* Clarified SET_CONFIG rejection behavior: rejected responses return + length = 0 with no payload. + Rationale: remove ambiguity for parser/validation behavior. +* Clarified ordering baseline: request/response ordering is per-device in-order, + while events remain asynchronous and may arrive at any time relative to + request/response traffic. + Rationale: keep baseline semantics clear without over-constraining event + delivery. +* Clarified virtqueue state transitions and reconfiguration rules around + enabled/disabled/reset states. + Rationale: align with transport expectations and avoid ambiguous queue-state + behavior. +* Clarified GET_DEVICE_INFO semantics using number of 32-bit feature blocks and + aligned related field descriptions. + Rationale: improve consistency and implementation clarity. +* Clarified GET_DEVICES semantics using direct slot/byte units; responders must + not return count values larger than requested; smaller (including zero) count + is valid when appropriate. + Rationale: make enumeration behavior precise while allowing efficient sparse + windows. +* Added an informative known bus implementation examples section, including the + FF-A bus specification reference and current implementation examples. + Rationale: provide concrete context without constraining architecture choices. +* Tightened conformance text to match the clarified normative behavior. + +Open topics and ongoing discussion: +* Out-of-order/performance extensions: + We kept the baseline behavior simple in this revision. If clear performance + benefit is demonstrated, we are open to introducing an optional feature-bit + based extension in a follow-up patch set. +* Graceful device removal sequencing: + Current direction is to handle graceful-remove sequencing in bus-specific + specifications. We welcome feedback on whether any additional transport-level + guidance would be useful. +* Transport scope and mapping guidance: + Discussion is still ongoing on transport-vs-bus binding scope, response + status modeling, and mapping guidance for mmio/pci/vhost-user/KVM userspace + cases. We are collecting reviewer input before deciding on follow-up text. +* Potential virtio-msg over virtqueues for PCI/MMIO: + This is still early discussion, including whether admin virtqueues should be + used or extended for this purpose. There is no consensus yet, and we are + continuing design exploration. Eco-system: * Added virtio-msg-loopback demo -* Arm has published the first draft of the virtio-msg over FFA spec [6] +* Arm has published a second draft of the virtio message bus over FF-A + specification (1.0 ALP1), aligned with the virtio-msg v1 proposal [6] * virtio-msg over FFA has been demonstrated with both Trusty and OP-TEE secure world * LKML RFC has been sent [7] * QEMU RFC has been sent [8] -This is the first non-RFC patch series. The known short comings have been -addressed. We ask for review in earnest on this series and thank you for -any feedback you can provide. +This is v2 of the first non-RFC patch series. We are grateful for the review +feedback and interest received on v1, and we ask for continued review on this +revision. Background info and work in progress implementations: * HVAC project page with intro slides [1] @@ -117,6 +157,6 @@ with this version of the spec. [3] https://git.kernel.org/pub/scm/linux/kernel/git/vireshk/linux.git/log/?h=virtio/msg [4] https://github.com/edgarigl/qemu/commits/edgar/virtio-msg-rfc/ [5] https://github.com/arnopo/open-amp/commits/virtio-msg/ -[6] https://documentation-service.arm.com/static/68f647791134f773ab3f0a7c +[6] https://developer.arm.com/documentation/den0153/0101/ [7] https://lore.kernel.org/all/cover.1753865268.git.viresh.kumar@linaro.org/ [8] https://mail.gnu.org/archive/html/qemu-devel/2025-10/msg07438.html From 0e073507e3e80d26989f78ede1997e77d39027d2 Mon Sep 17 00:00:00 2001 From: Bertrand Marquis Date: Wed, 25 Mar 2026 15:07:09 +0100 Subject: [PATCH 56/56] virtio-msg: clarify dev_num semantics for bus and transport messages Clarify that bus messages are identified by the common-header type field, not by dev_num, while still requiring bus messages to carry dev_num = 0. Also state explicitly that device number 0 is not reserved for transport messages, and require bus implementations to validate the target device number before forwarding transport traffic. These changes resolve ambiguity in the common-header and forwarding text without changing message definitions or the transport model. Signed-off-by: Bertrand Marquis --- transport-msg.tex | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/transport-msg.tex b/transport-msg.tex index 7f5f5b3..fec70f9 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -124,14 +124,17 @@ \subsubsection{Relationship Between Bus and Transport} \busnormative{\paragraph}{Transport Message Forwarding}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Relationship between bus and transport / Transport Message Forwarding} \begin{itemize} + \item A bus implementation MUST validate the device number in each transport + message before forwarding it. \item A bus implementation MUST relay each transport message to the device number identified in the message header, regardless of how it discovered or enumerated that device. \item A bus implementation SHOULD treat transport messages as opaque apart from enforcing generic transport limits, such as the advertised maximum message size, and SHOULD NOT modify the transport payload. - \item If a bus implementation cannot route a transport message to a device - number, it MAY drop the message or surface a transport-visible failure. + \item If a bus implementation cannot validate or route a transport message to + a device number, it MAY drop the message or surface a + transport-visible failure. \end{itemize} \subsubsection{Known Bus Implementation Examples} @@ -522,7 +525,7 @@ \subsubsection{Common Message Format} le16 token; /* bus-managed correlation identifier */ le16 msg_size; /* total size: header (16) + payload */ le16 reserved; /* reserved, MUST be zero */ - le64 dev_num; /* device number (0 for bus messages) */ + le64 dev_num; /* target device number; bus messages MUST use 0 */ u8 payload[]; }; \end{lstlisting} @@ -548,7 +551,9 @@ \subsubsection{Common Message Format} \item \field{reserved}: Reserved for future use. Transmitters set this field to zero, and receivers ignore it. \item \field{dev_num}: For transport messages, the device number that should - receive the message. Bus messages operate on device number 0. + receive the message. Device number 0 is not reserved for transport + messages. Bus messages are identified by \field{type} and MUST carry + \field{dev_num}=0. \item \field{payload}: Operation-specific data. If a bus introduces extra padding bytes, those bytes are not part of the payload semantics. \end{itemize}