summaryrefslogtreecommitdiffhomepage
diff options
context:
space:
mode:
-rw-r--r--doc/mdk_gstart.texi103
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: