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