partial doc update

1 files changed, 368 insertions, 1 deletions

diff --git a/doc/mdk_mixguile.texi b/doc/mdk_mixguile.texi
index 4939f9c..7637dc0 100644
--- a/doc/mdk_mixguile.texi
+++ b/doc/mdk_mixguile.texi
@@ -4,8 +4,375 @@
 @c   Free Software Foundation, Inc.
 @c See the file mdk.texi for copying conditions.
 
-@c $Id: mdk_mixguile.texi,v 1.1 2001/09/18 22:53:18 jao Exp $
+@c $Id: mdk_mixguile.texi,v 1.2 2001/09/26 23:13:15 jao Exp $
 
 @node mixguile, Problems, gmixvm, Top
 @chapter @code{mixguile}, the Scheme virtual machine
+@cindex @code{mixguile}
 
+This chapter provides a reference to using @code{mixguile} and the
+Scheme function library giving access to the MIX virtual machine in the
+@sc{mdk} emulators (@code{mixguile}, @code{mixvm} and @code{gmixvm}). See
+@ref{Using mixguile} for a tutorial, step by step introduction to
+@code{mixguile} and using Scheme as an extension language for the
+@sc{mdk} MIX virtual machines.
+
+@menu
+* Invoking mixguile::           Command line options.
+* Scheme functions reference::  Scheme functions accessing the VM.
+@end menu
+
+@node Invoking mixguile, Scheme functions reference, mixguile, mixguile
+@section Invoking @code{mixguile}
+@cindex @code{mixguile} options
+
+Invoking @code{mixguile} without arguments will enter the Guile REPL
+(read-eval-print loop) after loading, if it exists, the user's
+initialisation file (@file{~/.mdk/mixguile.scm}).
+
+@code{mixguile} accepts the same command line options than Guile:
+
+@example
+mixguile [-s SCRIPT] [-c EXPR] [-l FILE] [-e FUNCTION] [-qhv]
+         [--help] [--version]
+@end example
+
+The meaning of these options is as follows:
+
+@defopt -h
+@defoptx --help
+Prints usage summary and exits.
+@end defopt
+
+@defopt -v
+@defoptx --version
+Prints version and copyleft information and exits.
+@end defopt
+
+@defopt -s SCRIPT
+Loads Scheme code from @var{script}, evaluates it and exits. This option
+can be used to write executable Scheme scripts, as described in
+@ref{Scheme scripts}.
+@end defopt
+
+@defopt -c EXPR
+Evaluates the given Scheme expression and exits.
+@end defopt
+
+@defopt -l FILE
+Loads the given Scheme file and enters the REPL (read-eval-print loop).
+@end defopt
+
+@defopt -e FUNCTION
+After reading the script, executes the given function using the provided
+command line arguments. For instance, you can write the following Scheme
+script:
+
+@example
+#! /usr/bin/mixguile \
+-e main -s
+!#
+
+;;; execute a given program and print the registers.
+
+(define main
+  (lambda (args)
+    ;; load the file provided as a command line argument
+    (mix-load (cadr args))
+    ;; execute it
+    (mix-run)
+    ;; print the contents of registers
+    (mix-pall)))
+
+@end example
+@noindent
+save it in a file called, say, @file{foo}, make it executable, and run
+it as
+
+@example
+$ ./foo hello
+@end example
+@noindent
+This invocation will cause the evaluation of the @code{main} function
+with a list of command line parameters as its argument (@code{("./foo"
+"hello")} in the above example. Note that command line options to
+mixguile must be written in their own line after the @code{\} symbol.
+@end defopt
+
+@defopt -q
+Do not load user's initialisation file. When @code{mixguile} starts up,
+it looks for a file named @file{mixguile.scm} in the user's @sc{mdk}
+configuration directory (@file{~/.mdk}), and loads it if it exists. This
+option tells @code{mixguile} to skip this initialisation file loading.
+@end defopt
+
+
+@node Scheme functions reference,  , Invoking mixguile, mixguile
+@section Scheme functions reference
+
+As we have previously pointed out, @code{mixguile} embeds a MIX virtual
+machine that can be accessed through a set of Scheme functions, that is,
+of a Scheme library. Conversely, @code{mixvm} and @code{gmixvm} contain
+a Guile interpreter, and are able to use this same Scheme library, as
+well as all the other Guile/Scheme primitives and any user defined
+function. Therefore, you have at your disposal a powerful programming
+language, Scheme, to extend the @sc{mdk} virtual machine emulators (see
+@ref{Using Scheme in mixvm and gmixvm} for samples of how to do it).
+
+The following subsections describe available functions the MIX/Scheme
+library.
+
+@menu
+* mixvm wrappers::              Functions invoking mixvm commands.
+* Additional VM functions::     Functions accessing the MIX virtual machine.
+* Hooks::                       Adding hooks to mixvm commands.
+@end menu
+
+@node mixvm wrappers, Additional VM functions, Scheme functions reference, Scheme functions reference
+@subsection @code{mixvm} command wrappers
+
+For each of the @code{mixvm} commands listed in @ref{Commands}, there is
+a corresponding Scheme function named by prefixing the command name with
+@code{mix-} (e.g., @code{mix-load}, @code{mix-run} and so on). These
+command wrappers are implemented using a generic command dispatching
+function:
+
+@defun mixvm-cmd command argument
+Dispatchs the given @var{command} to the MIX virtual appending the
+provided @var{argument}. Both @var{command} and @code{argument} must be
+strings. The net result is as writing "@var{command} @var{argument}" at
+the @code{mixvm} or @code{gmixvm} command prompt.
+@end defun
+
+For instance, you can invoke the @code{run} command at the @code{mixvm}
+prompt in three equivalent ways:
+
+@example
+MIX > run hello
+MIX > (mix-run "hello")
+MIX > (mixvm-cmd "run" "hello")
+@end example
+@noindent
+(only the two last forms can be used at the @code{mixguile} prompt or
+inside a Scheme script).
+
+The @code{mix-} functions evaluate to a unspecified value. If you want
+to check the result of the last @code{mixvm} command invocation, use the
+@code{mix-last-result} function:
+
+@defun mix-last-result
+Returns @var{#t} if the last @code{mixvm} command invocation was
+successful, @var{#f} otherwise.
+@end defun
+@noindent
+Using this function, we could improve the script for running a program
+presented in the previous section by adding error checking:
+
+
+@example
+#! /usr/bin/mixguile \
+-e main -s
+!#
+
+;;; Execute a given program and print the registers.
+
+(define main
+  (lambda (args)
+    ;; load the file provided as a command line argument
+    (mix-load (cadr args))
+    ;; execute it if mix-load succeeded
+    (if (mix-last-result) (mix-run))
+    ;; print the contents of registers if the above commands succeded
+    (if (mix-last-result) (mix-pall))))
+@end example
+
+Please, refer to @ref{Commands} for a list of available commands. Given
+the description of a @code{mixvm}, it is straightforward to use its
+Scheme counterpart and, therefore, we shall not give a complete
+description of these functions here. Instead, we will only mention those
+wrappers that exhibit a treatment of their differing from that of their
+command counterpart.
+
+@defun mix-preg [register]
+@defunx mix-sreg register value
+The argument @var{register} of these functions can be either a string or
+a symbol representing the desired register. For instance, the following
+invocations are equivalent:
+
+@example
+(mix-preg 'I1)
+(mix-preg "I1")
+@end example
+@end defun
+
+@defun mix-pmem from [to]
+The command @code{pmem} takes a single argument which can be either a
+cell number or a range of the form @code{FROM-TO}. This function takes
+one argument to ask for a single memory cell contents, or two parameters
+to ask for a range. For instance, the following commands are equivalent:
+
+@example
+MIX > pmem 10-12
+0010: + 00 00 00 00 00 (0000000000)
+0011: + 00 00 00 00 00 (0000000000)
+0012: + 00 00 00 00 00 (0000000000)
+MIX > (mix-pmem 10 12)
+0010: + 00 00 00 00 00 (0000000000)
+0011: + 00 00 00 00 00 (0000000000)
+0012: + 00 00 00 00 00 (0000000000)
+MIX >
+@end example
+@end defun
+
+@defun mix-sover #t|#f
+The command @code{sover} takes as argument either the string @code{T} or
+the string @code{F}, to set, respectively, the overflow toggle to true
+or false. Its Scheme counterpart, @code{mix-sover}, takes as argument
+a Scheme boolean value: @code{#t} (true) or @code{#f}.
+@end defun
+
+For the remaining functions, you simply must take into account that when
+the command arguments are numerical, the corresponding Scheme function
+takes as arguments Scheme number literals. On the other hand, when the
+command argument is a string, the argument of its associated Scheme
+function will be a Scheme string. By way of example, the following
+invocations are pairwise equivalent:
+
+@example
+MIX > load ../samples/hello
+MIX > (mix-load "../samples/hello)
+
+MIX > next 5
+MIX > (mix-next 5)
+@end example
+
+@node Hooks,  , Additional VM functions, Scheme functions reference
+@subsection Hook functions
+
+Hooks are functions evaluated before or after executing a @code{mixvm}
+command (or its corresponding Scheme function wrapper), or after an
+explicit or conditional breakpoint is found during the execution of a
+MIX program. The following functions let you install hooks:
+
+@defun mix-add-pre-hook command hook
+Adds a function to the list of pre-hooks associated with the give
+@var{command}. @var{command} is a string naming the corresponding @code{mixvm}
+command, and @var{hook} is a function which takes a single argument: a
+string list of the commands arguments. The following scheme code defines
+a simple hook and associates it with the @code{run} command:
+
+@example
+(define run-hook
+  (lambda (args)
+    (display "argument list: ")
+    (display args)
+    (newline)))
+(mix-add-pre-hook "run" run-hook)
+@end example
+
+Pre-hooks are executed, in the order they are added, before invoking the
+corresponding command (or its associated Scheme wrapper function).
+@end defun
+
+@defun mix-add-post-hook command hook
+Adds a function to the list of pre-hooks associated with the give
+@var{command}. The arguments have the same meaning as in
+@code{mix-add-pre-hook}.
+@end defun
+
+@defun mix-add-global-pre-hook hook
+@defunx mix-add-global-post-hook hook
+Global pre/post hooks are executed before/after any @code{mixvm} command
+or function wrapper invocation. In this case, @var{hook} takes two
+arguments: a string with the name of the command being invoked, and a
+string list with its arguments.
+@end defun
+
+@defun mix-add-break-hook hook
+@defunx mix-add-cond-break hook
+Add a hook funtion to be executed when an explicit (resp. conditional)
+breakpoint is encountered during program execution. @var{hook} is a
+function taking two arguments: the source line number where the hook has
+occurred, and the current program counter value. The following code
+shows a simple definition and installation of a break hook:
+
+@example
+(define break-hook
+  (lambda (line address)
+    (display "Breakpoint at line ") (display line)
+    (display " and address ") (display address)
+    (newline)))
+(mix-add-break-hook break-hook)
+@end example
+
+Break hook functions are entirely implemented in Scheme using regular
+post-hooks for the @code{next} and @code{run} commands. If you are
+curious, you can check the Scheme source code at
+@file{@emph{prefix}/share/mdk/mixguile-vm-stat.scm} (where @emph{prefix}
+stands for your root install directory, usualy @code{/usr} or
+@code{/usr/local}. 
+@end defun
+
+
+See @ref{Hook functions} for further examples on using hook functions.
+
+
+@node Additional VM functions, Hooks, mixvm wrappers, Scheme functions reference
+@subsection Additional VM functions
+
+When writing non-trivial Scheme extensions using the MIX/Scheme library,
+you will probably need to evaluate the contents of the virtual machine
+components (registers, memory cells and so on). For instance, you may
+need to store the contents of the @code{A} register in a variable. The
+Scheme functions described so far are of no help: you can print the
+contents of @code{A} using @code{(mix-preg 'A)}, but you cannot define a
+variable containing the contents of @code{A}. To address this kind of
+problems, the MIX/Scheme library provides the following additional
+functions: 
+
+@defun mixvm-status
+@end defun
+
+@defun mix-reg register
+@defunx mix-set-reg! register value
+@end defun
+
+@defun mix-cell cell_no
+@defunx mix-set-cell cell_no value
+@end defun
+
+@defun mix-loc
+@end defun
+
+@defun mix-over
+@defunx mix-set-over! #t|#f
+@end defun
+
+@defun mix-cmp
+@defun mix-set-cmp! 'L|'E|'G
+@end defun
+
+@defun mix-up-time
+@end defun
+
+@defun mix-lap-time
+@end defun
+
+@defun mix-prog-time
+@end defun
+
+@defun mix-prog-name
+@end defun
+
+@defun mix-prog-path
+@end defun
+
+@defun mix-src-path
+@end defun
+
+@defun mix-src-line
+@defunx mix-src-line-no
+@end defun
+
+@defun mix-ddir
+@end defun