* Introduction

This is a modified version of Douglas Laing mix package. The original
version is available from http://home.telkomsa.net/dlaing/.

Please see COPYING for information about copying conditions.

The file NEWS contains a list of user-visible changes to the original
package.

* Building

The file INSTALL contains generic build instructions. In short, run

 $ ./configure
 $ make
 $ make install

So far, there is only one package-specific configuration option: 
--without-readline.  Use it if you wish to disable readline support in 
MIX terminal.

* The Assembler  -  mixal

mixal reads from the file named as an argument or from stdin if no
filename is given and writes the output load deck to stdout. The load
deck consists of a two card loading routine followed by instruction
cards and a transfer card. (See TAOCP 1.3.1 exercise 26.)  Any error
messages generated are written to stderr.

Mixal accepts several command line options that alter its
behavior. The option -l causes the assembled instructions to be
written to a file. The file name is obtained by replacing the input
file suffix with .lst, e.g. listing file for program `easter.mix' will
be named `easter.lst'. If the source file name does not have any
suffix, .lst is appended to it. Otherwise, if the source is taken from
the standard input, the listing file is named `mixal.lst'

The listing file ends with a dump of the symbol table used during
assembly.

The option -x instructs mixal to produce a cross-reference
listing of the assembled program. If -l is also given, this listing
is included into the last part of the listing file. Otherwise, it is
output to stderr.

The option -r instructs mixal to output the `raw code', i.e. to not
convert it to usual MIX card format and to not output the usual card
loading routine and transfer card. This option is useful for writing
card loaders.

The option -d sets the debugging level. It accepts an argument
consisting of at most two letters. The letter `y' enables tracing of
input file grammar analyzer, while the letter `l' (ell) enables
tracing of input file lexical analyzer. Thus, the full debugging
output can be obtained by running `mixal -d yl'.

There are also two informational options:  -V which reports the
version number and -h which displays a short usage summary.

* The simulator -  mixsim

When run without command line options, mixsim reads a load deck from
sysin, loads and executes it, writing any error messages to stderr. On
completion a dump of the machine state is written to stderr. If mixsim
is interrupted during execution, the machine state will be dumped to
stderr.

By default the card reader is connected to sysin, the printer to
sysout and the card punch to stderr. The tape units use files tape0 to
tape7 and the disk units use files disk8 to disk15 in the current
directory.

These defaults can be altered by giving the -a command line
option. The option takes a single argument in the form

  DEV=NAME

Its effect is to bind MIX device #DEV to UNIX file NAME (or, assign
the UNIX file NAME to MIX device #DEV, hence the option name
`-a[ssign]')

The disks are always opened for update without truncation so that old
data is not destroyed until it is overwritten. Note that big disk
files will never shrink unless they are deleted.

The machine is shipped without a papertape unit and without the
floating point feature.

* The terminal and the debugger

When run with -t command line option, mixsim starts up in MIX terminal
mode. This mode provides a set of commands for running and debugging
MIX programs. The commands are case-insensitive, each command has a
full and contracted form. Furthermore, if MIX is compiled with
readline support, any unambiguous abbreviation of the command name is
also allowed.

As a shortcut, hitting newline in terminal mode repeats the recent
command.

The list of available terminal commands is given below. For the sake
of consistency the commands are given in upper case. The full form is
given after two *'s, the contracted form is listed on the next line.

** BREAK <ADDR>
   B <ADDR>

Set breakpoint on address <ADDR>


** BREAK <ADDR> <NUMBER>
   B <ADDR> <NUMBER>

Set a breakpoint on address <ADDR>. The breakpoint will be deleted
after <NUMBER> crossings.

** BREAK TEMP <ADDR>
   BT <ADDR>

Set a temporary breakpoint on address <ADDR>. Such a breakpoint is
deleted after the first crossing.

This command is equivalent to BREAK <ADDR> 1.

** CLEAR BREAK <ADDR>
   CB <ADDR>

Delete the breakpoint from address <ADDR>.

** LIST BREAK
   LB

List all breakpoints

** NEXT
   N

Execute the next MIX instruction.

** STEP
   S

Execute the next MIX instruction. If it is a function call, step into
the function being called.

** ASGN <DEV> <FILE>
   A <DEV> <FILE>

Assign or bind a file to MIX device. For example, the command:

   ASGN 16 easter.mix

binds MIX card reader (device 16) to the UNIX file `easter.mix'. 

** GO
   G

Emulates GO button. Typing GO starts execution of the current program.

** DUMP
   DU

Dump entire MIX machine state

** DUMP REGISTERS
   DR

Dump MIX registers

** DUMP MEMORY [<BEG> [<END>]]
   DM [<BEG> [<END>]]

Dump the contents of MIX memory. If no arguments are given, the entire
memory range (0-4000) is printed. Otherwise, <BEG> and optional <END>
specify start and end addresses of the memory range to dump.

** UNASM [<BEG> [<END>]]
   U [<BEG> [<END>]]

Disassemble the given memory range. <BEG> and <END> have the same
meaning as for DU.

* LIST IO [<DEV>]
  LI [<DEV>]

List MIX I/O devices and their states.

When given an argument, the command will display the status of the
given device.

* CONT
  CO

Continue after encountering a breakpoint.

* QUIT
  Q

Quit the terminal. Typing ^D (end-of-file symbol) has the same effect.

* Debugging tips.

1. The usual terminal session starts with a command

ASGN 16 <DECK>

(where <DECK> is the name of UNIX file containing MIX card deck).

2. Set the breakpoints using BREAK command.

3. Finally, run GO

4. Upon encountering a breakpoint, the terminal stops and displays the
instruction to be executed next. Do whatever it is necessary to do
(e.g. examine the memory or registers, set new breakpoints or clear
old ones, etc) and type CONT to resume execution of the program.

5. You may restart the program after any breakpoint by typing GO again.

6. To exit the terminal, type end-of-file (Ctrl-D) or QUIT.


Local variables:
mode: outline
paragraph-separate: "[ 	]*$"
end:
