MIX Assembler and Simulator	Sergey Poznyakoff, Douglas Laing

• Main
• Downloads
• Installation
• Documentation
• Debugging

MIX Manual (split by chapter):

Section:

Chapter:

Doc:

?

2. mixal – MIX Assembler.

A MIX assembler is called mixal. The utility assembles its standard input (or a named file), which should be a valid MIXAL program, and writes the resulting object code to the standard output or to another file.

This chapter describes how to use mixal. The examples in this chapter assume that the file ‘hello.mix’ contains the following example program:

* ``HELLO, WORLD'' PROGRAM
PRINTER EQU  18
        ORIG 3000
HELLO   OUT  TEXT(PRINTER)
        JBUS *(PRINTER)
        HLT
TEXT    ALF  HELLO
        ALF  , WOR
        ALF  LD
        END  HELLO  

2.1 Assembling MIXAL Programs.

The simplest way to assemble a MIXAL program is to give it as an argument to mixal:

$ mixal hello.mix

The mixal utility assembles the program, and prints the resulting object code on the standard output. The object code is formatted as a card deck, as described in TAOCP, 1.3.1, p.141, ex. 26, therefore in this book we use the terms object file and deck file as synonyms.

Each line in the deck file corresponds to a single punch card. First two cards are always the same — they contain a loader routine, responsible for loading of the entire deck into MIX memory and passing control to the program entry point. The following lines, up to the last one, contain the program code, formatted as described in the following table:

For example, the card:

HELLO63000078721962107866953300000000133013558254406879733950219152384

contains 6 words to be loaded starting from address 3000. These words are:

The deck ends with a special transfer card, which contains information in format ‘TRANS0nnnn’, where nnnn is the address of the program entry point. For example, ‘TRANS03000’ means “start execution from address 3000”.

To illustrate this, here is the deck file produced for ‘hello.mix’ (the first two cards are omitted):

HELLO63000078721962107866953300000000133013558254406879733950219152384
TRANS03000

The card deck, produced by mixal can be executed by the MIX simulator, as described in mixsim – MIX Simulator.. In the simplest case, you can directly feed the deck to the standard input of mixsim:

$ mixal hello.mix | mixsim

However, for more complex programs, it is common to store the produced card deck in a file for further use by mixsim. To do so, use ‘--output’ (‘-o’) command line option, as shown in the example below:

$ mixal --output=hello.deck hello.mix

2.2 Program Listing

To obtain more details about the generated object deck, use ‘--list’ (‘-l’) command line option. This option generates a listing file. The file name for this file is constructed by appending ‘.lst’ suffix to the base name of the input file. For example, the following invocation will store the program listing in file ‘hello.lst’.

$ mixal -l hello.mix

If explicit input file is not given, e.g. when assembling the standard input, the listing is named ‘mixal.lst’.

These naming conventions can be overridden, by specifying the listing name explicitly, with ‘--list-file’ option. This option implies ‘--list’, so you need not give the two options together. For example, the following invocation will store the listing in file ‘out/hello.list’:

$ mixal --list-file=out/hello.list hello.mix

The program listing contains, for each line of the input source, the address of the corresponding MIX cell and the assembled cell contents, as shown in the table below:

The cell contents (columns 7–21) is formatted as described in TAOCP, 1.3.1, p.124, Instruction format:

The following example shows mixal listing for the ‘hello.mix’ program:

                          1 * ``HELLO, WORLD'' PROGRAM
                          2 PRINTER    EQU  18
                          3            ORIG 3000
3000: + 3003  0 18 37     4 HELLO      OUT  TEXT(PRINTER)
3001: + 3001  0 18 34     5            JBUS *(PRINTER)
3002: +    0  0  2  5     6            HLT  
3003: +  517 13 13 16     7 TEXT       ALF  HELLO
3004: + 2624 26 16 19     8            ALF  , WOR
3005: +  836  0  0  0     9            ALF  LD   
                         10            END  HELLO

After the listing comes a symbol table, which, for each symbol used in the program, shows its name, location and a source line, where it was defined. For example:

Symbol     Value  Line  
PRINTER       18    2   
HELLO       3000    4   
TEXT        3003    7   

The ‘Value’ column contains a MIX location, corresponding to that symbol, except in case of macro-definitions (EQU), where the actual value of the macro is printed (see ‘PRINTER’ in the example above).

The symbol table contains not only user-defined symbols, but also any literals and local labels used in the program. For literals, the ‘Symbol’ column contains their computed w-expressions, surrounded by equals sings. For example, the line

        MUL  =2*25+1=

will produce the symbol name ‘=51=’, e.g.:

Symbol     Value  Line  
=51=        1101   18

Local labels are displayed as two integer numbers, separated by a dash and surrounded by vertical bars (‘|’). The first number corresponds to the number of the local label, the second one means its ordinal number in the program text. For example, the MIXAL fragment below:

1H      INCX 0
        DECA 11
        JANP 1B
1H      INCX 1

will produce the following two entries in the symbol table:

Symbol     Value  Line  
|1-1|       1026    7
|1-2|       1029   10

An additional statistics about the input source can be obtained using ‘--xref’ (‘-x’) option, which instructs mixal to print a cross-reference table of all used symbols. A cross-reference table is added as an additional column to the symbol table, described above. The contents of this column lists the lines where the symbol was referenced. The following example shows a cross-reference table for the ‘hello.mix’ program:

Symbol     Value  Line  Referenced on line
PRINTER       18    2    4    5
HELLO       3000    4   10
TEXT        3003    7    4

If ‘--xref’ is used without ‘--list’ (or ‘--list-file’), the symbol table is printed on the standard error.

2.3 Raw Object Code.

Sometimes you may need to assemble a MIXAL program into a raw sequence of bytes, without composing a proper load deck. In particular, this becomes necessary if you wish to develop your own loading routine. The ‘--raw-output’ (‘-r’) allows you to do that. When called with this option, mixal outputs assembled code as is, without converting it to object card format and without prefixing it with loader routine. Currently this option assumes that the produced code will be read using device 16 (card reader), so the output byte stream is formatted in blocks of 16 words (80 bytes) delimited by newlines.

A particularly interesting implementation of this feature would be to produce a loader code for another type of input device, e.g. to load programs from magnetic tapes or disks. This, however, requires some further work on mixsim and will be implemented in future versions of the package.

2.4 mixal option summary.

Usage:
mixal [options] [file]

The following table summarizes the available command line options:

‘--list’

‘-l’

Produce a source listing. Unless ‘--list-file’ (see below) is used, the default listing file name is constructed by appending ‘.lst’ suffix to the base name of the input file. If standard input is used, the listing file is named ‘mixal.lst’.

See section Program Listing.

‘--list-file=file’

Set listing file name. Implies ‘--list’.

See mixal-list-file.

‘--force’

‘-f’

Force generating object deck (and, eventually, listing) even if there were errors during assembly.

‘--output=file’

‘-o’

Set output file name. By default, object deck is printed on the standard output.

See mixal-output.

‘--raw-output’

‘-r’

Produce raw object output.

See section Raw Object Code..

‘--xref’

‘--cross-reference’

‘-x’

Output a cross reference.

See mixal-xref.

‘--debug-gram’

Enable parser debugging output.

‘--debug-lex’

Enable lexical analyzer debugging output.

‘-d level’

Set debug level. This option is for compatibility with previous versions. The ‘-dy’ option is equivalent to ‘--debug-gram’, ‘-dl’ is equivalent to ‘--debug-lex’, ‘-dyl’ (or ‘-dly’) is equivalent to both.

‘--help’

‘-h’

Print a concise help summary.

‘--version’

‘-V’

Print program version and license information.

?