     [file version.texi not included]

This file documents the the MDK utilities for developing programs using Donald Knuth's MIX language.

Copyright (C) 2000, 2001 José Antonio Ortega Ruiz

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the sections entitled ``Copying'' and ``GNU General Public License'' are included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.

This file documents the MDK utilities to develop, run and debug programs written in the MIXAL programming language.  MIXAL is an assembler-like language for programming a virtual computer called MIX. They were created by Donald Knuth in the first volume of The Art of Computer Programming (Addison Wesley, 1997).

MDK was written by José Antonio Ortega Ruiz and is released under the GNU General Public license (see Copying), so that users are free to share and improve it.

Introduction
************

In his book series The Art of Computer Programming (published by Addison Wesley), D. Knuth uses an imaginary computer, the MIX, and its associated machine-code and assembly languages to ilustrate the concepts and algorithms as they are presented.

The MIX's architecture is a simplified version of those found in real CISC CPUs, and the MIX assembly language (MIXAL) provides a set of primitives that will be very familiar to any person with a minimum experience in assembly programming. The MIX/MIXAL definition is powerful and complete enough to provide a virtual development platform for writing quite complex programs, and close enough to real computers to be worth using when learning programming techniques. At any rate, if you want to learn or improve your programming skills, a MIX development environment would come in handy.

The MDK package aims at providing such virtual development environment on a GNU box. Thus, MDK offers you a set of utilities to simulate the MIX computer and to write, compile, run and debug MIXAL programs. As of version VERSION, MDK includes the following programs:

mixvm
     MIX virtual machine. Emulation of the MIX computer.

mixasm
     MIXAL assembler. Assembler which translates MIXAL source files into programs that can be run (and debugged) by mixvm.

mixvm implements a simulator of the MIX computer, giving you a virtual machine for executing and debugging MIX programs. These binary programs could be written by hand, but it is easier to produce them compiling MIXAL source files, using the MIXAL assembler mixasm.

This manual gives you a tutorial of MIX and MIXAL, and a thorough description of the use of the MDK utilities.

MIX and MIXAL tutorial
**********************

In the book series The Art of Computer Programming, by D. Knuth, a virtual computer, the MIX, is used by the author (together with the set of binary instructions that the virtual CPU accepts) to illustrate the algorithms and skills that every serious programmer should master. Like any other real computer, there is a symbolic assembler language that can be used to program the MIX: the MIX assembly language, or MIXAL for short.  In the following subsections you will find a tutorial on these topics, which will teach you the basics of the MIX architecture and how to program a MIX computer using MIXAL.

The MIX computer
================

In this section, you will find a description of the MIX computer, its components and instruction set.

MIX architecture
----------------

The basic information storage unit in the MIX computer is the byte, which stores positive values in the range 0-63 . Note that a MIX byte can be then represented as 6 bits, instead of the common 8 bits for a regular byte. Unless otherwise stated, we shall use the word byte to refer to a MIX 6-bit byte.

A MIX word is defined as a set of 5 bytes plus a sign. The bytes within a word are numbered from 1 to 5, being byte number one the most significant one. The sign is denoted by index 0. Graphically,

      -----------------------------------------------
     |   0   |   1   |   2   |   3   |   4   |   5   |
      -----------------------------------------------
     |  +/-  | byte  | byte  | byte  | byte  | byte  |
      -----------------------------------------------

Sample MIX words are - 12 00 11 01 63 and + 12 11 34 43 00.

You can refer to subfields within a word using a field specification or fspec of the form (L:R), where L denotes the first byte and R the last byte of the subfield. When L is zero, the subfield includes the word's sign. An fspec can also be represented as a single value F, given by F = 8*L + R (thus the fspec (1:3), denoting the first three bytes of a word, is represented by the integer 11).

The MIX computer stores information in registers, that can store either a word or two bytes and sign (see below), and memory cells, each one containing a word. Specifically, the MIX computer has 4000 memory cells with addresses 0 to 3999 (i.e., two bytes are enough to address a memory cell) and the following registers:

rA
     A register. General purpose register holding a word. Usually its contents serves as the operand of arithmetic and storing instructions.

rX
     X register. General purpose register holding a word. Often it acts as an extension or a replacement of rA.

rJ
     J (jump) register. This register stores positive two-byte values, usually representing a jump address.

rI[1-6]
     Index registers. These six registers can store a signed two-byte value. Their contents is used as indexing values for the computation of effective memory addresses.

In addition, the MIX computer contains:

  - An overflow toggle (a single bit with values on or off). In this manual, this toggle is denoted OV.

  - A comparison indicator (having three values: EQUAL, GREATER or LESS). In this manual, this indicator is denoted CM, and its possible values are abbreviated as E, G and L.

  - Input-output block devices. Each device is labelled as Un, where n runs from 0 to 20. In Knuth's definition, U0-7 are magnetic tape units, U8-15 are disks and drums, U16 is a card reader, U17 is a card writer, U18 is a line printer and, U19 is a typewriter terminal, and U20, a paper tape. Our implementation maps these devices to disk files, except for U19, which represents the standard output.

As noted above, communication of the MIX computer with the external world is achieved by a set of input-output devices which can be "connected" to it. Interchange of information is done in blocks of words whose length depend on the device at hand (see Devices). These words are interpreted by the device either as binary information (for devices 0-16), or as representing printable characters (devices 17-20). In the last case, each MIX byte is mapped onto a character according to the following table:

00      01   A   02   B   03   C
04   D   05   E   06   F   07   G
08   H   09   I   10   d   11   J
12   K   13   L   14   M   15   N
16   O   17   P   18   Q   19   R
20   s   21   p   22   S   23   T
24   U   25   V   26   W   27   X
28   Y   29   Z   30   0   31   1
32   2   33   3   34   4   35   5
36   6   37   7   38   8   39   9
40   .   41   ,   42   (   43   )
44   +   45   -   46   *   47   /
48   =   49   $   50   <   51   >
52   @   53   ;   54   :   55   '

The value 0 represents a whitespace. Lowercase letters (d, s, p) correspond to symbols non representable as ASCII characters (uppercase delta, sigma and gamma, respectively) and byte values 56-63 have no associated character.

Finally, the MIX computer features a virtual CPU which controls the above components, and which is able to execute a rich set of instructions (constituting its machine language, similar to those commonly found in real CPUs), including arithmetic, logical, storing, comparison and jump instructions. Being a typical von Neumann computer, the MIX CPU fetchs binary instructions from memory sequentially (unless a jump instruction is found), and stores the address of the next instruction to be executed in an internal register called location counter (also known as program counter in other architectures).

The next section, see MIX instruction set, gives a complete description of the available MIX binary instructions.

MIX instruction set
-------------------

The following subsections fully describe the instruction set of the MIX computer. We begin with a description of the structure of binary instructions and the notation used to refer to their subfields. The remaininig subsections are devoted to describing the actual instructions available to the MIX programmer.

Instruction structure
.....................

MIX instructions are codified as words with the following subfield structure:

Subfield   fspec   Description
ADDRESS   (0:2)
The first two bytes plus sign are the address field. Combined
with the INDEX field, denotes the memory address to be used by the
instruction.
INDEX   (3:3)
The third byte is the index, normally used for indexing the
address (The actual memory address the instruction refers to, is
obtained by adding to ADDRESS the value of the rI register
denoted by INDEX.).
MOD   (4:4)
Byte four is used either as an operation code modifier or as a field
specification.
OPCODE   (5:5)
The last (least significant) byte in the word denotes the operation
code.

or, graphically,

      ------------------------------------------------
     |   0   |   1   |   2   |   3   |   4   |   5    |
      ------------------------------------------------
     |        ADDRESS        | INDEX |  MOD  | OPCODE |
      ------------------------------------------------

For a given instruction, M stands for the memory address obtained after indexing the ADDRESS subfield (using its INDEX byte), and V is the contents of the subfield indicated by MOD of the memory cell with address M. For instance, suppose that we have the following contents of MIX registers and memory cells:

     [rI2] = + 00 63
     [31] = - 10 11 00 11 22

where [n] denotes the contents of the nth memory cell and [rI2] the contents of register rI2 (In general, [X] will denote the contents of entity X; thus, by definition, V = [M](MOD).).  Let us consider the binary instruction I = - 00 32 02 11 10. For this instruction we have:

     ADDRESS = - 00 32 = -32
     INDEX = 02 = 2
     MOD = 11 = (1:3)
     OPCODE = 10

     M = ADDRESS + [rI2] = -32 + 63 = 31
     V = [M](MOD) = (- 10 11 00 11 22)(1:3) = + 00 00 10 11 00

In the following subsections, we will assing to each MIX instruction a mnemonic, or symbolic name. For instance, the mnemonic of OPCODE 10 is LD2. Thus we can rewrite the above instruction as

     LD2  -32,2(1:3)

or, for a generic instruction:

     MNEMONIC  ADDRESS,INDEX(MOD)

Some instructions are identified by both the OPCODE and the MOD fields. In these cases, the MOD will not appear in the above symbolic representation. Also when ADDRESS or INDEX are zero, they can be omitted.  Finally, MOD defaults to (0:5) (meaning the whole word).

Loading operators
.................

The following instructions are used to load memory contents into a register.

LDA
     Put in rA the contents of cell no. M. OPCODE = 8, MOD = fspec. rA <- V.

LDX
     Put in rX the contents of cell no. M. OPCODE = 15, MOD = fspec. rX <- V.

LDi
     Put in rIi the contents of cell no. M. OPCODE = 8 + i, MOD = fspec. rIi <- V.

LDAN
     Put in rA the negative contents of cell no. M. OPCODE = 16, MOD = fspec. rA <- -V.

LDXN
     Put in rX the negative contents of cell no. M. OPCODE = 23, MOD = fspec. rX <- -V.

LDiN
     Put in rIi the negative contents of cell no. M. OPCODE = 16 + i, MOD = fspec. rIi <- -V.

In all the above load instructions the MOD field selects the bytes of the memory cell with address M which are loaded into the requisite register (indicated by the OPCODE).  For instance, the word + 00 13 01 27 11 represents the instruction

     LD3    13,1(3:3)
      ^      ^ ^  ^
      |      | |  |
      |      | |   --- MOD = 27 = 3*8 + 7
      |      |  --- INDEX = 1
      |       --- ADDRESS = 00 13
       --- OPCODE = 11

Let us suppose that, prior to this instruction execution, the state of the MIX computer is the following:

     [rI1] = - 00 01
     [rI3] = + 24 12
     [12] = - 01 02 03 04 05

As, in this case, M = 13 + [rI1] = 12, we have V = [M](3:3) = (- 01 02 03 04 05)(3:3) = + 00 00 00 00 03 (note that the specified subfield is left-padded with null bytes to complete a word). Hence, the MIX state, after the instruction execution, will be

     [rI1] = - 00 01
     [rI3] = + 00 03
     [12] = - 01 02 03 04 05

To further illustrate loading operators, the following table shows the contents of rX after different LDX instructions:

LDX 12(0:0)     [rX] = - 00 00 00 00 00

LDX 12(0:1)     [rX] = - 00 00 00 00 01

LDX 12(3:5)     [rX] = + 00 00 03 04 05

LDX 12(3:4)     [rX] = + 00 00 00 03 04

LDX 12(0:5)     [rX] = - 01 02 03 04 05

Storing operators
.................

The following instructions are the inverse of the load operations: they are used to store a subfield of a register into a memory location. Here, MOD represents the subfield of the memory cell that is to be overwritten with bytes from a register. These bytes are taken beginning by the rightmost side of the register.

STA
     Store rA. OPCODE = 24, MOD = fspec. V <- rA.

STX
     Store rX. OPCODE = 31, MOD = fspec. V <- rX.

STi
     Store rIi. OPCODE = 24 + i, MOD = fspec. V <- rIi.

STJ
     Store rJ. OPCODE = 32, MOD = fspec. V <- rJ.

STZ
     Store zero. OPCODE = 33, MOD = fspec. V <- 0.

By way of example, consider the instruction STA 1200(2:3). It causes the MIX to fetch bytes no. 4 and 5 of register A and copy them to bytes 2 and 3 of memory cell no. 1200 (remember that, for these instructions, MOD specifies a subfield of the memory address). The others bytes of the memory cell retain their values. Thus, if prior to the instruction execution we have

     [1200] = - 20 21 22 23 24
     [rA] = + 01 02 03 04 05

we will end up with

     [1200] = - 20 04 05 23 24
     [rA] = + 01 02 03 04 05

As a second example, ST2 1000(0) will set the sign of [1000] to that of [rI2].

Arithmetic operators
....................

The following instructions perform arithmetic operations between rA and rX register and memory contents.

ADD
     Add and set OV if overflow. OPCODE = 1, MOD = fspec. rA <- rA +V.

SUB
     Sub and set OV if overflow. OPCODE = 2, MOD = fspec. rA <- rA - V.

MUL
     Multiply V times rA and store the 10-bytes product in rAX. OPCODE = 3, MOD = fspec. rAX <- rA x V.

DIV
     rAX is considered a 10-bytes number, and it is divided by V. OPCODE = 4, MOD = fspec. rA <- rAX / V, rX <- reminder.

In all the above instructions, [rA] is one of the operands of the binary arithmetic operation, the other being V (that is, the specified subfield of the memory cell with address M), padded with zero bytes on its left-side to complete a word. In multiplication and division, the register X comes into play as a right-extension of the register A, so that we are able to handle 10-byte numbers whose more significant bytes are those of rA (the sign of this 10-byte number is that of rA: rX's sign is ignored).

Addition and substraction of MIX words can give rise to overflows, since the result is stored in a register with room to only 5 bytes (plus sign). When this occurs, the operation result modulo 1,073,741,823 (the maximum value storable in a MIX word) is stored in rA, and the overflow toggle is set to TRUE.

Address transfer operators
..........................

In these instructions, M (the address of the instruction after indexing) is used as a number instead of as the address of a memory cell.

ENTA
     Enter [rA]. OPCODE = 48, MOD = 2. rA <- M.

ENTX
     Enter [rX]. OPCODE = 55, MOD = 2. rX <- M.

ENTi
     Enter [rIi]. OPCODE = 48 + i, MOD = 2. rIi <- M.

ENNA
     Enter negative [rA]. OPCODE = 48, MOD = 3. rA <- -M.

ENNX
     Enter negative [rX]. OPCODE = 55, MOD = 3. rX <- -M.

ENNi
     Enter negative [rIi]. OPCODE = 48 + i, MOD = 3. rIi <- -M.

INCA
     Increase [rA]. OPCODE = 48, MOD = 0. rA <- rA + M.

INCX
     Increase [rX]. OPCODE = 55, MOD = 0. rX <- rX + M.

INCi
     Increase [rIi]. OPCODE = 48 + i, MOD = 0. rIi <- rIi + M.

DECA
     Decrease [rA]. OPCODE = 48, MOD = 1. rA <- rA - M.

DECX
     Decrease [rX]. OPCODE = 55, MOD = 0. rX <- rX - M.

DECi
     Decrease [rIi]. OPCODE = 48 + i, MOD = 0. rIi <- rIi - M.

In the above instructions, the subfield ADDRESS acts as an immediate (indexed) operand, and allow us to set directly the contents of the MIX registers without an indirection to the memory cells (in a real CPU this would mean that they are faster that the previously discussed instructions, whose operands are fetched from memory). So, if you want to store in rA the value -2000 (- 00 00 00 31 16), you can use the binary instruction + 31 16 00 03 48, or, symbolically,

     ENNA 2000

Used in conjuction with the store operations (STA, STX, etc.), these instructions also allow you to set memory cells contents to concrete values.

Note that in these address transfer operators, the MOD field is not a subfield specificator, but serves to define (together with OPCODE) the concrete operation to be performed.

Comparison operators
....................

So far, we have learned how to move values around between the MIX registers and its memory cells, and also how to perform arithmetic operations using these values. But, in order to write non-trivial programs, other functionalities are needed. One of the most common is the ability to compare two values, which, combined with jumps, will allow the execution of conditional statements. The following instructions compare the value of a register with V, and set the CM indicator to the result of the comparison (i.e. to E, G or L, equal, greater or lesser respectively).

CMPA
     Compare [rA] with V. OPCODE = 56, MOD = fspec.

CMPX
     Compare [rX] with V. OPCODE = 63, MOD = fspec.

CMPi
     Compare [rIi] with V. OPCODE = 56 + i, MOD = fspec.

As explained above, these instructions modify the value of the MIX comparison indicator; but maybe you are asking yourself how do you use this value: enter jump operators, in the next subsection.

Jump operators
..............

The MIX computer has an internal register, called the location counter, which stores the address of the next instruction to be fetched and executed by the virtual CPU. You cannot directly modify the contents of this internal register with a load instruction: after fetching the current instruction from memory, it is automatically increased in one unit by the MIX. However, the is a set of instructions (which we call jump instructions) which can alter the contents of the location counter provided some condition is met. When this occurs, the value of the next instruction address that would have been fetched in the absence of the jump is stored in rJ (except for JSJ), and the location counter is set to the value of M (so that the next instruction is fetched from this new address). Later on, you can return to the point when the jump occurred reading the address stored in rJ.

The MIX computer provides the following jump instructions: With these instructions you force a jump to the specified address. Use JSJ if you do not care about the return address.

JMP
     Unconditional jump. OPCODE = 39, MOD = 0.

JSJ
     Unconditional jump, but rJ is not modified. OPCODE = 39, MOD = 1.

These instructions check the overflow toggle to decide whether to jump or not.

JOV
     Jump if OV is set (and turn it off). OPCODE = 39, MOD = 2.

JNOV
     Jump if OV is not set (and turn it off). OPCODE = 39, MOD = 3.

In the following instructions, the jump is conditioned to the contents of the comparison flag:

JL
     Jump if [CM] = L. OPCODE = 39, MOD = 4.
JE
     Jump if [CM] = E. OPCODE = 39, MOD = 5.
JG
     Jump if [CM] = G. OPCODE = 39, MOD = 6.
JGE
     Jump if [CM] does not equal L. OPCODE = 39, MOD = 7.
JNE
     Jump if [CM] does not equal E. OPCODE = 39, MOD = 8.
JLE
     Jump if [CM] does not equal G. OPCODE = 39, MOD = 9.

You can also jump conditioned to the value stored in the MIX registers, using the following instructions:

JAN
JAZ
JAP
JANN
JANZ
JANP
     Jump if the contents of rA is, respectively, negative, zero, positive, non-negative, non-zero or non-positive. OPCODE = 40, MOD = 0, 1, 2, 3, 4, 5.

JXN
JXZ
JXP
JXNN
JXNZ
JXNP
     Jump if the contents of rX is, respectively, negative, zero, positive, non-negative, non-zero or non-positive. OPCODE = 47, MOD = 0, 1, 2, 3, 4, 5.

JiN
JiZ
JiP
JiNN
JiNZ
JiNP
     Jump if the contents of rIi is, respectively, negative, zero, positive, non-negative, non-zero or non-positive. OPCODE = 40 + i, MOD = 0, 1, 2, 3, 4, 5.

Input-output operators
......................

As explained in previous sections (see MIX architecture), the MIX computer can interact with a series of block devices. To that end, you have at your disposal the following instructions:

IN
     Transfer a block of words from the specified unit to memory, starting at address M. OPCODE = 36, MOD = I/O unit.

OUT
     Transfer a block of words from memory (starting at address M) to the specified unit. OPCODE = 37, MOD = I/O unit.

IOC
     Perfom a control operation (given by M) on the specified unit. OPCODE = 35, MOD = I/O unit.

JRED
     Jump to M if the specified unit is ready. OPCODE = 38, MOD = I/O unit.

JBUS
     Jump to M if the specified unit is busy. OPCODE = 34, MOD = I/O unit.

In all the above instructions, the MOD subfile must be in the range 0-20, since it denotes the operation's target device. The IOC instruction only makes sense for tape devices (MOD = 0-7 or 20): it shifts the read/write pointer by the number of words given by M (if it equals zero, the tape is rewound) (In Knuth's original definition, there are other control operations available, but they do not make sense when implementing the block devices as disk files (as we do in MDK simulator). For the same reason, MDK devices are always ready, since all input-output operations are performed using synchronous system calls.).

Conversion operators
....................

The following instructions convert between numerical values and their character representations.

NUM
     Convert rAX, assumed to contain a character representation of a number, to its numerical value and store it in rA. OPCODE = 5, MOD = 0.

CHAR
     Convert the number stored in rA to a character representation and store it in rAX. OPCODE = 5, MOD = 1.

Digits are represented in MIX by the range of values 30-39 (digits 9-0). Thus, if the contents of rA and rX is, for instance,

     [rA] = + 30 30 31 32 33
     [rX] = + 31 35 39 30 34

