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