Skip to content

Virtio msg: Add unique identifier and relax error handing by the bus #24

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
bertrand-marquis wants to merge 3 commits into from
Closed

Virtio msg: Add unique identifier and relax error handing by the bus #24

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4c2274c
virtio-msg: 8 byte header with unique identifier
bertrand-marquis Oct 9, 2025
8f86c16
virtio-msg: introduce a message correlation protocol
bertrand-marquis Oct 9, 2025
a3c4a36
virtio-msg: Relax error handling in the bus
bertrand-marquis Oct 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
143 changes: 96 additions & 47 deletions transport-msg.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -232,16 +232,31 @@ \subsubsection{Feature Negotiation Blocks}
\subsubsection{Error Signaling}
\label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / ErrorSignaling}

All legal transactions are defined at the transport level and responses defined.
If the transport level does something invalid or the bus has error conditions,
this \emph{SHOULD} be handled at the bus implementation level.
Errors may arise from: (a) malformed or unsupported transport messages, (b)
transmission or routing issues within a bus implementation, or (c) device-side
failures while processing a valid request. Local detection and recovery are
preferred, but a virtio-msg bus \textbf{MAY} report transmission errors to the
virtio-msg transport when it cannot deliver a request or obtain a response
within a bounded policy.

The following rules apply:
\begin{itemize}
\item A bus implementation \textbf{MAY} surface a transport-visible failure
(implementation-defined) after exhausting any bounded retry policy for
a transmission error.
\item Malformed headers or unsupported \field{msg_op} values \textbf{SHOULD}
be discarded; the receiver \textbf{MAY} log them and \textbf{SHOULD NOT}
generate further protocol traffic in response.
\item Event (one-way) messages \textbf{MUST NOT} elicit an error response.
\item Recovery actions (retry, selective reset, device removal) are
environment-specific but \textbf{MUST} comply with any normative reset
or status handling semantics described in
\ref{sec:Virtio Transport Options / Virtio Over Messages / Device Operation}.
\end{itemize}

How the bus recovers from an error (e.g., by retrying, resetting
devices, or escalating to a bus-wide reset) is environment-specific, but
\emph{MUST} adhere to any mandatory behaviors (see
\ref{sec:Virtio Transport Options / Virtio Over Messages / Bus Operation}
and
\ref{sec:Virtio Transport Options / Virtio Over Messages / Device Operation}).
This specification does not mandate a specific error reporting message for
transmission failures; it only permits a virtio-msg bus to surface such
failures to the virtio-msg transport when silent recovery is not feasible.

\subsubsection{Bus vs. Transport Messages}
\label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / BusVsTransport}
Expand Down Expand Up @@ -286,39 +301,73 @@ \subsubsection{Endianness}
\subsubsection{Common Message Format}
\label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Common Message Format}

All virtio-msg exchanges, whether \emph{bus messages} or \emph{transport messages},
begin with a shared header that indicates how the recipient should parse the
rest of the payload. This header has the following 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 header layout is:
\begin{lstlisting}
struct virtio_msg_message {
uint8_t type;
uint8_t msg_id;
uint16_t dev_num;
uint16_t msg_size;
u8 payload[];
struct virtio_msg_header {
uint8_t type; /* request/response + bus/transport */
uint8_t msg_op; /* message operation code */
uint16_t dev_num; /* device number (0 for bus messages) */
uint16_t msg_uid; /* correlation identifier (0 for events) */
uint16_t msg_size; /* total size: header (8) + payload */
uint8_t payload[];
};
\end{lstlisting}

The fields in this header have the following usage:
Field semantics:
\begin{itemize}
\item \field{type}:
\begin{itemize}
\item Bit[0]: Identifies if a message is a request (0) or a response
to a request (1).
\item Bit[1]: Identifies if a message is a Transport Message (0) or a
Bus Message (1).
\item Bit[2-7] Are reserved for future use and must be zero.
\item Bit[0]: 0=request, 1=response.
\item Bit[1]: 0=Transport Message, 1=Bus Message.
\item Bits[2..7]: \textbf{MUST} be zero; receivers \textbf{MUST} ignore.
\end{itemize}
\item \field{msg_id}:
Uniquely identifies which message definition applies (e.g., GET_DEVICES,
GET_DEVICE_FEATURES, SET_CONFIG). The specific range or enumeration of types is
defined in sections \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}:
Identifies the Device Number the message is targeting or is coming from for
Transport Message and must be zero of Bus messages.
\item \field{msg_size};
Indicates the total length of the message payload including the header.
\item \field{msg_op}: Operation code identifying the message definition. Ranges
are defined in
\ref{sec:Virtio Transport Options / Virtio Over Messages / Transport Messages}
and
\ref{sec:Virtio Transport Options / Virtio Over Messages / Bus Messages}.
\item \field{dev_num}: For Transport Messages, the target device number; for
Bus Messages \textbf{MUST} be zero.
\item \field{msg_uid}: Non-zero for requests that expect a response; zero
\textbf{MUST} be used only for event (one-way) messages. Responses
\textbf{MUST} echo the request's \field{msg_uid}.
\item \field{msg_size}: Total size in bytes of the complete message (header +
payload). \textbf{MUST} be \(\ge 8\) and \textbf{MUST NOT} exceed the
bus's maximum message size.
\item \field{payload}: Operation-specific data. Unused trailing bytes (if any
introduced by a bus framing) \textbf{MUST} be zero and \textbf{MUST} be
ignored by receivers.
\end{itemize}

All reserved header bits and any unspecified header values \textbf{MUST} be
sent as zero and \textbf{MUST} be ignored on receive to preserve forward
compatibility.

\subsubsection{Message Correlation}
\label{sec:Virtio Transport Options / Virtio Over Messages / Basic Concepts / Correlation}

Correlation associates a response with its request:
\begin{itemize}
\item Bus Message key: \field{msg_uid}.
\item Transport Message key: (\field{dev_num}, \field{msg_uid}).
\end{itemize}

Rules:
\begin{itemize}
\item The driver allocates a non-zero \field{msg_uid} for every request that
expects a response and \textbf{MUST NOT} reuse it while in flight.
\item Event (one-way) messages \textbf{MUST} set \field{msg_uid}=0 and MUST
NOT yield a response.
\item A response \textbf{MUST} echo \field{msg_uid}, \field{dev_num} (for
transport), and \field{msg_op}.
\item Unknown or already completed correlation tuples \textbf{SHOULD} result
in discarding the response without further protocol action.
\item Implementations \textbf{MAY} deliver responses out of order unless a
specific message definition mandates ordering.
\end{itemize}

\subsection{Bus Operation}
Expand Down Expand Up @@ -391,8 +440,8 @@ \subsubsection{Monitoring the Bus}
\subsubsection{Bus Specific Messages}
\label{sec:Virtio Transport Options / Virtio Over Messages / Bus Operation / Bus Specific Messages}

A range of message IDs are reserved for use by the specific bus
implementation. These messages can be used for any implementation specific
A range of message operation identifiers are reserved for use by the specific
bus implementation. These messages can be used for any implementation specific
usage. Example usage could include:

\begin{itemize}
Expand Down Expand Up @@ -715,11 +764,11 @@ \subsubsection{Overview}
Most transport messages adopt a \emph{request/response} pattern, but some are
unidirectional (e.g., asynchronous notifications).

\paragraph{Messages IDs and issuers}
\paragraph{Messages Operation (OP) identifiers and issuers}

\begin{tabular}{|l|l|l|}
\hline
Name & ID & Sender \\
Name & OP identifier & Sender \\
\hline
\hline
Reserved & 0x0 & \\
Expand Down Expand Up @@ -756,8 +805,8 @@ \subsubsection{Overview}
\hline
\end{tabular}

Transport message IDs 0x00 to 0x3F are used for messages that require a response
and IDs 0x40 to 0x7F are used for event messages. Transport message IDs 0x80
Transport message OPs 0x00 to 0x3F are used for messages that require a response
and OPs 0x40 to 0x7F are used for event messages. Transport message OPs 0x80
and above are reserved by this specification.

\paragraph{Mandatory Transport Messages}
Expand Down Expand Up @@ -1080,11 +1129,11 @@ \subsection{Bus Messages}\label{sec:Virtio Transport Options / Virtio Over Messa
firmware tables, device trees). Each bus instance \emph{may} use a subset of or
all these messages according to its design.

\paragraph{Messages IDs and issuers}
\paragraph{OPs identifiers and issuers}

\begin{tabular}{|l|l|l|}
\hline
Name & ID & Sender \\
Name & OP identifier & Sender \\
\hline
\hline
Reserved & 0x0 & \\
Expand All @@ -1099,14 +1148,14 @@ \subsection{Bus Messages}\label{sec:Virtio Transport Options / Virtio Over Messa
\hline
\end{tabular}

Bus message IDs below 0x80 are reserved for standardizes (but optional) bus
Bus message OPs below 0x80 are reserved for standardizes (but optional) bus
messages. A few are used here and more are expected in the future. Bus message
IDs below 0x40 are used for request/response messages and 0x40 and above for
OPs below 0x40 are used for request/response messages and 0x40 and above for
event messages.

Bus message IDs 0x80 and above are bus implementation specific. Bus
implementations \emph{MAY} specify the policy that IDs below 0xC0 be used
for request/response messages and IDs 0xC0 and above are used for event messages.
Bus message OPs 0x80 and above are bus implementation specific. Bus
implementations \emph{MAY} specify the policy that OPs below 0xC0 be used
for request/response messages and OPs 0xC0 and above are used for event messages.

\paragraph{Note:} A bus implementation \textbf{is not required} to use these
messages if it already provides equivalent functionality through some
Expand Down