scratchpad.tex

\section{Scratchpad}
This section contains ideas for future additions to the \bus protocol. Items
in this section are {\bf not} stable and should {\bf not} be implemented in
current \bus designs.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\paragraph{Broadcast Channel~2: \bus Configuration}
\label{scratch:sec:channel-2}

The purpose of this channel is to configure any \bus parameters. Commands
issued on channel~2 {\bf must} be targeted for the mediator node. By utilizing
a broadcast channel all interested nodes can easily ``subscribe'' to
configuration messages. Using a broadcast channel also permits nodes to
hard-code the address for configuration messages.

The current \bus specification does not define any channel~2 messages.
Possible future messages include:
\begin{itemize}
  \item Maximum message length
  \item Clock speed
\end{itemize}

\paragraph{Broadcast Channel~3: Member Node Events}
\label{scratch:sec:channel-3}

The purpose of this channel is for broadcast dissemination of events that are
specific to one member node.  It also permits the simplification of a member
node design by permitting the member node to hard-code a destination address
for certain classes of messages (e.g. interrupts).

Member node event messages {\bf must} also include a \hlc[lightergreen]{Member
Node Identifier}---the sending node's current short prefix---to disambiguate
member node events. It is possible, and acceptable, for a member node to
generate a member node event message before enumeration has completed, in
which case nodes without a \nameref{sec:addressing-static-short-prefix} send
their current short prefix \nameref{sec:spec-unassigned-short-prefix}.


\subparagraph{Member Node Level Interrupt}
\label{scratch:cmd:level-interrupt}
~

~

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

~

This message announces that an interrupt has occurred on this member node. The
semantics of a \bus level interrupt dictate that an interrupt must be
explicitly cleared. A member node {\bf must not} generate another level
interrupt message {\em for the same interrupt} until that interrupt is
explicitly cleared. A {\em different} interrupt may occur before the first
interrupt is cleared, in which case the bit vector {\bf must} indicate both
interrupts as active. Member nodes are permitted to batch or delay interrupts
if appropriate, that is, a single level interrupt message may indicate the
multiple interrupts have occurred.

Clearing interrupts is {\bf not} a Channel~3 message, as doing so would
require all member nodes to wake for every Channel~3 message.  As a
consequence, systems with multiple nodes capable of clearing a member node
interrupt should develop another means of coordinating the responsibility. A
member node designed to have multiple potential controlling nodes should
consider defining a broadcast control channel.

\bus defines active to be logical {\tt 1}. Member nodes whose internal
interrupts are active low must invert the signal before broadcasting the
interrupt vector. The remaining 24~bits of this message are defined as a bit
vector representing the current status of 24~interrupts.


\subparagraph{Member Node Edge Interrupt}
\label{scratch:cmd:edge-interrupt}
~

~

\begin{minipage}{\linewidth}
  \begin{varwidth}{.2\linewidth}
    \centering
    \begin{bytefield}{8}
      \bitheader{0-7} \\
      \colorbitbox{lightblue}{4}{0000}
      \colorbitbox{lightcyan}{4}{0011}
    \end{bytefield}
  \end{varwidth}
+
  \begin{varwidth}{.8\linewidth}
    \centering
    \begin{bytefield}[bitwidth=1.25em]{32}
      \bitheader{0-31} \\
      \colorbitbox{lightgreen}{4}{0001}
      \colorbitbox{lightergreen}{4}{\scriptsize Sending Node Short Prefix}
      \bitbox{24}{Interrupt Status Vector}
    \end{bytefield}
  \end{varwidth}
\end{minipage}

~

This message announces that an interrupt has occurred on this member node. The
semantics of a \bus edge interrupt dictate that the interrupt is implicitly
cleared. That is, after the broadcast message announcing the interrupt has
been sent the same interrupt is eligible to fire again. Member nodes are
permitted to batch or delay interrupts if appropriate, that is, a single edge
interrupt message may indicate multiple interrupts have occurred.

\bus defines active to be logical {\tt 1}. Member nodes whose internal
interrupts are active low must invert the signal before broadcasting the
interrupt vector. The remaining 24~bits of this message are defined as a bit
vector representing the current status of 24~interrupts.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


\subparagraph{Member Node Set Memory Stream Address LSB}
\label{scratch:cmd:conf-mem-stream-lsb}
~

~

\begin{minipage}{\linewidth}
  \begin{varwidth}{.2\linewidth}
    \centering
    \begin{bytefield}{8}
      \bitheader{0-7} \\
      \colorbitbox{lightblue}{4}{0000}
      \colorbitbox{lightcyan}{4}{0011}
    \end{bytefield}
  \end{varwidth}
+
  \begin{varwidth}{.8\linewidth}
    \centering
    \begin{bytefield}[bitwidth=1.25em]{32}
      \bitheader{0-31} \\
      \colorbitbox{lightgreen}{4}{0010}
      \colorbitbox{lightergreen}{4}{\scriptsize Sending Node Short Prefix}
      \bitbox{4}{\scriptsize Target Node Short Prefix}
      \bitbox{1}{\begin{sideways}{\tiny QRY}\end{sideways}}
      \bitbox{2}{\footnotesize Rsvd}
      \bitbox{1}{\begin{sideways}{\tiny CL T}\end{sideways}}
      \bitbox{16}{Memory Stream Address [15:0]}
    \end{bytefield}
  \end{varwidth}
\end{minipage}

~

This message sets the lower halfword of the \nameref{cmd:mem-stream-write}
destination address for the target node specified in bits 23-20. If the {\tt
CL~T} bit is high, the top halfword of the destination address is cleared (set
to zero).

If the {\tt QRY} (query) bit is set, the {\tt CL~B} and address are ignored.
Instead, the node generates a \nameref{cmd:conf-mem-strem-qresp} with the
Queried Parameter field set to {\tt 0011}.

\subparagraph{Member Node Set Memory Stream Address MSB}
\label{scratch:cmd:conf-mem-stream-msb}
~

~

\begin{minipage}{\linewidth}
  \begin{varwidth}{.2\linewidth}
    \centering
    \begin{bytefield}{8}
      \bitheader{0-7} \\
      \colorbitbox{lightblue}{4}{0000}
      \colorbitbox{lightcyan}{4}{0011}
    \end{bytefield}
  \end{varwidth}
+
  \begin{varwidth}{.8\linewidth}
    \centering
    \begin{bytefield}[bitwidth=1.25em]{32}
      \bitheader{0-31} \\
      \colorbitbox{lightgreen}{4}{0011}
      \colorbitbox{lightergreen}{4}{\scriptsize Sending Node Short Prefix}
      \bitbox{4}{\scriptsize Target Node Short Prefix}
      \bitbox{1}{\begin{sideways}{\tiny QRY}\end{sideways}}
      \bitbox{2}{\footnotesize Rsvd}
      \bitbox{1}{\begin{sideways}{\tiny CL B}\end{sideways}}
      \bitbox{16}{Memory Stream Address [31:16]}
    \end{bytefield}
  \end{varwidth}
\end{minipage}

~

This message sets the upper halfword of the \nameref{cmd:mem-stream-write}
destination address for the target node specified in bits 23-20. If the {\tt
CL~B} bit is high, the bottom halfword of the destination address is cleared
(set to zero).

If the {\tt QRY} (query) bit is set, the {\tt CL~B} and address are ignored.
Instead, the node generates a \nameref{cmd:conf-mem-strem-qresp} with the
Queried Parameter field set to {\tt 0011}.


\subparagraph{Member Node Set Memory Stream Length}
\label{scratch:cmd:conf-mem-stream-len}
~

~

\begin{minipage}{\linewidth}
  \begin{varwidth}{.2\linewidth}
    \centering
    \begin{bytefield}{8}
      \bitheader{0-7} \\
      \colorbitbox{lightblue}{4}{0000}
      \colorbitbox{lightcyan}{4}{0011}
    \end{bytefield}
  \end{varwidth}
+
  \begin{varwidth}{.8\linewidth}
    \centering
    \begin{bytefield}[bitwidth=1.25em]{32}
      \bitheader{0-31} \\
      \colorbitbox{lightgreen}{4}{0100}
      \colorbitbox{lightergreen}{4}{\scriptsize Sending Node Short Prefix}
      \bitbox{4}{\scriptsize Target Node Short Prefix}
      \bitbox{1}{\begin{sideways}{\tiny QRY}\end{sideways}}
      \bitbox{2}{\footnotesize Rsvd}
      \bitbox{1}{\begin{sideways}{\tiny EN}\end{sideways}}
      \bitbox{16}{Length-1}
    \end{bytefield}
  \end{varwidth}
\end{minipage}

~

\hl{TODO: Message}


\subparagraph{Member Node Query Memory Stream Response}
\label{scratch:cmd:conf-mem-stream-qresp}
~

~

\begin{minipage}{\linewidth}
  \begin{varwidth}{.2\linewidth}
    \centering
    \begin{bytefield}{8}
      \bitheader{0-7} \\
      \colorbitbox{lightblue}{4}{0000}
      \colorbitbox{lightcyan}{4}{0011}
    \end{bytefield}
  \end{varwidth}
+
  \begin{varwidth}{.8\linewidth}
    \centering
    \begin{bytefield}[bitwidth=1.25em]{32}
      \bitheader{0-31} \\
      \colorbitbox{lightgreen}{4}{0101}
      \colorbitbox{lightergreen}{4}{\scriptsize Sending Node Short Prefix}
      \bitbox{4}{\scriptsize Query Parameter}
      \bitbox{1}{\begin{sideways}{\tiny RSV}\end{sideways}}
        \bitbox{19}{Queried Parameter}
    \end{bytefield}
  \end{varwidth}
\end{minipage}

~

\hl{TODO: Message}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


\paragraph{Broadcast Channel~7: Data}
\label{scratch:scratch:sec:channel-7}
Channel~7 is used to send arbitrary data to every addressable entity on the
bus. \bus places no further restrictions or structure on channel~7 messages.
Channel~7 is intended for use by more flexible software nodes, though any node
may listen or transmit on channel~7.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

    \begin{tabular}{r|r|l}
      {\tt LU} & Resolution & Range \\
      \hline
      {\tt 00} & 1~word     & 1--64~words (4--256~B) \\
      {\tt 01} & 16~words   & 16--1K~words (64--4K~B) \\
      {\tt 10} & 256~words  & 256--16K~words (1K--64K~B) \\
      {\tt 11} & 4K~words   & 4K--256K~words (16K--1M~B) \\
    \end{tabular}

\subsubsection{Memory Stream Read, Configure, or Alert}
\label{scratch:cmd:mem-stream-multi}

\begin{bytefield}{9}
  \bitheader{0-7} \\
  \bitbox[rbt]{5}{{\dots}Prefix}
  \bitbox{4}{0100} \\
  \bitbox[t]{9}{\hspace{-.5em}$\underbrace{\hspace{9.5em}}_{\text{\small \bus Address}}$}
