>>Introduction
"archsim" allows users to simulate architectures for any assembly
language with the single restriction that the architecture be implemented
with Tanenbaum's level-1 machine.

Users can choose to work at the microprogramming level (Tanenbaum's
"level-1") or at the confentional machine language level (T's "level-2").
At level-1, user's commands refer to level-1's control store and
registers.  When the user is running at level-2, commands refer to 
level-2's memory and registers.  When running at level-2, all level-1
architectural details are concealed from the user.

>>Running archsim
At the unix prompt, the user types:

	archsim

The next thing the user sees on the screen is prompt
	
	mac:

The user is now in "archsim".

>>Command set summary
	Detailed explanations for each command follow the summary.

	I.  Switching between level-1 and level-2
	    1. mic
            2. mac
       II.  Loading memory, examining and setting registers
	    1. load  <pathname>
	    2. examine <register name>
	       examine <address>
	       examine <address1> - <address2>
 	    3. set <register name>  <value>
	       set <address> <value>    (level 2 only)
      III.  Setting breakpoints and tracing registers
	    1. breakpoint <address>
            2. trace <register name>
	    3. untrace <register name>
	    4. detail <detail amount>
       IV.  Executing a program
	    1. step
	    2. go
	V.  Other commands
	    1. quit
	    2. help
	
	All commands can be shortened to their initial two letters.
"archsim" is case-insensitive.

>>Commands
I.  Switching between microarchitecture level (level-1) and
    conventional machine language level (level-2)
	
	1. mic
	   Switch to level-1.  

	   As a reminder to the user that archsim
	   is running at level-1, the prompt changes to

	   	micro:

	2. mac
	   Switch to level-2.  

	   The prompt when running at level-2 is

		mac:

	   Switching from level-1 to level-2 should only be done
	   when the mpc is zero.  Switching at any other time will
	   leave a level-2 instruction partially executed.

II.  Loading memory, examining or setting registers
	
	1. load <pathname>
	   Load compiled program into memory. <pathname> is a
	   unix path-name.	

	   If running at level-1, <pathname> contains compiled
	   microassembly language ("mal") code, and is loaded
	   into the control store.  <pathname> must end in ".mic".

	   If running at level-2, <pathname> contains compiled
	   assembly language, and is loaded into the level-2 
	   memory.  <pathname> must end in ".mac".

	   The loaded program must be compiled prior to running archsim.  
	   To compile mal programs, exit form archsim and type:

		mal <pathname-mal>

	   where <pathname-mal> contains a microassembly language
	   program.  To compile assembly language programs, exit
	   from archsim and type:

		mac <pathname-mac>

	   when <pathname-mac> contains an assembly language program.

	   Archsim preloads both the control store and level-2
	   memory.  The control store is preloaded with Tanenbaum's
	   example microprogram from pp 176-177 of "Structured
	   Computer Organization", 3rd ed.  The level-2 memory
	   is preloaded with a program that computes 3!
	
	2. examine <register name>
	   examine <address>
	   examine <address1> - <address2>

	   Print the contents of the specified register or addresses. 

           The <register name> must refer to a valid register name.
	   At level-1, valid register names include mar, mbr, mpc
           (micro pc), mir (micro instruction register),
	   alatch, blatch, pc, ac, sp, ir, tir, zero, one, neg1,
	   amask, smask, a, b, c, d, e, and f.
	   Archsim prints the contents of the registers as a binary
	   string except for mir.  The contents of the mir are
           printed in symbolic mal for readibility.
	 
	   Valid level-2 register names depend on the assembly language.
	   The valid level-2 register names for Tanenbaum's MAC assembly
	   lanaguage are pc, ac, and sp.

	   When examining memory, a user can specify a single <address>
	   or a range from <address1> to <address2>.  Archsim prints
	   the contents of the control store in symbolic mal for
	   readibility.

	3. set <register name> <value>
	   set <address> <value>       (level 2 only)

	   Changes chosen register (or address) to the specified value.

	   The <register name> must be a valid register name.  The
     	   <value> can be specified in decimal or hex (0x----).
           The <address> should be decimal.

	   Notice: Users cannot change values in the control store.

III.  Setting breakpoints and tracing registers

	1. breakpoint <address>
	
	   Specifies a breakpoint.

	   After a breakpoint has been specified, the user can
	   type the command "go", and execution will stop at
	   the memory address given by the breakpoint command.

	2. trace <register name>

	   Print specified register after each instruction is
	   executed.

	   Suppose the user is at level-2.  S/he types

		trace pc
		go

	   This will cause the contents of the pc to be printed
	   after each instruction is executed.

	3. untrace <register name>

	   Stops the tracing of the specified register.

	4. detail <detail amount>

	   Trace a bunch of registers.

	   It's tedious to specify individual registers with the
	   "trace" command.  The "detail" command allows a user
	   a quick way to turn on a lot of tracing. 

	   At level-1, the <detail amount> ranges from 0 to 3:

	   <detail amount>	action taken

		0		trace no registers
		1		trace mpc, ir, and tir
		2               trace mar, mbr, ac, mir, 
					mpc, ir, and tir
		3		trace a,b,c, mar, mbr, ac,
					mar, mbr, ac, mir, 
					mpc, ir, and tir

	   At level-2, the <detail amount> ranges from 0 to 1:

	   <detail amount>      action taken

	  	0		trace no registers
		1		trace pc, ac, and sp

	   If using "detail" and "trace" together, use the "detail"
	   command first.  Using "detail" after "trace" may contradict
 	   "trace" command otherwise.	

IV.  Executing the program
	
	1.  step
	    Executes one instruction
       
        2.  go
	    Executes instructions

	    Execution begins at the current value of the mpc (or pc
	    if at level-2) and continues until a breakpoint is
	    encountered or a level-2 STOP instruction is encountered.

V.  Other commands 

	1.  quit

	    exit to unix prompt.	

	2.  help

	    allows user to read this document.  
