path: root/doc/mdk.texi

\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename mdk.info
@settitle MIX Development Kit (mdk)
@finalout
@setchapternewpage odd
@c %**end of header

@include version.texi
@set JAO Jos@'e Antonio Ortega Ruiz
@footnotestyle separate

@ifinfo
This file documents the the @sc{mdk} utilities for developing
programs using Donald Knuth's MIX language.

Copyright (C) 2000 @value{JAO}

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.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
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.
@end ifinfo

@titlepage
@title MDK
@subtitle MIX Development Kit
@subtitle Edition @value{EDITION}, for @sc{mdk} Version @value{VERSION}
@subtitle @value{UPDATED}
@author by @value{JAO}

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 2000 @value{JAO}

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.
@end titlepage

@node Top, Introduction, (dir), (dir)

@ifinfo
This file documents the @sc{mdk} utilities to develop programs
using Donald Knuth's MIXAL language.  MIXAL is an assembler-like
language for writing programs for the (virtual) MIX computer. They are
described in the first volume of @cite{The Art of Computer Programming}
by D. Knuth (Addison Wesley, 1997), and used throughout the (up to now)
three published volumes.

@sc{mdk} was written by @value{JAO} and is released under the GNU
General Public license (@pxref{Copying}), so that users are free to share
and change it.

@end ifinfo

@menu
* Introduction::                
* MIX and MIXAL overview::      Quick tutorial of Knuth's MIX computer.
* Getting started::             Basic usage of the @sc{mdk} tools.
* mixvm::                       Invoking the MIX virtual machine.
* mixasm::                      Invoking the MIXAL assembler.
* Copying::                     @sc{mdk} licensing terms.
* Problems::                    Reporting bugs.
* Concept Index::               Index of concepts.

@detailmenu
 --- The Detailed Node Listing ---

MIX and MIXAL overview

* The MIX computer::            Architecture and instruction set 
                                of the MIX computer.
* MIXAL::                       The MIX assembly language.

The MIX computer

* MIX architecture::            
* MIX instruction set::         

MIX instruction set

* Loading operators::           
* Storing operators::           
* Arithmetic operators::        
* Address transfer operators::  
* Comparison operators::        
* Jump operators::              
* Miscellaneous operators::     
* Input-output operators::      
* Conversion operators::        

MIXAL

* Instructions::                
* Comments::                    
* Expressions::                 
* Local symbols::               
* Miscellaneous::               

Getting started

* Writing a source file::       A sample MIXAL source file.
* Compiling::                   Using @code{mixasm} to compile source
                                files into binary format.
* Running the program::         Running and debugging your program.

Running the program

* Non-interactive mode::        Running your programs non-interactively.
* Interactive mode::            Running programs interactively.
* Debugging::                   Commands for debugging your programs.

@code{mixvm}, the MIX computer simulator

* Invocation::                  Options when invoking @code{mixvm}.
* Commands::                    Commands available in interactive mode.
* Devices::                     MIX block devices implementation.

@code{mixasm}, the MIXAL assembler

* Invoking @code{mixasm}::      @code{mixasm} options

@end detailmenu
@end menu

@node Introduction, MIX and MIXAL overview, Top, Top
@comment  node-name,  next,  previous,  up
@unnumbered Introduction
@cindex Introduction

In his book series @cite{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
CSIC CPUs, and the MIX assembly language 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 read
and learn from Knuth excellent books on computer programming, a MIX
development environment would come in handy.

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

@table @code
@item mixvm
MIX virtual machine. Emulation of the MIX computer.
@item mixasm
MIXAL assembler. Assembler which translates MIXAL source files into
programs that can be run (and debugged) by @code{mixvm}.
@end table 

@code{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 @code{mixasm}.

This manual gives you a brief survey of MIX and MIXAL, and a thorough
description of the use of the @sc{mdk} utilities.



@node MIX and MIXAL overview, Getting started, Introduction, Top
@comment  node-name,  next,  previous,  up
@chapter MIX and MIXAL overview
@cindex MIX
@cindex MIXAL

In the book series @cite{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, in the example
programs and exercises. 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. The MIX computer architecture and
the MIXAL language are defined in volume 1 of the series,
@cite{Fundamental Algorithms}. In the following subsections you will
find a brief survey of these topics, which is not meant to replace the
precise description given in the book (if you are interested in using
the @sc{mdk} utilities, most probably the reason is that you have access
to a copy of TAOCP), but to serve as a quick reminder of key points and
nomenclature used in the rest of this manual.

@menu
* The MIX computer::            Architecture and instruction set 
                                of the MIX computer.
* MIXAL::                       The MIX assembly language.
@end menu

@node The MIX computer, MIXAL, MIX and MIXAL overview, MIX and MIXAL overview
@comment  node-name,  next,  previous,  up
@section The MIX computer

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

@menu
* MIX architecture::            
* MIX instruction set::         
@end menu

@node MIX architecture, MIX instruction set, The MIX computer, The MIX computer
@comment  node-name,  next,  previous,  up
@subsection MIX architecture
@cindex byte
@cindex MIX byte
@cindex word
@cindex MIX word
@cindex MIX architecture
@cindex MIX computer
@cindex register
@cindex MIX register
@cindex field specification
@cindex fspec
@cindex instruction
@cindex MIX instruction
@cindex address
@cindex memory cell
@cindex cell
@cindex memory
@cindex index

The basic information storage unit in the MIX computer is the
@dfn{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 @emph{regular} byte. Unless otherwise stated, we shall use the
word @dfn{byte} to refer to a MIX 6-bit byte.

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

@example
 -----------------------------------------------
|   0   |   1   |   2   |   3   |   4   |   5   |
 -----------------------------------------------
|  +/-  | byte  | byte  | byte  | byte  | byte  |     
 -----------------------------------------------
@end example

You can refer to subfields within a word using a
@dfn{field specification} or @dfn{fspec} of the form @samp{(L:R)}, where
@samp{L} denotes the first byte and @samp{R} the last byte of the
subfield. When @samp{L} is zero, the subfield includes the word's
sign. An fspec can be also represented as a single value @samp{F}, given
by @code{F = 8*L + R}.

The MIX computer stores information in @dfn{registers}, that can store
either a word or two bytes and sign (see below), and @dfn{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:

@table @samp
@item rA
A register. General purpose register holding a word. Usually its
contents serves as operator for arithmetic and storing instructions.
@item rX
X register. General purpose register holding a word. Often it acts as an
extension or a replacement of @samp{rA}.
@item rJ
J (jump) register. This register stores positive two-byte values,
usually representing a jump address.
@item 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
an effective memory address.
@end table

@cindex @sc{ov}
@cindex @sc{cm}
@cindex @samp{Un}
@cindex overflow toggle
@cindex comparison indicator
@cindex input-output devices
@noindent
In addition, the MIX computer contains:

@itemize @minus
@item
An @dfn{overflow toggle} (a single bit with values @dfn{on} or
@dfn{off}). In this manual, this toggle is denoted @sc{ov}.
@item
A @dfn{comparison indicator} (having three values: @dfn{EQUAL},
@dfn{GREATER} or @dfn{LESS}). In this manual, this indicator is denoted
@sc{cm}.
@item
Input-output devices. Each device is labelled as @samp{Un}, where
@samp{n} runs from 0 to 19@footnote{@samp{U0-7} are magnetic tape units,
@samp{U8-15} are disks and drums, @samp{U16} is a card reader,
@samp{U17} is a card writer, @samp{U18} is a line printer and
@samp{U19}, a paper tape.}.
@end itemize

MIX @dfn{instructions} are codified as words with the following subfield
structure:

@multitable @columnfractions .15 .20 .65
@item @emph{Subfield} @tab @emph{fspec} @tab @emph{Description}

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

@noindent
or, graphically,

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

The MIX computer understands a quite complete set of instructions
commonly found in real computers, including arithmetic, logical,
storing, comparison and jump instructions. We refer the reader to
D. Knuth's TAOCP (volume 1, section 1.3.1) for a complete description of
these instructions. @xref{MIX instruction set}, gives a quick synopsis
of the available instructions.

@node MIX instruction set,  , MIX architecture, The MIX computer
@comment  node-name,  next,  previous,  up
@subsection MIX instruction set
@cindex instruction set

The following subsections summarize the instruction set of the MIX
computer. In this description @samp{M} stands for
the memory address obtained after indexing the ADDRESS subfield of the
instruction (using its INDEX byte), and @samp{V} is the contents of the
subfield indicated by MOD of the memory cell with address @samp{M}.

@menu
* Loading operators::           
* Storing operators::           
* Arithmetic operators::        
* Address transfer operators::  
* Comparison operators::        
* Jump operators::              
* Miscellaneous operators::     
* Input-output operators::      
* Conversion operators::        
@end menu

@node Loading operators, Storing operators, MIX instruction set, MIX instruction set
@comment  node-name,  next,  previous,  up
@subsubsection Loading operators
@cindex loading operators

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

@ftable @code
@item LDA
Load rA. OPCODE = 8, MOD = fspec. @code{rA <- V}.
@item LDX
Load rX. OPCODE = 15, MOD = fspec. @code{rX <- V}.
@item LDi
Load rIi. OPCODE = 8 + i, MOD = fspec. @code{rIi <- V}.
@item LDAN
Load rA negative. OPCODE = 16, MOD = fspec. @code{rA <- -V}.
@item LDXN
Load rX negative. OPCODE = 23, MOD = fspec. @code{rX <- -V}.
@item LDiN
Load rIi negative. OPCODE = 16 + i, MOD = fspec. @code{rIi <- -V}.
@end ftable


@node Storing operators, Arithmetic operators, Loading operators, MIX instruction set
@comment  node-name,  next,  previous,  up
@subsubsection Storing operators
@cindex storing operators

The following instructions are used to store a subfield of a register
into a memory location.

@ftable @code
@item STA
Store rA. OPCODE = 24, MOD = fspec. @code{V <- rA}.
@item STX
Store rX. OPCODE = 31, MOD = fspec. @code{V <- rX}.
@item STi
Store rIi. OPCODE = 24 + i, MOD = fspec. @code{V <- rIi}.
@item STJ
Store rJ. OPCODE = 32, MOD = fspec. @code{V <- rJ}.
@item STZ
Store zero. OPCODE = 33, MOD = fspec. @code{V <- 0}.
@end ftable


@node Arithmetic operators, Address transfer operators, Storing operators, MIX instruction set
@comment  node-name,  next,  previous,  up
@subsubsection Arithmetic operators
@cindex arithmetic operators

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

@ftable @code
@item ADD
Add and set OV if overflow. OPCODE = 1, MOD = fspec. 
@code{rA <- rA +V}.
@item SUB
Sub and set OV if overflow. OPCODE = 2, MOD = fspec.
@code{rA <- rA - V}.
@item MUL
Multiply V times rA and store the 10-bytes product in rAX.
OPCODE = 3, MOD = fspec. @code{rAX <- rA x V}.
@item DIV
rAX is considered a 10-bytes number, and it is divided by V.
OPCODE = 4, MOD = fspec. @code{rA <- rAX / V}, @code{rX} <- reminder.
@end ftable

@node Address transfer operators, Comparison operators, Arithmetic operators, MIX instruction set
@comment  node-name,  next,  previous,  up
@subsubsection Address transfer operators
@cindex 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.

@ftable @code
@item ENTA
Enter rA. OPCODE = 48, MOD = 2. @code{rA <- M}.
@item ENTX
Enter rX. OPCODE = 55, MOD = 2. @code{rX <- M}.
@item ENTi
Enter rIi. OPCODE = 48 + i, MOD = 2. @code{rIi <- M}.
@item ENNA
Enter negative rA. OPCODE = 48, MOD = 3. @code{rA <- -M}.
@item ENNX
Enter negative rX. OPCODE = 55, MOD = 3. @code{rX <- -M}.
@item ENNi
Enter negative rIi. OPCODE = 48 + i, MOD = 3. @code{rIi <- -M}.
@item INCA
Increase rA. OPCODE = 48, MOD = 0. @code{rA <- rA + M}.
@item INCX
Increase rX. OPCODE = 55, MOD = 0. @code{rX <- rX + M}.
@item INCi
Increase rIi. OPCODE = 48 + i, MOD = 0. @code{rIi <- rIi + M}.
@item DECA
Decrease rA. OPCODE = 48, MOD = 1. @code{rA <- rA - M}.
@item DECX
Decrease rX. OPCODE = 55, MOD = 0. @code{rX <- rX - M}.
@item DECi
Decrease rIi. OPCODE = 48 + i, MOD = 0. @code{rIi <- rIi - M}.
@end ftable


@node Comparison operators, Jump operators, Address transfer operators, MIX instruction set
@comment  node-name,  next,  previous,  up
@subsubsection Comparison operators
@cindex comparison operators

The following instructions compare the value of a register with V, and
set the CM indicator to the result of the comparison.

@ftable @code
@item CMPA
Compare rA with V. OPCODE = 56, MOD = fspec.
@item CMPX
Compare rX with V. OPCODE = 63, MOD = fspec.
@item CMPi
Compare rIi with V. OPCODE = 56 + i, MOD = fspec.
@end ftable

@node Jump operators, Miscellaneous operators, Comparison operators, MIX instruction set
@comment  node-name,  next,  previous,  up
@subsubsection Jump operators
@cindex jump operators

The following instructions provoke jumps by setting the program
counter (address of the next instruction to fetch) to M (if a condition
is met). If a jump 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 @code{JSJ}).

@ftable @code
@item JMP
Unconditional jump. OPCODE = 39, MOD = 0.
@item JSJ
Unconditional jump, but rJ is not modified. OPCODE = 39, MOD = 1.
@item JOV
Jump if OV is set (and turn it off). OPCODE = 39, MOD = 2.
@item JNOV
Jump if OV is not set (and turn it off). OPCODE = 39, MOD = 3.
@item JL
@itemx JE
@itemx JG
@itemx JGE
@itemx JNE
@itemx JLE
Jump according to the value of CM. OPCODE = 39, MOD = 4, 5, 6, 7, 8, 9.
@item JAN
@itemx JAZ
@itemx JAP
@itemx JANN
@itemx JANZ
@itemx 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.
@item JXN
@itemx JXZ
@itemx JXP
@itemx JXNN
@itemx JXNZ
@itemx 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.
@item JiN
@itemx JiZ
@itemx JiP
@itemx JiNN
@itemx JiNZ
@itemx 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.
@end ftable

@node Miscellaneous operators, Input-output operators, Jump operators, MIX instruction set
@comment  node-name,  next,  previous,  up
@subsubsection Miscellaneous operators
@cindex miscellaneous operators

@ftable @code
@item SLA
@itemx SRA
@itemx SLAX
@itemx SRAX
@itemx SLC
@itemx 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.
@item MOVE
Move MOD words from M to the location stored in rI1.
OPCODE = 7, MOD = no. of bytes.
@item NOP
No operation. OPCODE = 0, MOD = 0.
@item HLT
Halt. Stops instruction fetching. OPCODE = 5, MOD = 2.
@end ftable

@node Input-output operators, Conversion operators, Miscellaneous operators, MIX instruction set
@comment  node-name,  next,  previous,  up
@subsubsection Input-output operators
@cindex input-output operators

The following instructions perform input-output operations. 

@ftable @code
@item IN
Transfer a block of words from the specified unit to memory, starting at
address M.
OPCODE = 36, MOD = I/O unit.
@item OUT
Transfer a block of words from memory (starting at address M) to the
specified unit.
OPCODE = 37, MOD = I/O unit.
@item IOC
Perfom a control operation (given by M) on the specified unit.
OPCODE = 35, MOD = I/O unit.
@item JRED
Jump to M if the specified unit is ready.
OPCODE = 38, MOD = I/O unit.
@item JBUS
Jump to M if the specified unit is busy.
OPCODE = 34, MOD = I/O unit.
@end ftable

@node Conversion operators,  , Input-output operators, MIX instruction set
@comment  node-name,  next,  previous,  up
@subsubsection Conversion operators
@cindex conversion operators

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

@ftable @code
@item 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.
@item CHAR
Convert the number stored in rA to a character representation and store
it in rAX.
OPCODE = 5, MOD = 1.
@end ftable

@node MIXAL,  , The MIX computer, MIX and MIXAL overview
@comment  node-name,  next,  previous,  up
@section MIXAL
@cindex MIXAL
@cindex MIX assembly language
@cindex assembly

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 is
fully described in volume 1 of D. Knuth's TAOCP. This section is not
meant as a replacement of the book's description, but as a brief survey
of MIXAL.

@menu
* Instructions::                
* Comments::                    
* Expressions::                 
* Local symbols::               
* Miscellaneous::               
@end menu

@node Instructions, Comments, MIXAL, MIXAL
@comment  node-name,  next,  previous,  up
@subsection Instructions
@cindex MIXAL instructions
@cindex instructions
@cindex instruction parts

MIX instructions are written in MIXAL according to the following
pattern:

@example
[LABEL]   OPCODE  [OPERAND]   [COMMENT]
@end example

@noindent
where @samp{OPERAND} is of the form

@example
[ADDRESS][,INDEX][(MOD)]
@end example

Items between square brackets are optional, and

@table @code
@item LABEL
Is an alphanumeric identifier (a @dfn{symbol}) which gets the value of
the current compilation address, and can be used in subsequent
expressions.
@item OPCODE
Is a literal denoting the operation code of the instruction
(e.g. @code{LDA}, @code{STA}) or an assembly pseudoinstruction
(e.g. @code{ORG}, @code{EQU}).
@item ADDRESS
Expression evaluating to the address subfield of the instruction.
@item 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 
@code{ADDRESS} is present.
@item MOD
Expression evaluating to the mod subfield of the instruction. Its
default value, when omitted, depends on @code{OPCODE}.
@item 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
@samp{OPERAND} field).
@end table

Note that spaces are @emph{not} allowed between the @code{ADDRESS},
@code{INDEX} and @code{MOD} fields if they are present. White space is
used to separate the label, operation code and operand parts of the
instruction@footnote{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 @sc{mdk}, @code{mixasm}, does not impose
such restriction.}.

MIXAL instructions can be either one of the MIX machine instructions
(@pxref{MIX instruction set}) or one of the following assembly
pseudoinstructions:

@ftable @code
@item ORIG
Sets the value of the memory address to which following instructions
will be allocated after compilation.
@item EQU
Used to define a symbol's value, e.g. @w{@code{SYM  EQU  2*200/3}}.
@item CON
The value of the given expression is copied directly into the current
memory address.
@item ALF
Takes as operand five characters, constituting the five bytes of a word
which is copied directly into the current memory address.
@item END
Marks the end of the program. Its operand gives the start address for
program execution.
@end ftable

Sample MIXAL instructions are

@example
HERE     LDA  2000
         LDX  HERE,2(1:3)  this is a comment
         JMP  1234
NEXT     STA  HERE*2(8)
         ORG  4000
VALUE    EQU  NEXT+HERE//2
@end example

@node Comments, Expressions, Instructions, MIXAL
@comment  node-name,  next,  previous,  up
@subsection Comments
@cindex comments

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

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

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

@example
LABEL     LDA   100  This is also a comment
@end example

@node Expressions, Local symbols, Comments, MIXAL
@comment  node-name,  next,  previous,  up
@subsection Expressions
@cindex operator
@cindex binary operator
@cindex unary operator
The @code{ADDRESS}, @code{INDEX} and @code{MOD} fields of a MIXAL
instruction can be expressions, formed by numbers, identifiers and
binary operators (@code{+ - * / // :}). @code{+} and @code{-} 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,

@example
     4+2**
@end example

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

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

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

@node Local symbols, Miscellaneous, Expressions, MIXAL
@comment  node-name,  next,  previous,  up
@subsection Local symbols
@cindex local symbols

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

@example
* 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
@end example

@node Miscellaneous,  , Local symbols, MIXAL
@comment  node-name,  next,  previous,  up
@subsection Miscellaneous
@cindex literal constants

MIXAL allows the introduction of @dfn{literal constants}, which are
automatically stored in memory addresses after the end of the program by
the assembler. Literal constants are denoted as @code{=exp=}, where
@code{exp} is an expression. For instance, the code

@example
L         EQU   10
          LDA   =20-L=
@end example

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

@example
L         EQU  10
          LDA  a
@dots{}
a         CON  20-L    
          END  start
@end example


@node Getting started, mixvm, MIX and MIXAL overview, Top
@comment  node-name,  next,  previous,  up
@chapter Getting started

In this chapter, you will find a sample code-compile-run-debug session
using the @sc{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 @ref{MIX and MIXAL overview}. 

@menu
* Writing a source file::       A sample MIXAL source file.
* Compiling::                   Using @code{mixasm} to compile source
                                files into binary format.
* Running the program::         Running and debugging your program.
@end menu

@node Writing a source file, Compiling, Getting started, Getting started
@comment  node-name,  next,  previous,  up
@section Writing a source file
@cindex MIXAL
@cindex source file

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

@example
*                                                        (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)
@end example
         
@noindent MIXAL source files should have the extension @file{.mixal}
when used with the @sc{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 @sc{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:

@itemize @minus
@item
an optional label, which either refers to the current memory address (as
@code{START} and @code{MSG} in lines 7 and 9) or a defined symbol
(@code{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),
@item
an operation mnemonic, which can represent either a MIX instruction
(@code{OUT} and @code{HLT} in lines 6 and 7 above), or an assembly
pseudoinstruction.
@item
an optional operand for the (pseudo)instruction, and
@item
an optional free text comment.
@end itemize

@noindent Lines 9-12 of the @file{hello.mixal} file above also show the
second (and last) difference between Knuth's MIXAL definition and ours:
the operand of the @code{ALF} pseudoinstruction (a word of five
characters) must be quoted with using ""@footnote{In Knuth's definition,
the operand always starts at a fixed column number, and the use of
quotation is therefore unnecessary. As @code{mixasm} releases this
requirement, marking the beginning and end of the @code{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
@ref{MIX and MIXAL overview}, for a quick tutorial.

@node Compiling, Running the program, Writing a source file, Getting started
@comment  node-name,  next,  previous,  up
@section Compiling
@cindex compiling
@cindex binary programs
@cindex virtual machine
@cindex assembler
@cindex @code{mixasm}

A simulator of the MIX computer, called @code{mixvm} (MIX virtual
machine) is included in the @sc{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 @code{mixasm}, the MIXAL assembler. So, in order to compile
the @file{hello.mixal} file, you can type the following 
command at your shell prompt:

@example
mixasm -g hello @key{RET}
@end example

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


@node Running the program,  , Compiling, Getting started
@comment  node-name,  next,  previous,  up
@section Running the program
@cindex @code{mixvm}
@cindex non-interactive mode
@cindex interactive mode

MIX is a mythical computer, so it is no use ordering it from your
favorite hardware provider. @sc{mdk} provides a software simulator of
the computer, though. It is called @code{mixvm}, which stands for
@dfn{MIX virtual machine}. Using it, you can run your MIXAL programs,
after compiling them with @code{mixasm} into binary @file{.mix}
files. @code{mixvm} can be used either in @dfn{interactive} or
@dfn{non-interactive} mode. In the second case, @code{mixvm} will load
your program into memory, execute it (producing any output due to MIXAL
@code{OUT} instructions present in the program), and exit when it
encounters a @code{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).

@menu
* Non-interactive mode::        Running your programs non-interactively.
* Interactive mode::            Running programs interactively.
* Debugging::                   Commands for debugging your programs.
@end menu

@node Non-interactive mode, Interactive mode, Running the program, Running the program
@comment  node-name,  next,  previous,  up
@subsection Non-interactive mode
@cindex non-interactive mode

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

@example
mixvm -r hello @key{RET}
@end example

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

@example
MIXAL HELLO WORLD
@end example

@noindent Since our hello world program uses MIX's device number 19 as
its output device (@pxref{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.), @code{mixvm} would
have created a file named after the device used (e.g. @file{disk4.dev})
and written its output there.

Sometimes, you will prefer to store the results of your program in MIX
registers rather than writing them to a device. In such cases,
@code{mixvm}'s @code{-d} flag is your friend: it makes @code{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

@example
mixvm -d -r hello
@end example

@noindent you will obtain the following output:

@example
MIXAL HELLO WORLD
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
@end example

@noindent which, in addition to the program's outputs, 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.

@node Interactive mode, Debugging, Non-interactive mode, Running the program
@comment  node-name,  next,  previous,  up
@subsection Interactive mode
@cindex interactive mode

To enter the MIX virtual machine interactive mode, simply type

@example
mixvm @key{RET}
@end example

@noindent at your shell command prompt. This command enters the
@code{mixvm} command shell. You will be presented the following command
prompt:

@example
MIX >
@end example

@noindent The virtual machine is initialised and ready to accept your
commands. The @code{mixvm} command shell uses GNU's readline, so that
you have at your disposal command completion (using @key{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 @ref{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 @code{load} command,
which takes as an argument the name of the @file{.mix} file to be
loaded. Thus, typing

@example
MIX > load hello @key{RET}
Program loaded. Start address: 3000
MIX >
@end example

@noindent will load @file{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
@code{pc}:

@example
MIX > pc
Current address: 3000
MIX >
@end example

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

@example
MIX > run
Running ...
MIXAL HELLO WORLD                                                     
... done
MIX > 
@end example

@noindent After running the program, the program counter will point to
the address after the one containing the @code{HLT} instruction. In our
case, asking the value of the program counter after executing the
program will give us

@example
MIX > pc
Current address: 3002
MIX >
@end example

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

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

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

@example
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 >
@end example

@noindent
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

@example
MIX > preg A
rA: + 00 00 00 00 00 (0000000000)
MIX >
@end example

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

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

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

@node Debugging,  , Interactive mode, Running the program
@comment  node-name,  next,  previous,  up
@subsection Debugging commands

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

@example
MIX > load hello
Program loaded. Start address: 3000
MIX > pc
Current address: 3000
MIX > next
MIXAL HELLO WORLD                                                     
MIX > pc
Current address: 3001
MIX > next
MIX > pc
Current address: 3002
MIX > next
End of program reached at address 3002
MIX > 
@end example

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

@example
MIX > sbpa 3001
Breakpoint set at address 3001
MIX > run
Running ...
MIXAL HELLO WORLD                                                     
... stopped: breakpoint at line 8 (address 3001)
MIX > run
Running ...
... done
MIX >
@end example

@noindent
Note that, since we compiled @file{hello.mixal} with debug info enabled
(the @code{-g} flag of @code{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 @code{sbp LINE_NO}, e.g.

@example
MIX > sbp 4
Breakpoint set at line 7
MIX > 
@end example

@noindent
@code{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 @code{cbpa ADDRESS} and @code{cbp LINE_NO}, or
@code{cabp} to remove all currently set breakpoints. 

MIXAL lets you define symbolic constants, either using the @code{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 @code{psym} command. For our hello world sample, you
will obtain the following output:

@example
MIX > psym
START:  3000
TERM:  19
MSG:  3002
MIX > 
@end example

For a complete description of all available MIX commands, @xref{mixvm}.



@node mixvm, mixasm, Getting started, Top
@comment  node-name,  next,  previous,  up
@chapter @code{mixvm}, the MIX computer simulator

@cindex mixvm

This chapter describes @code{mixvm}, the MIX computer
simulator. @code{mixvm} is a command line interface programme which
simulates the MIX computer (@pxref{The MIX computer}). It is able
to run MIXAL programs (@pxref{MIXAL}) previously compiled with the MIX
assembler (@pxref{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
@code{mixvm} usage, @xref{Running the program}.

@menu
* Invocation::                  Options when invoking @code{mixvm}.
* Commands::                    Commands available in interactive mode.
* Devices::                     MIX block devices implementation.
@end menu

@node Invocation, Commands, mixvm, mixvm
@comment  node-name,  next,  previous,  up
@section Invoking @code{mixvm}

@code{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):

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

@noindent
The meaning of these options is as follows:

@defopt -v
@defoptx --version
Prints version and copyleft information and exits.
@end defopt

@defopt -h
@defoptx --help
@defoptx -u
@defoptx --usage
Prints a summary of available options and exits.
@end defopt

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

@defopt -d
@defoptx --dump
This option must be used in conjuction with @code{-r}, and tells
@code{mixvm} to print the value of the virtual machine's registers,
comparison flag and overflow toggle after executing the program named
@var{FILE}. See @xref{Non-interactive mode}, for sample usage.
@end defopt

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

@example
MIX >
@end example

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

@node Commands, Devices, Invocation, mixvm
@comment  node-name,  next,  previous,  up
@section Interactive commands 

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

@example
MIX >
@end example

@noindent
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 as 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 @code{bash} shell). As a beginner, your
best friend will be the @code{help} command, which shows you a summary
of all available MIX commands and their usage; its syntax is as follows:

@deffn {@code{mixvm} command} help [command]
@deffnx {@code{mixvm} command} ? [command]
Prints a short description of the given @var{command} and its usage. If
@var{command} is omitted, all available commands are described.
@end deffn

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

@deffn {file command} load file[.mix]
This command loads a binary file, @var{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 @code{END} pseudoinstruction. Thus, if your
@file{sample.mixal} source file contains the line:

@example
     END 3000
@end example

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

@example
MIX > load sample
Program loaded. Start address: 3000
MIX >
@end example

@end deffn

@deffn {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 @code{load},
will run the loaded program until either a @code{HLT} instruction or a
breakpoint is found. If you provide a MIX filename as argument, the
given file will be loaded (as with @code{load} @var{file}) and
executed. If @code{run} is invoked again after program execution
completion (i.e., after the @code{HLT} instruction has been found in a
previous run), the program counter is repositioned and execution starts
again from the beginning. 
@end deffn

@deffn {file command} edit file[.mixal]
The source file @var{file.mixal} is edited using the editor defined in
the environment variable @var{MIX_EDITOR}. If this variable is not set,
the following ones are tried out in order: @var{X_EDITOR}, @var{EDITOR}
and @var{VISUAL}.
@end deffn

@deffn {file command} compile file[.mixal]
The source file @var{file.mixal} is compiled (with debug information
enabled) using @code{mixasm}.
@end deffn

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

@deffn {debug command} next [ins_number]
This command causes the virtual machine to fetch and execute  up to
@var{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. 
@end deffn

@deffn {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
@code{ORIG} or @code{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 @file{hello.mixal} file:

@example
*                                                        (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)
...
@end example

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

@example
MIX > sbp 5
Breakpoint set at line 7
MIX > 
@end example

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

@deffn {debug command} spba address
Sets a breakpoint at the given memory @var{address}. The argument must
be a valid MIX memory address, i.e., it must belong into the range
@w{[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 @code{sbpa}.
@end deffn

@deffn {debug command} cbp line_no
Clears a (previously set) breakpoint at the given source file line.
@end deffn

@deffn {debug command} cbpa address
Clears a (previously set) breakpoint at the given memory address.
@end deffn

@deffn {debug command} cabp
Clears all currently set breakpoints.
@end deffn

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

@example
VAR     EQU  2168
        ORIG 4000
START   LDA  VAR
@end example

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

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

@deffn {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.
@end deffn

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

@example
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 > 
@end example

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.

@code{pall} prints the contents of all registers plus the comparison
flag and overflow toggle.

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

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

@end deffn


@deffn {state command} pflags
@deffnx {state command} scmp E | G | L
@deffnx {state command} sover F | T
@code{pflags} prints the value of the comparison flag and overflow
toggle of the virtual machine, e.g.

@example
MIX > pflags
Overflow: F
Cmp: E
MIX > 
@end example

@noindent
The values of the overflow toggle are either @var{F} (false) or @var{T}
(true), and, for the comparison flag, @var{E}, @var{G}, @var{L} (equal,
greater, lesser). @code{scmp} and @code{sover} are setters of the
comparison flag and overflow toggle values.
@end deffn

@deffn {state command} pmem from[-to]
@deffnx {state command} smem address value
@code{pmem} prints the contents of memory cells in the address range
@w{[@var{FROM}-@var{TO}]}. If the upper limit @var{to} is omitted, only
the contents of the memory cell with address @var{FROM} is printed, as
in

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

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.

@code{smem} sets the content of the memory cell with address
@var{address} to @var{value}, expressed as a decimal constant.

@end deffn

Finally, you can use the @code{quit} command to exit @code{mixvm}.

@node Devices,  , Commands, mixvm
@comment  node-name,  next,  previous,  up
@section MIX block devices

The MIX computer comes equipped with a set of block devices for
input-output operations (@pxref{Input-output operators}). @code{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).

@multitable {the device name} {xx-xx} {filena[x-x].dev} {bin  i/o} 
@item @emph{Device}  @tab @emph{No.} @tab @emph{filename} @tab @emph{type}
@item Tape @tab 0-7 @tab @file{tape[0-7].dev} @tab bin i/o
@item Disks @tab 8-15 @tab @file{disk[0-7].dev} @tab bin i/o
@item Card reader @tab 16 @tab @file{cardrd.dev} @tab char in
@item Card writer @tab 17 @tab @file{cardwr.dev} @tab char out
@item Line printer @tab 18 @tab @file{printer.dev} @tab char out
@item Terminal @tab 19 @tab @code{stdout} @tab char out
@item Paper tape @tab 20 @tab @file{paper.dev} @tab char out
@end multitable



@node mixasm, Copying, mixvm, Top
@comment  node-name,  next,  previous,  up
@chapter @code{mixasm}, the MIXAL assembler
@cindex @code{mixasm}
@cindex MIXAL
@cindex assembler

MIX programs, as executed by @code{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 (@pxref{MIXAL}) which is compiled into binary
form by @code{mixasm}, the MIXAL assembler included in @sc{mdk}. In this
chapter, you will find a complete description of @code{mixasm} options.

@menu
* Invoking @code{mixasm}::      @code{mixasm} options
@end menu

@node Invoking @code{mixasm},  , mixasm, mixasm
@comment  node-name,  next,  previous,  up
@section Invoking @code{mixasm}

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

@example
mixasm hello
@end example

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

In addition, @code{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):

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

@noindent
The meaning of these options is as follows:

@defopt -v
@defoptx --version
Prints version and copyleft information and exits.
@end defopt

@defopt -h
@defoptx --help
@defoptx -u
@defoptx --usage
Prints a summary of available options and exits.
@end defopt

@defopt -g
@defoptx --debug
Includes debugging information in the compiled file, allowing breakpoint
setting at source level and symbol table inspection under @code{mixvm}.
@end defopt

@defopt -o output_file
@defoptx --output=output_file
By default, the given source file @var{file.mixal} is compiled into
@var{file.mix}. You can provide a different name for the output file
using this option.
@end defopt

@defopt -l
@defoptx --list[=list_file]
This option causes @code{mixasm} to produce, in addion to the
@file{.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 @file{.mls} if no argument is provided; otherwise, the
listing file is named according to the argument.
@end defopt



@node Copying, Problems, mixasm, Top
@chapter Copying
@lowersections
@include gpl.texi
@raisesections

@node Problems, Concept Index, Copying, Top
@chapter Reporting Bugs
@cindex bugs
@cindex problems

If you find a bug in @sc{mdk} (or have questions, comments or suggestions
about it), please send electronic mail to @email{jaortega@@acm.org,
the author}. 

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

@node Concept Index,  , Problems, Top
@unnumbered Concept Index

@cindex tail recursion
@printindex cp

@c @node MIXAL instructions,  , Concept Index, Top
@comment  node-name,  next,  previous,  up
@c @unnumbered MIXAL instructions
@c @printindex fn

@shortcontents
@contents
@bye