summaryrefslogtreecommitdiffhomepage
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/mdk.texi317
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: