% -*- Mode:Text -*- 

\chapter{The controller as a steplist processor}\sectlabel{steplist-processor}

Commands to the \step\ machine are given by writing in host memory
instructions for the \step\ controller, and appropriately directing to
controller to locate and interpret these instructions. Here we describe
(a) the format of these instructions; (b) the protocol by which the
controller is called to execute them and by which it acknowledges
completion---or signals exceptions encountered during execution; and
(c) the basic procedure followed by the controller in decoding the
instructions and supervising their execution throughout the \step\
machine.

\section{Step lists}\label{sect.step-list}

The ``program'' that the controller executes consists of a sequence
of instructions, called {\em step list}, residing in the host's
memory.\footnote
	{The step list is analogous to the ``display list'' routinely
used for interfacing a conventional processor to a specialized,
high-performance graphics processor.}
	Typically, the step list and the associated data buffers will
have been constructed at leisure by a user program running under
\unix, without much concern for real-time performance. On the other hand,
dependable real-time performance is expected of the controller; to
this end, the controller is given {\em bus master} access to the
\sbus\ when interpreting the step list.

The data buffers provide designated areas for transfering data to and
from the \step\ array. A typical data buffer would be a \lut\ buffer,
i.e., a memory image of a \step\ lookup table.

The step lists and the associated data buffers reside in an
area of host memory that is shared beween the host and the controller.
Several step lists (with the associated sets of data buffers) may be
present in shared memory at the same time, ready to be executed in
turn. In the \sparcstation, this shared memory is mapped
simultaneously into the kernel's virtual address space (where it is
seen by the controller) and into the user's address space (where it
is seen by the user's program). All shared memory is allocated in
multiples of four 32-bit words (16 bytes).


\subsection{Instruction format}\sectlabel{format}

Each step-list instruction consists of exactly four 32-bit words named
as follows
 \begin{equation}\label{eq.ibuf}
 \begin{tabular}{|l|}\hline
	opcode\\
	buffer pointer\\
	register length\\
	link to next instruction\\\hline
 \end{tabular}\;.
 \end{equation}

Typically, an instruction makes reference to some associated data.
These data can be in an {\em inline buffer}, immediately following the
instruction, or in a separately allocated buffer. In either case, the
buffer pointer field in \eq{ibuf} points to the origin of this buffer.
Small amounts of data can also be encoded in {\em immediate} form,
i.e., within the instruction itself; in this case no data buffer is
used. 

Scanning of a step list proceeds sequentially from the beginning to
the end of the list---there are no flow-control instructions such
as {\sc if}s, {\sc jump}s, or {\sc goto}s.

\subsection{Instruction fetching}\sectlabel{fetching}

Writing a memory address to the {\sym Next List Pointer} tells the controller
that a step list is present in memory at the given address and that the
controller should start executing it as soon as it is done with the list (if
any) which it is currently executing.  The exact sequence of events will
depend on the current state of the controller. For the purposes of writes to
the {\sym NLP}, the controller can be in one of three states: {\em execute},
{\em wait-for-host}, and {\em error-wait-for-host}.

In the execute state, the controller is still executing the previous
step list.  Assuming that no errors are encountered, the controller
will start executing the new list as soon as the previous one is
finished.

In the wait-for-host state, the controller is idle. As soon as the
{\sym NLP} is written to, the controller immediately starts
execution of the given list.

In the error-wait-for-host state, besides writing to the {\sym NLP} it
is necessary to indicate---through the ``enable-dvma'' option---to
resume execution; simply writing to the {\sym NLP} is not sufficient.
The reason for this is to prevent execution from continuing when the
interface receives an error during the write to the {\sym NLP}, in which case
execution of the new step list should not commence.


\section{\STEP\ controller}\sectlabel{controller}

As explained in the \AR, the \step\ controller's main function is to
interpret step lists, which reside in the host's memory, traslating them into
sequences of transactions between data buffers in host memory and \chip\
registers in the modules.

\medskip

The controller contains a number of hardware registers, called {\em
control registers}, which are use to initialize, direct, and monitor
its operation. These registers, some parts of which are read-only,
some write-only, and others read/write, are memory mapped on the
\sbus\ as four consecutive 32-bit words which are accessed as \sbus\
slaves.

