                Getting Started with CAM-8


Locate the CAM-8 system unit near the back of the SPARCstation system
unit, or on top of it.  You need to orient it so that you can connect
the CAMBus cable between the SBus card we provide and the "CAMBUS"
connector on the CAM-8.  Note that the SBus card has the same kind of
connector as the SCSI bus: don't plug the CAMBus cable into the SCSI
bus by mistake!  The CAMBus cable is not polarized: it doesn't matter
which end you connect to CAM, and which end to the SPARCstation.
Since CAM gets its system clock from the SPARCstation, it *must* be
turned off if it isn't connected to the SPARCstation, or if the
SPARCstation is turned off.  Leaving CAM turned on in these situations
can possibly result in hardware damage.

If you haven't created any user accounts, you can test the machine by
logging in as user "cam8" (no password).  This has the home directory
of "/cam8/demos", which contains demonstration programs.  When you
create other users, you should look at the search path and environment
variables set up for this user.  Start up the X-window environment by
executing "xinit".

If your host computer has a 20MHz SBus (e.g. SPARCstation 1), the
environment variable "STEP_SPEED" needs to be set to "20", for a 25
MHz machine (e.g. SPARC20/50), it should be set to "25".  You can
check what its value is by executing "printenv".  The VGA display will
misbehave if this environment variable isn't set right.

Now make sure that you're in the "/cam8/demos" directory and start the
CAM-8 software by running the program "step".  This starts off in a
"single-key-interpreter" mode, in which pressing single keys on the
keyboard makes things happen.  If you press "l" (the lowercase letter
"L"), the software will prompt you for the name of an experiment, with
the default of "diags.exp".  Hit return, and a set of diagnostic
routines will be loaded and run.  After testing all 8 modules in the
machine, the software should annonce that all modules passed the
tests.

If you have a VGA monitor, you should connect this to the VGA
connector on CAM-8.  If not, you can play with the demos in an
X-window.  Press the "x" key to start an X-window "X-monitor".  You
may want to echo all display to the X-monitor even if you have a VGA
monitor, in case you want to save images to disk (the X-monitor has
useful menu items, such as "dump to xv", which dumps images through
the powerful "xv" image manipulation program).

Press "d" and then <Return> to see a listing of subdirectories of
"/cam8/demos" containing demonstration programs.  Press "e" and then
type "revor" to switch to the "revor" experiment subdirectory.  Press
"l" and then <Return> to load the default experiment file,
"revor-mom.exp".  (Note that if you type in an experiment name, you
can leave off the ".exp" at the end of the name).  Press <Return> to
run the experiment, <Space> to single-step or stop, "i" and "o" to
zoom in and out, and the arrow keys to shift around.  These keys (and
many others) work in all experiments.  Type "m" for a list of menus,
and (for example) "2m" to see a list of generic keys that let you
control the display.

Use the "d" and "e" and "l" keys to try other demos.  Try, for
example, the "anneal" experiment subdirectory, and the
"anneal-demo.exp" experiment.  This is a 3D annealing simulation, with
real-time 3D rendering.  Some of the experiments define special keys
(for example, the "revor-mom" experiment defines the <BackSpace> key
to make things run backwards).  These keys are listed as the
experiment is loaded, and can also be viewed using "0m".

Use the "q" key to quit from the key-interpreter and exit into the
Forth interpreter (this key is listed in the "5m" menu).  Here you can
directly experiment with Forth (which is useful for learning the
language), and you can exit from the "step" program by typing "bye"
and then <Return>.  For a Forth tutorial, see the software manual.

Source code for the sample experiments can be viewed by looking at the
various ".exp" files you find in the experiment subdirectories.  Take
a look in the file "/cam8/doc/basic.list" for a basic list of Forth
words used to control CAM.  Forth documentation can be found in this
same subdirectory, in "softman.ps".  For documentation of more
advanced words used in experiments, look at the source files in
"/cam8/step".

For simple experiments, you can load a "neighborhood" file, such as
"3x3.hood", which defines neighbor names, how the neighbors are
interconnected, etc.  You only have to specify a rule and some initial
conditions.  For a simple example of an experiment which *doesn't* use
a neighborhood (i.e., defines everything from scratch) take a look at
"/cam8/demos/hpp/hpp2.exp".

When an experiment is loaded, the word "rule>table" is used to
generate a lookup table for use by the hardware from a logical rule
definition.  Most experiments use the word "?rule>table" instead,
which looks for a previously generated table (saved on disk) to simply
copy, rather than recompiling all possible cases of the lookup table
each time the experiment is loaded.  If you want to force all tables
to be regenerated from their rule definitions, you can type "0l" (zero
el) instead of just the letter "l" when you load an experiment.  This
is mostly useful when you're defining your own experiments.

Some of the experiment subdirectories contain files that end in ".8p".
These are for generating initial conditions using the "campat" utility
program (see the UNIX man page for "campat", and also "ppmtopat" and
"pattoppm").  You will also see files that end in ".pat" or ".pat.gz".
These are the actual pattern files loaded into CAM.  These files
contain no header information, and consist of a sequence of 16-bit
values, loaded into consecutive 16-bit cells of the specified space.
The ".pat" files are always a power of two in length, since each
dimension of the overall space must be a power of two.  The ".pat.gz"
files are gzip-ed files, compressed to save space.  If you try to
"get" a pattern using the "g" key, the software will first look for a
"pat.gz" version of the pattern, and then look for a ".pat" version.
If you "put" a pattern using the "p" key, the software will produce a
".pat.gz" file.

When experiments are loaded, or experiment files load other files, if
the desired file is not found in the current directory, there is a
search path where it looks (see the environment variable
"STEP_INPUTS").  In your distribution, many of the commonly used
neighborhoods, as well as some 3D rendering routines, are collected
into the "/cam8/common" directory using this mechanism.

We would advise you to start your own experimenting with CAM-8 by
copying some simple demonstration experiment into a separate
directory, and then making a slightly modified version.  By looking at
examples, "basic.list", and the step source files, you should be able
to get started.  When you reach the point of trying to debug
experiments, look at the note on "writing experiments", which
discusses debugging, the CAM-8 machine model, and the CAM-8 software
model.
