new mixvm commands documented

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