This document is intended to help programmers new to the Raw
processor to learn to work within the Starsearch heirarchy.
It will outline a sequence of steps to take that will allow you
to obtain a programming environment for the Raw chip and learn
how to program and debug within that environment.

There are two audiences that will be addressed: new members of
the Computer Architecture Group at MIT, and recipients of the Raw
binary distribution.  Some small differences will exist for the
two cases.

Step 1 - Obtaining a Starsearch directory heirarchy:

CAG Members:  In an appropriate place (e.g., on one of the "bits"
filesystems) checkout the Starsearch directories from the CVS
repository.  The CVSROOT directory is "/projects/raw/cvsroot".

Binary Distribution:  Check with your local Raw guru and obtain
a copy of the Starsearch directories.  Most likely this will involve
extracting them from a tar file: e.g. "tar -xf <pathname>/starsearch.tar".

Step 2 - Initialize your Starsearch directory:

Move to the new Starsearch directory and do "make setup".

Step 3 - Going through the Raw programming tutorial:

[Note:  this is still a work-in-progress, so not all of the tutorial
texts may be complete yet.]

Go to "starsearch/examples" and read the README there.  Follow its
instructions.

Step 4 - Reading other Documentation:

[Note: The best place to find Raw Documentation is to start at the
Raw Infrastructure Map page at http://cag.lcs.mit.edu/raw/RawMap.html.
Pretty much all existing documentation can be found from there.]

Besides the Raw Processor Specification (found through the Raw
Infrastructure Map page) there are two other documents to start with.

The first is "starsearch/README".  This will provide additional
documentation beyond that in the tutorial.  For CAG members it will
also discuss features that are not included in the binary distribution.
Some of this is explicitly directed at writing module tests for our
regression tests and can be ignored for other purposes.

[Note:  If you are working with the binary distribution you will only have
the btl simulator available.  You can ignore references to "rtl", "snakeboot",
"fastboot", and the "emulator".]

The second is found under the Raw Infrastructure Map page (click
on the "btl" link) and documents the btl debugger more fully.

Step 5 - Write some programs:

Two possible techniques:

1) Make yourself a working directory in the institutional subdirectory
of starsearch that has been set up for you.  For CAG members this
could be "starsearch/Raw_Group".

2) Make yourself a working directory anywhere you want.  You will,
however, have to change your Makefiles to replace the standard:

include ../../../Makefile.include	[or however many "../"s are needed]

with:

TOPDIR = /pathname/starsearch		[substitute the appropriate pathname]
include $(TOPDIR)/Makefile.include

[Note: "pathname" must be a full pathname, no "~"s allowed.]


Once you have a working directory make use of models in the different
directories under starsearch/examples to create a Makefile and code
source files for your project.  You may also want to look at the header
files (".h" files) for the libraries that exist.  These can be found in
the "newlib/include" and "rawlib/include" directories under the root
directory of the Raw installaion.

For CAG group members this will be /home/pkg/brave_new_linux/nnnn.xyz/install,
where "nnnn.xyz" should be an appropriate version directory (e.g. "0067.btl").

For users of the binary distribution this will probably be
"/usr/local/raw/install", or wherever the distribution has been
installed.