programmer_model.tex

\section{\proto Programmer's Model}
\label{sec:programmer}

This section documents the \bus and \proto MMIO interface used in the M3
system.

\subsection{Accessing \proto Registers [simple method]}
\label{prog:proto-registers-simple}

The \proto registers are mapped directly into the MMIO address space. Since
\proto registers are only 24~bits wide, the top 8~bits of data are always
RZWI.

\subsubsection{\proto Registers}
\label{prog:mmap:proto-registers-simple}
\begin{tabular}{p{9cm} c}
\vspace{-4em}
These registers map directly to \proto registers. For details of each
register's behavior, see \nameref{cmd:mmap}. Registers below \#192 are
chip-specific registers.

&

\begin{tabular}{r l}
  Bits Required & Purpose \\
  \hline
  \hline
  \multicolumn{1}{l}{\em Address} & \\
  24 & Memory Map Location \\
   8 & \proto Register \\
  \multicolumn{1}{l}{\em Data} & \\
  24 & Register contents \\
\end{tabular}

\\
\end{tabular}

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

\begin{bytefield}{32}
  \bitheader{0-31} \\
  \begin{leftwordgroup}{\tt Address}
    \colorbitbox{lightgreen}{8}{0xAX}
    \colorbitbox{lightergreen}{16}{0x0001}
    \bitbox{8}{\proto Addr}
  \end{leftwordgroup} \\
\end{bytefield}

\begin{bytefield}{32}
  \bitheader{0-31} \\
  \begin{leftwordgroup}{\tt ~~~Data}
    \colorbitbox{lightgray}{8}{Reserved}
    \bitbox{24}{Register contents}
  \end{leftwordgroup} \\
\end{bytefield}

\end{centering}
\end{figure}

\subsection{Accessing \proto Registers [efficient method]}
\label{prog:proto-registers-efficient}

\hl{%
  This is just a thought. It reduces a lot of masking and shifting on the CPU
  side, but requires the HW to access either 2 or 4 registers on each MMIO
  operation.
}

As \proto registers are 24~bits wide and machine words are 32~bits wide, we
can map 4~\proto registers onto 3~MMIO words. We define a \emph{bank} of
\proto registers as a set of four \proto registers. Each bank has a
\texttt{TOP}, \texttt{LOW}, and \texttt{HIGH} register.

\begin{quote}
  \texttt{BANK0\_T: \{R3[23:16], R2[23:16], R1[23:16], R0[23:16]\}} \\
  \texttt{BANK0\_L: \{R1[15:0], R0[15:0]\}} \\
  \texttt{BANK0\_H: \{R3[15:0], R2[15:0]\}}
\end{quote}

There are 256~\proto registers, and thus 64~banks.

\subsubsection{\proto Registers}
\label{prog:mmap:proto-registers-efficient}
\begin{tabular}{p{9cm} c}
\vspace{-4em}
These registers map directly to \proto registers. For details of each
register's behavior, see \nameref{cmd:mmap}. Registers below \#192 are
chip-specific registers.

&

\begin{tabular}{r l}
  Bits Required & Purpose \\
  \hline
  \hline
  \multicolumn{1}{l}{\em Address} & \\
  24 & Memory Map Location \\
   6 & Bank ID \\
   2 & Top/Low/High \\
  \multicolumn{1}{l}{\em Data} & \\
  32 & Bank register contents \\
\end{tabular}

\\
\end{tabular}

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

\begin{bytefield}{32}
  \bitheader{0-31} \\
  \begin{leftwordgroup}{\tt Address}
    \colorbitbox{lightgreen}{8}{0xAX}
    \colorbitbox{lightergreen}{16}{0x0002}
    \bitbox{6}{Bank ID}
    \bitbox{2}{\scriptsize TLH}
  \end{leftwordgroup} \\
\end{bytefield}

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

\end{centering}
\end{figure}


\newpage
\subsection{Sending \bus Transactions}
\label{prog:send-txn}

The core issues \bus transactions by emulating incoming \bus transactions. For
example, to issue a DMA transaction to another node (a memory \emph{write}),
the core emulates a memory \emph{read} request from the destination node. This
can be tricky to reason about, especially for writing general-purpose
transactions. System designers are highly encouraged to use the provided
\texttt{mbus.c} library.


\subsubsection{\texttt{CMD0, CMD1, CMD2}}
\label{prog:mmap:cmd}
\begin{tabular}{p{9cm} c}
\vspace{-4em}
These three registers hold the data ``from'' the bus. Bits ``arrive in
order'', that is, the MSB of \texttt{CMD0} is the first \emph{data} bit to
arrive on the bus. The address is not included. The destination
prefix is omitted, and the FUID is specified by the
\nameref{prog:mmap:fuid-len} register.

&

\begin{tabular}{r l}
  Bits Required & Purpose \\
  \hline
  \hline
  \multicolumn{1}{l}{\em Address} & \\
  32 & Memory Map Location \\
  \multicolumn{1}{l}{\em Data} & \\
  32 & Payload \\
\end{tabular}

\\
\end{tabular}

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

\begin{bytefield}{32}
  \bitheader{0-31} \\
  \begin{leftwordgroup}{\tt Address}
    \colorbitbox{lightgreen}{8}{0xAX}
    \colorbitbox{lightergreen}{24}{0x000000}
  \end{leftwordgroup} \\
\end{bytefield}

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

\begin{bytefield}{32}
  \bitheader{0-31} \\
  \begin{leftwordgroup}{\tt Address}
    \colorbitbox{lightgreen}{8}{0xAX}
    \colorbitbox{lightergreen}{24}{0x000004}
  \end{leftwordgroup} \\
\end{bytefield}

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

\begin{bytefield}{32}
  \bitheader{0-31} \\
  \begin{leftwordgroup}{\tt Address}
    \colorbitbox{lightgreen}{8}{0xAX}
    \colorbitbox{lightergreen}{24}{0x000008}
  \end{leftwordgroup} \\
\end{bytefield}

\begin{bytefield}{32}
  \bitheader{0-31} \\
  \begin{leftwordgroup}{\tt ~~~Data}
    \bitbox{32}{Payload bits 64--95}
  \end{leftwordgroup} \\
\end{bytefield}

\end{centering}
\end{figure}


\subsubsection{\texttt{FUID\_LEN} [write only]}
\label{prog:mmap:fuid-len}
\begin{tabular}{p{9cm} c}
\vspace{-4em}
This register specifies the FUID of the received message and the length of the
\texttt{MBUS\_CMD} that is valid. A write to this register will issue the
transaction.

&

\begin{tabular}{r l}
  Bits Required & Purpose \\
  \hline
  \hline
  \multicolumn{1}{l}{\em Address} & \\
  32 & Memory Map Location \\
  \multicolumn{1}{l}{\em Data} & \\
   4 & FUID \\
   2 & Length (in words) \\
\end{tabular}

\\
\end{tabular}

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

\begin{bytefield}{32}
  \bitheader{0-31} \\
  \begin{leftwordgroup}{\tt Address}
    \colorbitbox{lightgreen}{8}{0xAX}
    \colorbitbox{lightergreen}{24}{0x00000C}
  \end{leftwordgroup} \\
\end{bytefield}

\begin{bytefield}{32}
  \bitheader{0-31} \\
  \begin{leftwordgroup}{\tt ~~~Data}
    \colorbitbox{lightgray}{26}{Reserved}
    \bitbox{2}{Len}
    \bitbox{4}{FUID}
  \end{leftwordgroup} \\
\end{bytefield}

\end{centering}
\end{figure}


\subsection{Interrupts}
\label{prog:interrupts}

\nameref{cmd:conf-proto-int} controls what events generate interrupts.
Interrupt handlers should read
\hyperref[cmd:status-register-summary]{Reg \#240[23:16]} to determine the
interrupt source.