update for version 0.2

1 files changed, 286 insertions, 31 deletions

diff --git a/doc/mdk.texi b/doc/mdk.texi
index 650fe97..d481ae4 100644
--- a/doc/mdk.texi
+++ b/doc/mdk.texi
@@ -14,7 +14,7 @@
 This file documents the the @sc{mdk} utilities for developing
 programs using Donald Knuth's MIX language.
 
-Copyright (C) 2000 @value{JAO}
+Copyright (C) 2000, 2001 @value{JAO}
 
 Permission is granted to make and distribute verbatim copies of
 this manual provided the copyright notice and this permission notice
@@ -49,7 +49,7 @@ approved by the Free Software Foundation.
 
 @page
 @vskip 0pt plus 1filll
-Copyright @copyright{} 2000 @value{JAO}
+Copyright @copyright{} 2000, 2001 @value{JAO}
 
 Permission is granted to make and distribute verbatim copies of
 this manual provided the copyright notice and this permission notice
@@ -120,12 +120,14 @@ MIX instruction set
 * Conversion operators::        
 * Shift operators::             
 * Miscellaneous operators::     
+* Execution times::             
 
 MIXAL
 
 * 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.
 
@@ -148,6 +150,12 @@ Running the program
 * Commands::                    Commands available in interactive mode.
 * Devices::                     MIX block devices implementation.
 
+Interactive commands 
+
+* File commands::               Loading and executing programs.
+* Debug commands::              Debugging programs.
+* State commands::              Inspecting the virtual machine state.
+
 @code{mixasm}, the MIXAL assembler
 
 * Invoking @code{mixasm}::      @code{mixasm} options
@@ -406,6 +414,7 @@ available to the MIX programmer.
 * Conversion operators::        
 * Shift operators::             
 * Miscellaneous operators::     
+* Execution times::             
 @end menu
 
 @node Instruction structure, Loading operators, MIX instruction set, MIX instruction set
@@ -494,7 +503,6 @@ 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
@@ -945,7 +953,7 @@ Note that the sign is unaffected by shift operations. On the other hand,
 [rA] = + 04 05 06 07 08  [rX] = - 09 10 00 00 00
 @end example
 
-@node Miscellaneous operators,  , Shift operators, MIX instruction set
+@node Miscellaneous operators, Execution times, Shift operators, MIX instruction set
 @comment  node-name,  next,  previous,  up
 @subsubsection Miscellaneous operators
 @cindex miscellaneous operators
@@ -966,6 +974,52 @@ Halt. Stops instruction fetching. OPCODE = 5, MOD = 2.
 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
@@ -996,6 +1050,7 @@ provided by @sc{mdk} are described later on (@pxref{Getting started}).
 * 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
@@ -1097,6 +1152,11 @@ 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
@@ -1175,7 +1235,7 @@ MSG       ALF  "THIS "   MSG gets defined here
 @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
+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}).
@@ -1198,7 +1258,7 @@ space, as in
 LABEL     LDA   100  This is also a comment
 @end example
 
-@node Expressions, Local symbols, MIXAL directives, MIXAL
+@node Expressions, W-expressions, MIXAL directives, MIXAL
 @comment  node-name,  next,  previous,  up
 @subsection Expressions
 @cindex operator
@@ -1254,7 +1314,67 @@ e.g.
 S1       LD1  2000
 @end example
 
-@node Local symbols, Literal constants, Expressions, MIXAL
+@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
@@ -1321,8 +1441,9 @@ ST		NOP
 
 MIXAL allows the introduction of @dfn{literal constants}, which are
 automatically stored in memory addresses after the end of the program by
-the assembler. Literal constants are denoted as @code{=exp=}, where
-@code{exp} is an expression. For instance, the code
+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
@@ -1502,6 +1623,7 @@ mixvm -r hello @key{RET}
 
 @example
 MIXAL HELLO WORLD
+** Execution time: 11
 @end example
 
 @noindent Since our hello world program uses MIX's device number 19 as
@@ -1509,7 +1631,9 @@ 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.
+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,
@@ -1526,6 +1650,7 @@ mixvm -d -r hello
 
 @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)
@@ -1536,9 +1661,10 @@ Overflow: F
 Cmp: E
 @end example
 
-@noindent which, in addition to the program's outputs, gives you the
-contents of the MIX registers and the values of the overflow toggle and
-comparison flag (admittedly, rather uninteresting in our sample).
+@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
@@ -1594,21 +1720,27 @@ 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:
+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 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
+@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
@@ -1683,16 +1815,27 @@ Program loaded. Start address: 3000
 MIX > pc
 Current address: 3000
 MIX > next
-MIXAL HELLO WORLD                                                     
+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
-End of program reached at address 3002
+MIXAL HELLO WORLD
+Elapsed time: 1 /Total program time: 1 (Total uptime: 12)
 MIX > 
-@end example
+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,
@@ -1707,9 +1850,11 @@ 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
 
@@ -1749,7 +1894,10 @@ MSG:  3002
 MIX > 
 @end example
 
-For a complete description of all available MIX commands, @xref{mixvm}.
+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}.
 
 
 
@@ -1848,12 +1996,13 @@ MIX >
 @noindent
 which indicates that a new virtual machine has been initialised and is
 ready to execute your commands. As we have already mentioned, this
-command prompt offers you command line editing facilities as described
-in the Readline user's manual (chances are that you are already familiar
-with these command line editing capabilities, as they are present in
-many GNU utilities, e.g. the @code{bash} shell). As a beginner, your
-best friend will be the @code{help} command, which shows you a summary
-of all available MIX commands and their usage; its syntax is as follows:
+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]
@@ -1861,8 +2010,18 @@ 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 file, as well as manipulate MIXAL source files:
+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
@@ -1902,7 +2061,7 @@ again from the beginning.
 
 @deffn {file command} edit file[.mixal]
 The source file @var{file.mixal} is edited using the editor defined in
-the environment variable @var{MIX_EDITOR}. If this variable is not set,
+the 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
@@ -1912,6 +2071,11 @@ 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:
 
@@ -2000,6 +2164,97 @@ 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: