diff options
| author | jaortega <jaortega> | 2001-03-17 14:26:36 +0000 |
|---|---|---|
| committer | jaortega <jaortega> | 2001-03-17 14:26:36 +0000 |
| commit | c0eeccaaee4816f0fffe028bdc0ef1e4731d3794 (patch) | |
| tree | 5fc85d43dd6d910fa5aa8bc0be7f01a6c0d1ead8 | |
| parent | 58871c45c0d152690c2b6e6acfaf9d57d24b0691 (diff) | |
| download | mdk-c0eeccaaee4816f0fffe028bdc0ef1e4731d3794.tar.gz mdk-c0eeccaaee4816f0fffe028bdc0ef1e4731d3794.tar.bz2 | |
docs splitting
| -rw-r--r-- | doc/Makefile.am | 4 | ||||
| -rw-r--r-- | doc/gpl.texi | 6 | ||||
| -rw-r--r-- | doc/mdk.texi | 2362 | ||||
| -rw-r--r-- | doc/mdk_emixvm.texi | 9 | ||||
| -rw-r--r-- | doc/mdk_gstart.texi | 433 | ||||
| -rw-r--r-- | doc/mdk_index.texi | 10 | ||||
| -rw-r--r-- | doc/mdk_intro.texi | 48 | ||||
| -rw-r--r-- | doc/mdk_mixasm.texi | 79 | ||||
| -rw-r--r-- | doc/mdk_mixvm.texi | 478 | ||||
| -rw-r--r-- | doc/mdk_tut.texi | 1259 | ||||
| -rw-r--r-- | doc/ss_devices.png | bin | 0 -> 16621 bytes | |||
| -rw-r--r-- | doc/ss_mix.png | bin | 0 -> 12642 bytes | |||
| -rw-r--r-- | doc/ss_mixal.png | bin | 0 -> 14536 bytes | |||
| -rw-r--r-- | doc/ss_worddlg.png | bin | 0 -> 15050 bytes |
14 files changed, 2347 insertions, 2341 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am index cda27ea..42953a8 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -15,7 +15,9 @@ SUFFIXES = .html info_TEXINFOS = mdk.texi -mdk_TEXINFOS = gpl.texi +mdk_TEXINFOS = gpl.texi mdk_intro.texi mdk_tut.texi mdk_gstart.texi \ + mdk_mixvm.texi mdk_emixvm.texi mdk_mixasm.texi mdk_bugs.texi \ + mdk_index.texi html_docs = mdk.html diff --git a/doc/gpl.texi b/doc/gpl.texi index 5b0da1a..361504a 100644 --- a/doc/gpl.texi +++ b/doc/gpl.texi @@ -1,4 +1,6 @@ -@setfilename gpl.info +@node Copying, Problems, mixasm, Top +@chapter Copying +@lowersections @unnumbered GNU GENERAL PUBLIC LICENSE @center Version 2, June 1991 @@ -394,3 +396,5 @@ proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Library General Public License instead of this License. + +@raisesections 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 diff --git a/doc/mdk_emixvm.texi b/doc/mdk_emixvm.texi new file mode 100644 index 0000000..d99fd68 --- /dev/null +++ b/doc/mdk_emixvm.texi @@ -0,0 +1,9 @@ +@node mixvm.el, mixasm, mixvm, Top +@comment node-name, next, previous, up +@chapter mixvm.el + +If you are an Emacs user and write your MIXAL programs using this +editor, you will find the elisp program @file{mixvm.el} quite +useful. @file{mixvm.el} allows running the MIX virtual machine +@code{mixvm} (@pxref{mixvm}) inside an Emacs @acronym{GUD} buffer, while +visiting the MIXAL source file in another buffer. diff --git a/doc/mdk_gstart.texi b/doc/mdk_gstart.texi new file mode 100644 index 0000000..cfa44ea --- /dev/null +++ b/doc/mdk_gstart.texi @@ -0,0 +1,433 @@ +@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}. diff --git a/doc/mdk_index.texi b/doc/mdk_index.texi new file mode 100644 index 0000000..cb752f0 --- /dev/null +++ b/doc/mdk_index.texi @@ -0,0 +1,10 @@ +@node Concept Index, , Problems, Top +@unnumbered Concept Index + +@cindex tail recursion +@printindex cp + +@c @node MIXAL instructions, , Concept Index, Top +@comment node-name, next, previous, up +@c @unnumbered MIXAL instructions +@c @printindex fn diff --git a/doc/mdk_intro.texi b/doc/mdk_intro.texi new file mode 100644 index 0000000..8d1cfba --- /dev/null +++ b/doc/mdk_intro.texi @@ -0,0 +1,48 @@ +@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 mixasm +MIXAL assembler. Assembler which translates MIXAL source files into +programs that can be run (and debugged) by @code{mixvm} or @code{gmixvm}. +@item mixvm +MIX virtual machine. Emulation of the MIX computer with a @acronym{CLI}. +@item gmixvm +A GTK+ GUI for the MIX virtual machine. Provides all of @code{mixvm} +functionality accessible through a graphical interface. +@item mixvm.el +This elisp program allows running @code{mixvm} inside an Emacs GUD +buffer, allowing concurrent edition and debugging of MIXAL programs. +@end table + +@code{mixvm} and @code{gmixvm} implement 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. diff --git a/doc/mdk_mixasm.texi b/doc/mdk_mixasm.texi new file mode 100644 index 0000000..d48852a --- /dev/null +++ b/doc/mdk_mixasm.texi @@ -0,0 +1,79 @@ +@node mixasm, Copying, mixvm.el, 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 diff --git a/doc/mdk_mixvm.texi b/doc/mdk_mixvm.texi new file mode 100644 index 0000000..56a14fa --- /dev/null +++ b/doc/mdk_mixvm.texi @@ -0,0 +1,478 @@ +@node mixvm, mixvm.el, 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 diff --git a/doc/mdk_tut.texi b/doc/mdk_tut.texi new file mode 100644 index 0000000..f1ff53e --- /dev/null +++ b/doc/mdk_tut.texi @@ -0,0 +1,1259 @@ +@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 + diff --git a/doc/ss_devices.png b/doc/ss_devices.png Binary files differnew file mode 100644 index 0000000..bb2ee83 --- /dev/null +++ b/doc/ss_devices.png diff --git a/doc/ss_mix.png b/doc/ss_mix.png Binary files differnew file mode 100644 index 0000000..9d0e6b6 --- /dev/null +++ b/doc/ss_mix.png diff --git a/doc/ss_mixal.png b/doc/ss_mixal.png Binary files differnew file mode 100644 index 0000000..506a170 --- /dev/null +++ b/doc/ss_mixal.png diff --git a/doc/ss_worddlg.png b/doc/ss_worddlg.png Binary files differnew file mode 100644 index 0000000..be6e7f2 --- /dev/null +++ b/doc/ss_worddlg.png |
