protocol.tex

\section{\bus Protocol Design}
\label{sec:protocol}

To maximize device interoperability, \bus defines a higher-level protocol for
basic point-to-point register and memory access. \bus also defines a protocol
for broadcast messages.

\bus reserves two prefixes: a {\em broadcast} prefix and an {\em extension}
prefix.  The extension prefix is used in the short prefix space to identify
full addresses. It is currently unused and reserved in the full prefix space.

\markedsubsection{Broadcast Messages}{Broadcast Messages (Address \texttt{0x0X}, \texttt{0xf000000X})}
\label{sec:control-broadcast}
\bus defines the broadcast short prefix as {\tt 0b0000} and the broadcast full
prefix as {\tt 0x00000}. Broadcast messages
are permitted to be of arbitrary length. Messages longer than 32~bits may be
silently dropped by nodes with small buffers. A node \textbf{must not}
interject a broadcast message to indicate buffer overflow. Interjections
are permitted for broadcast messages greater than 4~bytes in length.

For broadcast messages, the functional unit ID field is used to define
broadcast {\em channels}. Broadcast channel selection is used to differentiate
between the different types of broadcast messages. \bus reserves half of these
channels and leaves the rest as implementation-defined.
%
The MSB of the broadcast channel identifier (address bit~3) shall identify
\bus broadcast operations. If the MSB is {\tt 0} it indicates an official \bus
broadcast message as specified in this document and subsequent revisions.
Broadcast messages with a channel MSB of {\tt 1} are implementation-defined.
It is recommended that nodes leveraging implementation-defined broadcast
channels provide a mechanism to dynamically select broadcast channel to help
mitigate conflicts.

A broadcast message that is not understood \textbf{must} be completely
ignored. During acknowledgment, an ignorant node shall forward.

\subsubsection{Broadcast Messages and Power-Gating}
Some systems may have inter-node dependencies on {\tt Layer} power state,
e.g.\ activating a higher power regulator before a high-power component. For
this reason, by default nodes must not change {\tt Layer} power state upon
receipt of a broadcast message, excepting messages that explicitly change {\tt
Layer} power state.

Some nodes, for example a general purpose processor that is snooping, may want
to wake their {\tt Layer} for all messages. This is permitted, but nodes with
non-standard broadcast power behavior must clearly document power semantics to
be \bus compliant.

\subsubsection{Broadcast Channels and Messages}
This section breaks down all of the defined \bus broadcast channels and messages.
All undefined channels are reserved and shall not be used. A node receiving a
broadcast message for a reserved channel shall ignore the message. It {\bf
must not} acknowledge a message on a reserved channel and {\bf must} forward
during the acknowledgment cycle.

All \bus broadcast messages, except those sent on \nameref{sec:channel-7},
follow a common template. The messages are 32~bits long. The four most
significant bits identify the message~type/command. Some messages do not
require all 32~bits. The unused bits are named {\em insignificant bits}.
Messages may be truncated, omitting the insignificant bits on the
wire\footnote{
  With the caveat that all \bus messages must be byte-aligned. Some
insignificant bits may still be sent on the wire as a consequence.}.

All examples are shown with short addresses for space. There is no distinction
between the use of the short or full broadcast address.
Bitfields are presented \textbf{\color{blue} Address}~+~\textbf{\color{OliveGreen} Data}.
Addresses are broken down into the \hlc[lightblue]{Broadcast Prefix} and the
\hlc[lightcyan]{Broadcast Channel}. Data is broken down into a
\hlc[lightgreen]{Message Type Specifier} and the message itself.
%
In the bitfields,
{\tt 0} and {\tt 1} indicate bits that must be set to that value, {\tt X}
indicates bits that depend on the current message, and {\tt Z} indicates bits
that should be {\em ignored}---accept any value, send as {\tt 0}.
\hlc[lightgray]{Insignificant Bits} are also indicated as {\tt Z}.

\paragraph{Broadcast Channel~0: Node Discovery and Enumeration}
\label{sec:channel-0}

Channel~0 is used for messages related to node discovery and enumeration.
Channel~0 messages either require a response or are a response. Channel~0
response messages should not be sent unless solicited. The {\tt
Bus~Controller} is responsible for handling Channel~0 messages. Channel~0
messages should not affect {\tt Layer} power state.

\subparagraph{Query Devices}
\label{cmd:query-devices}
~

~

\begin{minipage}{\linewidth}
  \begin{varwidth}{.2\linewidth}
    \centering
    \begin{bytefield}{8}
      \bitheader{0-7} \\
      \colorbitbox{lightblue}{4}{0000}
      \colorbitbox{lightcyan}{4}{0000}
    \end{bytefield}
  \end{varwidth}
