% -*- Mode:Text -*- 


\setcounter{chapter}{3}
\chapter{\Step\ device driver}\sectlabel{driver}

All interaction between a program running on the host under \unix\ and
the \ctrler\ is mediated by an {\em installable device driver}\footnote
	{{\em Writing \sbus\ Device Drivers}, \sun\ Microsystems
(...).}
	called the {\em \step\ 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) are applicable in addition to the
standard open, close, read, and write calls.  Devices appear in the
{\tt /dev} directory; the \step\ device driver is listed as \flag {\tt
/dev/step}.

\medskip

\noindent\flag {\sc Note}: In its current version, the \step\ driver is
called {\tt /dev/cam}, and in its nomenclature uses the string {\tt
cam} rather than {\tt step} throughout.

\medskip

\noindent\flag [This appendix to be greatly expanded.]


\section{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 the \step\ controller or of the driver
itself.

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


\section{Driver entry points}

\addtocontents{toc}{\protect\offtocsubsections}

\subsection{\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 \ctrler, 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.)

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

\subsection{\tt RESET-INTF}

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

\subsection{\tt RESET-CAM}

This call is used to reset the \step\ hardware.  Unlike the
\ctrler\ 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

\subsection{\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.)

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

\subsection{\tt Clear-status-interrupt}

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

\subsection{\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.)

\subsection{\tt GET-HNP}

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

\subsection{\tt GET-CURR-INST}

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

\subsection{\tt GET-PREV-INST}

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

\addtocontents{toc}{\protect\ontocsubsections}



