docs splitting

1 files changed, 23 insertions, 2339 deletions

diff --git a/doc/mdk.texi b/doc/mdk.texi
index ade349a..1a985c5 100644
--- a/doc/mdk.texi
+++ b/doc/mdk.texi
@@ -1,17 +1,19 @@
-\input texinfo @c -*-texinfo-*-
+\input texinfo 
 @c %**start of header
 @setfilename mdk.info
-@settitle MIX Development Kit (mdk)
+@settitle GNU MIX Development Kit (mdk)
 @finalout
 @setchapternewpage odd
 @c %**end of header
 
-@include version.texi
+@set UPDATED 20 February 2001
+@set EDITION 0.3
+@set VERSION 0.3
 @set JAO Jos@'e Antonio Ortega Ruiz
 @footnotestyle separate
 
 @ifinfo
-This file documents the the @sc{mdk} utilities for developing
+This file documents the the GNU @sc{mdk} utilities for developing
 programs using Donald Knuth's MIX language.
 
 Copyright (C) 2000, 2001 Free Software Foundation, Inc.
@@ -41,9 +43,9 @@ 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}
+@title GNU MDK
+@subtitle GNU MIX Development Kit
+@subtitle Edition @value{EDITION}, for GNU @sc{mdk} Version @value{VERSION}
 @subtitle @value{UPDATED}
 @author by @value{JAO}
 
@@ -71,16 +73,18 @@ approved by the Free Software Foundation.
 @node Top, Introduction, (dir), (dir)
 
 @ifinfo