+
  \begin{varwidth}{.8\linewidth}
    \begin{bytefield}[bitwidth=1.25em]{32}
      \bitheader{0-31} \\
      \colorbitbox{lightgreen}{4}{0000}
      \bitbox{4}{ZZZZ}
      \colorbitbox{lightgray}{24}{ZZZZ ZZZZ ZZZZ ZZZZ ZZZZ ZZZZ}
    \end{bytefield}
  \end{varwidth}
\end{minipage}

~

The query devices command is a request for all devices to broadcast their
static full prefix and currently assigned short prefix on the bus. Every \bus
node must prepare a \nameref{cmd:query-response} when this message is
received.

\medskip
\noindent
\textit{All nodes are required to support this message and respond.}

\subparagraph{Query/Enumerate Response}
\label{cmd:query-response}
~

~

\begin{minipage}{\linewidth}
  \begin{varwidth}{.2\linewidth}
    \centering
    \begin{bytefield}{8}
      \bitheader{0-7} \\
      \colorbitbox{lightblue}{4}{0000}
      \colorbitbox{lightcyan}{4}{0000}
    \end{bytefield}
  \end{varwidth}
+
  \begin{varwidth}{.8\linewidth}
    \centering
    \begin{bytefield}[bitwidth=1.25em]{32}
      \bitheader{0-31} \\
      \colorbitbox{lightgreen}{4}{0001}
      \bitbox{4}{ZZZZ}
      \bitbox{20}{Full Prefix}
      \bitbox{4}{Short Prefix}
    \end{bytefield}
  \end{varwidth}
\end{minipage}

~

This message is sent in response to a \nameref{cmd:query-devices} or
\nameref{cmd:invalidate-prefix} request. When responding to
\nameref{cmd:query-devices}, every node will be transmitting their address,
and nodes should anticipate losing arbitration several times before they are
able to send their response.

The top four bits of the data field identify the message as a Query~Response.
The next four bits are ignored. The following 20~bits contain the full prefix
of the node. The final 4~bits are the currently assigned short prefix. Nodes
that have not been enumerated should report a short prefix of {\tt 0b1111}.

This message must be sent in response to \nameref{cmd:query-devices} or
\nameref{cmd:enumerate-node}. When responding to \nameref{cmd:query-devices},
nodes {\bf must} retry until the message is sent. When responding to
\nameref{cmd:enumerate-node}, nodes {\bf must not} retry sending if
arbitration is lost and {\bf must} retry sending if interjected.\footnote{
  An interjection should not occur during this message. Such an interjection
  would be an error.}

\medskip
\noindent
\textit{All nodes are required to support this message.}

\subparagraph{Enumerate Node}
\label{cmd:enumerate-node}
~

~

\begin{minipage}{\linewidth}
  \begin{varwidth}{.2\linewidth}
    \centering
    \begin{bytefield}{8}
      \bitheader{0-7} \\
      \colorbitbox{lightblue}{4}{0000}
      \colorbitbox{lightcyan}{4}{0000}
    \end{bytefield}
  \end{varwidth}
+
  \begin{varwidth}{.8\linewidth}
    \centering
    \begin{bytefield}[bitwidth=1.25em]{32}
      \bitheader{0-31} \\
      \colorbitbox{lightgreen}{4}{0010}
      \bitbox{4}{Short Prefix}
      \colorbitbox{lightgray}{24}{ZZZZ ZZZZ ZZZZ ZZZZ ZZZZ ZZZZ}
    \end{bytefield}
  \end{varwidth}
\end{minipage}

~

This message assigns a short prefix to a device. All nodes that receive this
message and do not have an assigned short prefix {\bf must} attempt to reply
with a \nameref{cmd:query-response}. Nodes with a short prefix shall ignore
the message (broadcast NAK, that is, forward). Nodes shall perform exactly one
attempt to reply to this message. The node that wins arbitration shall be
assigned the short prefix from this message. Nodes that lose arbitration shall
remain unchanged.

Nodes that have an assigned short prefix shall ignore this message.

\medskip
\noindent
\textit{All nodes are required to support this message and respond if
appropriate.}

\subparagraph{Invalidate Prefix}
\label{cmd:invalidate-prefix}
~

~

\begin{minipage}{\linewidth}
  \begin{varwidth}{.2\linewidth}
    \centering
    \begin{bytefield}{8}
      \bitheader{0-7} \\
      \colorbitbox{lightblue}{4}{0000}
      \colorbitbox{lightcyan}{4}{0000}
    \end{bytefield}
  \end{varwidth}
+
  \begin{varwidth}{.8\linewidth}
    \centering
    \begin{bytefield}[bitwidth=1.25em]{32}
      \bitheader{0-31} \\
      \colorbitbox{lightgreen}{4}{0011}
      \bitbox{4}{Short Prefix}
      \colorbitbox{lightgray}{24}{ZZZZ ZZZZ ZZZZ ZZZZ ZZZZ ZZZZ}
    \end{bytefield}
  \end{varwidth}
