diff options
Diffstat (limited to 'doc/mdk.texi')
| -rw-r--r-- | doc/mdk.texi | 2362 |
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 |