% -*- Mode:TeX -*-
\chapter{Software interface with CAM}\label{cam}

The \cam\ software,\index{Software/interface} as currently realized, consists of eight source
files that are loaded on top of the Forth system; the latter is a
modified version of F83 (see Introduction and Section \ref{F83}).

The \cam\ part of the system serves not only as a shared language for
use by the \cam\ community, but also---for those who might want to
implement their own \cam\ driving software in some other language---as
an example of how to make \cam\ perform various functions.

Details concerning data formats used by this software (which should be
useful to those wishing to write programs (in Forth or other languages) to
perform data analysis, pattern generation, etc.) are provided in the
next section.  In this section, we provide a brief overview of the
structure and organization of the \cam-specific part of the software.

\medskip

The lowest level of the software is contained in the file
\prog{CAM-INT.4TH}.  This contains the interrupt driver for \cam\ that
normally gets control during every \cam\ vertical blanking
interval; interrupts that invoke this driver are generated by the
master \cam\ (\cam\ number 0) every sixtieth of a second.  The
principal function of this routine is to maintain the shadow registers
that constitute the primary real-time interface between application
programs and the \cam\ hardware.  For each installed \cam, the
interrupt driver copies control-register data and color-map data to
the machine, and retrieves any accumulated counts from the event
counters before scheduling a new step (if one is pending).  Since the
high-level word \iprog{STEP} waits for this copying to occur before
proceeding, any settings of neighborhoods, color maps, phase bits,
etc.\ that are made before \iprog{STEP} is executed will have actually
been sent to \cam\ before the application can try to change them
further.  The actual interlock between the interrupt routines and the
mainline routines is handled by the intermediate level word
\iprog{PEND}, which sets a flag that is cleared by the interrupt
routine when the copying has actually taken place, and the word
\iprog{WAIT-FOR-PEND}, which waits for this flag to be cleared.  The
interrupt routine can also read or write a limited amount of plane
data during the vertical blanking time (see \prog{R/FLY}\index{R.FLY{\tt R/FLY}} and
\prog{W/FLY}\index{W.FLY{\tt W/FLY}} in the glossary); it is this facility that is used to
draw the dot and cage cursors used by the \cxp\ program.  The
file \prog{CAM-INT.4TH} contains shadow screens and is carefully
annotated; it provides an example of how well suited Forth is to
being used as a macro-assembler language.

The rest of the \cam\ source files are documented principally by the
glossary, some sections of this manual, and the \cambook.  After the interrupt level
routines are loaded, the next-lowest level of routines (contained in the
file \prog{CAM-IO.4TH}) is added.  These input/output routines are used
to interface with the shadow variables that are maintained by the
interrupt, and also to do plane and table I/O, which involves inhibiting
the interrupt routine and taking direct control over \cam\ hardware
registers.  The software is designed to handle up to eight \cam{}s
simultaneously; at the interrupt level all \cam{}s are always treated on
an equal footing, except that step-requests are sent only to the master
\cam.  At the I/O level, we adopt the strategy of only communicating
with one machine at a time (see \prog{CAM-SELECT}), avoiding the need to
have all I/O routines take a \cam\ number as an argument.  The interlock
words \iprog{PEND} and \iprog{WAIT-FOR-PEND} are defined in this file.

The next level of the software, contained in the file
\prog{CAM-BUF.4TH}, defines words for performing memory management
outside of the 64K segment containing the Forth system: allocating and
de-allocating buffers.  Most of the extra buffer areas used by the
remainder of the routines are defined here, as well as operations
on and between buffers addressed by segment and offset (including random
number generation) and operations between buffers and planes or tables.

At the next level (\prog{CAM-HOOD.4TH}) we worry about table generation.
We define the word \id|==|,\index{Lookup table/address-line assignment} and use it to define all of the
compilation variables used in table generation;\index{Lookup table/generation} we define \id|>>| and
use it to define all of the words used to modify table entries during
table generation; we define all of the major and minor neighborhood
selectors; and we define \iprog{MAKE-TABLE}.  Similarly, we define the
words used in color-map generation.

\medskip

With this background, we are ready to worry about making \cam\ run
steps (\prog{CAM-STEP.4TH}).  We define a stepping coroutine called
\iprog{NEXT-STEP}, and the words \iprog{STEP} and \iprog{IDLE}, which
cause a coroutine exit to the main program when used within the Forth
word attached to this coroutine. \iprog{NEXT-STEP} resumes the
coroutine where you last left off, beginning by causing the active
step (or idle step) where you exited to actually start.
\iprog{MAKE-CYCLE} is used for attaching a Forth word to the stepping
coroutine.  In this file, we also make provision for service steps
(see \iprog{BEGIN-SERVICE-STEPS}) such as shifts of bit-planes, which
can be interposed between two steps of an experiment: \cam\ stepping
control and status information (as well as tables and color maps) is
restored (by \iprog{END-SERVICE-STEPS}) when done.  Provision for
showing an expanded version of the central portion of the screen using
\cam\ itself as the display device while running is also made here.

The penultimate file is \prog{CAM-EDIT.4TH}.  It contains all of the
routines used for the limited graphic editing facilities provided.
Cursors are drawn by using the facility for reading and writing plane
data during the vertical blanking time without turning off \cam's
display (as is required by the normal plane I/O routines).  This file
also contains an interrupt driver for a {\sc mouse systems} serial mouse,
which can be used instead of the arrow keys in the control panel
program to move the dot-editing cursor.

Finally, the file \prog{CAM-KEYS.4TH} defines a key-interpreter loop
that constitutes the \cxp\ program.  When a key is pressed, a
set of vocabularies (\iprog{GENERAL}, \iprog{PLANE-OPS}, etc.)  is
searched for that key name.  If it appears as a Forth word in one of
these vocabularies, then this word is executed.  Key names are put in
these vocabularies by the word \iprog{ALIAS}, which makes the key name
be essentially a synonym for another Forth word.  When the key name is
executed, the name of the associated Forth word is printed, and then
this word is executed.  For each of the \prog{ALIAS} vocabularies, a
listing of key names and the names of associated Forth words is made
available as a sort of menu.  The order of items in these menus
reflects the order in which the keys were added to the dictionary.
User defined {\tt ALIAS}es are put in the \iprog{ALTERNATE}
vocabulary, and (to avoid confusion with system-defined keys) are
always attached to {\tt Alt-} keys.

\medskip

All of these files are loaded by the master file \prog{CAM-LOAD.4TH},
which also defines how \cam\ is initialized when it first starts up,
and what clean-up activities are done when you end the \cam\ program.

