% -*- Mode:Text -*- 

\def\driver{driver}
\def\ioctl{{\tt ioctl}}


\chapter{Host and controller}\label{sect.host}

Even though the current implementation of \step{} uses a
\sparcstation{} as a host, hardware and software were designed so as
to be essentially independent of the nature of the host. The only
host-specific component of the system is the host side of the
\controller, which is matched to the host's bus. The current
\controller{} interfaces with the \sparcstation's \sbus.

Basically, the \controller{} sequentially interprets a list of
intructions found in the host's memory, and translates them into
commands to be broadcast on the \bus. Most of these instructions
entail moving a block of data from a memory buffer on the host to the
\step{} array or viceversa.


\section{Host/controller communication}\label{sect.host/controller-comm}

The \controller\ has two separate modes of communication with the
\sbus, one as a bus {\em slave} and one as a bus {\em master}.

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 reod-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.

Under certain conditions, writing to the first of these registers (the
{\sym Next List Pointer}) initiates the execution of a step list
(\sect{step-list})---an activity that the \controller\ performs as an \sbus\
master.

\section{Shared memory}\label{sect.shared-memory}

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).


\section{The step list}\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 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 (\cf{host/controller-comm}).

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

\medskip

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.

\medskip

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, writing to the ... \flag [clarify
this] this register can be written, but is is additionally necessary
for the user (through the driver) to indicate to CAM that it is
acceptable to resume execution, through the ``enable-dvma'' option --
simply writing to the NLP is insufficient.  The reason for this is to
prevent execution from continuing when the interface receives an error
during the write to the NLP, in which case execution of the new step
list should not commence.


\section{The \controller's control registers}\label{sect.controller-registers}

The \controller's control 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}

The three pointers above ({\sym NLP}, {\sym CIP}, and {\sym PIP}),
the low four bits have a special use. The addresses to which the
pointers refer are always 16-byte aligned (\cf{shared-memory}), so
that their 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
(\cf{controller-registers}) 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}


[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 happen to affect also exception control (see above);
this is an oversight (fortunately a harmless one), and will be fixed with
the next release of the \controller\ chip set.}

\medskip

\figonegiven{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.}

\figonegiven{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-registers}) 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-registers}) 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 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.


\section{\Step\ device driver}\label{sect.driver}

All interaction between a program running on the host under \unix\ and
the \controller\ is mediated by an {\em installable device
driver}\cite{}, called the \driver, which acts as a custom extension
of the \unix\ kernel.

{\sc Unix} treats devices as a special files, to which certain
special-purpose operations (\ioctl{}s) are applicable in addition to the
standard open, close, read, and write calls.  Devices appear in
the {\tt /dev} directory; the \driver\ is listed as {\tt /dev/cam}.


\subsection{Using the \driver}

In order for the \driver's entry points to be accessible by a user
program, the {\tt fcntl.h} and {\tt errno.h} system header files as
well as the custom header file {\tt camio.h} must be included.  The
latter declares the entry points to the driver, defines the structure
{\tt sl\_element} of a step list instruction, and also defines the
arguments for the different \ioctl\ calls permitted on the driver.

The {\tt cam} device is opened with the standard {\tt open} call.  The
cam device must be opened for read/write access ({\tt O\_RDWR}) in
order to function correctly.  Similarly, {\tt cam} is closed with the
standard {\tt close} call. All meaningful interactions with the device
are done through \ioctl\ calls.  The standard {\tt read} and {\tt
write} calls are not used; though entry points for these calls are
provided, they result simply in an error being returned, with no
effect on the state of \step\ or its device driver.

The macros for the \ioctl\ calls, described in the following
subsections, are defined in the {\tt camio.h} header file. The call
names are identical to the subsection headings. (Eventually, both
call names and subsection headings should be updated to reflect
the actual register names.\flag)


\subsubsection{\tt CIOSTEP}

This call is used to schedule a step list.  Basically, the call
receives a pointer to the beginning of a step list, ideally in both
the user and kernel address spaces.  The call prepends a no-op
instruction with a soft interrupt to the beginning of the step list,
sets the {\sym Next List Pointer} on the \controller, and then waits
for the hardware to perform the interrupt.  The call returns as soon
as the soft interrupt is received. (This is the typical behavior
expected from a read/write device driver call.)

\subsubsection{\tt CIOSTOP}

This call is essentially the scheduling of a stop step list.  The
stop call generates a no-op instruction with a soft interrupt and a
wait for host.  The host next pointer on the interface is set
appropriately, and the call waits for the hardware to perform the
interrupt.  The call returns as soon as the soft interrupt is
received.

\subsubsection{\tt RESET-INTF}

This call is used to reset the \controller. The associated bit of {\tt
cam\_rstintr} automatically clears itself when the \controller\ reset
sequence is complete.

\subsubsection{\tt RESET-CAM}

This call is used to reset the \step\ hardware.  Unlike the
\controller\ reset, this reset is not self-clearingd; the associated
bit of {\tt cam\_rstintr} needs to be explicitly cleared.  This bit
should not be cleared until the driver has waited a sufficient time
for the \step\ hardware to have completed the reset.  (For the actual
timing of the \step\ reset sequence, consult Tom D.)\flag

\subsubsection{\tt SPARC-2?}

Returns the type of \sparcstation\ in which the
board is installed.  This call exists so that the hardware may take
advantage of the ability of newer \sparcstation{}s to use 16-word bus
transfers in addition to 4-word transfers. (\flag Actually, it may not be
necessary to make this a call, as it is probably not necessary for the
higher-level software to be concerned with this distinction.
Basically, the purpose of this is to permit 16-word transfers on the
SPARC-2 and limit transfers to 4-words on the SPARC-1.)

\subsubsection{\tt Get-status-interrupt}

Senses the interrupt status of the device.  It returns a {\tt u\_int}
which encodes the interrupt status.  This is the mechanism for passing
interrupt information to the user program, since the {\tt cam\_intr}
routine, being a ``bottom half'' routine\cite{}, cannot directly pass
information to the user program.

\subsubsection{\tt Clear-status-interrupt}

Clears the interrupt status of the device as seen by a user program.

\subsubsection{\tt MEM}

\flag This kernel call is supposed to allocate memory for sharing between
the user program and the device.  This needs to allocate memory that
is mapped in the kernel context (as well as the user context.)

\subsubsection{\tt GET-HNP}

Returns the value of the {\sym Next List Pointer}.\flag

\subsubsection{\tt GET-CURR-INST}

Returns the value of the {\sym Current Instruction Pointer}..

\subsubsection{\tt GET-PREV-INST}

Returns the value of the {\sym Previous Instruction Pointer}.





\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.






	

