![[MIX logo]](/software/mix/graphics/mix-small.jpg){kind=small}
|
|
|
MIX Assembler and Simulator |
Sergey Poznyakoff, Douglas Laing |
| MIX Manual (split by section): |  |
 |
 |
 |
 |
 |
 |
? |
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.
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).
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 |
HELP? To obtain help about all available commands, type HELP.
HELP cmd? cmdWhen used with an argument, it displays usage summary for the given command verb, e.g.:
MIX> HELP ASGN ASGN <DEVICE> <FILE> |
QUITQ 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.
ASGN device fileA device fileAssign 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 number.
I/O time per block.
Seek time.
Memory address for the pending I/O operation.
Device position for the pending I/O operation. This column is meaningful only for tape and disk devices.
Opcode or ‘N/A’, if no operation is pending.
Clock time when the I/O will occur. To examine the current clock time, see Listing Breakpoints.
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 |
GOGRUNREmulates MIX GO button.
This command does the following:
JMP to location ‘0000’ occurs. The
J-register is also set to 0.
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 |
Breakpoints are set with the BREAK command (abbreviated
B).
BREAK locationB locationSet 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 locationBT locationTB locationSets 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.
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:
MIX> DELETE |
MIX> DELETE 1 3 5 |
MIX> ADDRESS DELETE 1000 3000 |
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-listENA number-listEnable 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.
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 countI number countSet ignore count for breakpoint number to count.
PASSCOUNT number countP number countSet 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 |
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:
| Column | Meaning |
|---|---|
| NUM | Breakpoint number. |
| LOC | Location. |
| ENB | Is the breakpoint enabled or not. |
| CNT | Number of passes registered this far. |
| IGN | Ignore count. |
| PAS | Pass count. |
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).
CONTINUECContinue 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.
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.
DUMPDUDump 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 REGISTERSDRDump 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 |
For convenience, this section lists all available terminal commands in alphabetical order, along with a short description and a reference to their detailed description.
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.
Assign file to the given MIX device.
See section Assigning and Listing Devices.
Set a breakpoint at the given location. If TEMP is given,
set a temporary breakpoint, active for one pass only.
See section Breakpoints.
Shortcut for BREAK TEMP.
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.
Continue program execution, at the address where it last stopped.
See section Stopping and Continuing.
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.
Dump a range of memory as MIX instructions.
See section DISASSEMBLE.
Dump MIX registers and memory contents.
See section Examining Data and Registers.
Dump contents of MIX registers.
See section DUMP REGISTERS.
Dump MIX memory.
See section DUMP MEMORY.
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.
Run a program. See section Running a Program.
Display a short usage summary about command-verb. Without arguments, display all available commands.
See section Obtaining On-line Help.
Set ignore count for breakpoint number to count.
number is a breakpoint number or, if ADDRESS prefix is
used, its address.
See section IGNORE.
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.
Without arguments, list all devices. With a numeric argument, show information about that particular device.
See section INFO IO.
Execute next count (default is 1) instructions and stop again.
See section NEXT.
Set pass count for breakpoint number to count.
number is a breakpoint number or, if ADDRESS prefix is
used, its address.
See section PASSCOUNT.
Execute the command file filename.
See section Command Files, for more information about command files and their execution.
Quit the terminal. See section Quitting the Terminal.
Execute given shell command. See section Executing Shell Commands..
Execute next count (default is 1) instructions and stop again. If a function call is encountered, descend into the function.
See section STEP.
| MIX Manual (split by section): | |
|
|
|
|
|
|
? |
Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.