GET_DEVICES improve, update plan, use normative #28

bertrand-marquis · 2025-11-20T13:32:15Z

In this pull request, I try to do the following:

improve GET_DEVICES message description as it was using number in an imprecise way
sync the plan to other transport definitions (remove introduction, remove BUS operations, have discovery, initialization and operation to mimic other transports)
start to switch to normative statements (only done for now in basic concept and discovery)

Would be nice to have some feedback on the normative and validate the new plan before i finish this.

PDF version of this PR as of 2025-12-03 5PM UTC:
https://github.com/wmamills/virtio-msg-spec/releases/download/bertrand-pr28-wmamills-draft-v31/bertrand-pr28-wmamills-draft-v31.pdf

Rework GET_DEVICES message description to prevent confusion between Number of devices and device number by using device-number for the device number identifier and renaming fields of the message. Also provide an example to illustrate the usage of the message. Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

To comply with the rest of the OASIS Virtio specification removing all emph or textbf around MUST/MAY/SHOULD. Do some minor rewording to prevent using normative wording when not required. Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

To follow the organization of other transports, remove the introduction chapter by moving its content into basic concepts and just having a small introduction paragraph for the chapter instead. Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

Create a stand-alone device discovery section to have the same organization as other transports. Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

Merge content into messages description directly by adding an intended usage paragraph or into the Basic Concepts section. This makes the transport content look more like PCI or Channel IO. Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

Rework the Basic concepts to merge all chapters speaking of bus vs transport and the bus messages and transport messages into a single one to prevent repetition. Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

Move version compatibility rules in a sub-chapter of transport revision in the basic concepts. This is to prepare for the removal of the compliance chapter. Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

Add a new command to have a standard way to define virtio-msg bus normative statements. Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

epilys · 2025-11-24T12:41:38Z

transport-msg.tex

+    These messages are \emph{optional} in environments where
+    device discovery or state changes occur through other means (e.g., device
+    tree). However, if a bus chooses to handle those tasks via messages,
+    it SHOULD implement the appropriate bus message definitions.


Suggestion: move SHOULD statement to busnormative section below

epilys · 2025-11-24T12:42:18Z

transport-msg.tex

+
+\busnormative{\paragraph}{Transport Message Forwarding}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Relationship between bus and transport / Transport Message Forwarding}
+\begin{itemize}
+  \item A bus implementation MUST relay each transport message to the device
+        number identified in the message header, regardless of how it
+        discovered or enumerated that device.
+  \item A bus implementation SHOULD treat transport messages as opaque apart
+        from enforcing generic transport limits, such as the advertised maximum
+        message size, and SHOULD NOT modify the transport payload.
+\end{itemize}
+
+This separation lets a bus remain minimal if it obtains device information from
+firmware tables, while still supporting fully message-based enumeration and
+hotplug when desired.
+


Change order:

Suggested change

\busnormative{\paragraph}{Transport Message Forwarding}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Relationship between bus and transport / Transport Message Forwarding}

\begin{itemize}

\item A bus implementation MUST relay each transport message to the device

number identified in the message header, regardless of how it

discovered or enumerated that device.

\item A bus implementation SHOULD treat transport messages as opaque apart

from enforcing generic transport limits, such as the advertised maximum

message size, and SHOULD NOT modify the transport payload.

\end{itemize}

This separation lets a bus remain minimal if it obtains device information from

firmware tables, while still supporting fully message-based enumeration and

hotplug when desired.

This separation lets a bus remain minimal if it obtains device information from

firmware tables, while still supporting fully message-based enumeration and

hotplug when desired.

\busnormative{\paragraph}{Transport Message Forwarding}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / Relationship between bus and transport / Transport Message Forwarding}

\begin{itemize}

\item A bus implementation MUST relay each transport message to the device

number identified in the message header, regardless of how it

discovered or enumerated that device.

\item A bus implementation SHOULD treat transport messages as opaque apart

from enforcing generic transport limits, such as the advertised maximum

message size, and SHOULD NOT modify the transport payload.

\end{itemize}

epilys · 2025-11-24T12:45:30Z

transport-msg.tex

+imposed by the underlying bus (for example, a framing header) does not count
+against this limit. Today the maximum useful transport payload is expected to
+be 274 bytes, which is sufficient for a GET_CONFIG or SET_CONFIG transfer with
+256 bytes of configuration data.


Today the maximum useful transport payload is expected to
be 274 bytes, which is sufficient for a GET_CONFIG or SET_CONFIG transfer with
256 bytes of configuration data

Not ideal phrasing here. How about turning this into a SHOULD normative statement?

I am a bit wondering if we should not remove this size statement all together as this is really a finger in the air statement, current PoCs are using size smaller than that and ffa is using 104 bytes.

Did a try, let me know what you think

epilys · 2025-11-24T12:46:14Z

transport-msg.tex

+A higher transport revision or additional transport feature bits extend the
+protocol with new messages or capabilities. Implementations are expected to
+remain interoperable across revisions: devices and drivers designed for a newer
+revision still implement the mandatory messages and semantics defined in prior
+revisions. When a bus instance, driver, or device encounters an unsupported
+message or feature, it should reject the request explicitly or ignore it rather
+than exhibit undefined behavior.


This sounds like potential normative statements, too

i will give that a try

Did a try, let me know what you think

epilys · 2025-11-24T12:52:25Z

transport-msg.tex


-A device \emph{MUST} respond with all zero feature data for features bit
-requested beyond those the device implements.
+\devicenormative{\paragraph}{Feature Blocks (Device)}{Virtio Transport Options / Virtio Over Messages / Basic Concepts / FeatureBlocks / Device}


Is FeatureBlocks instead of Feature Blocks on purpose?

This is reusing the label format upper but happy to put full naming here and elsewhere for coherency

epilys · 2025-11-24T12:58:15Z

transport-msg.tex

 \subsubsection{Normative References}
 \label{sec:Virtio Transport Options / Virtio Over Messages / Compliance / NormativeRefs}
-The terms \textbf{MUST}, \textbf{MUST NOT}, \textbf{SHOULD}, \textbf{SHOULD NOT},
-and \textbf{MAY} in this document are to be interpreted as specified by
+The terms MUST, MUST NOT, SHOULD, SHOULD NOT,
+and MAY in this document are to be interpreted as specified by
 \href{https://www.rfc-editor.org/rfc/rfc2119}{RFC 2119}.


this is not necessary, since it's stated in 1.3 Terminology of the spec

The complete compliance section will be removed once we have switch to normative

compliance is now removed

Add bus normative statement in bus vs transport section of basic concepts. Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

Rework the transport revision and maximum message size section to switch to normative declarations. Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

Add normative statement on message size constraints in the revisions chapter. Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

Define some normative statements for backward compatibility rules. Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

Switch to normative statement in device numbers and enumeration section. Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

Rework Generation Count section in basic concept to use normative statements. Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

Also convert the overview Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

All the content of the chapter is now present in normative statements in the required sections. Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

Rework the correlation handling: - fully delegate correlation to the bus - only enforce for answers to be received in the order of the requests - remove restriction to set token to 0 for events - enforce for the device to not make any assumption on the token value Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

Remove (Driver), (Device) or (Bus) as those are repeating the requirement title. Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

Add entries for conformance of Virtio over Message for Driver, Device and bus. Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

Use a table to properly define the message IDs area reserved for specific usage. Use the same format and fully specify also the message IDs area for bus messages. Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

Define the messages format using structures instead of using table to be more coherent with other transports and the rest of virtio specification. Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

Replace compressed forms of labels or normative with long forms (for example FeatureBlocks to Feature Blocks). While there update conformance chapter. Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

To keep messages in the order of the table of IDs, move ping definition before event_device. Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

bertrand-marquis · 2025-12-01T16:55:20Z

I updated the pull request with the following:

full normative rework including adding entries in conformance.tex
switch message definitions to use struct instead of tables: tell me if you think this is better, easy to revert
moved ping before event_device to have the right order
rework correlation chapter to simplify as said during last meeting
clear up message ID numbers by having numbers defined in tables to have clear range for msg/event/custom msg/event on both transport and bus messages

wmamills

This is ready for the PATCH V1

wmamills

I will approve and merge to the virtio-msg-rfc2 branch and then squash and prepare virtio-msg-patch1 branch

bertrand-marquis added 8 commits November 20, 2025 14:18

virtio-msg: create a Device discovery section

92a39c6

Create a stand-alone device discovery section to have the same organization as other transports. Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

virtio-msg: merge all bus vs transport chapters in one

91a41ba

Rework the Basic concepts to merge all chapters speaking of bus vs transport and the bus messages and transport messages into a single one to prevent repetition. Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

virtio-msg: move compatibility rules in basic concepts

d81941b

Move version compatibility rules in a sub-chapter of transport revision in the basic concepts. This is to prepare for the removal of the compliance chapter. Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

virtio-msg: add new command for bus normative

f55c83c

Add a new command to have a standard way to define virtio-msg bus normative statements. Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

bertrand-marquis requested review from arnopo, edgarigl, stsquad and wmamills November 20, 2025 13:33

wmamills requested a review from epilys November 20, 2025 15:07

epilys reviewed Nov 24, 2025

View reviewed changes

bertrand-marquis added 16 commits December 1, 2025 15:57

virtio-msg: normative in bus vs transport relationship

2cae300

Add bus normative statement in bus vs transport section of basic concepts. Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

virtio-msg: rework transport revision

00abb58

Rework the transport revision and maximum message size section to switch to normative declarations. Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

virtio-msg: Add normative statement for message size

da563c1

Add normative statement on message size constraints in the revisions chapter. Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

virtio-msg: Add normative statements for version compat

963fa80

Define some normative statements for backward compatibility rules. Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

virtio-msg: Switch to normative in device numbers

7296f14

Switch to normative statement in device numbers and enumeration section. Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

virtio-msg: switch generation count to normative

6859b5b

Rework Generation Count section in basic concept to use normative statements. Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

virtio-msg: apply normative in feature blocks

db203b9

Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

virtio-msg: Switch error signaling to normative

718d1c0

Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

virtio-msg: switch endianness to normative

b804cc4

Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

virtio-msg: convert common message format to normative

a971eb2

Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

virtio-msg: convert correlation to normative

231b768

Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

virtio-msg: convert device discovery to normative

6a1f550

Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

virtio-msg: convert flow overview to normative

9c88065

Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

virtio-msg: convert device information to normative

3a942a1

Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

virtio-msg: convert feature negotiation to normative

8913885

Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

virtio-msg: switch device configuration to normative

3646c29

Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

bertrand-marquis added 24 commits December 1, 2025 17:37

virtio-msg: convert config changes to normative

da771b3

Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

virtio-msg: convert virtqueue change to normative

a7efbca

Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

virtio-msg: convert reset and shutdown to normative

d08bd5c

Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

virtio-msg: convert hotplug and removal to normative

1002f30

Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

virtio-msg: convert transport messages intro to normative

2060d08

Also convert the overview Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

virtio-msg: convert GET_DEVICE_INFO to normative

770f340

Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

virtio-msg: convert get_features to normative

d17f18f

Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

virtio-msg: convert set_features to normative

f363356

Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

virtio-msg: convert get/set config to normative

e55a0c3

Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

virtio-msg: convert get/set status to normative

42b70ab

Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

virtio-msg: convert vqueue messages to normative

e2b3e9f

Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

virtio-msg: convert get_shm to normative

bd256d6

Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

virtio-msg: convert event messages to normative

9d097f3

Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

virtio-msg: reword bus message intro and overview

c85ef0d

Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

virtio-msg: convert get_devices to normative

a4b4100

Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

virtio-msg: convert event dev and ping to normative

17d1729

Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

virtio-msg: remove compliance chapter

433d538

All the content of the chapter is now present in normative statements in the required sections. Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

virtio-msg: Remove (xx) in normative

b67346b

Remove (Driver), (Device) or (Bus) as those are repeating the requirement title. Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

virtio-msg: add conformance entries in conformance chapter

3688857

Add entries for conformance of Virtio over Message for Driver, Device and bus. Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

virtio-msg: Improve message ID specification

3851e6e

Use a table to properly define the message IDs area reserved for specific usage. Use the same format and fully specify also the message IDs area for bus messages. Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

virtio-msg: Use struct instead of tables for messages

1f2e4d9

Define the messages format using structures instead of using table to be more coherent with other transports and the rest of virtio specification. Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

virtio-msg: Remove compressed chapter lable/normative

c25b9bd

Replace compressed forms of labels or normative with long forms (for example FeatureBlocks to Feature Blocks). While there update conformance chapter. Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

virtio-msg: move ping before event_device

7891b6b

To keep messages in the order of the table of IDs, move ping definition before event_device. Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>

bertrand-marquis force-pushed the bertrand/rfc3 branch from d406e92 to 7891b6b Compare December 1, 2025 16:49

wmamills reviewed Jan 15, 2026

View reviewed changes

wmamills self-requested a review January 15, 2026 10:19

wmamills approved these changes Jan 15, 2026

View reviewed changes

wmamills merged commit 7891b6b into Linaro:virtio-msg-rfc2 Jan 15, 2026
1 check passed

GET_DEVICES improve, update plan, use normative #28

GET_DEVICES improve, update plan, use normative #28

Uh oh!

Conversation

bertrand-marquis commented Nov 20, 2025 • edited by wmamills Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bertrand-marquis commented Dec 1, 2025

Uh oh!

wmamills left a comment

Choose a reason for hiding this comment

Uh oh!

wmamills left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

bertrand-marquis commented Nov 20, 2025 •

edited by wmamills

Loading