diff options
| -rw-r--r-- | doc/mdk_gstart.texi | 103 |
1 files changed, 84 insertions, 19 deletions
diff --git a/doc/mdk_gstart.texi b/doc/mdk_gstart.texi index b35fea7..9cdebf3 100644 --- a/doc/mdk_gstart.texi +++ b/doc/mdk_gstart.texi @@ -4,7 +4,7 @@ @c Free Software Foundation, Inc. @c See the file mdk.texi for copying conditions. -@c $Id: mdk_gstart.texi,v 1.6 2001/09/13 00:13:39 jao Exp $ +@c $Id: mdk_gstart.texi,v 1.7 2001/09/14 00:41:40 jao Exp $ @node Getting started, mixvm.el, MIX and MIXAL tutorial, Top @chapter Getting started @@ -494,9 +494,9 @@ non-interactive modes. The following subsections provide a quick tour on using this MIX emulator. @menu -* The mixguile shell:: -* Additional functions:: -* Defining new functions:: +* The mixguile shell:: Using the Scheme MIX virtual machine. +* Additional functions:: Scheme functions accessing the VM. +* Defining new functions:: Defining your own Scheme functions. @end menu @node The mixguile shell, Additional functions, Using mixguile, Using mixguile @@ -571,8 +571,56 @@ advantage of the Guile interpreter. @node Additional functions, Defining new functions, The mixguile shell, Using mixguile @subsection Additional MIX Scheme functions +The @code{mix-} function counterparts of the @code{mixvm} commands don't +return any value, and are evaluated only for their side-effects +(possibly including informational messages to the standard output and/or +error stream). When writting your own Scheme functions to manipulate the +MIX virtual machine within @code{mixguile} (@pxref{Defining new +functions}), you'll probably need Scheme functions returning the value +of the registers, memory cells and so on. Don't worry: @code{mixguile} +also offers you such functions. For instance, to access the (numerical) +value of a register you can use @code{mix-reg}: + +@example +guile> (mix-reg 'I2) +0 +guile> +@end example +@noindent +Note that, unlike @code{(mix-preg 'I2)}, the expression @code{(mix-reg +'I2)} in the above example evaluates to a Scheme number and does not +produce any side-effect: + +@example +guile> (number? (mix-reg 'I2)) +#t +guile> (number? (mix-preg 'I2)) +rI2: + 00 00 (0000) +#f +guile> +@end example + +In a similar fashion, you can access the memory contents using +@code{(mix-cell)}, or the program counter using @code{(mix-loc)}: + +@example +guile> (mix-cell 3000) +786957541 +guile> (mix-loc) +3002 +guile> +@end example + +Other functions returning the contents of the virtual machine components +are @code{mix-cmp} and @code{mix-over}, which eval to the value of the +comparison flag and the overflow toggle respectively. For a complete +list of these additional functions, see @xref{mixguile----}. + +In the next section, we'll see a sample of using these functions to +extend @code{mixguile}'s functionality. + @node Defining new functions, , Additional functions, Using mixguile -@subsection Definining new functions +@subsection Defining new functions @cindex Scheme functions Scheme is a powerful language, and you can use it inside @code{mixguile} @@ -629,28 +677,45 @@ Elapsed time: 1 /Total program time: 1 (Total uptime: 45) guile> @end example -As you can see, the possibilities are virtually unlimited. Of course, -you don't need to type a function definition each time you start -@code{mixguile}. You can write it in a file, and load it using Scheme's -@code{load} function. For instance, you can create a file named, say, -@file{functions.scm} with the contents: +As a third example, the following function loads a program, runs it and +prints the contents of the memory between the program's start and end +addresses: @example -(define my-load-and-run-with-bp - (lambda (file line) - (mix-load file) - (mix-sbp line) - (mix-run))) +guile> (define my-run + (lambda (file) + (mix-load file) + (let ((start (mix-loc))) + (mix-run) + (mix-pmem start (mix-loc))))) +guile> (my-run "hello") +Program loaded. Start address: 3000 +Running ... +MIXAL HELLO WORLD +... done +Elapsed time: 11 /Total program time: 11 (Total uptime: 11) +3000: + 46 58 00 19 37 (0786957541) +3001: + 00 00 00 02 05 (0000000133) +3002: + 14 09 27 01 13 (0237350989) +guile> @end example + +As you can see, the possibilities are virtually unlimited. Of course, +you don't need to type a function definition each time you start +@code{mixguile}. You can write it in a file, and load it using Scheme's +@code{load} function. For instance, you can create a file named, say, +@file{functions.scm} with your definitions (or any Scheme expression) and load it at the @code{mixguile} prompt: @example guile> (load "functions.scm") @end example +Alternatively, you can make @code{mixguile} to load it for you. When +@code{mixguile} starts, it looks for a file named @file{mixguile.scm} in +your MDK configuration directory (@file{~/.mdk}) and, if it exists, +loads it before entering the REPL. Therefore, you can copy your +definitions in that file, or load the @file{functions.scm} file in +@file{mixguile.scm}. - -As a third example, the following function loads a program, runs it and -prints the contents of the memory between the program's start and end -addresses: |