\end{bytefield}
~
\begin{bytefield}[bitwidth=.5em]{64}
%  \bitheader{0,31} \\
  \bitbox[]{1}{\tiny ~ \\ ~ \\ 31}
  \bitbox[]{5}{}
  \bitbox[]{2}{\tiny ~ \\ ~ \\ 24}
  \bitbox[]{1}{\tiny ~ \\ ~ \\ \begin{sideways}{\tiny 23~}\end{sideways}}
  \bitbox[]{1}{\tiny ~ \\ ~ \\ \begin{sideways}{\tiny 22~}\end{sideways}}
  \bitbox[]{1}{\tiny ~ \\ ~ \\ \begin{sideways}{\tiny 21~}\end{sideways}}
  \bitbox[]{1}{\tiny ~ \\ ~ \\ \begin{sideways}{\tiny 20~}\end{sideways}}
  \bitbox[]{2}{\tiny ~ \\ ~ \\ 19}
  \bitbox[]{1}{\tiny ~ \\ ~ \\ \tt \bf \dots}
  \bitbox[]{16}{}
  \bitbox[]{1}{\tiny ~ \\ ~ \\ 0}
  \bitbox[]{2}{\tiny ~ \\ ~ \\ 31}
  \bitbox[]{1}{\tiny ~ \\ ~ \\ \tt \bf \dots}
  \bitbox[]{26}{}
  \bitbox[]{1}{\tiny ~ \\ ~ \\ 2}
  \bitbox[]{1}{\tiny ~ \\ ~ \\ 1}
  \bitbox[]{1}{\tiny ~ \\ ~ \\ 0}
  \\
  \bitbox{8}{\tiny \bus Reply Address}
  \bitbox{1}{\footnotesize 0}
  \colorbitbox{lightgray}{1}{\footnotesize \tt Z}
  \colorbitbox{lightgray}{1}{\footnotesize \tt Z}
  \colorbitbox{lightgray}{1}{\footnotesize \tt Z}
  \bitbox{20}{Length-1}
  \bitbox{30}{Read Start Address}
  \colorbitbox{lightgray}{1}{\footnotesize \tt Z}
  \colorbitbox{lightgray}{1}{\footnotesize \tt Z}
  \bitbox[]{10}{\raggedright ~$\leftarrow$ Read}
  \\
  \bitbox{8}{\tiny Alert \bus Address}
  \bitbox{1}{\footnotesize 1}
  \bitbox{2}{\tiny 01 10 11}
  \bitbox{1}{\begin{sideways}{\tiny DBLB}\end{sideways}}
  \bitbox{20}{Buffer Length-1}
  \bitbox{30}{Write Start Address}
  \colorbitbox{lightgray}{1}{\footnotesize \tt Z}
  \colorbitbox{lightgray}{1}{\footnotesize \tt Z}
  \bitbox[]{12}{\raggedright ~$\leftarrow$ Configure}
  \\
  \bitbox{8}{\tiny Source \bus Address}
  \bitbox{1}{\footnotesize 1}
  \bitbox{2}{\footnotesize 00}
  \colorbitbox{lightgray}{1}{\footnotesize \tt Z}
  \bitbox{20}{Valid Data Length-1}
  \bitbox{30}{Valid Data Start Address}
  \colorbitbox{lightgray}{1}{\footnotesize \tt Z}
  \colorbitbox{lightgray}{1}{\footnotesize \tt Z}
  \bitbox[]{10}{\raggedright ~$\leftarrow$ Alert}
  \\
  \bitbox[t]{64}{$\underbrace{\hspace{30em}}_{\text{\small \bus Data}}$}
\end{bytefield}

Three commands share the {\tt 0100} FU\_ID. Bits~21--23 in the first word
determine whether the command is a read, configure, or alert. A stream read
generates a stream write. A stream configure is an isolated command with no
response. A stream alert is generated in response to a stream write.

\paragraph{Read (Bit 23 == 0):}
\label{scratch:cmd:mem-stream-multi-read}
The first word indicates the \bus address to reply to and the length of the
requested read in words less one.
The second word received is the address in memory to read from. The bottom two
bits of the address field are reserved and {\bf must} be transmitted as 0.

The response is sent immediately and the message is formatted exactly as the
\nameref{cmd:mem-stream-write} command, that is a series of sequential 32~bit
data fields.

\subparagraph{Overflow:} If the starting address field and subsequent length
exceed the memory space, that is a request for address {\tt 0x100000000} would
have been made during the response, the layer controller wraps and continues
sending from address {\tt 0x00000000}.
{\em Tests: \ref{test:mem-stream-overflow}.}

\paragraph{Interjection Semantics:} If the reply is interjected, the
transaction is aborted and is {\bf not} retried.