\end{minipage}

~

This message clears the assignment of a short prefix. The bottom 4~bits
specify the node whose prefix shall be reset. A node shall reset its prefix
to \nameref{sec:spec-unassigned-short-prefix}. If the prefix to clear is set
to \nameref{sec:spec-unassigned-short-prefix}, then all nodes shall reset
their prefixes.

\medskip
\noindent
\textit{All nodes are required to support this message.}

\paragraph{Broadcast Channel~1: {\tt Layer} Power}
\label{sec:channel-1}

Channel~1 is used to query and command the {\tt Layer} power state of \bus
nodes.  Power-oblivious nodes may ignore channel~1. Power-aware nodes whose
power model does not align well with these commands may ignore channel~1
messages {\em except} \nameref{cmd:all-sleep}. All nodes capable of entering a
low-power state {\bf must} enter their lowest power state in response to an
\nameref{cmd:all-sleep} message.

A node {\tt Layer} is implicitly waked when a message is addressed to it,
explicitly issuing a wake command is unnecessary to communicate with a node.
Nodes may build finer-grained power constructs beyond the macro {\tt Layer}
control provided by \bus. For the purposes of \bus, a node's ``sleep'' state
should be a minimal power state. Nodes may have different sleep
configurations, e.g.\ different interrupts that are armed.

\subparagraph{All Sleep}
\label{cmd:all-sleep}
~

~

\begin{minipage}{\linewidth}
  \begin{varwidth}{.2\linewidth}
    \centering
    \begin{bytefield}{8}
      \bitheader{0-7} \\
      \colorbitbox{lightblue}{4}{0000}
      \colorbitbox{lightcyan}{4}{0001}
    \end{bytefield}
  \end{varwidth}
+
  \begin{varwidth}{.8\linewidth}
    \centering
    \begin{bytefield}[bitwidth=1.25em]{32}
      \bitheader{0-31} \\
      \colorbitbox{lightgreen}{4}{0000}
      \bitbox{4}{ZZZZ}
      \colorbitbox{lightgray}{24}{ZZZZ ZZZZ ZZZZ ZZZZ ZZZZ ZZZZ}
    \end{bytefield}
  \end{varwidth}
\end{minipage}

~

All nodes receiving this message {\bf must} immediately enter their lowest
possible power state. The bottom~28 bits of this message are reserved and
should be {\em ignored}.

\medskip
\noindent
\textit{All power-aware nodes are required to support this message.}

\subparagraph{All Wake}
\label{cmd:all-wake}
~

~

\begin{minipage}{\linewidth}
  \begin{varwidth}{.2\linewidth}
    \centering
    \begin{bytefield}{8}
      \bitheader{0-7} \\
      \colorbitbox{lightblue}{4}{0000}
      \colorbitbox{lightcyan}{4}{0001}
    \end{bytefield}
  \end{varwidth}
+
  \begin{varwidth}{.8\linewidth}
    \centering
    \begin{bytefield}[bitwidth=1.25em]{32}
      \bitheader{0-31} \\
      \colorbitbox{lightgreen}{4}{0001}
      \bitbox{4}{ZZZZ}
      \colorbitbox{lightgray}{24}{ZZZZ ZZZZ ZZZZ ZZZZ ZZZZ ZZZZ}
    \end{bytefield}
  \end{varwidth}
\end{minipage}

~

All nodes receiving this message {\bf must} immediately wake up. The bottom
28~bits of this message are reserved and should be {\em ignored}.

\subparagraph{Selective Sleep By Short Prefix}
\label{cmd:selective-sleep-short}
~

~

\begin{minipage}{\linewidth}
  \begin{varwidth}{.2\linewidth}
    \centering
    \begin{bytefield}{8}
      \bitheader{0-7} \\
      \colorbitbox{lightblue}{4}{0000}
      \colorbitbox{lightcyan}{4}{0001}
    \end{bytefield}
  \end{varwidth}
+
  \begin{varwidth}{.8\linewidth}
    \centering
    \begin{bytefield}[bitwidth=1.25em]{32}
      \bitheader{0-31} \\
      \colorbitbox{lightgreen}{4}{0010}
      \bitbox{1}{Z}
      \bitbox{1}{X} \bitbox{1}{X} \bitbox{1}{X} \bitbox{1}{X} \bitbox{1}{X}
      \bitbox{1}{X} \bitbox{1}{X} \bitbox{1}{X} \bitbox{1}{X} \bitbox{1}{X}
      \bitbox{1}{X} \bitbox{1}{X} \bitbox{1}{X} \bitbox{1}{X}
      \bitbox{1}{Z}
      \bitbox{4}{ZZZZ}
      \colorbitbox{lightgray}{8}{ZZZZ ZZZZ}
    \end{bytefield}
  \end{varwidth}
