README FILE

AN ASSEMBLER FOR STM
====================

INTRODUCTION:
============
assem.pl is an assembler for the Simulated Toy Machine (STM).
It is a Perl script written by David Stewart, who took
my OS class in Spring 2005.

USAGE:
=====
It takes 1 command line argument which is the name of the 
file to read in.  Thus to assemble gcd.txt you would type:

	% assem.pl gcd.txt

The output will be the assembled file and will have the same 
name as the input file with a .stm extension.

E.g.  "gcd.txt" => "gcd.stm"
      "gcd" => "gcd.stm"

CAREFUL: If the output file already exists it will be overwritten.

INPUT FORMAT:
============
The format of the input file should be:

Three letter operation code (i.e. "LOA") then one space and 
then the list of arguments each separated by a space.  Register
arguments should be in form "Rx" where x is the register number.
Constants are acceptable in the argument list as are loop and jump 
labels.  To set a loop or jump label simply place it by itself on 
the line above the statement you want it to point to.

E.g. 

	LOOP
	IFZ R2 EXIT      --- if B == 0, exit
	DIV R1 R2 R3 R4  --- A / B
	CPR R1 R2        --- A := B;
	CPR R2 R4        --- B := A(old) % B
	JMP LOOP         --- Jump to top of loop


In the above example LOOP defines a label and then the JMP instruction
takes the label as an argument.

The assembler will ask you to define your constants when it assembles
the file so you don't need to define them in your code.  The appropriate
lines will be added to the end of the file to store the constant values.
For instance, if you need to load the constant "1", to your
register R1, you can write

	LOA R1,ONE

and the assembler will ask you what you want ONE to stand for.
You can type "1" in response.


NOTES:
======
1. Any non-assembler commands will pass through as comments
	(i.e., simply copied to the output file).

2. On some machines, the output of the assembler
	contains funny looking characters when you view
	the file in an editor.  On gvim, it shows up as "^@"
	but some students reported seeing an empty box symbol.
	Don't worry about them -- it is some white space character,
	and your stm file can run without any changes.
	But to clean this up, you can type this command in gvim:
	":g/^@/s// /g".
	The "^@" character is generated by "control-@" (press the keys
	control-shift-@ or control-shift-2).