\paragraph{Configure (Bit 23 == 1, Bits 22-21 in (01,10,11):}
\label{scratch:cmd:mem-stream-multi-conf}
Bits~22--21 specify which streaming channel is currently being configured.
The first byte holds the \bus address that an Alert message will be sent to
when this streaming channel's buffer is full.
Bits~19--0 specify the maximum length of the buffer.
The second word specifies the address in memory to begin writing to.
Bit~20 {\tt DBLB} specifies whether double-buffering mode is active. Without
double-buffering, an Alert is generated once the buffer is full and the buffer
cannot be written into again until another Configure is received. With
double-buffering, an Alert is generated once halfway through the buffer and
again at the end of the buffer. At the end of the buffer, the address resets
to the beginning of the buffer and continues to accept writes.

\paragraph{Alert (Bit 23 == 1, Bits 22-21 == 00):}
\label{scratch:cmd:mem-stream-multi-alert}
The first byte holds the address of the node generating the Alert.
The second word holds the start of the buffer in the local address space and
the end of the first word specifies the length of the buffer that is valid.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{tabular}{l l}
  {\em asynchronous} & Send single word message to address. \\
  {\em  synchronous} & Retrieve received single-word message. \\
\end{tabular}

\begin{figure}[!h]
\begin{tabular}{ c|c|l }
  {\tt 0xA51} & \tt ~W & \nameref{reg-tx-single} \\
  {\tt 0xA54} & \tt R~ & \nameref{reg-rx-single} \\
\end{tabular}
\end{figure}

\subsubsection{Single Word Write [Write Only]}
\label{scratch:reg-tx-single}
\begin{tabular}{p{9cm} c}
\vspace{-4em}
As a small optimization for the simple, single-word case a single memory write
can express all of the needed information without requiring the layer
controller to issue another request to memory to retrieve data.

As there is no hardware retry primitive, the software is still obligated to
issue a read to determine if the message send was successful. For similar
reasons, this message is an asynchronous message and should return control to
the processor as soon as the layer controller accepts the request, not waiting
for the bus controller to send the message.

&

\begin{tabular}{r l}
  Bits Required & Purpose \\
  \hline
  \hline
  \multicolumn{1}{l}{\em Address} & \\
  8 & \bus Memory Map Location \\
  4 & Command Specifier \\
  8 & Message Destination Address \\
  \multicolumn{1}{l}{\em Data} & \\
  32 & Data to send on \bus \\
\end{tabular}

\\
\end{tabular}

\begin{figure}[!h]
\begin{centering}

\begin{bytefield}{32}
  \bitheader{0-31} \\
  \begin{leftwordgroup}{\tt Address}
    \colorbitbox{lightgreen}{8}{0xA5}
    \colorbitbox{lightergreen}{4}{0x1}
    \bitbox{12}{\em Reserved}
    \bitbox{8}{\footnotesize Destination Address}
  \end{leftwordgroup} \\
\end{bytefield}

\begin{bytefield}{32}
  \bitheader{0-31} \\
  \begin{leftwordgroup}{\tt ~~~Data}
    \bitbox{32}{Data to send on \bus}
  \end{leftwordgroup} \\
\end{bytefield}

\end{centering}
\end{figure}

\subsubsection{RX Word (single-word) [Read Only]}
\label{scratch:reg-rx-single}
\begin{tabular}{p{9cm} c}
\vspace{-4em}
Similar to TX, a shorter path to receive a single word message. If another
message is received prior to this message being read out, the new message
should be NAK'd.

The layer controller may include a small internal queue of received messages.
In that case, the RX~Received interrupt~(\ref{int-rx-rx}) should remain
asserted until all messages have been read out. This will ensure software
cannot disable reception until all messages have been received.

&

\begin{tabular}{r l}
  Bits Required & Purpose \\
  \hline
  \hline
  \multicolumn{1}{l}{\em Address} & \\
  8 & \bus Memory Map Location \\
  4 & Command Specifier \\
  \multicolumn{1}{l}{\em Data} & \\
  32 & Data received \\
\end{tabular}

\\
\end{tabular}

\begin{figure}[!h]
\begin{centering}

\begin{bytefield}{32}
  \bitheader{0-31} \\
  \begin{leftwordgroup}{\tt Address}
    \colorbitbox{lightgreen}{8}{0xA5}
    \colorbitbox{lightergreen}{4}{0x4}
    \bitbox{20}{\em Reserved}
  \end{leftwordgroup} \\
\end{bytefield}

\begin{bytefield}{32}
  \bitheader{0-31} \\
  \begin{leftwordgroup}{\tt ~~~Data}
    \bitbox{32}{Data Received}
  \end{leftwordgroup} \\
\end{bytefield}

\end{centering}
\end{figure}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%% Old Programmer Model


In addition to \proto, \bus also defines a suggested programmer API. While
\proto implementations are not required to adhere to this specification, it is
highly recommended. This specification includes a lightweight software library
built on top of this API.

\begin{tabular}{l l}
  {\em asynchronous} & Dropped message notification. \\
  {\em asynchronous} & Notification of received message and type. \\
\end{tabular}

\subsection{Overview, Memory Map, and Interrupts}
\proto requires a $2^{24}$ region of memory mapped I/O space. By default,
\proto uses {\tt 0xA5000000-0xA6000000}, however this may be changed by
defining the macro {\tt MPQ\_MMIO\_PREFIX} before including {\tt mpq.h}.
The next most significant byte is used to identify the type of request. The
remaining five bytes are defined by each request type:

\begin{tabular}{ c|c|l|l }
  {\tt 0xA50}  & \tt RW & {\em  synchronous} & \nameref{reg-conf} \\
  {\tt 0xA51}  & \tt R~ & {\em  synchronous} & \nameref{reg-int} \\
  {\tt 0xA52}  & \tt ~W & {\em asynchronous} & \nameref{reg-tx-multi} \\
  {\tt 0xA53}  & \tt R~ & {\em  synchronous} & \nameref{reg-tx-result} \\
  {\tt 0xA55}  & \tt RW & {\em  synchronous} & \nameref{reg-rx-multi} \\
  {\tt \vdots} & \tt ~~ &                    & \em Reserved \\
\end{tabular}

In the following sections, there are many reserved bits. These bits shall be
considered RZWI (Read as Zero, Write Ignored). These bits are currently
unused but are reserved for possible future use. Software should write {\tt 0}
to reserved bits to ensure future compatibility.

\subsection{Configurable Parameters}

\subsubsection{Interrupt Configuration [Read/Write]}
\label{reg-conf}
\begin{tabular}{p{9cm} c}
\vspace{-5em}
Depending on the system design, it may be desirable for an interrupt to fire
when a transmission request is completed. Given the very different nature of
long and short requests, they are configured separately.

There is no need to explicitly enable/disable receipt interrupts, as they are
implicitly disabled if all buffer target written bits are set.

&

\begin{tabular}{r l}
  Bits Required & Purpose \{Abbrv\} \\
  \hline
  \hline
  \multicolumn{1}{l}{\em Address} & \\
  8 & \bus Memory Map Location \\
  4 & Command Specifier \\
  \multicolumn{1}{l}{\em Data} & \\
  1 & Long TX Complete Interrupt \{TX L\} \\
  1 & Short TX Complete Interrupt \{TX S\} \\
  1 & Bus dropped an RX~\ref{int-rx-drop} \{RX D\} \\
  1 & Bus received a message~\ref{int-rx-rx} \{RX R\} \\
\end{tabular}

\\

\end{tabular}

\begin{figure}[!h]
\begin{centering}

\begin{bytefield}{32}
  \bitheader{0-31} \\
  \begin{leftwordgroup}{\tt Address}
    \colorbitbox{lightgreen}{8}{0xA5}
    \colorbitbox{lightergreen}{4}{0x0}
    \bitbox{20}{\em Reserved}
  \end{leftwordgroup} \\
\end{bytefield}

\begin{bytefield}{32}
  \bitheader{0-31} \\
  \begin{leftwordgroup}{\tt ~~~Data}
    \bitbox{28}{\em Reserved}
    \bitbox{1}{\begin{sideways}{\tiny RX R}\end{sideways}}
    \bitbox{1}{\begin{sideways}{\tiny RX D}\end{sideways}}
    \bitbox{1}{\begin{sideways}{\tiny TX S}\end{sideways}}
    \bitbox{1}{\begin{sideways}{\tiny TX L}\end{sideways}}
  \end{leftwordgroup} \\
\end{bytefield}

\end{centering}
\end{figure}

\pagebreak

\subsection{TX Transaction Registers}
A properly written program will only issue one transaction at a time---that
is, every request to send a message on the bus will be followed read of the
success of that transaction before issuing another one. If a program does
issue two requests back-to-back, the layer controller should block the second
request until the first is completed. The second request should unblock the
memory bus as soon at the first request is complete and the layer controller
is ready to begin processing the second request. A request for the last
transaction result should reflect the second transaction, blocking if
necessary. There is no method for such an erroneously coded program to check
the return status of the first message.

\subsubsection{Arbitrarily Long Write [Write Only]}
\label{reg-tx-multi}
\begin{tabular}{p{9cm} c}
\vspace{-4.5em}
This transaction requires a buffer to read from and a length. Instead of
duplicating memory units and copying a buffer into the layer controller, the
layer controller instead DMA's directly from memory. This means the layer
controller should have enough local buffer to always stay ahead of the bus
controller and have data prepared in case it loses memory bus arbitration.

For the programmer, this means the region pointed to during this transaction
is immutable. It is undefined what occurs if a write to the transmission
buffer is attempted.

&

\begin{tabular}{r l}
  Bits Required & Purpose \\
  \hline
  \hline
  \multicolumn{1}{l}{\em Address} & \\
  8 & \bus Memory Map Location \\
  4 & Command Specifier \\
  8 & Message Destination Address \\
  8 & Number of {\em words} to send (max 256) \\
  \multicolumn{1}{l}{\em Data} & \\
  32 & Pointer DMA buffer start \\
\end{tabular}

\\
\end{tabular}

\begin{figure}[!h]
\begin{centering}

\begin{bytefield}{32}
  \bitheader{0-31} \\
  \begin{leftwordgroup}{\tt Address}
    \colorbitbox{lightgreen}{8}{0xA5}
    \colorbitbox{lightergreen}{4}{0x2}
    \bitbox{4}{\em Rsvd}
    \bitbox{8}{Length-1}
    \bitbox{8}{\footnotesize Destination Address}
  \end{leftwordgroup} \\
\end{bytefield}

\begin{bytefield}{32}
  \bitheader{0-31} \\
  \begin{leftwordgroup}{\tt ~~~Data}
    \bitbox{32}{Pointer to start of message}
  \end{leftwordgroup} \\
\end{bytefield}

\end{centering}
\end{figure}

\subsubsection{Transaction Result [Read Only]}
\label{reg-tx-result}
\begin{tabular}{p{9cm} c}
\vspace{-4em}
A register that stores the result of the previous transaction request.
``Result'' is defined as the number of bytes successfully sent on the bus
before a reset event occurred and whether the transaction was ACK or NAK'd.
Note that the ACK bit will only be set if the entire transaction completed
successfully and was ACK'd. The length field is primarily useful for a NAK'd
transmission as a {\em hint} to the programmer of what {\em likely} went
wrong. If a message is ACK'd, the length field must match the length of the
request.

The register should block, not returning from the read request until the bus
transaction is complete (though see~\ref{sec:todo-amba} for some concerns). A
read of this register before a transaction has been request will return with a
NAK, the rest of the register contents is undefined.

&

\begin{tabular}{r l}
  Bits Required & Purpose \\
  \hline
  \hline
  \multicolumn{1}{l}{\em Address} & \\
  8 & \bus Memory Map Location \\
  4 & Command Specifier \\
  \multicolumn{1}{l}{\em Data} & \\
  1 & ACK (1) or NAK (0) \\
  8 & Number of {\em words} sent \\
\end{tabular}

\\
\end{tabular}

\begin{figure}[!h]
\begin{centering}

\begin{bytefield}{32}
  \bitheader{0-31} \\
  \begin{leftwordgroup}{\tt Address}
    \colorbitbox{lightgreen}{8}{0xA5}
    \colorbitbox{lightergreen}{4}{0x3}
    \bitbox{20}{\em Reserved}
  \end{leftwordgroup} \\
\end{bytefield}

\begin{bytefield}{32}
  \bitheader{0-31} \\
  \begin{leftwordgroup}{\tt ~~~Data}
    \bitbox{1}{\begin{sideways}{\tiny ACK}\end{sideways}}
    \bitbox{15}{\em Reserved}
    \bitbox{8}{Length-1}
    \bitbox{8}{\em Reserved}
  \end{leftwordgroup} \\
\end{bytefield}

\end{centering}
\end{figure}

\subsection{Transaction RX}

\subsubsection{RX Interrupts}

\paragraph{RX Dropped}
\label{int-rx-drop}
A reception was dropped (bus controller sent reset / did not ACK) by the bus
because there was not enough room to store the message. This interrupt may be
suppressed by~\ref{reg-conf}.

\paragraph{RX Received}
\label{int-rx-rx}
A message has been received. Depending on the expense of
interrupts~(TODO~\ref{sec:todo-interrupts}), this may be a unique interrupt
per RX Buffer or a single shared interrupt with a register to read where a
message came in. This interrupt may be suppressed by~\ref{reg-conf}.
\textbf{Disabling this interrupt will disable message reception.} The bus
controller will NAK even single-word messages if this interrupt is disabled.

\subsubsection{RX Buffer (multi-word) [Read/Write]}
\label{reg-rx-multi}
\begin{tabular}{p{9cm} c}
\vspace{-6em}
Incoming messages need to be stored somewhere, they also may take a non-zero
time to copy out of memory, or in many cases actually copying the message may
be a completely unnecessary and wasteful operation.

The layer controller has \hl{NNNN} configurable message buffer targets. These
targets hold a memory address and a maximum length in words. The target
address must be word-aligned, however the bottom two bits of the address are
reserved for possible future use. Software should take care to write in
word-aligned addresses to this field and to clear the bottom bits when reading
back before use in case they are used by a future implementation. When the
layer controller uses a buffer to store a message, it sets the length of the
received transaction, which marks that buffer as invalid for future use by the
layer controller.

Out of reset, the RX'd message length is non-zero for every target, meaning
the layer is incapable of receiving multi-word messages directly out of reset.
For programs not designed to receive large messages, this will set the M3
system up to automatically NAK long transactions with no programmer
intervention.

&

\begin{tabular}{r l}
  Bits Required & Purpose \\
  \hline
  \hline
  \multicolumn{1}{l}{\em Address} & \\
  8 & \bus Memory Map Location \\
  4 & Command Specifier \\
  2-4 & Buffer Target Index \\
  \multicolumn{1}{l}{\em Data} & \\
  8 & Length of RX'd message \\
  8 & Length of buffer (256 {\em word} max) \\
  16 & Buffer memory address \\
\end{tabular}

\\
\end{tabular}

\begin{figure}[!h]
\begin{centering}

\begin{bytefield}[bitwidth=1em]{32}
  \bitheader{0-31} \\
  \begin{leftwordgroup}{\tt Address}
    \colorbitbox{lightgreen}{8}{0xA5}
    \colorbitbox{lightergreen}{4}{0x5}
    \bitbox{16}{\em Reserved}
    \bitbox{4}{\footnotesize Buffer Index}
  \end{leftwordgroup} \\
\end{bytefield}

\begin{bytefield}[bitwidth=1em]{32}
  \bitheader{0-31} \\
  \begin{leftwordgroup}{\tt ~~~Data}
    \bitbox{8}{\footnotesize Length Received - 1}
    \bitbox{8}{\footnotesize Buffer Length - 1}
    \bitbox{14}{Buffer Address}
    \bitbox{1}{\em R}
    \bitbox{1}{\em R}
  \end{leftwordgroup} \\
\end{bytefield}

\end{centering}
\end{figure}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%% Old Injection Method
\begin{comment}
For a packaged system using \bus, simply providing an external {\tt DIN} and
{\tt DOUT} that is normally jumpered, plus access to the {\tt CLK} line, is
sufficient to allow transient bus elements (such as a programmer, debugger).

For completely contained systems, it is desirable to also define a bus
injection methodology that can be probed onto a chip, as well as a passive
listening method. \bus defines two additional, optional pads that may be added
to any node:

\begin{itemize}
  \item {\tt DSNOOP} -- Snoop, Data out
  \item {\tt MODE}   -- Connected?, Data in
\end{itemize}

The {\tt MODE} pad is connected to a weak pull-down resistor. During device
power-on, if the {\tt MODE} pad is found to be high, an external device is
assumed to be connected. In this case, the {\tt DIN} pad is routed to the {\tt
DSNOOP} pad and the {\tt MODE} pad is routed to the chip-internal {\tt DIN}
signal. Otherwise the {\tt MODE} pad is ignored and the chip {\tt DIN} pad
routes to both the chip-internal {\tt DIN} signal and the {\tt DSNOOP} pad.
These functions are determined during Power-On-Reset and remain fixed until a
future chip-Reset.
\end{comment}
%% END Old Injection Method

Thought from \nameref{sec:bus-return-idle}:
\begin{quote}
\textit{M3 Implementation Note:} (Referring to
\cref{fig:int}) A broadcast sleep message cannot be considered a
sleep until time~18 when the transmitter asserts that all the sent bits were
desired to be sent. This leaves edges at time~20 and time~22 as the required
two edges to power gate the layer.

This could be complicated, however, if a node elects (for some reason) to send
a response to the broadcast sleep message. The sleep controller will still
have four edges (Arbitration, Priority~Drive, Priority~Latch,
Begin~Transmission) to wake its bus controller, but the timing between arming
its {\tt CLK\_IN} fall detector and the mediator node pulling {\tt CLK\_IN} low
in response could cause the sleep controller to miss wakeup.
\end{quote}