Professor Norman Matloff
Department of Computer Science
University of California at Davis
Last Updated February 2, 1999
(Please mail any questions to Norm Matloff.)
Table of Contents:
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
Among other things, you will now see a directory named ist. Take note of where it is.
The package will compile on most systems without incident. Try testing it on the program sort.asm in ist/frend/one: As noted in the readme file in the "one" directory, sort.asm sorts 10 numbers stored in locations 100-109. Use sim's "go" command to start execution, and use its "examine" command on memory locations 100-109 to see that the sort executed properly.
Once installed, the package cannot be moved, nor copied by others, due to hardcoding of directory names.
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).
The three main programs are:
microassembler
assembler for the target architecture
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. Better yet, write a shell alias to do this automatically.
User-produced:
defines registers, op codes, etc. for the target architecture
the microassembly code for the given target architecture
assembly code for an application on the target architecture
Generated by programs:
the microcode generated from .mal by ma; each record is 13 bytes, corresponding to the 13 fields in a microinstruction
similar to .def; generated by assem
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.
Write the .def and .mal files for your target architecture (explained later in this document), say x.def and x.mal. Then type
ma x
Write the .asm file for your application for the target architecture, say y.asm. Then type
assem x.def y
Say your target architecture application files have prefix y and your microengine files have prefix x. Then type
sim y.mac x.mic
This loads the program x.mic into the microengine memory and the program y.mac into the target architecture memory. The sim program runs at either the target-architecture level or the microengine level; it is initially at the former. You can go back and forth between the two levels during a sim session (try the "help" command).
Below are a few of the commands which are available in sim. (We use their full names here, but the program will accept their first two letters as abbreviations.)
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 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.
Execute a single microengine or target-architecture instruction (the one pointed to by the PC register).
Execute the microengine or target-architecture code, starting with the one pointed to by the PC register, continuing until a breakpoint or a STOP instruction (at the end) is reached.
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. Also, note that execution will stop after the instruction at the breakpoint runs.
The command
stats on
turns on statistics collection. If you set it at the beginning of a program (and don't turn it off), then after the program executes, a report will be printed to the screen on the number of clock cycles executed, and the number of target-architecture memory words read and written (unfortunately described as ``assembly'' words in the report).
Online help command.
Exit the simulator.
A target architecture is defined through the .mal file, which contains the microcode, and the .def file, which is used to set up the symbolic correspondences needed by the target-architecture assembler. (Important: The .def file is used only for the assembler; it does not enter in to the operation of sim at all. Make sure you understand why.)
The best way to get to know how these work is to see how they are set up for a machine you already know, Tanenbaum's Mac-1 from the handout on microcode ( ). Take a look at the files one.mal and one.def in the directory ist/ frend/one/one.mal in the DePaul package.
The file one.mal is the same as what you saw in the handout (though with different labels). The .def file defines registers and op-code mnemonics. Here are some excerpts:
#registers ;tanenbaum's one-address machine pc null 0 ac null 1 sp null 2
The first line states that register definitions follow in the next few lines. Then there is one line for each register in the target architecture. (You might wonder about other registers, e.g. ir, tir and so on, but remember these are in the microengine and not part of the Mac-1 architecture itself. For example, a Mac-1 assembly language programmer would never see these registers; he/she only knows about pc, ac and sp.)
Within a register-definition line, first comes the name of the register (one can use any names, not the ones Tanenbaum gave them), then the register's value in the machine language of the target architecture, then finally the number of the register (0-15) among the 16 registers of our microengine. In our example here, all three register values are given as "null", because no machine language instruction refers to them explicitly. Mac-1's loco instruction, for instance, does affect the ac register, but since it is the only possible destination the instruction need not store a number for it.
By contrast, suppose we had a target architecture with 2 general-purpose registers, named v and w, and suppose it also had a loco instruction. For instance, a program for the target architecture might include the instruction
loco v,5
which would load 5 into v.
Suppose we decide to set things up as follows: We use the Mic-1 microengine's registers c and d (numbers 12 and 13 in the microengine) to implement the target-architecture registers v and w; loco's op code will be 0111, in the first 4 bits (bits 0-3) of the instruction; and the register, v or w, will be specified in the fifth bit (bit 4) of the instruction (0 for v, 1 for w). Then a portion of the .def file would look like this:
#registers pc null 0 sp null 2 v 0 12 w 1 13 ... #instruction #opcode 0:3 loco 0b0111 registers #source1 4:4
The remainder of the .def file lists the different op-codes and their assembly-langauge mnemonics.
You should keep in mind that MAL, for instance, is not just a language; it is notation for physical manipulation of the Mic-1 machine. If you are too casual in writing code in the MAL "language," you may do something which is physically impossible. Make sure to keep a picture of Mic-1 handy when you are writing the code.
The ma microassembler is supposed to detect and reject MAL code which is physically impossible. In most cases it does so (printing an error message "syntax error," which is unfortunate phrasing because it masks the problem, which is the physical conflict which the MAL code has set up). However, MAL fails to detect one such error:
The ma microassembler erroneously allows you to do an operation of the form
mar:=***********;
within a microinstruction which does a 2-operand ALU operation. This is physically impossible, since the "mar:=" section needs the b bus, while the 2-operation ALU operation needs both the a and b buses.
Thus the implementation of Mac-1's POPI instruction is incorrect.