-This file documents the @sc{mdk} utilities to develop, run and debug
+This file documents the GNU @sc{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 @cite{The
 Art of Computer Programming} (Addison Wesley, 1997).
 
-@sc{mdk} was written by @value{JAO} and is released under the GNU
+GNU @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 improve it.
 
+GNU @sc{mdk} is an official GNU package.
+
 @end ifinfo
 
 @menu
@@ -88,11 +92,13 @@ and improve it.
 * MIX and MIXAL tutorial::      Learn the innards of MIX and MIXAL.
 * Getting started::             Basic usage of the @sc{mdk} tools.
 * mixvm::                       Invoking the MIX virtual machine.
+* mixvm.el::                    Using @code{mixvm} within Emacs.
 * mixasm::                      Invoking the MIXAL assembler.
 * Copying::                     @sc{mdk} licensing terms.
 * Problems::                    Reporting bugs.
 * Concept Index::               Index of concepts.
 
+
 @detailmenu
  --- The Detailed Node Listing ---
 
@@ -163,2338 +169,16 @@ Interactive commands
 @end detailmenu
 @end menu
 
-@node Introduction, MIX and MIXAL tutorial, 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
-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 @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 tutorial of MIX and MIXAL, and a thorough
-description of the use of the @sc{mdk} utilities.
-
-
-
-@node MIX and MIXAL tutorial, Getting started, Introduction, Top
-@comment  node-name,  next,  previous,  up
-@chapter MIX and MIXAL tutorial
-@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) 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.
-
-@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 tutorial, MIX and MIXAL tutorial
-@comment  node-name,  next,  previous,  up
-@section The MIX computer
-
-In this section, you will find a 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 from 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
-@noindent
-Sample MIX words are @samp{- 12 00 11 01 63} and @samp{+ 12 11 34 43
-00}.
-
-You can refer to subfields within a word using a @dfn{field
-specification} or @dfn{fspec} of the form ``(@var{l}:@var{r})'', where
-@var{l} denotes the first byte, and @var{r} the last byte of the
-subfield.
-When @var{l} is zero, the subfield includes the word's
-sign. An fspec can also be represented as a single value @code{F}, given
-by @code{F = 8*L + R} (thus the fspec @samp{(1:3)}, denoting the first
-three bytes of a word, is represented by the integer 11).
-
-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:
-
-@cindex rA
-@cindex rX
-@cindex rJ
-@cindex rIn
-@cindex register
-
-@table @asis
-@item @code{rA}
-A register. General purpose register holding a word. Usually its
-contents serves as the operand of arithmetic and storing instructions.
-@item @code{rX}
-X register. General purpose register holding a word. Often it acts as an
-extension or a replacement of @samp{rA}.
-@item @code{rJ}
-J (jump) register. This register stores positive two-byte values,
-usually representing a jump address.
-@item @code{rI1}, @code{rI2}, @code{rI3}, @code{rI4}, @code{rI5}, @code{rI6}
-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.
-@end table
-
-@cindex @sc{ov}
-@cindex @sc{cm}
-@cindex @code{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}, and its possible values are abbreviated as @dfn{E}, @dfn{G} and
-@dfn{L}.
-@item
-Input-output block devices. Each device is labelled as @code{un}, where
-@code{n} runs from 0 to 20. In Knuth's definition, @code{u0} through
-@code{u7} are magnetic tape units, @code{u8} through @code{15} are disks
-and drums, @code{u16} is a card reader, @code{u17} is a card writer,
-@code{u18} is 
-a line printer and, @code{u19} is a typewriter terminal, and @code{u20},
-a paper tape. Our implementation maps these devices to disk files,
-except for @code{u19}, which represents the standard output.
-@end itemize
-
-As noted above, the MIX computer communicates with the external world by
-a set of input-output devices which can be ``connected'' to it. The
-computer interchanges information using blocks of words whose length
-depends on the device at hand (@pxref{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:
-
-@multitable  {00} {C} {00} {C} {00} {C} {00} {C}
-@item  00 @tab  @tab 01 @tab A @tab 02 @tab B @tab 03 @tab C
-@item  04 @tab D @tab 05 @tab E @tab 06 @tab F @tab 07 @tab G
-@item  08 @tab H @tab 09 @tab I @tab 10 @tab d @tab 11 @tab J
-@item  12 @tab K @tab 13 @tab L @tab 14 @tab M @tab 15 @tab N
-@item  16 @tab O @tab 17 @tab P @tab 18 @tab Q @tab 19 @tab R
-@item  20 @tab s @tab 21 @tab p @tab 22 @tab S @tab 23 @tab T
-@item  24 @tab U @tab 25 @tab V @tab 26 @tab W @tab 27 @tab X
-@item  28 @tab Y @tab 29 @tab Z @tab 30 @tab 0 @tab 31 @tab 1 
-@item  32 @tab 2 @tab 33 @tab 3 @tab 34 @tab 4 @tab 35 @tab 5
-@item  36 @tab 6 @tab 37 @tab 7 @tab 38 @tab 8 @tab 39 @tab 9
-@item  40 @tab . @tab 41 @tab , @tab 42 @tab ( @tab 43 @tab )
-@item  44 @tab + @tab 45 @tab - @tab 46 @tab * @tab 47 @tab /
-@item  48 @tab = @tab 49 @tab $ @tab 50 @tab < @tab 51 @tab >
-@item  52 @tab @@ @tab 53 @tab ; @tab 54 @tab : @tab 55 @tab '
-@end multitable
-@noindent
-The value 0 represents a whitespace. Lowercase letters (d, s, p)
-correspond to symbols not 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 @dfn{location
-counter} (also known as program counter in other architectures).
-
-The next section, @xref{MIX instruction set}, gives a complete description
-of the available MIX binary 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 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.
-
-@menu
-* Instruction structure::       
-* Loading operators::           
-* Storing operators::           
-* Arithmetic operators::        
-* Address transfer operators::  
-* Comparison operators::        
-* Jump operators::              
-* Input-output operators::      
-* Conversion operators::        
-* Shift operators::             
-* Miscellaneous operators::     
-* Execution times::             
-@end menu
-
-@node Instruction structure, Loading operators, MIX instruction set, MIX instruction set
-@comment  node-name,  next,  previous,  up
-@subsubsection Instruction structure
-
-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
-
-For a given instruction, @samp{M} stands for
-the memory address obtained after indexing the ADDRESS subfield 
-(using its INDEX byte), and @samp{V} is the contents of the
-subfield indicated by MOD of the memory cell with address @samp{M}. For
-instance, suppose that we have the following contents of MIX registers
-and memory cells:
-
-@example
-[rI2] = + 00 63
-[31] = - 10 11 00 11 22
-@end example
-@noindent
-where @samp{[n]} denotes the contents of the nth memory cell and
-@samp{[rI2]} the contents of register @samp{rI2}@footnote{In general,
-@samp{[X]} will denote the contents of entity @samp{X}; thus, by
-definition, @w{@samp{V = [M](MOD)}}.}.  Let us consider the binary
-instruction @w{@samp{I = - 00 32 02 11 10}}. For this instruction we
-have:
-
-@example
-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
-@end example
-
-In the following subsections, we will assing to each MIX instruction a
-mnemonic, or symbolic name. For instance, the mnemonic of @samp{OPCODE}
-10 is @samp{LD2}. Thus we can rewrite the above instruction as
-
-@example
-LD2  -32,2(1:3)
-@end example
-@noindent
-or, for a generic instruction:
-
-@example
-MNEMONIC  ADDRESS,INDEX(MOD)
-@end example
-@noindent
-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).
-
-@node Loading operators, Storing operators, Instruction structure, 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
-Put in rA the contents of cell no. M.
-OPCODE = 8, MOD = fspec. @code{rA <- V}.
-@item LDX
-Put in rX the contents of cell no. M.
-OPCODE = 15, MOD = fspec. @code{rX <- V}.
-@item LDi
-Put in rIi the contents of cell no. M.
-OPCODE = 8 + i, MOD = fspec. @code{rIi <- V}.
-@item LDAN
-Put in rA the negative contents of cell no. M.
-OPCODE = 16, MOD = fspec. @code{rA <- -V}.
-@item LDXN
-Put in rX the negative contents of cell no. M.
-OPCODE = 23, MOD = fspec. @code{rX <- -V}.
-@item LDiN
-Put in rIi the negative contents of cell no. M.
-OPCODE = 16 + i, MOD = fspec. @code{rIi <- -V}.
-@end ftable
-
-In all the above load instructions the @samp{MOD} field selects the
-bytes of the memory cell with address @samp{M} which are loaded into the
-requisite register (indicated by the @samp{OPCODE}).  For instance, the
-word @w{@samp{+ 00 13 01 27 11}} represents the instruction
-
-@example
-LD3    13,1(3:3)
- ^      ^ ^  ^
- |      | |  |
- |      | |   --- MOD = 27 = 3*8 + 7
- |      |  --- INDEX = 1
- |       --- ADDRESS = 00 13
-  --- OPCODE = 11
-@end example
-Let us suppose that, prior to this instruction execution, the state of
-the MIX computer is the following:
-
-@example
-[rI1] = - 00 01
-[rI3] = + 24 12
-[12] = - 01 02 03 04 05
-@end example
-@noindent
-As, in this case, @w{@samp{M = 13 + [rI1] = 12}}, we have
-@w{@samp{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
-
-@example
-[rI1] = - 00 01
-[rI3] = + 00 03
-[12] = - 01 02 03 04 05
-@end example
-
-To further illustrate loading operators, the following table shows the
-contents of @samp{rX} after different @samp{LDX} instructions:
-
-@table @samp
-@item LDX 12(0:0)     [rX] = - 00 00 00 00 00
-@item LDX 12(0:1)     [rX] = - 00 00 00 00 01
-@item LDX 12(3:5)     [rX] = + 00 00 03 04 05
-@item LDX 12(3:4)     [rX] = + 00 00 00 03 04
-@item LDX 12(0:5)     [rX] = - 01 02 03 04 05
-@end table
-
-
-@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 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.
-
-@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
-
-By way of example, consider the instruction @samp{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 @emph{the memory
-address}). The others bytes of the memory cell retain their
-values. Thus, if prior to the instruction execution we have
-
-@example
-[1200] = - 20 21 22 23 24
-[rA] = + 01 02 03 04 05
-@end example
-@noindent
-we will end up with
-
-@example
-[1200] = - 20 04 05 23 24
-[rA] = + 01 02 03 04 05
-@end example
-
-As a second example, @samp{ST2 1000(0)} will set the sign of
-@samp{[1000]} to that of @samp{[rI2]}.
-
-@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. 
-@w{@code{rA <- rA +V}}.
-@item SUB
-Sub and set OV if overflow. OPCODE = 2, MOD = fspec.
-@w{@code{rA <- rA - V}}.
-@item MUL
-Multiply V times rA and store the 10-bytes product in rAX.
-OPCODE = 3, MOD = fspec. @w{@code{rAX <- rA x V}}.
-@item DIV
-rAX is considered a 10-bytes number, and it is divided by V.
-OPCODE = 4, MOD = fspec. @w{@code{rA <- rAX / V}}, @code{rX} <- reminder.
-@end ftable
-
-In all the above instructions, @samp{[rA]} is one of the operands
-of the binary arithmetic operation, the other being @samp{V} (that is,
-the specified subfield of the memory cell with address @samp{M}), padded
-with zero bytes on its left-side to complete a word. In multiplication
-and division, the register @samp{X} comes into play as a right-extension
-of the register @samp{A}, so that we are able to handle 10-byte numbers
-whose more significant bytes are those of @samp{rA} (the sign of this
-10-byte number is that of @samp{rA}: @samp{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 @w{1,073,741,823}
-(the maximum value storable in a MIX word) is stored in @samp{rA}, and
-the overflow toggle is set to TRUE.
-
-@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, @samp{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
-
-In the above instructions, the subfield @samp{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 @samp{rA} the value -2000 (- 00 00 00 31 16), you
-can use the binary instruction @w{+ 31 16 00 03 48}, or, symbolically,
-
-@example
-ENNA 2000
-@end example
-@noindent
-Used in conjuction with the store operations (@samp{STA}, @samp{STX},
-etc.), these instructions also allow you to set memory cells contents to
-concrete values.
-
-Note that in these address transfer operators, the @samp{MOD} field is
-not a subfield specificator, but serves to define (together with
-@samp{OPCODE}) the concrete operation to be performed.
-
-@node Comparison operators, Jump operators, Address transfer operators, MIX instruction set
-@comment  node-name,  next,  previous,  up
-@subsubsection Comparison operators
-@cindex 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 @samp{V}, and
-set the @sc{cm} indicator to the result of the comparison (i.e. to
-@samp{E}, @samp{G} or @samp{L}, equal, greater or lesser respectively).
-
-@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
-
-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.
-
-@node Jump operators, Input-output operators, Comparison operators, MIX instruction set
-@comment  node-name,  next,  previous,  up
-@subsubsection Jump operators
-@cindex jump operators
-
-The MIX computer has an internal register, called the @dfn{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 @samp{rJ} (except for @code{JSJ}), and the location
-counter is set to the value of @samp{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 @samp{rJ}.
-
-The MIX computer provides the following jump instructions:
-With these instructions you force a jump to the specified address. Use
-@samp{JSJ} if you do not care about the return address.
-
-@ftable @code
-@item JMP
-Unconditional jump. OPCODE = 39, MOD = 0.
-@item JSJ
-Unconditional jump, but rJ is not modified. OPCODE = 39, MOD = 1.
-@end ftable
-
-These instructions check the overflow toggle to decide whether to jump
-or not.
-
-@ftable @code
-@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.
-@end ftable
-
-In the following instructions, the jump is conditioned to the contents of the
-comparison flag:
-
-@ftable @code
-@item JL
-Jump if @w{@code{[CM] = L}}. OPCODE = 39, MOD = 4.
-@itemx JE
-Jump if @w{@code{[CM] = E}}. OPCODE = 39, MOD = 5.
-@itemx JG
-Jump if @w{@code{[CM] = G}}. OPCODE = 39, MOD = 6.
-@itemx JGE
-Jump if @code{[CM]} does not equal @code{L}. OPCODE = 39, MOD = 7.
-@itemx JNE
-Jump if @code{[CM]} does not equal @code{E}. OPCODE = 39, MOD = 8.
-@itemx JLE
-Jump if @code{[CM]} does not equal @code{G}. OPCODE = 39, MOD = 9.
-@end ftable
-
-You can also jump conditioned to the value stored in the MIX registers,
-using the following instructions:
-
-@ftable @code
-@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 Input-output operators, Conversion operators, Jump operators, MIX instruction set
-@comment  node-name,  next,  previous,  up
-@subsubsection Input-output operators
-@cindex input-output operators
-
-As explained in previous sections (@pxref{MIX architecture}), the MIX
-computer can interact with a series of block devices. To that end, you
-have at your disposal the following instructions:
-
-@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
-@noindent
-In all the above instructions, the @samp{MOD} subfile must be in the
-range 0-20, since it denotes the operation's target device. The
-@samp{IOC} instruction only makes sense for tape devices (@samp{MOD} =
-0-7 or 20): it shifts the read/write pointer by the number of words
-given by @samp{M} (if it equals zero, the tape is rewound)@footnote{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 @sc{mdk} simulator). For the same
-reason, @sc{mdk} devices are always ready, since all input-output
-operations are performed using synchronous system calls.}.
-
-
-@node Conversion operators, Shift 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
-@noindent
-Digits are represented in MIX by the range of values 30-39 (digits
-9-0). Thus, if the contents of @samp{rA} and @samp{rX} is, for instance,
-
-@example
-[rA] = + 30 30 31 32 33
-[rX] = + 31 35 39 30 34
-@end example
-@noindent
-the represented number is 0012315904, and @samp{NUM} will store this
-value in @samp{rA} (i.e., we end up with @samp{[rA]} = @w{+ 0 46 62 52
-0} = 12315904. @samp{CHAR} performs the inverse operation.
-
-@node Shift operators, Miscellaneous operators, Conversion operators, MIX instruction set
-@comment  node-name,  next,  previous,  up
-@subsubsection Shift operators
-@cindex shift
-@cindex shift operators
-
-The following instructions perform byte-wise shifts of the contents of
-@samp{rA} and @samp{rX}.
-
-@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.
-@end ftable
-@noindent
-If we begin with, say, @samp{[rA]} = @w{- 01 02 03 04 05}, we would
-have the following modifications to @samp{rA} contents when performing
-the instructions on the left column:
-
-@multitable {SLA 00} {[rA] = - 00 00 00 00 00}
-@item SLA 2 @tab [rA] = - 03 04 05 00 00
-@item SRA 1 @tab [rA] = - 00 01 02 03 04
-@item SLC 3 @tab [rA] = - 04 05 01 02 03
-@item SRC 24 @tab [rA] = - 05 01 02 03 04
-@end multitable
-@noindent
-Note that the sign is unaffected by shift operations. On the other hand,
-@samp{SLAX} and @samp{SRAX} treat @samp{rA} and @samp{rX} as a single
-10-bytes register (ignoring again the signs), so that, if we begin with
-@samp{[rA]} = @w{+ 01 02 03 04 05} and @samp{[rX]} = @w{- 06 07 08 09
-10}, executing @samp{SLAX 3} would yield:
-
-@example
-[rA] = + 04 05 06 07 08  [rX] = - 09 10 00 00 00
-@end example
-
-@node Miscellaneous operators, Execution times, Shift operators, MIX instruction set
-@comment  node-name,  next,  previous,  up
-@subsubsection Miscellaneous operators
-@cindex miscellaneous operators
-
-Finally, we list in the following table three miscellaneous MIX
-instructions which do not fit in any of the previous subsections:
-
-@ftable @code
-@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
-@noindent
-The only effect of executing @samp{NOP} is increasing the location
-counter, while @samp{HLT} usually marks program termination.
-
-@node Execution times,  , Miscellaneous operators, MIX instruction set
-@comment  node-name,  next,  previous,  up
-@subsubsection Execution times
-
-@cindex exection time
-@cindex time
-
-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.
-
-@multitable {INSSSS} {01} {INSSSS} {01} {INSSSS} {01} {INSSSS} {01}
-@item @code{NOP} @tab 1 @tab @code{ADD} @tab 2 @tab @code{SUB}
-@tab 2 @tab @code{MUL} @tab 10
-@item @code{DIV} @tab 12 @tab @code{NUM} @tab 10 @tab @code{CHAR}
-@tab 10 @tab @code{HLT} @tab 10
-@item @code{SLx} @tab 2 @tab @code{SRx} @tab 2 @tab @code{LDx}
-@tab  2 @tab @code{STx} @tab 2 
-@item @code{JBUS} @tab 1 @tab @code{IOC} @tab 1 @tab @code{IN}
-@tab  1@tab @code{OUT} @tab 1
-@item @code{JRED} @tab 1 @tab @code{Jx} @tab 1 @tab @code{INCx}
-@tab  1 @tab @code{DECx} @tab 1 
-@item @code{ENTx} @tab 1 @tab @code{ENNx} @tab 1 @tab @code{CMPx}
-@tab  1 @tab @code{MOVE} @tab 1+F  
-@end multitable
-
-In the above table, 'F' stands for the number of blocks to be moved
-(given by the @code{FSPEC} subfield of the instruction); @code{SLx} and
-@code{SRx} are a short cut for the byte-shifting operations; @code{LDx}
-denote all the loading operations; @code{STx} are the storing
-operations; @code{Jx} stands for all the jump operations, and so on with
-the rest of abbreviations.
-
-@node MIXAL,  , The MIX computer, MIX and MIXAL tutorial
-@comment  node-name,  next,  previous,  up
-@section MIXAL
-@cindex MIXAL
-@cindex MIX assembly language
-@cindex assembly
-
-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 @sc{mdk} are described later on (@pxref{Getting started}).
-
-@menu
-* Basic structure::             Writing basic MIXAL programs.
-* MIXAL directives::            Assembler directives.
-* Expressions::                 Evaluation of expressions.
-* W-expressions::               Evaluation of w-expressions.
-* Local symbols::               Special symbol table entries.
-* Literal constants::           Specifying an immediate operand.
-@end menu
-
-@node Basic structure, MIXAL directives, MIXAL, MIXAL
-@comment  node-name,  next,  previous,  up
-@subsection 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@footnote{We shall call them,
-collectively, MIXAL instructions.} are written in MIXAL (one per
-source file line) according to the following pattern:
-
-@example
-[LABEL]   MNEMONIC  [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 current
-value of the location counter, and can be used in subsequent
-expressions.
-@item MNEMONIC
-Is a literal denoting the operation code of the instruction
-(e.g. @code{LDA}, @code{STA}; see @pxref{MIX instruction set}) 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.}.
-
-We have already listed the mnemonics associated will each MIX
-instructions; sample MIXAL instructions representing MIX instructions
-are:
-@example
-HERE     LDA  2000         HERE represents the current location counter
-         LDX  HERE,2(1:3)  this is a comment
-         JMP  1234
-@end example
-
-@node MIXAL directives, Expressions, Basic structure, MIXAL
-@comment  node-name,  next,  previous,  up
-@subsection MIXAL directives
-
-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
-
-The operand of @code{ORIG}, @code{EQU}, @code{CON} and @code{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,
-@pxref{Expressions}) or a w-expression (@pxref{W-expressions}).
-
-All MIXAL programs must contain an @code{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 @code{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
-
-@example
-          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
-@end example
-@noindent
-The assembler will generate two binary instructions (@code{NOP} (@w{+ 00
-00 00 00 00}) and @code{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 @code{HLT} instruction,
-which will mark the end of program execution (but not of program
-compilation). 
-
-The @code{EQU} directive allows the definition of symbolic names for
-specific values. For instance, we could rewrite the above program as
-follows:
-
-@example
-START     EQU   2000
-          ORIG  START
-          NOP
-          HLT
-          END   START
-@end example
-@noindent
-which would give rise to the same compiled code. Symbolic constants (or
-symbols, for short) can also be implicitly defined placing them in the
-@code{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
-
-@example
-          ORIG  2000
-START     NOP
-          HLT
-          END   START
-@end example
-
-The @code{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
-
-@example
-          ORIG  1150
-          CON   -1823473
-@end example
-@noindent
-it will assign to the memory cell number 1150 the contents @w{- 00 06 61
-11 49} (which corresponds to the decimal value -1823473). 
-
-Finally, the @code{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:
-
-@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.  "
-@end example
-@noindent
-The above snippet also shows the use of a @dfn{future reference}, that
-is, the usage of a symbol (@code{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
-(@pxref{Expressions}).
-
-@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
-@code{MNEMONIC} 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, W-expressions, MIXAL directives, 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.
-
-The special binary operator @code{:} has the same meaning as in fspecs,
-i.e.,
-
-@example
-A:B = 8*A + B
-@end example
-@noindent
-while @code{A//B} stands for the quotient of the ten-byte number @w{@code{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
-@code{B}. Sample expressions are:
-
-@example
-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)
-@end example
-@noindent
-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 @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 W-expressions, Local symbols, Expressions, MIXAL
-@comment  node-name,  next,  previous,  up
-@subsection W-expressions
-@cindex w-expressions
-
-Besides expressions, as described above (@pxref{Expressions}), the MIXAL
-assembler is able to handle the so called @dfn{w-expressions} as the
-operands of the directives @code{ORIG}, @code{EQU}, @code{CON} and
-@code{END} (@pxref{MIXAL directives}). The general form of a
-w-expression is the following:
-
-@example
-     WEXP = EXP[(EXP)][,WEXP]
-@end example
-@noindent
-where @code{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:
-
-@example
-2000
-235(3)
-S1+3(S2),3000
-S1,S2(3:5),23
-@end example
-
-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, @samp{S1+2(2:4)} where @samp{S1} equals 265230, we
-have @samp{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 @w{@samp{+ 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 @w{@samp{+ 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
-
-@example
-1(1:2),66(4:5)
-@end example
-@noindent
-we first take two bytes from 1 (00 and 01) and store them as bytes 1 and
-2 of the result (obtaining @w{@samp{+ 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 @w{@samp{+ 00 01 00 01 02}} (262210). The process
-is repeated for each new comma-separated example. For instance:
-
-@example
-1(1:1),2(2:2),3(3:3),4(4:4) = 01 02 03 04 00
-@end example
-
-As stated before, w-expressions can only appear as the operands of MIXAL
-directives taking a constant value (@code{ORIG}, @code{EQU}, @code{CON}
-and @code{END}). Future references are @emph{not} allowed within
-w-expressions (i.e., all symbols appearing in a w-expression must be
-defined before they are used).
-
-@node Local symbols, Literal constants, W-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
-
-Note that a @code{B} local symbol never refers to a definition in its
-own line, that is, in the following program:
-
-@example
-		ORIG 1999
-ST		NOP
-3H		EQU 69
-3H		ENTA 3B  local symbol 3B refers to 3H in previous line
-		HLT
-		END ST
-@end example
-@noindent
-the contents of @samp{rA} is set to 69 and @emph{not} to 2001. An
-specially tricky case occurs when using local symbols in conjunction
-with @code{ORIG} pseudoinstructions. To wit@footnote{The author wants to
-thank Philip E. King for pointing these two special cases of local
-symbol usage to him.},
-
-@example
-		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
-@end example
-
-@node Literal constants,  , Local symbols, MIXAL
-@comment  node-name,  next,  previous,  up
-@subsection Literal constants
-@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{=wexp=}, where
-@code{exp} is an w-expression (@pxref{W-expressions}). 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 tutorial, 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 tutorial}. 
-
-@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 tutorial}, 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
-** Execution time: 11
-@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. 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 (@pxref{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,
-@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
-** 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
-@end example
-
-@noindent 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.
-
-@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
-Elapsed time: 11 /Total program time: 11 (Total uptime: 11)
-MIX > 
-@end example
-
-@noindent 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 @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
-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 > @end example
-@noindent
-(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
-@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)
-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 >
-@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
-
-Other useful commands for debugging are @code{tron} (which turns on
-tracing of executed intructions) and @code{weval} (which evaluates
-w-expressions on the fly). 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 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 @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
-
-@menu
-* File commands::               Loading and executing programs.
-* Debug commands::              Debugging programs.
-* State commands::              Inspecting the virtual machine state.
-@end menu
-
-@node File commands, Debug commands, Commands, Commands
-@comment  node-name,  next,  previous,  up
-@subsection 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:
-
-@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{MDK_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
-
-
-@node Debug commands, State commands, File commands, Commands
-@comment  node-name,  next,  previous,  up
-@subsection Debug commands
-
-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
-
-The virtual machine can also show you the instructions it is executing,
-using the following commands:
-
-@deffn {debug command} tron
-@deffnx troff
-@code{tron} enables instruction tracing. When tracing is enabled, each
-time the virtual machine executes an instruction (due to your issuing a
-@code{run} or @code{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
-@code{troff} command. A typical tracing session could be like this:
-
-@example
-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 > 
-@end example
-@noindent
-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.
-@end deffn
-
-@code{mixvm} is also able of evaluating w-expressions
-(@pxref{W-expressions}) using the following command:
-
-@deffn {debug command} weval WEXP
-Evaluates the given w-expression, @var{WEXP}. The w-expression can
-contain any currently defined symbol. For instance:
-
-@example
-MIX > psym START
-+ 00 00 00 46 56 (0000003000)
-MIX > weval START(0:1),START(3:4)
-+ 56 00 46 56 00 (0939716096)
-MIX >
-@end example
-@end deffn
-
-New symbols can be defined using the @code{ssym} command:
-@deffn {debug command} ssym SYM WEXP
-Defines the symbol named @var{SYM} with the value resulting from
-evaluating @var{WEXP}, an w-expression. The newly defined symbol can be
-used in subsequent @code{weval} commands, as part of the expression to
-be evaluated. E.g.,
-
-@example
-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 > 
-@end example
-@end deffn
-
-Finally, if you want to discover which is the decimal value of a MIX
-word expressed as five bytes plus sign, you can use
-
-@deffn {debug command} w2d WORD
-Computes the decimal value of the given word. @var{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 @code{weval}. For instance: 
-
-@example
-MIX > w2d - 01 00 00 02 02
--16777346
-MIX > weval -16777346
-- 01 00 00 02 02 (0016777346)
-MIX > 
-@end example
-@end deffn
-
-@node State commands,  , Debug commands, Commands
-@comment  node-name,  next,  previous,  up
-@subsection State commands
-
-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 mdk_intro.texi
+@include mdk_tut.texi
+@include mdk_gstart.texi
+@include mdk_mixvm.texi
+@include mdk_emixvm.texi
+@include mdk_mixasm.texi
 @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
+@include mdk_bugs.texi
+@include mdk_index.texi
 
-@c @node MIXAL instructions,  , Concept Index, Top
-@comment  node-name,  next,  previous,  up
-@c @unnumbered MIXAL instructions
-@c @printindex fn
 
 @shortcontents
 @contents