

INSTALLATION:

We assume that you are running from the C shell.  Some modification will
be needed for other shells.

From the directory you are in now (which we will refer to as the ``top''
directory), i.e. the one which contains the file Ist.tar, simply type

   source Install

The package will compile on most systems without incident.  

Among other things, you will now see a directory named ist.  Take note
of it.

Once installed, the package cannot be moved, nor copied used by others, due
to hardcoding of directory names.


DIRECTORY STRUCTURE:

It will be convenient later on if you add the directories ist/ma,
ist/assem and ist/sim to your search path.  These contain the programs
of the same names; e.g. ma is in the directory ist/ma.

The directories ist/frend/one, ist/frend/two and ist/frend/three 
contain machine definitions and sample programs for three different 
target architectures.  The directory for Tanenbaum's Mac-1 machine is
ist/frend/one.

The package seems to have a bug about path names.  For this reason,
place all your .def, .mal and .asm files (and the files generated 
from them) in the same directory, and run ma, assem and sim from that 
directory (ma, assem and sim themselves can be in other directories).


OVERVIEW OF THE PROGRAMS:

The three main programs are:

   ma   --   microassembler
   assem   --   assembler for the target architecture
   sim   --   the simulator (microengine and target architecture)


Important note:  The programs ma and assem will NOT overwrite old files.
So, for example, remove the old .mic file before running ma, which will
create a new one.


OVERVIEW OF FILE-NAME SUFFIXES:

User-produced:

   .def   --   defines registers, op codes, etc. for the target 
               architecture

   .mal   --   the microassembly code for the given target architecture

   .asm   --   assembly code for an application on the target 
               architecture

Generated by programs:

   .mic   --   the microcode generated from .mal by ma

   .set   --   similar to .def; generated by assem

   .mac   --   machine code for application on target architecture;
               generated by assem

Important note:  In the command-line formats listed below, pay careful
attention to which ones ask for file-name suffixes and which do not.


HOW TO USE ma:

Write the .def and .mal files for your target architecture, say x.def
and x.mal.  Then type

   ma x


HOW TO USE assem:

Write the .asm file for your application for the target architecture,
say y.asm.  Then type

   assem x.def y


HOW TO USE sim:

Type

   sim y.mac x.mic

Below are a few of the commands which are available.   (We use their
full names here, but the program will accept their first two letters as
abbreviations.)

examine:

   Check the contents of a register, a memory location, or a set of
   contiguous memory locations.  In the latter two cases, addresses are
   given in decimal form.

set:

   Set the contents of a register or memory location to a specified
   value.  The value can be specified either in hex form, using the 0x
   prefix, or decimal form (no prefix).  However, the address (if the
   value is being placed in a memory location) must again be given in
   decimal form.

step:  

   Execute a single instruction (the one pointed to by the PC register).

go:

   Execute the code, starting with the one pointed to by the PC
   register, continuing until a breakpoint is reached.

breakpoint:  

   Specify a stopping point, to be used in conjunction with the `go'
   command.  Note that breakpoints are set on a one-time basis; to
   re-use a breakpoint, you must set it again.

quit:  

   Exit the simulator.


FURTHER DOCUMENTATION:

The Postscript file Doc.PS in the top directory is the package author's
own documentation.  She provides complete details of program operation,
and sample .def files.  