the represented number is 0012315904, and NUM will store this value in rA (i.e., we end up with [rA] = + 0 46 62 52 0 = 12315904. CHAR performs the inverse operation.

Shift operators
...............

The following instructions perform byte-wise shifts of the contents of rA and rX.

SLA
SRA
SLAX
SRAX
SLC
SRC
     Shift rA or rAX left, right, or rAX circularly left or right. M specifies the number of bytes to be shifted. OPCODE = 6, MOD = 0, 1, 2, 3, 4, 5.

If we begin with, say, [rA] = - 01 02 03 04 05, we would have the following modifications to rA contents when performing the instructions on the left column:

SLA 2   [rA] = - 03 04 05 00 00
SRA 1   [rA] = - 00 01 02 03 04
SLC 3   [rA] = - 04 05 01 02 03
SRC 24   [rA] = - 05 01 02 03 04

Note that the sign is unaffected by shift operations. On the other hand, SLAX and SRAX treat rA and rX as a single 10-bytes register (ignoring again the signs), so that, if we begin with [rA] = + 01 02 03 04 05 and [rX] = - 06 07 08 09 10, executing SLAX 3 would yield:

     [rA] = + 04 05 06 07 08  [rX] = - 09 10 00 00 00

Miscellaneous operators
.......................

Finally, we list in the following table three miscellaneous MIX instructions which do not fit in any of the previous subsections:

MOVE
     Move MOD words from M to the location stored in rI1. OPCODE = 7, MOD = no. of bytes.

NOP
     No operation. OPCODE = 0, MOD = 0.

HLT
     Halt. Stops instruction fetching. OPCODE = 5, MOD = 2.

The only effect of executing NOP is increasing the location counter, while HLT usually marks program termination.

Execution times
...............

When writing MIXAL programs (or any kind of programs, for that matter), whe shall often be interested in their execution time. Loosely speaking, we will interested in the answer to the question: how long takes a program to execute? Of course, this execution time will be a function of the input size, and the answer to our question is commonly given as the asymptotic behaviour as a function of the input size. At any rate, to compute this asymptotic behaviour, we need a measure of how long execution of a single instruction takes in our (virtual) CPU. Therefore, each MIX instruction will have an associated execution time, given in arbitrary units (in a real computer, the value of this unit will depend on the hardware configuration). When our MIX virtual machine executes programs, it will give you the value of their execution time based upon the execution time of each single instruction.

In the following table, the execution times (in the above mentioned arbitrary units) of the MIX instructions are given.

NOP   1   ADD   2   SUB
2   MUL   10
DIV   12   NUM   10   CHAR
10   HLT   10
SLx   2   SRx   2   LDx
2   STx   2
JBUS   1   IOC   1   IN
1  OUT   1
JRED   1   Jx   1   INCx
1   DECx   1
ENTx   1   ENNx   1   CMPx
1   MOVE   1+F

In the above table, 'F' stands for the number of blocks to be moved (given by the FSPEC subfield of the instruction); SLx and SRx are a short cut for the byte-shifting operations; LDx denote all the loading operations; STx are the storing operations; Jx stands for all the jump operations, and so on with the rest of abbreviations.

MIXAL
=====

In the previous sections we have listed all the available MIX binary instructions. As we have shown, each instruction is represented by a word which is fetched from memory and executed by the MIX virtual CPU. As is the case with real computers, the MIX knows how to decode instructions in binary format (the so--called machine language), but a human programmer would have a tough time if she were to write her programs in machine language. Fortunately, the MIX computer can be programmed using an assembly language, MIXAL, which provides a symbolic way of writing the binary instructions understood by the imaginary MIX computer. If you have used assembler languages before, you will find MIXAL a very familiar language. MIXAL source files are translated to machine language by a MIX assembler, which produces a binary file (the actual MIX program) which can be directly loaded into the MIX memory and subsequently executed.

In this section, we describe MIXAL, the MIX assembly language. The implementation of the MIX assembler program and MIX computer simulator provided by MDK are described later on (see Getting started).

Basic program structure
-----------------------

The MIX assembler reads MIXAL files line by line, producing, when required, a binary instruction, which is associated to a predefined memory address. To keep track of the current address, the assembler maintains an internal location counter which is incremented each time an instruction is compiled. In addition to MIX instructions, you can include in MIXAL file assembly directives (or pseudoinstructions) addressed at the assembler itself (for instance, telling it where the program starts and ends, or to reposition the location counter; see below).

MIX instructions and assembler directives (We shall call them, collectively, MIXAL instructions.) are written in MIXAL (one per source file line) according to the following pattern:

     [LABEL]   MNEMONIC  [OPERAND]   [COMMENT]

where OPERAND is of the form

     [ADDRESS][,INDEX][(MOD)]

Items between square brackets are optional, and

LABEL
     Is an alphanumeric identifier (a symbol) which gets the current value of the location counter, and can be used in subsequent expressions.

MNEMONIC
     Is a literal denoting the operation code of the instruction (e.g. LDA, STA; see MIX instruction set) or an assembly pseudoinstruction (e.g. ORG, EQU).

ADDRESS
     Expression evaluating to the address subfield of the instruction.

INDEX
     Expression evaluating to the index subfield of the instruction. It defaults to 0 (i.e., no use of indexing) and can only be used when ADDRESS is present.

MOD
     Expression evaluating to the mod subfield of the instruction. Its default value, when omitted, depends on OPCODE.

COMMENT
     Any number of spaces after the operand mark the beggining of a comment, i.e. any text separated by white space from the operand is ignored by the assembler (note that spaces are not allowed within the OPERAND field).

Note that spaces are not allowed between the ADDRESS, INDEX and MOD fields if they are present. White space is used to separate the label, operation code and operand parts of the instruction (In fact, Knuth's definition of MIXAL restricts the column number at which each of these instruction parts must start. The MIXAL assembler included in MDK, mixasm, does not impose such restriction.).

We have already listed the mnemonics associated will each MIX instructions; sample MIXAL instructions representing MIX instructions are:

     HERE     LDA  2000         HERE represents the current location counter
              LDX  HERE,2(1:3)  this is a comment
              JMP  1234

MIXAL directives
----------------

MIXAL instructions can be either one of the MIX machine instructions (see MIX instruction set) or one of the following assembly pseudoinstructions:

ORIG
     Sets the value of the memory address to which following instructions will be allocated after compilation.

EQU
     Used to define a symbol's value, e.g. SYM  EQU  2*200/3.

CON
     The value of the given expression is copied directly into the current memory address.

ALF
     Takes as operand five characters, constituting the five bytes of a word which is copied directly into the current memory address.

END
     Marks the end of the program. Its operand gives the start address for program execution.

The operand of ORIG, EQU, CON and END can be any expression evaluating to a constant MIX word, i.e., either a simple MIXAL expression (composed of numbers, symbols and binary operators, see Expressions) or a w-expression (see W-expressions).

All MIXAL programs must contain an END directive, with a twofold end: first, it marks the end of the assembler job, and, in the second place, its (mandatory) operand indicates the start address for the compiled program (that is, the address at which the virtual MIX machine must begin fetching instructions after loading the program). It is also very common (although not mandatory) to include at least an ORIG directive to mark the initial value of the assembler's location counter (remember that it stores the address associated with each compiled MIX instruction). Thus, a minimal MIXAL program would be

               ORIG  2000    set the initial compilation adress
               NOP           this instruction will be loaded at adress 2000
               HLT           and this one at address 2001
               END   2000    end of program; execution will start at address 2000
     this line is not parsed by the assembler

The assembler will generate two binary instructions (NOP (+ 00 00 00 00 00) and HLT (+ 00 00 02 05)), which will be loaded at addresses 2000 and 2001. Execution of the program will begin at address 2000. Every MIXAL program should also include a HLT instruction, which will mark the end of program execution (but not of program compilation).

The EQU directive allows the definition of symbolic names for specific values. For instance, we could rewrite the above program as follows:

     START     EQU   2000
               ORIG  START
               NOP
               HLT
               END   START

which would give rise to the same compiled code. Symbolic constants (or symbols, for short) can also be implicitly defined placing them in the LABEL field of a MIXAL instruction: in this case, the assembler assigns to the symbol the value of the location counter before compiling the line. Hence, a third way of writing our trivial program is

               ORIG  2000
     START     NOP
               HLT
               END   START

The CON directive allows you to directly specify the contents of the memory address pointed by the location counter. For instance, when the assembler encounters the following code snippet

               ORIG  1150
               CON   -1823473

it will assign to the memory cell number 1150 the contents - 00 06 61 11 49 (which corresponds to the decimal value -1823473).

Finally, the ALF directive let's you specify the memory contents as a set of five (quoted) characters, which are translated by the assembler to their byte values, conforming in that way the binary word that is to be stored in the corresponding memory cell. This directive comes in handy when you need to store printable messages in a memory address, as in the following example:

               OUT  MSG       MSG is not yet defined here (future reference)
     MSG       ALF  "THIS "   MSG gets defined here
               ALF  "IS A "
               ALF  "MESSA"
               ALF  "GE.  "

The above snippet also shows the use of a future reference, that is, the usage of a symbol (MSG in the example) prior of its actual definition. The MIXAL assembler is able to handle future references subject to some limitations which are described in the following section (see Expressions).

Any line starting with an asterisk is treated as a comment and ignored by the assembler.

     * This is a comment: this line is ignored.
         * This line is an error: * must be in column 1.

As noted in the previous section, comments can also be located after the MNEMONIC field of an instruction, separated from it by white space, as in

     LABEL     LDA   100  This is also a comment

Expressions
-----------

The ADDRESS, INDEX and MOD fields of a MIXAL instruction can be expressions, formed by numbers, identifiers and binary operators (+ - * / // :). + and - can also be used as unary operators. Order of evaluation is from left to right: there is no other operator precedence rule, and parentheses cannot be used for grouping. A stand-alone asterisk denotes the current memory location; thus, for instance,

          4+2**

evaluates to 4 plus two times the current memory location. White space is not allowed within expressions.

The special binary operator : has the same meaning as in fspecs, i.e.,

     A:B = 8*A + B

while A//B stands for the quotient of the ten-byte number A 00 00 00 00 00 (that is, A right-padded with 5 null bytes or, what amounts to the same, multiplied by 64 to the fifth power) divided by B. Sample expressions are:

     18-8*3 = 30
     14/3 = 4
     1+3:11 = 4:11 = 43
     1//64 = (01 00 00 00 00 00)/(00 00 00 01 00) = (01 00 00 00 00 00)

Note that all MIXAL expressions evaluate to a MIX word (by definition).

All symbols appearing within an expression must be previously defined. Future references are only allowed when appearing stand-alone (or modified by an unary operator) in the ADDRESS part of a MIXAL instruction, e.g.

     * OK: stand alone future reference
              STA  -S1(1:5)
     * ERROR: future reference in expression
              LDX  2-S1
     S1       LD1  2000

W-expressions
-------------

Besides expressions, as described above (see Expressions), the MIXAL assembler is able to handle the so called w-expressions as the operands of the directives ORIG, EQU, CON and END (see MIXAL directives). The general form of a w-expression is the following:

          WEXP = EXP[(EXP)][,WEXP]

where EXP stands for an expression and square brackets denote optional items. Thus, a w-expression is made by a regular expression followed by an optional expression between parenthesis, followed by any number of similar constructs separated by commas. Sample w-expressions are:

     2000
     235(3)
     S1+3(S2),3000
     S1,S2(3:5),23

W-expressions are evaluated as follows. First, all expressions are evaluated according to the rules given in the previous section. Thus, if we start with, say, S1+2(2:4) where S1 equals 265230, we have 265232(2:4). The expression between parenthesis must be a valid f-spec, for it specifies the bytes to be taken from the preceding word. In our example, we must take 3 bytes of the word + 00 01 00 48 16 (which is 265232), and store them in positions 2, 3 and 4 of the result, resulting in the new word + 00 00 48 16 00 (i.e., the decimal value 197632). When we have two expressions separated with a comma, we take, for each one, the subfield specified and compose the word to obtain the result. For instance, in the w-expression

     1(1:2),66(4:5)

we first take two bytes from 1 (00 and 01) and store them as bytes 1 and 2 of the result (obtaining + 00 01 00 00 00) and, afterwards, take two bytes from 66 (01 and 02) and store them as bytes 4 and 5 of the result, obtaining + 00 01 00 01 02 (262210). The process is repeated for each new comma-separated example. For instance:

     1(1:1),2(2:2),3(3:3),4(4:4) = 01 02 03 04 00

As stated before, w-expressions can only appear as the operands of MIXAL directives taking a constant value (ORIG, EQU, CON and END). Future references are not allowed within w-expressions (i.e., all symbols appearing in a w-expression must be defined before they are used).

Local symbols
-------------

Besides user defined symbols, MIXAL programmers can use the so called local symbols, which are symbols of the form [1-9][HBF]. A local symbol nB refers to the address of the last previous occurrence of nH as a label, while nF refers to the next nH occurrence. Unlike user defined symbols, nH can appear multiple times in the LABEL part of different MIXAL instructions. The following code shows an instance of local symbols' usage:

     * line 1
     1H    LDA  100
     * line 2: 1B refers to address of line 1, 3F refers to address of line 4
           STA  3F,2(1B//2)
     * line 3: redefinition of 1H
     1H    STZ
     * line 4: 1B refers to address of line 3
     3H    JMP  1B

Note that a B local symbol never refers to a definition in its own line, that is, in the following program:

     		ORIG 1999
     ST		NOP
     3H		EQU 69
     3H		ENTA 3B  local symbol 3B refers to 3H in previous line
     		HLT
     		END ST

the contents of rA is set to 69 and not to 2001. An specially tricky case occurs when using local symbols in conjunction with ORIG pseudoinstructions. To wit (The author wants to thank Philip E. King for pointing these two special cases of local symbol usage to him.),

     		ORIG 1999
     ST		NOP
     3H		CON 10
     		ENT1 *
     		LDA 3B
     ** rI1 is 2001, rA is 10.  So far so good!
     3H		ORIG 3B+1000
     ** at this point 3H equals 2003
     ** and the location counter equals 3000.
     		ENT2 *
     		LDX 3B
     ** rI2 contains 3000, rX contains 2003.
     		HLT
     		END ST

Literal constants
-----------------

MIXAL allows the introduction of literal constants, which are automatically stored in memory addresses after the end of the program by the assembler. Literal constants are denoted as =wexp=, where exp is an w-expression (see W-expressions). For instance, the code

     L         EQU   10
               LDA   =20-L=

causes the assembler to add after the program's end an instruction with contents 10, and to assemble the above code as the instruction LDA a, where a stands for the address in which the value 10 is stored. In other words, the compiled code is equivalent to the following:

     L         EQU  10
               LDA  a
     ...
     a         CON  20-L
               END  start

Getting started
***************

In this chapter, you will find a sample code-compile-run-debug session using the MDK utilities. Familiarity with the MIX mythical computer and its assembly language MIXAL (as described in Knuth's TAOCP) is assumed; for a compact reminder, see MIX and MIXAL tutorial.

Writing a source file
=====================

MIXAL programs can be written as ASCII files with your editor of choice. Here you have the mandatory hello world as written in the MIXAL assembly language:

     *                                                        (1)
     * hello.mixal: say 'hello world' in MIXAL                (2)
     *                                                        (3)
     * label ins    operand     comment                       (4)
     TERM    EQU    19          the MIX console device number (5)
             ORIG   1000        start address                 (6)
     START   OUT    MSG(TERM)   output data at address MSG    (7)
             HLT                halt execution                (8)
     MSG     ALF    "MIXAL"                                   (9)
             ALF    " HELL"                                   (10)
             ALF    "O WOR"                                   (11)
             ALF    "LD   "                                   (12)
             END    START       end of the program            (13)

MIXAL source files should have the extension .mixal when used with the MDK utilities. As you can see in the above sample, each line in a MIXAL file can be divided into four fields separated by an arbitrary amount of whitespace characters (blanks and or tabs). While Knuth's definition of MIXAL each field must start at a fixed pre-defined column number, the MDK assembler loosens this requirement and lets you format the file as you see fit. The only restrictions retained are for comment lines (like 1-4) which must begin with an asterisk (*) placed at column 1, and for the label field (see below) which, if present, must also start at column 1. The four fields in each non-comment line are:

  - an optional label, which either refers to the current memory address (as START and MSG in lines 7 and 9) or a defined symbol (TERM) (if present, the label must always start at the first column in its line, for the first whitespace in the line maks the beginning of the second field),

  - an operation mnemonic, which can represent either a MIX instruction (OUT and HLT in lines 6 and 7 above), or an assembly pseudoinstruction.

  - an optional operand for the (pseudo)instruction, and

  - an optional free text comment.

Lines 9-12 of the hello.mixal file above also show the second (and last) difference between Knuth's MIXAL definition and ours: the operand of the ALF pseudoinstruction (a word of five characters) must be quoted with using "" (In Knuth's definition, the operand always starts at a fixed column number, and the use of quotation is therefore unnecessary. As mixasm releases this requirement, marking the beginning and end of the ALF operand disambiguates the parser's recognition of this operand when it includes blanks).

The workings of this sample program should be straightforward if you are familiar with MIXAL. See TAOCP vol. 1 for a thorought definition or MIX and MIXAL tutorial, for a quick tutorial.

Compiling
=========

A simulator of the MIX computer, called mixvm (MIX virtual machine) is included in the MDK tools. It is able to run binary files containing MIX instructions written in their binary representation. You can translate MIXAL source files into this binary form using mixasm, the MIXAL assembler. So, in order to compile the hello.mixal file, you can type the following command at your shell prompt:

     mixasm -g hello RET

If the source file contains no errors, this will produce a binary file called hello.mix which can be loaded and run by the MIX virtual machine. The -g flag tells the assembler to include debug information in the executable file (for a complete description of all the compilation options, see mixasm.) Now, your are ready to run your first MIX program, as described in the following section.

Running the program
===================

MIX is a mythical computer, so it is no use ordering it from your favorite hardware provider. MDK provides a software simulator of the computer, though. It is called mixvm, which stands for MIX virtual machine. Using it, you can run your MIXAL programs, after compiling them with mixasm into binary .mix files. mixvm can be used either in interactive or non-interactive mode. In the second case, mixvm will load your program into memory, execute it (producing any output due to MIXAL OUT instructions present in the program), and exit when it encounters a HLT instruction. In interactive mode, you will enter a shell prompt which allows you issuing commands to the running virtual machine. This commands will permit you loading, running and debugging programs, as well as inspecting the MIX computer state (register contents, memory cells contents and so on).

Non-interactive mode
--------------------

To make mixvm work in non-interactive mode, use the -r flag. Thus, to run our hello.mix program, simply type

     mixvm -r hello RET

at your command prompt, and you will get the following output:

     MIXAL HELLO WORLD
     ** Execution time: 11

Since our hello world program uses MIX's device number 19 as its output device (see Writing a source file), the output is redirected to the shell's standard output. Had you used any other MIX output devices (disks, drums, line printer, etc.), mixvm would have created a file named after the device used (e.g. disk4.dev) and written its output there. Note also that the virtual machine reports the execution time of the program, according to the (virtual) time spent in each of the binary instructions (see Execution times).

Sometimes, you will prefer to store the results of your program in MIX registers rather than writing them to a device. In such cases, mixvm's -d flag is your friend: it makes mixvm to dump the contents of its registers and flags after executing the loaded program. For instance, typing the following command at your shell's prompt

     mixvm -d -r hello

you will obtain the following output:

     MIXAL HELLO WORLD
     ** Execution time: 11
     rA: + 00 00 00 00 00 (0000000000)
     rX: + 00 00 00 00 00 (0000000000)
     rJ: + 00 00 (0000)
     rI1: + 00 00 (0000)     rI2: + 00 00 (0000)
     rI3: + 00 00 (0000)     rI4: + 00 00 (0000)
     rI5: + 00 00 (0000)     rI6: + 00 00 (0000)
     Overflow: F
     Cmp: E

which, in addition to the program's outputs and execution time, gives you the contents of the MIX registers and the values of the overflow toggle and comparison flag (admittedly, rather uninteresting in our sample).

As you can see, running programs non-interactively has many limitations. You cannot peek the virtual machine's memory contents, not to mention stepping through your program's instructions or setting breakpoints. Enter interactive mode.

Interactive mode
----------------

To enter the MIX virtual machine interactive mode, simply type

     mixvm RET

at your shell command prompt. This command enters the mixvm command shell. You will be presented the following command prompt:

     MIX >

The virtual machine is initialised and ready to accept your commands. The mixvm command shell uses GNU's readline, so that you have at your disposal command completion (using TAB) and history functionality, as well as other line editing shortcuts common to all utilities using this library (for a complete description of readline's line editing usage, see Command Line Editing (Readline).)

Usually, the first thing you will want to do is loading a compiled MIX program into memory. This is acomplished by the load command, which takes as an argument the name of the .mix file to be loaded. Thus, typing

     MIX > load hello RET
     Program loaded. Start address: 3000
     MIX >

will load hello.mix into the virtual machine's memory and set the program counter to the address of the first instruction. You can obtain the contents of the program counter using the command pc:

     MIX > pc
     Current address: 3000
     MIX >

After loading it, you are ready to run the program, using, as you surely have guessed, the run command:

     MIX > run
     Running ...
     MIXAL HELLO WORLD
     ... done
     Elapsed time: 11 /Total program time: 11 (Total uptime: 11)
     MIX >

Note that now the timing statistics are richer. You obtain the elapsed execution time (i.e., the time spent executing instructions since the last breakpoint), the total execution time for the program up to now (which in our case coincides with the elapsed time, since there were no breakpoints), and the total uptime for the virtual machine (you can load and run more than one program in the same session). After running the program, the program counter will point to the address after the one containing the HLT instruction. In our case, asking the value of the program counter after executing the program will give us

     MIX > pc
     Current address: 3002
     MIX >

You can check the contents of a memory cell giving its address as an argument of the command pmem, like this

     MIX > pmem 3001
     3001: + 00 00 00 02 05 (0000000133)
     MIX >

and convince yourself that address 3001 contains the binary representation of the instruction HLT. An address range of the form FROM-TO can also be used as the argument of pmem:

     MIX > pmem 3000-3006
     3000: + 46 58 00 19 37 (0786957541)
     3001: + 00 00 00 02 05 (0000000133)
     3002: + 14 09 27 01 13 (0237350989)
     3003: + 00 08 05 13 13 (0002118477)
     3004: + 16 00 26 16 19 (0268542995)
     3005: + 13 04 00 00 00 (0219152384)
     3006: + 00 00 00 00 00 (0000000000)
     MIX >

In a similar manner, you can look at the contents of the MIX registers and flags. For instance, to ask for the contents of the A register you can type

     MIX > preg A
     rA: + 00 00 00 00 00 (0000000000)
     MIX >

Use the comand help to obtain a list of all available commands, and help COMMAND for help on a specific command, e.g.

     MIX > help run
     run             Run loaded or given MIX code file. Usage: run [FILENAME]
     MIX >

For a complete list of commands available at the MIX propmt, see mixvm. In the following subsection, you will find a quick tour over commands useful for debugging your programs.

Debugging commands
------------------

The interactive mode of mixvm lets you step by step execution of programs as well as breakpoint setting. Use next to step through the program, running its instructions one by one. To run our two-instruction hello.mix sample you can do the following:

     MIX > load hello
     Program loaded. Start address: 3000
     MIX > pc
     Current address: 3000
     MIX > next
     MIXAL HELLO WORLD
     Elapsed time: 1 /Total program time: 1 (Total uptime: 1)
     MIX > pc
     Current address: 3001
     MIX > next
     End of program reached at address 3002
     Elapsed time: 10 /Total program time: 11 (Total uptime: 11)
     MIX > pc
     Current address: 3002
     MIX > next
     MIXAL HELLO WORLD
     Elapsed time: 1 /Total program time: 1 (Total uptime: 12)
     MIX >
     MIX > run
     Running ...
     ... done
     Elapsed time: 10 /Total program time: 11 (Total uptime: 22)
     MIX > example

     (As an aside, the above sample also shows how the virtual machine
     handles cummulative time statistics and automatic program restart).

     You can set a breakpoint at a given address using the command
     sbpa (set breakpoint at address). When a breakpoint is set,
     run will stop before executing the instruction at the given
     address. Typing run again will resume program execution. Coming
     back to our hello world example, we would have:

          MIX > sbpa 3001
          Breakpoint set at address 3001
          MIX > run
          Running ...
          MIXAL HELLO WORLD
          ... stopped: breakpoint at line 8 (address 3001)
          Elapsed time: 1 /Total program time: 1 (Total uptime: 23)
          MIX > run
          Running ...
          ... done
          Elapsed time: 10 /Total program time: 11 (Total uptime: 33)
          MIX >

     Note that, since we compiled hello.mixal with debug info enabled
     (the -g flag of mixasm), the virtual machine is able to
     tell us the line in the source file corresponding to the breakpoint we
     are setting. As a matter of fact, you can directly set breakpoints at
     source code lines using the command sbp LINE_NO, e.g.

          MIX > sbp 4
          Breakpoint set at line 7
          MIX >

     sbp sets the breakpoint at the first meaningful source code line;
     thus, in the above example we have requested a breakpoint at a line
     which does not correspond to a MIX instruction and the breakpoint is set
     at the first line containing a real instruction after the given one. To
     unset breakpoints, use cbpa ADDRESS and cbp LINE_NO, or
     cabp to remove all currently set breakpoints.

     MIXAL lets you define symbolic constants, either using the EQU
     pseudoinstruction or starting an instruction line with a label (which
     assigns to the label the value of the current memory address). Each
     MIXAL program has, therefore, an associated symbol table which you can
     inspect using the psym command. For our hello world sample, you
     will obtain the following output:

          MIX > psym
          START:  3000
          TERM:  19
          MSG:  3002
          MIX >

     Other useful commands for debugging are tron (which turns on
     tracing of executed intructions) and weval (which evaluates
     w-expressions on the fly). For a complete description of all available
     MIX commands, see mixvm.

mixvm, the MIX computer simulator
*********************************

This chapter describes mixvm, the MIX computer simulator. mixvm is a command line interface programme which simulates the MIX computer (see The MIX computer). It is able to run MIXAL programs (see MIXAL) previously compiled with the MIX assembler (see mixasm). The simulator allows inspection of the MIX computer components (registers, memory cells, comparison flag and overflow toggle), step by step execution of MIX programmes, and breakpoint setting to aid you in debugging your code. For a tutorial description of mixvm usage, see Running the program.

Invoking mixvm
==============

mixvm can be invoked with the following command line options (note, that, following GNU's conventions, we provide a long option name for each available single letter switch):

     mixvm [-vhurd] [--version] [--help] [--usage] [--run] [--dump]
           [FILE[.mix]]

The meaning of these options is as follows:

 -- User Option: -v
 -- User Option: --version
     Prints version and copyleft information and exits.

 -- User Option: -h
 -- User Option: --help
 -- User Option: -u
 -- User Option: --usage
     Prints a summary of available options and exits.

 -- User Option: -r
 -- User Option: --run
     Loads the specified FILE and executes it. After the program execution, mixvm exits. FILE must be the name of a binary .mix program compiled with mixasm. If your program does not produce any output, use the -d flag (see below) to peek at the virtual machine's state after execution.

 -- User Option: -d
 -- User Option: --dump
     This option must be used in conjuction with -r, and tells mixvm to print the value of the virtual machine's registers, comparison flag and overflow toggle after executing the program named FILE. See Non-interactive mode, for sample usage.

When run without the -r flag, mixvm enters its interactive mode, showing you a prompt like this one:

     MIX >

and waiting for your commands (see Commands). If the optional FILE argument is given, the file FILE.mix will be loaded into the virtual machine memory before entering the interactive mode.

Interactive commands
====================

You can enter the interactive mode of the MIX virtual machine by simply invoking mixvm without arguments. You will then presented a shell prompt

     MIX >

which indicates that a new virtual machine has been initialised and is ready to execute your commands. As we have already mentioned, this command prompt offers you command line editing facilities which are described in the Readline user's manual (chances are that you are already familiar with these command line editing capabilities, as they are present in many GNU utilities, e.g. the bash shell). As a beginner, your best friend will be the help command, which shows you a summary of all available MIX commands and their usage; its syntax is as follows:

 -- mixvm command: help [command]
 -- mixvm command: ? [command]
     Prints a short description of the given COMMAND and its usage. If COMMAND is omitted, all available commands are described.

File commands
-------------

You have at your disposal a series of commands that let you load and execute MIX executable files, as well as manipulate MIXAL source files:

 -- file command: load file[.mix]
     This command loads a binary file, FILE.MIX into the virtual machine memory, and positions the program counter at the beginning of the loaded program. This address is indicated in the MIXAL source file as the operand of the END pseudoinstruction. Thus, if your sample.mixal source file contains the line:

               END 3000

     and you compile it with mixasm to produce the binary file sample.mix, you will load it into the virtual machine as follows:

          MIX > load sample
          Program loaded. Start address: 3000
          MIX >

 -- file command: run [file[.mix]]
     When executed without argument, this command initiates or resumes execution of instructions from the current program counter address. Therefore, issuing this command after a successful load, will run the loaded program until either a HLT instruction or a breakpoint is found. If you provide a MIX filename as argument, the given file will be loaded (as with load FILE) and executed. If run is invoked again after program execution completion (i.e., after the HLT instruction has been found in a previous run), the program counter is repositioned and execution starts again from the beginning.

 -- file command: edit file[.mixal]
     The source file FILE.MIXAL is edited using the editor defined in the environment variable MDK_EDITOR. If this variable is not set, the following ones are tried out in order: X_EDITOR, EDITOR and VISUAL.

 -- file command: compile file[.mixal]
     The source file FILE.MIXAL is compiled (with debug information enabled) using mixasm.

Debug commands
--------------

Sequential execution of loaded programs can be interrupted using the following debug commands:

 -- debug command: next [ins_number]
     This command causes the virtual machine to fetch and execute  up to INS_NUMBER instructions, beginning from the current program counter position. Execution is interrupted either when the specified number of instructions have been fetched or a breakpoint is found, whatever happens first. If run without arguments, one instruction is executed.

 -- debug command: sbp line_number
     Sets a breakpoint at the specified source file line number. If the line specified corresponds to a command or to a MIXAL pseudoinstruction which does not produce a MIX instruction in the binary file (such as ORIG or EQU) the breakpoint is set at the first source code line giving rise to a MIX instruction after the specified one. Thus, for our sample hello.mixal file:

          *                                                        (1)
          * hello.mixal: say 'hello world' in MIXAL                (2)
          *                                                        (3)
          * label ins    operand     comment                       (4)
          TERM    EQU    19          the MIX console device number (5)
                  ORIG   1000        start address                 (6)
          START   OUT    MSG(TERM)   output data at address MSG    (7)
          ...

     trying to set a breakpoint at line 5, will produce the following result:

          MIX > sbp 5
          Breakpoint set at line 7
          MIX >

     since line 7 is the first one compiled into a MIX instruction (at address 3000). In order to sbp to work, the source file must be compiled using the -g flags, which tells mixasm to include debug information in the binary .mix file.

 -- debug command: spba address
     Sets a breakpoint at the given memory ADDRESS. The argument must be a valid MIX memory address, i.e., it must belong into the range [0-3999]. Note that no check is performed to verify that the specified address is reachable during program execution. No debug information is needed to set a breakpoint by address with sbpa.

 -- debug command: cbp line_no
     Clears a (previously set) breakpoint at the given source file line.

 -- debug command: cbpa address
     Clears a (previously set) breakpoint at the given memory address.

 -- debug command: cabp
     Clears all currently set breakpoints.

 -- debug command: psym [symbol_name]
     MIXAL programs can define symbolic constants, using either the EQU pseudoinstruction or a label at the beginning of a line. Thus, in the program fragment

          VAR     EQU  2168
                  ORIG 4000
          START   LDA  VAR

     the symbol VAR stands for the value 2168, while START is assigned the value 4000. When MIXAL programs are compiled using the -g flag (which tells mixasm to include debug information in the binary .mix file), the symbol table can be consulted from the mixvm command line using psym followed by the name of the symbol whose contents you are interested in. When run without arguments, psym will print all defined symbols and their values.

The virtual machine can also show you the instructions it is executing, using the following commands:

 -- debug command: tron
 -- troff:
     tron enables instruction tracing. When tracing is enabled, each time the virtual machine executes an instruction (due to your issuing a run or next command), it is printed in its canonical form (that is, with all expressions evaluated to their numerical values) and, if the program was compiled with debug information, as it was originally typed in the MIXAL source file. Instruction tracing is disable with the troff command. A typical tracing session could be like this:

          MIX > tron
          Instruction tracing has been turned ON.
          MIX > next
          3000: [OUT	3002,0(2:3)]	START	OUT	MSG(TERM)
          MIXAL HELLO WORLD
          Elapsed time: 1 /Total program time: 1 (Total uptime: 1)
          MIX > next
          3001: [HLT	0,0]		HLT
          End of program reached at address 3002
          Elapsed time: 10 /Total program time: 11 (Total uptime: 11)
          MIX > troff
          Instruction tracing has been turned OFF.
          MIX >

     The executed instruction, as it was translated, is shown between square brackets after the memory address, and, following it, you can see the actual MIXAL code that was compiled into the executed instruction.

mixvm is also able of evaluating w-expressions (see W-expressions) using the following command:

 -- debug command: weval WEXP
     Evaluates the given w-expression, WEXP. The w-expression can contain any currently defined symbol. For instance:

          MIX > psym START
          + 00 00 00 46 56 (0000003000)
          MIX > weval START(0:1),START(3:4)
          + 56 00 46 56 00 (0939716096)
          MIX >

New symbols can be defined using the ssym command:
 -- debug command: ssym SYM WEXP
     Defines the symbol named SYM with the value resulting from evaluating WEXP, an w-expression. The newly defined symbol can be used in subsequent weval commands, as part of the expression to be evaluated. E.g.,

          MIX > ssym S 2+23*START
          + 00 00 18 19 56 (0000075000)
          MIX > psym S
          + 00 00 18 19 56 (0000075000)
          MIX > weval S(3:4)
          + 00 00 19 56 00 (0000081408)
          MIX >

Finally, if you want to discover which is the decimal value of a MIX word expressed as five bytes plus sign, you can use

 -- debug command: w2d WORD
     Computes the decimal value of the given word. WORD must be expressed as a sign (+/-) followed by five space-delimited, two-digit decimal values representing the five bytes composing the word. The reverse operation (showing the word representation of a decimal value) can be accomplished with weval. For instance:

          MIX > w2d - 01 00 00 02 02
          -16777346
          MIX > weval -16777346
          - 01 00 00 02 02 (0016777346)
          MIX >

State commands
--------------

Inspection and modification of the virtual machine state (memory, registers, overflow toggle and comparison flag contents) is accomplished using the following commands:

 -- state command: pc
     Prints the current value of the program counter, which stores the address of the next instruction to be executed in a non-halted program.

 -- state command: preg [A | X | J | I[1-6]]
 -- state command: pall
 -- state command: sreg A | X | J | I[1-6] value
     preg prints the contents of a given MIX register. For instance, preg A will print the contents of the A-register. When invoked without arguments, all registers shall be printed:

          MIX > preg
          rA: - 00 00 00 00 35 (0000000035)
          rX: + 00 00 00 15 40 (0000001000)
          rJ: + 00 00 (0000)
          rI1: + 00 00 (0000)	rI2: + 00 00 (0000)
          rI3: + 00 00 (0000)	rI4: + 00 00 (0000)
          rI5: + 00 00 (0000)	rI6: + 00 00 (0000)
          MIX >

     As you can see in the above sample, the contents is printed as the sign plus the values of the MIX bytes stored in the register and, between parenthesis, the decimal representation of its module.

     pall prints the contents of all registers plus the comparison flag and overflow toggle.

     Finally, sreg Sets the contents of the given register to VALUE, expressed as a decimal constant. If VALUE exceeds the maximum value storable in the given register, VALUE mod MAXIMU_VALUE is stored, e.g.

          MIX > sreg I1 1000
          MIX > preg I1
          rI1: + 15 40 (1000)
          MIX > sreg I1 1000000
          MIX > preg I1
          rI1: + 09 00 (0576)
          MIX >

 -- state command: pflags
 -- state command: scmp E | G | L
 -- state command: sover F | T
     pflags prints the value of the comparison flag and overflow toggle of the virtual machine, e.g.

          MIX > pflags
          Overflow: F
          Cmp: E
          MIX >

     The values of the overflow toggle are either F (false) or T (true), and, for the comparison flag, E, G, L (equal, greater, lesser). scmp and sover are setters of the comparison flag and overflow toggle values.

 -- state command: pmem from[-to]
 -- state command: smem address value
     pmem prints the contents of memory cells in the address range [FROM-TO]. If the upper limit TO is omitted, only the contents of the memory cell with address FROM is printed, as in

          MIX > pmem 3000
          3000: + 46 58 00 19 37 (0786957541)
          MIX >

     The memory contents is displayed both as the set of five MIX bytes plus sign composing the stored MIX word and, between parenthesis, the decimal representation of the module of the stored value.

     smem sets the content of the memory cell with address ADDRESS to VALUE, expressed as a decimal constant.

Finally, you can use the quit command to exit mixvm.

MIX block devices
=================

The MIX computer comes equipped with a set of block devices for input-output operations (see Input-output operators). mixvm implements these block devices as disk files, with the exception of block device no. 19 (typewriter terminal) which is redirected to standard output. When you request an output operation on any other (output) device, a file named according to the following table will be created in the current directory, and the specified MIX words will be written to the file in binary form (for binary devices) or in ASCII (for char devices). Files corresponding to input block devices should be created and filled beforehand to be used by the MIX virtual machine (for input-output devices this creation can be accomplished by a MIXAL program writing to the device the required data, or, if you prefer, with your favourite editor).

Device    No.   filename   type
Tape   0-7   tape[0-7].dev   bin i/o
Disks   8-15   disk[0-7].dev   bin i/o
Card reader   16   cardrd.dev   char in
Card writer   17   cardwr.dev   char out
Line printer   18   printer.dev   char out
Terminal   19   stdout   char out
Paper tape   20   paper.dev   char out

mixasm, the MIXAL assembler
***************************

MIX programs, as executed by mixvm, are composed of binary instructions loaded into the virtual machine memory as MIX words. Although you could write your MIX programs directly as a series of words in binary format, you have at your disposal a more friendly assembly language, MIXAL (see MIXAL) which is compiled into binary form by mixasm, the MIXAL assembler included in MDK. In this chapter, you will find a complete description of mixasm options.

Invoking mixasm
===============

In its simplest form, mixasm is invoked with a single argument, which is the name of the MIXAL file to be compiled, e.g.

     mixasm hello

will compile either hello or hello.mixal, producing a binary file named hello.mix if no errors are found.

In addition, mixasm can be invoked with the following command line options (note, that, following GNU's conventions, we provide a long option name for each available single letter switch):

     mixasm [-vhulg] [-o OUTPUT_FILE] [--version] [--help]
            [--usage] [--debug] [--output=OUTPUT_FILE] [--list[=LIST_FILE]] file

The meaning of these options is as follows:

 -- User Option: -v
 -- User Option: --version
     Prints version and copyleft information and exits.

 -- User Option: -h
 -- User Option: --help
 -- User Option: -u
 -- User Option: --usage
     Prints a summary of available options and exits.

 -- User Option: -g
 -- User Option: --debug
     Includes debugging information in the compiled file, allowing breakpoint setting at source level and symbol table inspection under mixvm.

 -- User Option: -o output_file
 -- User Option: --output=output_file
     By default, the given source file FILE.MIXAL is compiled into FILE.MIX. You can provide a different name for the output file using this option.

 -- User Option: -l
 -- User Option: --list[=list_file]
     This option causes mixasm to produce, in addion to the .mix file, an ASCII file containing a summary of the compilation results. The file is named after the MIXAL source file, changing its extension to .mls if no argument is provided; otherwise, the listing file is named according to the argument.

Copying
*******

     [file gpl.texi not included]

Reporting Bugs
**************

If you find a bug in MDK (or have questions, comments or suggestions about it), please send electronic mail to the author.

In your report, please include the version number, which you can find by running mixasm --version.  Also include in your message the output that the program produced and the output you expected.