diff options
Diffstat (limited to 'doc/mdk_mixvm.texi')
| -rw-r--r-- | doc/mdk_mixvm.texi | 139 |
1 files changed, 102 insertions, 37 deletions
diff --git a/doc/mdk_mixvm.texi b/doc/mdk_mixvm.texi index 67c429c..61b7d1c 100644 --- a/doc/mdk_mixvm.texi +++ b/doc/mdk_mixvm.texi @@ -4,7 +4,7 @@ @c Free Software Foundation, Inc. @c See the file mdk.texi for copying conditions. -@c $Id: mdk_mixvm.texi,v 1.7 2001/09/13 00:13:39 jao Exp $ +@c $Id: mdk_mixvm.texi,v 1.8 2001/09/17 23:36:45 jao Exp $ @node mixvm, gmixvm, mixvm.el, Top @comment node-name, next, previous, up @@ -89,7 +89,10 @@ mode. The first time @code{mixvm} is invoked, a directory named @file{.mdk} is created in your home directory. It contains the @code{mixvm} configuration file, the command history file and (by default) the block -devices files (@pxref{Devices}). +devices files (@pxref{Devices}). Before showing you the command prompt, +@code{mixvm} looks in the @file{~/.mdk} directory for a file named +@code{mixguile.scm}; if it exists, it is read and evaluated by the +embedded Guile interpreter (@pxref{Defining new functions}). @node Commands, Devices, Invocation, mixvm @comment node-name, next, previous, up @@ -123,7 +126,6 @@ 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, @code{help} prints the short description for all available commands. @@ -137,7 +139,6 @@ all available commands. @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 @@ -199,9 +200,30 @@ command can be set using the @code{sasm} command (@pxref{Configuration commands}). @end deffn +@deffn {file command} pprog +@deffnx {file command} psrc +Print the path of the currently loaded MIX program and its source file: + +@example +MIX > load ../samples/primes +Program loaded. Start address: 3000 +MIX > pprog +../samples/primes.mix +MIX > psrc +/home/jao/projects/mdk/gnu/samples/primes.mixal +MIx> +@end example +@end deffn + +Finally, you can use the @code{quit} command to exit @code{mixvm}: + +@deffn {file command} quit +Exit @code{mixvm}, saving the current configuration parameters in +@file{~/.mdk/mixvm.config}. +@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 @@ -340,21 +362,18 @@ arguments, @code{psym} will print all defined symbols and their values. The virtual machine can also show you the instructions it is executing, using the following commands: -@deffn {debug command} tracing [on|off] -@code{tracing on} enables instruction tracing. When tracing is enabled, +@deffn {debug command} strace [on|off] +@code{strace on} 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 disabled with @code{tracing off} -command. When run without arguments, @code{tracing} shows the current -tracing status. A typical tracing session could be like this: +file. Instruction tracing is disabled with @code{strace off} +command. A typical tracing session could be like this: @example -MIX > tracing on -MIX > tracing -Instruction tracing is currently ON. +MIX > strace on MIX > next 3000: [OUT 3002,0(2:3)] START OUT MSG(TERM) MIXAL HELLO WORLD @@ -363,9 +382,7 @@ 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 > tracing off -MIX > tracing -Instruction tracing is currently OFF. +MIX > strace off MIX > @end example @noindent @@ -375,6 +392,21 @@ actual MIXAL code that was compiled into the executed instruction. The tracing behaviour is stored as a configuration parameter in @file{~/.mdk}. @end deffn +@deffn {debug command} pline [LINE_NUMBER] +Prints the requested source line (or the current one if +@var{line_number} is omitted: + +@example +MIX > load ../samples/hello +Program loaded. Start address: 3000 +MIX > pline +Line 5: START OUT MSG(TERM) +MIX > pline 6 +Line 6: HLT +MIX > +@end example +@end deffn + @deffn {debug command} pbt [INS_NUMBER] This command prints a backtrace of executed instructions. Its optional argument @var{ins_number} is the number of instructions to print. If it @@ -419,12 +451,12 @@ MIX > @end example Note that the executed instruction trace gives you the label of the -executed line or, if it has no label, the its address. +executed line or, if it has no label, its address. @end deffn As you have probably observed, @code{mixvm} prints timing statistics when running programs. This behaviour can be controlled using the -@code{timing} command (@pxref{Configuration commands}). +@code{stime} command (@pxref{Configuration commands}). @code{mixvm} is also able of evaluating w-expressions (@pxref{W-expressions}) using the following command: @@ -443,6 +475,7 @@ MIX > @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 @@ -480,21 +513,39 @@ MIX > @end deffn @node State commands, Configuration 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} pstat +This commands prints the current virtual machine state, which can be one +of the following: +@itemize @minus +@item +No program loaded +@item +Program successfully loaded +@item +Execution stopped (@code{next} executed) +@item +Execution stopped: breakpoint encountered +@item +Execution stopped: conditional breakpoint encountered +@item +Program successfully terminated +@end itemize +@end deffn + @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]] +@deffn {state command} sreg A | X | J | I[1-6] value +@deffnx {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: @@ -519,7 +570,7 @@ 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 +maximum value storable in the given register, @code{VALUE mod MAXIMU_VALUE} is stored, e.g. @example @@ -577,29 +628,38 @@ representation of the module of the stored value. @end deffn -Finally, you can use the @code{quit} command to exit @code{mixvm}. - @node Configuration commands, , State commands, Commands -@comment node-name, next, previous, up @subsection Configuration commands This section describes commands that allow you to configure the virtual machine behaviour. This configuration is stored in the @sc{mdk} directory @file{~/.mdk}. -@deffn {config command} timing [on|off] -This command (un)sets the printing of timing statistics. When run -without argument, it prints the current timing statistics. +As you can see in their description, some commands print, as a side +effect, informational messages to the standard output (e.g. @code{load} +prints a message telling you the loaded program's start address): these +messages can be enabled/disabled using @code{slog}: + +@deffn {config command} slog on|off +Turns on/off the logging of informational messages. Note that error +messages are always displayed, as well as state messages required using +commands prefixed with @code{p} (@code{preg}, @code{pmem} and the like). +@end deffn + +@deffn {config command} stime on|off +@deffnx {config command} ptime +The @code{stime} command (un)sets the printing of timing statistics, and +@code{ptime} prints their current value: @example -MIX > timing +MIX > ptime Elapsed time: 10 /Total program time: 11 (Total uptime: 11) MIX > @end example @end deffn @deffn {config command} sedit TEMPLATE -@deffnx pedit +@deffnx {config command} pedit @code{sedit} sets the command to be used to edit MIXAL source files with the @code{edit} command. @var{TEMPLATE} must contain the control characters @code{%s} to mark the place where the source's file name will @@ -618,7 +678,7 @@ the operating system command @w{@code{emacsclient foo.mixal}}. @end deffn @deffn {config command} sasm TEMPLATE -@deffnx pasm +@deffnx {config command} pasm @code{sasm} sets the command to be used to compile MIXAL source files with the @code{compile} command. @var{template} must contain the control characters @code{%s} to mark the place where the source's file name will @@ -636,15 +696,20 @@ the operating system command @w{@code{mixasm -g -l foo.mixal}}. @end deffn -@deffn {config command} devdir [DIRNAME] -MIX devices (@pxref{Devices}) are implemented as regular files -stored, by default, inside @file{~/.mdk}. This command lets you specify -an alternative location for storing these device files. When run without -arguments, @code{devdir} prints the current device directory. +@deffn {config command} sddir DIRNAME +@deffnx {config command} pddir +MIX devices (@pxref{Devices}) are implemented as regular files stored, +by default, inside @file{~/.mdk}. The @code{sddir} command lets you +specify an alternative location for storing these device files, while +@code{pddir} prints the current device directory. @end deffn +@node Scheme commands +@subsection Scheme commands + +:TODO: guile scripts + @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 |