diff --git a/transport-msg.tex b/transport-msg.tex index 79a0a5b..9f8df6f 100644 --- a/transport-msg.tex +++ b/transport-msg.tex @@ -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} @@ -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} @@ -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} @@ -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 & \\ @@ -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} @@ -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 & \\ @@ -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