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: the microassembler
assem: the 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. You may wish to add an alias to your .cshrc file which automates this.

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: the 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; there is not much consistency here.

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.