Specifically, the registers comprise one read/write register
(the {\sym Next List Pointer}), three read-only registers, and three
write-only registers. Read-only and write-only registers share the
same three memory locations. Thus, when read from, the controller's
control registers have the following description
 \begin{equation}\label{eq.hard-read}
	\begin{tabular}{|l|l|}\hline
	\multicolumn{2}{|c|}{controller's registers (read)}\\\hline\hline
	\sym NLP & \sym Next List Pointer \\
	\sym ISR & \sym Interrupt Status Register\\
	\sym CIP & \sym Current Instruction Pointer\\
	\sym PIP & \sym Previous Instruction Pointer\\\hline
	\end{tabular}\;,
 \end{equation}

\noindent and when written to they have the following description
 \begin{equation}\label{eq.hard-write}
	\begin{tabular}{|l|l|}\hline
	\multicolumn{2}{|c|}{controller's registers (write)}\\\hline\hline
	\sym NLP & \sym Next List Pointer \\
	\sym ICR & \sym Interrupt Control Register\\
	\sym DSL & \sym Display Scan Length\\
	\sym DBL & \sym Display Blank Length\\\hline
	\end{tabular}\;.
 \end{equation}

In the three pointers above ({\sym NLP}, {\sym CIP}, and {\sym PIP}),
the low four bits have a special use. Since the addresses to which the
pointers refer are always 16-byte aligned, the pointers' low four bits
are predictably 0s and need not be explicitly given. In their stead,
those four bit positions are used as read-only windows on certain
status bits (writes to the same bit positions are ignored.)

\subsection{Next List Pointer}\label{sect.NLP}

The {\sym Next List Pointer} is a read/write register.  Bits 4--31
({\tt next\_list}) represent the starting address (without the low
four bits, which are understood to be 0s) of the step list to be
executed next. Bits 0--3 are read-only status bits with the following meaning

 \begin{equation}\label{eq.NLP}
 \begin{tabular}{|r|l|p{1.5in}|}\hline
	\multicolumn{3}{|c|}{{\sym Next List Pointer} status bits}\\
	bit & \multicolumn{1}{c|}{name}&\multicolumn{1}{c|}{function}\\\hline\hline
	0 & \tt nlp\_written & the controller is
still executing the previous display list, and has not yet made use of the
{\sym NLP}.\\\hline
	1 & \tt exception\_status & the controller has seen an
exception (timeout or \step\ interrupt).\\\hline
	2 & \tt wait\_for\_host & the controller is in
``wait-for-host'' mode.\\\hline
	3 & \tt interface\_halted & the controller is currently
halted.\\\hline
 \end{tabular}\;.
 \end{equation}


[\flag As soon as the controller is free (it might have
been executing another step list), it looks at the {\sym
NLP} and starts executing the step list pointed to by it. At the same time,
it signals to the host (by means of an {\tt nlp\_int} interrupt)
that the current step-list pointer value has been read from the
{\sym NLP} register, and a new value can be written in it.]

[revise this paragraph\flag] 
Bit 3 is a status bit which is set if CAM is currently scanning.  Bit
2 is set if the interface is in the ``DMA Active'' mode, meaning that
it is performing, or ready to perform the execution of step list.  Bit
1 is set if the interface is in ``wait-for-host'' mode, and bit 0 is
set if the current NLP has not yet been processed by the interface
(meaning that the interface is still working on the previous display
list.)

\subsection{Interrupt Status/Control Registers}\label{sect.ICSR}

The {\sym Interrupt Status Register} (\fig{ISR}) and the {\sym
Interrupt Control Register} (\fig{ICR}) are used to monitor, enable,
or disable interrupts generated by the controller. The latter
register is is also used to reset, halt, and restart the controller,
and to reset the \step\ array.

\medskip

The controller can place on the \sbus\ five kinds of interrupts, namely,
 \begin{equation}\label{eq.controller-interrupts}
 \begin{tabular}{|l|p{2in}|}\hline
	\multicolumn{2}{|c|}{controller interrupts}\\
	\multicolumn{1}{|c|}{name} & \multicolumn{1}{c|}{description}\\\hline\hline
	\tt soft\_int & Software interrupt.\\\hline
	\tt cam\_int & \step-originated interrupt.\\\hline
	\tt sbus\_int & The controller detected an \sbus\ error.\\\hline
	\tt timeout\_int & Timeout in communicating with the \step\
array.\\\hline
	\tt nlp\_int & Next List Pointer interrupt: the controller has
started executing the step list indicated by the {\sym Next List
Pointer}; a new step list can be scheduled by writing a new address to
the {\sym Next List Pointer}.\\\hline
 \end{tabular}\;.
 \end{equation}

\noindent To each of these interrupts the controller associates an
{\em interrupt enable} bit and an {\em interrupt flag} bit, whose
functions will be explained in a moment. The five enable bits and the
five flag bits are directly readable respectively in positions 0--4 and
8--12 of the {\sym Interrupt Status Register}.

The five flag bits cannot be directly written by the host. Each of these
bits is set by the occurrence of the corresponding interrupt condition
(e.g., timeout interrupt); they are collectively cleared by any read
operation performed on the {\sym Interrupt Status Register}.

Whether a flagged interrupt actually generates an interrupt on the
\sbus\ depends on whether that particular interrrupt is enabled.  The
five enable bits of the {\sym Interrupt Status Register} are not
writable in a conventional way.  They are {\em set} by writing a 1 to
respectively bits 8, 9, 10, 11, and 12 of the {\sym Interrupt Control
Register}, and {\em cleared} by writing a 1 to, respectively, bits 0,
1, 2, 3, and 4 of the same register.

\medskip

The occurence of a {\tt cam\_int} or a {\tt timeout\_int} suspends the
list scanning activity of the controller, regardless of whether these
interrupts are enabled (and thus reported to the host as \sbus\ interrupts).
However, these interrupts can be masked at an earlier stage, so that
they will not be seen at all by the controller. This is done by
two more enable bits, namely {\tt cam\_exception} and {\tt timeout\_exception},
which can be set or cleared in a way similar to the other enable bits,
by writing a 1 to, respectively, bits 5 and 6 or bits 13 and 14 of the
{\sym Interrupt Control Register}.

\medskip

Finally, as shown in \fig{ICR}, four more control functions are
performed by writing a 1 to bits 12, 13, 16, and 31 of the {\sym Interrupt
Control Register}.\footnote
	{Bits 12 and 13 also happen to affect exception control (see ``also''
entries in \protect\fig{ICR});
this is an oversight---fortunately a harmless one---and will be fixed with
the next release of the controller chip set.}

\medskip

\figonecol{ISR}{
\begin{tabular}{|r|l|}\hline
	\multicolumn{2}{|c|}{\sym Interrupt Status Register}\\
	bit & \multicolumn{1}{c|}{name}\\\hline\hline
	0 & soft\_int\_flag\\\hline
	1 & cam\_int\_flag\\\hline
	2 & sbus\_int\_flag\\\hline
	3 & timeout\_int\_flag\\\hline
	4 & nlp\_int\_flag\\\hline
	5--7 & ---\\\hline
	8 & soft\_int\_enable\\\hline
	9 & cam\_int\_enable\\\hline
	10 & sbus\_int\_enable\\\hline
	11 & timeout\_int\_enable\\\hline
	12 & nlp\_int\_enable\\\hline
	13--31 & ---\\\hline
 \end{tabular}
}{Structure of the {\sym Interrupt Status Register}.
Bits 0--4 (interrupt flags) are set by the occurrence of the
appropriate interrupt conditions, and are automatically cleared by any
read of this register. Bits 8--11 are set by writing 1s to
bits 8--11 of the {\sym Interrupt Control Register}, and
cleared by writing 1s to bits 0--5 of the same register.}

\figonecol{ICR}{
\begin{tabular}{|r|l|}\hline
	\multicolumn{2}{|c|}{\sym Interrupt Control Register}\\
	bit & \multicolumn{1}{c|}{effect of writing a 1}\\\hline\hline
	0 & {\tt soft\_int} disable\\\hline
	1 & {\tt cam\_int} disable\\\hline
	2 & {\tt sbus\_int} disable\\\hline
	3 & {\tt timeout\_int} disable\\\hline
	4 & {\tt nlp\_int} disable\\\hline
	5 & {\tt cam\_exception} disable\\\hline
	6 & {\tt timeout\_exception} disable\\\hline
	7 & ---\\\hline
	8 & {\tt soft\_int} enable\\\hline
	9 & {\tt cam\_int} enable\\\hline
	10 & {\tt sbus\_int} enable\\\hline
	11 & {\tt timeout\_int} enable\\\hline
	12 & {\tt nlp\_int} enable\\\hline
	   & also: Clear fault\\\hline
	13 & {\tt cam\_exception} enable\\\hline
	   & also: Clear exception\\\hline
	14 & {\tt timeout\_exception} enable\\\hline
	16 & Halt the controller.\\\hline
	17--30 & ---\\\hline
	31 & Reset the controller.  \\\hline
 \end{tabular}
}{Structure of the {\sym Interrupt Control Register}.}


\subsection{Current Instruction Pointer}\label{sect.CIP}

The {\sym Current Instruction Pointer} is a read-only register (writes
to this location affect the {\sym Display Scan Length}; \sect{DSBL}).
Bits 4--31 ({\tt curr\_inst}) represent the address (without the low
four bits, which are understood to be 0s) of the step-list instruction
currently being executed. Bits 0--3 are read-only status bits
(\cf{controller}) with the following meaning

 \begin{equation}\label{eq.CIP}
 \begin{tabular}{|r|l|p{1.5in}|}\hline
	\multicolumn{3}{|c|}{{\sym Current Instruction Pointer} status bits}\\
	bit & \multicolumn{1}{c|}{name}&\multicolumn{1}{c|}{function}\\\hline\hline
	0 & \tt sbus\_error & The controller is suspended because of
\sbus\ error.\\\hline
	1 & \tt partial\_write & Owing to an \sbus\ error, only a
partial write was performed by the controller.\\\hline
	2 & \tt done\_status & controller is not relaying to \step.\\\hline
	3 & --- & Reserved.\\\hline
 \end{tabular}\;.
 \end{equation}

[Edit bit 2\flag.]


\subsection{Previous Instruction Pointer}\label{sect.PIP}

The {\sym Previous Instruction Pointer} is a read-only register
(writes to this location affect the {\sym Display Blank Length};
\sect{DSBL}).  Bits 4--31 ({\tt prev\_inst}) represent the address
(without the low four bits, which are understood to be 0s) of the
step-list instruction executed before the current one. Bits 0--3 are
read-only status bits (\cf{controller}) with the following
meaning

 \begin{equation}\label{eq.PIP}
 \begin{tabular}{|r|l|p{1.5in}|}\hline
	\multicolumn{3}{|c|}{{\sym Previous Instruction Pointer} status bits}\\
	bit & \multicolumn{1}{c|}{name}&\multicolumn{1}{c|}{function}\\\hline\hline
	0 & \tt cam\_int\_active & This bit reflects the status of the
{\sym Interrupt} signal of the \bus, resynchronized to the \sbus\
clock. It allows the host to directly see whether there is
an interrupt on the \bus.\\\hline
	1 & \tt cam\_scanning & \step\ is scanning\\\hline
	2 & & (Reserved for \sparcstation-2 bit.)\\\hline
	3 & & (Reserved.)\\\hline
 \end{tabular}\;.
 \end{equation}

\flag  Bit 2 (?) of the previous instruction register
indicates if the long-burst transfer mode supported on the
\sparcstation-2 is being used by the interface board.

\subsection{Display Scan/Blank Length}\label{sect.DSBL}


\subsection{Remarks}

[understand and drop in place the following remarks\flag.]

wait-for-host is fixed by writing to the NLP

all error interrupts except new-list (NLP) and soft cause
dvma-inactive and wait-for-host mode.

cam-error:  parity and verify-write errors are not signalled until end
of transfer,   this interrupt will always be in the ``next''
instruction.

current-instruction:  generally this is the current instruction if
``stop'' is received.  This instruction should have been attempted,
the previous instruction has generally been completed.

Check the state that interface and cam are in when a hardware interrupt
is received.  do not assume that interface is in some ``clean'' state.



\endinput



Control of these five interrupts is summarized by the following table

\begin{equation}\label{eq.interrupt-control}
 % \begin{minipage}{3in}{
 \begin{tabular}{|l||*{4}{l|}}\hline
	\multicolumn{1}{|c||}{interrupt} & \multicolumn{2}{c|}{enable}step-list
					 & \multicolumn{2}{c|}{status}\\
	\multicolumn{1}{|c||}{name}
	  & \multicolumn{1}{c|}{set} & \multicolumn{1}{c|}{clear}
	  & \multicolumn{1}{c|}{set} & \multicolumn{1}{c|}{clear}\\\hline\hline
	\tt soft\_int & write bit 0 & write bit 8 & & read \sym IR\\\hline
	\tt cam\_int & write bit 1 & write bit 9 & & read \sym IR\\\hline
	\tt sbus\_int & write bit 2 & write bit 10 & & read \sym IR\\\hline
	\tt timeout\_int & write bit 3 & write bit 11 & & read \sym IR\\\hline
	\tt nlp\_int & write bit 4 & write bit 12 & & read \sym IR\\\hline
 \end{tabular}\;.
 % \footnoterule
\end{equation}		
 
The remaining five bits of the {\sym Interrupt Registers} are used
in a straightforward way to perform a number of control functions.