\end{minipage}

~

This message instructs selected nodes to sleep. The 16~bits of data are
treated as a bit vector, mapping short prefixes to bit indicies. That is, the
node with short prefix {\tt 0b1101} is controlled by the second bit received
(bit~25 in the bit vector above). If a bit is set to
{\tt 1}, the selected node {\bf must} enter sleep mode. If a bit is set to
{\tt 0}, the selected node should not change power state. The bits for
prefixes {\tt 0b1111} and {\tt 0b0000} are ignored.

\subparagraph{Selective Wake By Short Prefix}
\label{cmd:selective-wake}
~

~

\begin{minipage}{\linewidth}
  \begin{varwidth}{.2\linewidth}
    \centering
    \begin{bytefield}{8}
      \bitheader{0-7} \\
      \colorbitbox{lightblue}{4}{0000}
      \colorbitbox{lightcyan}{4}{0001}
    \end{bytefield}
  \end{varwidth}
+
  \begin{varwidth}{.8\linewidth}
    \centering
    \begin{bytefield}[bitwidth=1.25em]{32}
      \bitheader{0-31} \\
      \colorbitbox{lightgreen}{4}{0011}
      \bitbox{1}{Z}
      \bitbox{1}{X} \bitbox{1}{X} \bitbox{1}{X} \bitbox{1}{X} \bitbox{1}{X}
      \bitbox{1}{X} \bitbox{1}{X} \bitbox{1}{X} \bitbox{1}{X} \bitbox{1}{X}
      \bitbox{1}{X} \bitbox{1}{X} \bitbox{1}{X} \bitbox{1}{X}
      \bitbox{1}{Z}
      \bitbox{4}{ZZZZ}
      \colorbitbox{lightgray}{8}{ZZZZ ZZZZ}
    \end{bytefield}
  \end{varwidth}
\end{minipage}

~

This message instructs selected nodes to wake. The 16~bits of data are
treated as a bit vector, mapping short prefixes to bit indicies. That is, the
node with short prefix {\tt 0b1101} is controlled by the second bit received
(bit~18 in the bit vector above). If a bit is set to
{\tt 1}, the selected node {\bf must} wake up. If a bit is set to
{\tt 0}, the selected node should not change power state. The bits for
prefixes {\tt 0b1111} and {\tt 0b0000} are ignored.

\subparagraph{Selective Sleep By Full Prefix}
\label{cmd:selective-sleep-full}
~

~

\begin{minipage}{\linewidth}
  \begin{varwidth}{.2\linewidth}
    \centering
    \begin{bytefield}{8}
      \bitheader{0-7} \\
      \colorbitbox{lightblue}{4}{0000}
      \colorbitbox{lightcyan}{4}{0001}
    \end{bytefield}
  \end{varwidth}
+
  \begin{varwidth}{.8\linewidth}
    \centering
    \begin{bytefield}[bitwidth=1.25em]{32}
      \bitheader{0-31} \\
      \colorbitbox{lightgreen}{4}{0100}
      \bitbox{4}{ZZZZ}
      \bitbox{20}{Full Prefix}
      \bitbox{4}{ZZZZ}
    \end{bytefield}
  \end{varwidth}
\end{minipage}

~

This message instructs selected nodes to sleep. Any node whose full prefix
matches {\bf must} enter sleep.

\subparagraph{Selective Wake By Full Prefix}
\label{cmd:selective-wake-full}
~

~

\begin{minipage}{\linewidth}
  \begin{varwidth}{.2\linewidth}
    \centering
    \begin{bytefield}{8}
      \bitheader{0-7} \\
      \colorbitbox{lightblue}{4}{0000}
      \colorbitbox{lightcyan}{4}{0001}
    \end{bytefield}
  \end{varwidth}
+
  \begin{varwidth}{.8\linewidth}
    \centering
    \begin{bytefield}[bitwidth=1.25em]{32}
      \bitheader{0-31} \\
      \colorbitbox{lightgreen}{4}{0101}
      \bitbox{4}{ZZZZ}
      \bitbox{20}{Full Prefix}
      \bitbox{4}{ZZZZ}
    \end{bytefield}
  \end{varwidth}
\end{minipage}

~

This message instructs selected nodes to wake. Any node whose full prefix
matches {\bf must} wake up.

\paragraph{Broadcast Channels~2-7: Reserved}
\label{sec:channel-2}
\label{sec:channel-3}
\label{sec:channel-4}
\label{sec:channel-5}
\label{sec:channel-6}
\label{sec:channel-7}

\markedsubsection{Extension Messages}{Extension Messages (Address \texttt{0xffffffff})}
This address is reserved for future extensions to \bus.