MIX Assembler and Simulator	Sergey Poznyakoff, Douglas Laing

• Main
• Downloads
• Installation
• Documentation
• Debugging

MIX Manual (split by chapter):

Section:

Chapter:

Doc:

?

3. mixsim – MIX Simulator.

The MIX simulator, mixsim, allows you to execute object code assembled by mixal, and to inspect the machine state at any stage of the execution. The simulator also includes a debugging facility, useful when analyzing the examples and solving problems from TAOCP.

The simulator is written in compliance with the recommendations found in TAOCP, 1.4.3.1, p.198, MIX Simulator.

3.1 A MIX Machine Implementation.

The simulator implements the MIX machine as described in TAOCP, 1.3.1, p.120, Description of MIX. The machine is shipped with all external equipment, except the paper tape unit(1), and the floating point feature.

Each I/O device is bound to a particular UNIX file. By default the card reader is connected to stdin, the printer to stdout and the card punch to stderr. The typewriter is connected to stdin. The paper tape unit is not yet implemented.

The tape units use files ‘tape0’ to ‘tape7’ and the disk units use files ‘disk0’ to ‘disk8’ in the current directory. None of these files is required to exist: they will be created on demand, when the first output operation on the given unit takes place.

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.

In contrast, the tapes are always opened with truncation, so that any existing data is lost after the first OUT instruction is executed.

3.2 Executing MIX Programs.

When run without command line options, mixsim reads a load deck from device 16, 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.

At most one argument can be given. It is treated as a file name to be assigned to the card reader device. Thus, there are three ways to execute a load deck previously stored in a file:

1. Redirect the file's contents to the mixsim stdin:

   $ mixsim < hello.deck

2. Give the file name as an argument to mixsim:

   $ mixsim hello.deck

3. Assign the file to device ‘#16’, using ‘-a’ option (see below):

   $ mixsim -a 16=hello.deck

The default device assignments can be changed using ‘--assign-device’ (‘-a’) command line option. It takes a single argument in the form dev=file, where dev is the MIX device number and file is the name of file to be assigned to it. For example, the following invocation tells mixsim to connect the card puncher (device 17) to file ‘punch.out’:

$ mixsim --assign 17=punch.out

3.3 Terminal Mode and Debugger.

When given the ‘--terminal’ (‘-t’) option, mixsim starts in terminal mode. The terminal mode provides a custom shell for executing, tracing and debugging MIX programs. When you start mixsim in this mode, you will see:

$ mixsim -t

MIX TERMINAL STATION READY FOR COMMUNICATION

MIX> _

The ‘MIX>’ string at the end of the screen is the terminal prompt, inviting you to enter a command. The syntax of terminal commands is similar to that of shell: each command consists of a command verb, optionally followed by one or more arguments, separated by any amount of whitespace. A command ends with a newline character.

3.3.1 Mixsim Commands

All mixsim command verbs (hereinafter referred to as commands) are case-insensitive. Each command has a full and contracted form, the latter one being designed to save extra typing.

If the package is configured with readline support enabled (which is the default, if readline is present on the system), you can abbreviate a command to the first few letters of the command name, if that abbreviation is unambiguous. A flexible command line editing facility is also available in this case. See section Command Completion, for a detailed desctiption.

You can test if an abbreviation is valid by using it as an argument to the help command (see section Obtaining On-line Help).

A blank line as input to GDB (typing just RET) means to repeat the previous command.

Any text from a ‘#’ to the end of the line is a comment; it is ignored. This is useful mainly in command files (see section Command Files).

3.3.1.1 Command Completion

This subsection discusses the command completion facility, available if mix is configured with readline support. Using this feature is recommended. If you don't have GNU readline, we suggest you to get it from the Readline Home Page prior to compiling mix.

See Command Line Editing: (readline)Command Line Editing section `Command Line Editing' in GNU Readline Library, for more information about the library.

Mixsim can fill in the rest of a word in a command for you, if there is only one possibility; it can also show you what the valid possibilities are for the next word in a command, at any time.

Press the TAB key whenever you want mixsim to fill out the rest of a word for you. If there is only one possibility, it will replace the partial word and will wait for you to finish the command. This command completion is context-dependent. For example, if you type:

MIX> br_TAB

this command will immediately be expanded to break, since it is the only possibility in this context:

MIX> break

If there is more than one possibility to complete the word you are typing, mixsim rings a bell. You can either supply more characters and try again, or just press TAB one more time, in which case mixsim will display all the possible completions for that word. For example, the address command (see section Breakpoints) can be followed by several keywords, so, if you type TAB after address, mixsim rings a bell and waits for your further actions. If you press TAB second time, you'll see:

MIX> ADDRESS _TAB
A bell sounds. Pess TAB again to see:
CB         DELETE     ENABLE     INFO       LIST
CLEAR      DISABLE    IGNORE     LB         PASSCOUNT
MIX> ADDRESS _

To save you typing, it is also possible to view the list of alternatives in the first place. To do so, type M-?, instead of pressing TAB twice. M-? means either to hold down a key designated as the META shift on your keyboard (if there is one) while typing ?, or to press ESC, followed by ?.

If the context requires you to type a file name, mixsim will complete file names. For example:

MIX> ASGN 16 ../examples/_M-?
mystery.mix    hello.mix      init.mix       p.mix
easter.mix     load.mix       tsort.mix

Similarly, if the context requires a name of an executable file, you will see the appropriate completion, made using your PATH environment variable setting:

MIX> ! ca_TAB TAB
cat             cal

3.3.2 Obtaining On-line Help

HELP

?

To obtain help about all available commands, type HELP.

HELP cmd

? cmd

When used with an argument, it displays usage summary for the given command verb, e.g.:

MIX> HELP ASGN ASGN <DEVICE> <FILE>

3.3.3 Quitting the Terminal

QUIT

Q

To exit the terminal, use the QUIT (abbreviated Q), or type an end-of-file character (usually C-d).

An interrupt (C-c) does not exit from mixsim, but rather stops the program being executed (see section Stopping and Continuing), or, if no program is being run, cancels the current input line.

3.3.4 Assigning and Listing Devices

ASGN device file

A device file

Assign file to the given MIX device. device specifies the device number. In the effect of this command, output operations on device will write the data to file, and input operations on device will read data from file.

For example, to assign file ‘hello.deck’ to the card reader, type:

MIX> ASGN 16 hello.deck

To obtain information about MIX devices, including their current assignments, use the following command:

INFO IO [device]

LIST IO [device]

LI [device]

Without arguments, lists all devices. With a numeric argument, shows information about that particular device. For more uses of INFO command, see Listing Breakpoints.

The information is displayed in tabular form and contains the following columns:

UNIT

Unit number.

IOT

I/O time per block.

SKT

Seek time.

ADDR

Memory address for the pending I/O operation.

POS

Device position for the pending I/O operation. This column is meaningful only for tape and disk devices.

OP

Opcode or ‘N/A’, if no operation is pending.

CLOCK

Clock time when the I/O will occur. To examine the current clock time, see Listing Breakpoints.

ASGN

File assigned to that device.

The example below shows the information about card reader, obtained after the first loader card was read:

MIX> info io 16
UNIT    IOT    SKT  ADDR  POS   OP  CLOCK ASGN
  16  10000      0    16    0   IN  15000 easter.obj

3.3.5 Running a Program

GO

G

RUN

R

Emulates MIX GO button.

This command does the following:

1. A single card is read into locations ‘0000--0015’;
2. When the card has been completely read and the card reader is no longer busy, a JMP to location ‘0000’ occurs. The J-register is also set to 0.

3.3.6 Breakpoints

A breakpoint makes your program stop whenever a certain location in the program is reached. When the program stops at a breakpoint we say that this breakpoint has been passed or hit.

For each breakpoint, two numbers are defined: ignore count, which specifies the number of passes before that breakpoint is enabled, and pass count, which specifies the number of passes after which the breakpoint will be deleted.

Each created breakpoint is assigned a sequence number, which can be used to refer to that breakpoint in other commands. Another way to refer to a breakpoint is by the program location it is set at. Thus, each command described in this subsection has two forms: a form which uses breakpoint numbers, and a form that uses program locations. The second form is constructed by prefixing the command with ADDRESS keyword (abbreviated AD). For example, the following command deletes breakpoint number 2 (see section Deleting Breakpoints):

MIX> DELETE 2

In contrast, the following command deletes all breakpoints set at address 1000:

MIX> ADDRESS DELETE 1000

3.3.6.1 Setting Breakpoints

Breakpoints are set with the BREAK command (abbreviated B).

BREAK location

B location

Set a breakpoint at the given location. Both ignore and pass counts are set to 0. A sequence number assigned to the breakpoint is displayed, as shown in the example below:

MIX> BR 1000 BREAKPOINT 1 IS SET AT ADDRESS 1000

This sequence number can then be used to refer to this breakpoint.

BREAK TEMP location

BT location

TB location

Sets a temporary breakpoint at the given location. A temporary breakpoint is a breakpoint which is deleted after a single hit. In other words, it has pass count set to 1.

This command is equivalent to:

BREAK location ADDRESS PASSCOUNT location 1

See section Configure Breakpoints, for information about PASSCOUNT command.

You can set any number of breakpoints at the same place in your program. This feature is not very useful at the moment, it is reserved for future use.

3.3.6.2 Deleting Breakpoints

It is often necessary to eliminate a breakpoint which has done its job and is no longer needed. This is called deleting the breakpoint. A deleted breakpoint no longer exists, and its sequence number is returned to the pool of available numbers.

It is not necessary to delete a breakpoint to proceed past it. Mixsim automatically ignores breakpoints on the first instruction to be executed when you continue execution without changing the execution address.

DELETE [number-list]

D [number-list]

Delete specified breakpoints. number-list is a whitespace-separated list of breakpoint numbers. If no argument is specified, delete all breakpoints (in this case mixsim asks confirmation).

When prefixed with ADDRESS (abbreviated AD), number-list is treated as a list of addresses, instead of breakpoint numbers.

Examples:

1. Delete all breakpoints:

   MIX> DELETE

2. Delete breakpoints 1, 3 and 5:

   MIX> DELETE 1 3 5

3. Delete breakpoints set at addresses 1000 and 3000:

   MIX> ADDRESS DELETE 1000 3000

3.3.6.3 Disabling and Enabling Breakpoints

Instead of deleting a breakpoint, you might prefer to disable it. A disabled breakpoint continues to exist, but is ignored. You may enable it again later, if the need arises.

To disable and enable breakpoints, use ENABLE and DISABLE commands, described below. To obtain information about existing breakpoints and their status, use INFO BREAK command (see section Listing Breakpoints).

DISABLE [number-list]

DIS [number-list]

Disable breakpoints, specified by number-list. If no arguments are given, disables all breakpoints.

ENABLE number-list

ENA number-list

Enable breakpoints, specified by number-list. If no arguments are given, enables all breakpoints.

Both commands may be prefixed with ADDRESS (abbreviated AD), to specify breakpoints by MIX addresses, rather than by breakpoint numbers.

3.3.6.4 Configure Breakpoints

Each breakpoint has two numbers associated with it: ignore count, which specifies the number of passes before that breakpoint is enabled, and pass count, which specifies the number of passes after which the breakpoint will be deleted.

IGNORE number count

I number count

Set ignore count for breakpoint number to count.

PASSCOUNT number count

P number count

Set pass count for breakpoint number to count.

Both commands may be prefixed with ADDRESS (abbreviated AD), in which case their first argument, n, is treated as a MIX location where the breakpoint is set, rather than its number. For example, the following command sets pass count to 1 for all breakpoints set at location 1000:

MIX> ADDRESS PASSCOUNT 1000 1

3.3.6.5 Listing Breakpoints

INFO BREAK [num]

LIST BREAK [num]

LB [num]

Without argument, lists all existing breakpoints. With an argument, lists only breakpoint num. When prefixed with ADDRESS (abbreviated AD), treats its argument as a MIX location and lists breakpoints set at that location.

Following is an example of a breakpoint listing:

 NUM  LOC  ENB  CNT  IGN  PAS
   1 1000    Y    1    0    0
   2 1040    N   10    8    0
   3 1230    Y    0    0    1

The columns and their meanings are:

3.3.7 Stopping and Continuing

The principal purposes of using a debugger are so that you can stop your program before it terminates; or so that, if your program runs into trouble, you can investigate and find out why.

Inside mixsim a program may stop either because it hit an active breakpoint or because it reached a new line after NEXT or STEP command (see below). Additionally, you can stop a running program at any moment, by pressing interrupt (usually C-c).

CONTINUE

C

Continue program execution, at the address where it last stopped.

A typical debugging technique is to set a breakpoint (see section Setting Breakpoints) at the location where a problem is believed to lie, run your program until it stops at that breakpoint, and then step through the suspect area, examining the variables that are interesting, until you see the problem happen.

The following two commands are useful with this technique.

NEXT [count]

N [count]

Execute next instruction and stop again. With an argument, execute next count instructions. If any of the executed instructions is a function call, that function is not descended into.

STEP [count]

S [count]

Execute next instruction and stop again. If the instruction is a function call, descend into that function. With an argument, execute next count instructions.

3.3.8 Executing Shell Commands.

SHELL [command]

! [command]

Execute given shell command, by running /bin/sh -c command. For example, to see the listing of the current working directory, do:

MIX> ! ls -l

If no arguments are supplied, execute a subordinate shell.

3.3.9 Examining Data and Registers

DUMP

DU

Dump MIX registers and memory contents. The output format is described below.

DUMP MEMORY [from [to]]

DM [from [to]]

Dump MIX memory. When used without arguments, dumps entire address space. When used with one argument, dumps the memory contents starting from location from. When used with two arguments, dumps the contents of memory between the locations from and to, inclusive. Both locations are rounded to the nearest word boundary.

The output is formatted in blocks, each one containing 5 machine words. Each block is preceded by the location of its first word. Each word is printed in three forms, located in rows. The first row is the decimal value of the word, the second row is its representation in instruction format (TAOCP, 1.3.1, p.124, Instruction format), and the last one gives its printable representation. For example, the words ‘3000--3004’ of ‘hello.mix’ code look as follows:

3000 +0000787219621 +0000786695330 +0000000000133 +3003 00 18 37 +3001 00 18 34 +0000 00 02 05 '*d Q7' '*b Q4' ' BE' +0000135582544 +0000687973395 +0517 13 13 16 +2624 26 16 19 'HELLO' ', WOR'

The above example is split in two groups due to printing restrictions.

If several blocks of memory contain the same data, only first of them is displayed, the rest being replaced by a message, similar to the following:

Lines 3015 to 3995 are the same.

DUMP REGISTERS

DR

Dump contents of MIX registers. The following example illustrates the output format:

Registers A/X    +00000000000 +00041363636
                 +          0 +    8775582

Index Registers  +00000  +00000  +05670  +00000  +00000  +00000
                 +    0  +    0  + 3000  +    0  +    0  +    0

Jump Register    +00015     Overflow toggle:      OFF
                 +   13     Comparison Indicator: EQUAL

Clock = 262436 u. Location = 3001, M 3003, I 0, F 18, C 37,
inst = + 5673002245

DISASSEMBLE [from [to]]

UNASM [from [to]]

U [from [to]]

Dump a range of memory from–to as MIX instructions. If to is not given, disassemble first five words starting at from. If no arguments are given, disassemble first five words starting from the current instruction pointer:

MIX> disassemble 0 0 IN 16(16) 1 IN 29(16) 2 LD1 0(0:0) 3 JBUS *(16) 4 LDA 30

3.3.10 A Summary of Terminal Commands.

For convenience, this section lists all available terminal commands in alphabetical order, along with a short description and a reference to their detailed description.

Terminal Command: ADDRESS breakpoint-command

breakpoint-command is any of the following commands with appropriate arguments: DELETE, ENABLE, INFO BREAK, DISABLE, IGNORE, PASSCOUNT.

The ADDRESS prefix makes breakpoint-command to refer to breakpoints using memory locations they are set as, rather than breakpoint numbers. See section ADDRESS prefix.

Terminal Command: ASGN device file

Assign file to the given MIX device.

See section Assigning and Listing Devices.

Terminal Command: BREAK [TEMP] location

Set a breakpoint at the given location. If TEMP is given, set a temporary breakpoint, active for one pass only.

See section Breakpoints.

Terminal Command: BT location-list

Terminal Command: TB location-list

Shortcut for BREAK TEMP.

Terminal Command: DELETE [num-list]

Delete specified breakpoints. num-list is a list of breakpoint numbers or, if ADDRESS prefix is used, their addresses. Without arguments, delete all breakpoints.

See section Deleting Breakpoints.

Terminal Command: CONTINUE

Terminal Command: C

Continue program execution, at the address where it last stopped.

See section Stopping and Continuing.

Terminal Command: DISABLE [num-list]

Disable breakpoints. num-list is a list of breakpoint numbers or, if ADDRESS prefix is used, their addresses. Without arguments, disable all breakpoints.

See section Disabling and Enabling Breakpoints.

Terminal Command: DISASSEMBLE [from [to]]

Terminal Command: UNASM [from [to]]

Terminal Command: U [from [to]]

Dump a range of memory as MIX instructions.

See section DISASSEMBLE.

Terminal Command: DUMP

Terminal Command: DU

Dump MIX registers and memory contents.

See section Examining Data and Registers.

Terminal Command: DUMP REGISTERS

Terminal Command: DR

Dump contents of MIX registers.

See section DUMP REGISTERS.

Terminal Command: DUMP MEMORY [from [to]]

Terminal Command: DM [from [to]]

Dump MIX memory.

See section DUMP MEMORY.

Terminal Command: ENABLE [num-list]

Enable breakpoints. num-list is a list of breakpoint numbers or, if ADDRESS prefix is used, their addresses. Without arguments, enable all breakpoints.

See section ENABLE.

Terminal Command: GO

Terminal Command: RUN

Run a program. See section Running a Program.

Terminal Command: HELP [command-verb]

Terminal Command: ? [command-verb]

Display a short usage summary about command-verb. Without arguments, display all available commands.

See section Obtaining On-line Help.

Terminal Command: IGNORE number count

Set ignore count for breakpoint number to count. number is a breakpoint number or, if ADDRESS prefix is used, its address.

See section IGNORE.

Terminal Command: INFO BREAK [num]

Terminal Command: LIST BREAK [num]

Terminal Command: LB [num]

Without argument, lists all existing breakpoints. With an argument, lists only breakpoint num. May be prefixed with ADDRESS to use breakpoint address instead of number.

See section Listing Breakpoints.

Terminal Command: INFO IO [num]

Terminal Command: LIST IO [num]

Terminal Command: LI [num]

Without arguments, list all devices. With a numeric argument, show information about that particular device.

See section INFO IO.

Terminal Command: NEXT [count]

Execute next count (default is 1) instructions and stop again.

See section NEXT.

Terminal Command: PASSCOUNT number count

Set pass count for breakpoint number to count.

number is a breakpoint number or, if ADDRESS prefix is used, its address.

See section PASSCOUNT.

Terminal Command: SOURCE filename

Terminal Command: SO filename

Execute the command file filename.

See section Command Files, for more information about command files and their execution.

Terminal Command: QUIT

Quit the terminal. See section Quitting the Terminal.

Terminal Command: SHELL [command]

Terminal Command: ? [command]

Execute given shell command. See section Executing Shell Commands..

Terminal Command: STEP [count]

Execute next count (default is 1) instructions and stop again. If a function call is encountered, descend into the function.

See section STEP.

3.4 Command Files

A command file is a file containing mixsim commands, one per line. Comments (lines starting with ‘#’) and empty lines are also allowed. An empty line in a command file does nothing; it does not mean to repeat the last command, as it would from the terminal.

Command files are useful to store sequences of mixsim commands for executing them later. There are two ways to execute a command file: explicit, by using SOURCE command, or implicit, by naming the file ‘.mixsim’ and storing it in the current working directory.

SOURCE filename

SO filename

Execute the command file filename.

The lines in a command file are executed sequentially. They are not printed as they are executed. An error in any command terminates execution of the command file and control is returned to the console. However, any mixsim command that prints a diagnostic message saying what it is doing, continues to do so even when called from a command file.

Commands that would ask for confirmation if used interactively proceed without asking, as if an affirmative answer was obtained.

When started in terminal mode (see section Terminal Mode and Debugger.), mixsim searches for file named ‘.mixsim’ in the current working directory, and, if this file exists, executes it. This file can be used to provide necessary default settings. For example, the following ‘.mixsim’ file assigns ‘easter.dck’ to the card reader device and sets breakpoint at address ‘1000’:

asgn 16 easter.dck
br 1000

3.5 mixsim option summary.

This section summarizes mixsim command line options.

Usage:
mixsim [options] [deck-file]

‘--assign-device=dev=file’

‘-a dev=file’

Assign file to the MIX device dev.

See section Executing MIX Programs..

‘--terminal’

‘-t’

Run in terminal mode.

See section Terminal Mode and Debugger..

‘--help’

‘-h’

Print a concise help summary.

‘--version’

‘-V’

Print program version and license information.

?