summaryrefslogtreecommitdiffhomepage
path: root/doc/mdk_gstart.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/mdk_gstart.texi')
-rw-r--r--doc/mdk_gstart.texi239
1 files changed, 222 insertions, 17 deletions
diff --git a/doc/mdk_gstart.texi b/doc/mdk_gstart.texi
index 70ded05..b35fea7 100644
--- a/doc/mdk_gstart.texi
+++ b/doc/mdk_gstart.texi
@@ -4,9 +4,11 @@
@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 $
+
@node Getting started, mixvm.el, MIX and MIXAL tutorial, Top
-@comment node-name, next, previous, up
@chapter Getting started
+@cindex tutorial
In this chapter, you will find a sample code-compile-run-debug session
using the @sc{mdk} utilities. Familiarity with the MIX mythical computer
@@ -17,14 +19,16 @@ assumed; for a compact reminder, see @ref{MIX and MIXAL tutorial}.
* Writing a source file:: A sample MIXAL source file.
* Compiling:: Using @code{mixasm} to compile source
files into binary format.
-* Running the program:: Running and debugging your program.
+* Running the program:: Running and debugging your programs.
+* Using mixguile:: Using the Scheme interpreter to run and
+ debug your programs.
@end menu
@node Writing a source file, Compiling, Getting started, Getting started
-@comment node-name, next, previous, up
@section Writing a source file
@cindex MIXAL
@cindex source file
+@cindex .mixal file
MIXAL programs can be written as ASCII files with your editor of choice.
Here you have the mandatory @emph{hello world} as written in the MIXAL
@@ -87,10 +91,9 @@ blanks}.
The workings of this sample program should be straightforward if you are
familiar with MIXAL. See TAOCP vol. 1 for a thorought definition or
-@ref{MIX and MIXAL tutorial}, for a quick tutorial.
+@ref{MIX and MIXAL tutorial}, for a tutorial.
@node Compiling, Running the program, Writing a source file, Getting started
-@comment node-name, next, previous, up
@section Compiling
@cindex compiling
@cindex binary programs
@@ -98,18 +101,20 @@ familiar with MIXAL. See TAOCP vol. 1 for a thorought definition or
@cindex assembler
@cindex @code{mixasm}
-A simulator of the MIX computer, called @code{mixvm} (MIX virtual
-machine) is included in the @sc{mdk} tools. It is able to run binary
-files containing MIX instructions written in their binary
+Three simulators of the MIX computer, called @code{mixvm}, @code{gmixvm}
+and @code{mixguile}, are included in the @sc{mdk} tools. They are able to
+run binary files containing MIX instructions written in their binary
representation. You can translate MIXAL source files into this binary
form using @code{mixasm}, the MIXAL assembler. So, in order to compile
-the @file{hello.mixal} file, you can type the following
-command at your shell prompt:
+the @file{hello.mixal} file, you can type the following command at your
+shell prompt:
@example
mixasm -g hello @key{RET}
@end example
+@cindex .mix file
+
If the source file contains no errors, this will produce a binary file
called @file{hello.mix} which can be loaded and run by the MIX virtual
machine. The @code{-g} flag tells the assembler to include debug
@@ -118,18 +123,34 @@ the compilation options, see @ref{mixasm}.) Now, your are ready to run
your first MIX program, as described in the following section.
-@node Running the program, , Compiling, Getting started
-@comment node-name, next, previous, up
+@node Running the program, Using mixguile, Compiling, Getting started
@section Running the program
@cindex @code{mixvm}
@cindex non-interactive mode
@cindex interactive mode
MIX is a mythical computer, so it is no use ordering it from your
-favorite hardware provider. @sc{mdk} provides a software simulator of
-the computer, though. It is called @code{mixvm}, which stands for
-@dfn{MIX virtual machine}. Using it, you can run your MIXAL programs,
-after compiling them with @code{mixasm} into binary @file{.mix}
+favorite hardware provider. @sc{mdk} provides three software simulators of
+the computer, though. They are
+
+@itemize @bullet
+@item
+@code{mixvm}, a command line oriented simulator,
+@item
+@code{gmixvm}, a GTK based graphical interface to @code{mixvm}, and
+@item
+@code{mixguile}, a Guile shell with a built-in MIX simulator.
+@end itemize
+
+All three simulators accept the same set of user commands, but offer a
+different user interface, as noted above. In this section we shall
+describe some of these commands, and show you how to use them from
+@code{mixvm}'s command line. You can use them as well at @code{gmixvm}'s
+command prompt (@pxref{gmixvm}), or using the built-in Scheme primitives
+of @code{mixguile} (@pxref{Using mixguile}).
+
+Using the MIX simulators, you can run your MIXAL programs, after
+compiling them with @code{mixasm} into binary @file{.mix}
files. @code{mixvm} can be used either in @dfn{interactive} or
@dfn{non-interactive} mode. In the second case, @code{mixvm} will load
your program into memory, execute it (producing any output due to MIXAL
@@ -242,6 +263,7 @@ all utilities using this library (for a complete description of
readline's line editing usage, see @ref{Command Line
Editing,,,Readline}.)
+@cindex @code{load}
Usually, the first thing you will want to do is loading a compiled MIX
program into memory. This is acomplished by the @code{load} command,
which takes as an argument the name of the @file{.mix} file to be
@@ -258,12 +280,14 @@ and set the program counter to the address of the first instruction. You
can obtain the contents of the program counter using the command
@code{pc}:
+@cindex @code{pc}
@example
MIX > pc
Current address: 3000
MIX >
@end example
+@cindex @code{run}
After loading it, you are ready to run the program, using, as you surely
have guessed, the @code{run} command:
@@ -294,6 +318,7 @@ Current address: 3002
MIX >
@end example
+@cindex @code{pmem}
@noindent You can check the contents of a memory cell giving its address
as an argument of the command @code{pmem}, like this
@@ -320,6 +345,7 @@ MIX > pmem 3000-3006
MIX >
@end example
+@cindex @code{preg}
@noindent
In a similar manner, you can look at the contents of the MIX registers
and flags. For instance, to ask for the contents of the A register you
@@ -331,6 +357,7 @@ rA: + 00 00 00 00 00 (0000000000)
MIX >
@end example
+@cindex @code{help}
@noindent
Use the comand @code{help} to obtain a list of all available commands,
and @code{help COMMAND} for help on a specific command, e.g.
@@ -350,6 +377,7 @@ over commands useful for debugging your programs.
@comment node-name, next, previous, up
@subsection Debugging commands
+@cindex @code{next}
The interactive mode of @code{mixvm} lets you step by step execution of
programs as well as breakpoint setting. Use @code{next} to step through
the program, running its instructions one by one. To run our
@@ -383,6 +411,9 @@ MIX > @end example
(As an aside, the above sample also shows how the virtual machine
handles cummulative time statistics and automatic program restart).
+@cindex @code{sbpa}
+@cindex breakpoints
+
You can set a breakpoint at a given address using the command
@code{sbpa} (set breakpoint at address). When a breakpoint is set,
@code{run} will stop before executing the instruction at the given
@@ -404,6 +435,8 @@ Elapsed time: 10 /Total program time: 11 (Total uptime: 33)
MIX >
@end example
+@cindex @code{sbp}
+@cindex breakpoints
@noindent
Note that, since we compiled @file{hello.mixal} with debug info enabled
(the @code{-g} flag of @code{mixasm}), the virtual machine is able to
@@ -429,6 +462,7 @@ execution whenever a register, a memory cell, the comparison flag or the
overflow toggle change using the commands @w{@code{sbp[rmco]}}
(@pxref{Debug commands}).
+@cindex @code{psym}
MIXAL lets you define symbolic constants, either using the @code{EQU}
pseudoinstruction or starting an instruction line with a label (which
assigns to the label the value of the current memory address). Each
@@ -444,8 +478,179 @@ MSG: 3002
MIX >
@end example
-Other useful commands for debugging are @code{tracing} (which turns on
+Other useful commands for debugging are @code{strace} (which turns on
tracing of executed intructions), @code{pbt} (which prints a backtrace
of executed instructions) and @code{weval} (which evaluates
w-expressions on the fly). For a complete description of all available
MIX commands, @xref{mixvm}.
+
+@node Using mixguile, , Running the program, Getting started
+@section Using @code{mixguile}
+
+With @code{mixguile} you can run a MIX simulator embedded in a Guile
+shell, that is, using Scheme functions and programs. As with
+@code{mixvm}, @code{mixguile} can be run both in interactive and
+non-interactive modes. The following subsections provide a quick tour on
+using this MIX emulator.
+
+@menu
+* The mixguile shell::
+* Additional functions::
+* Defining new functions::
+@end menu
+
+@node The mixguile shell, Additional functions, Using mixguile, Using mixguile
+@subsection The @code{mixguile} shell
+@cindex Scheme
+@cindex @code{mixguile}
+@cindex REPL
+
+If you simply type
+
+@example
+mixguile @key{RET}
+@end example
+@noindent
+at the command prompt, you'll be presented a Guile shell prompt like
+this
+
+@example
+guile>
+@end example
+@noindent
+At this point, you have entered a Scheme read-eval-print loop (REPL)
+which offers you all the Guile functionality plus a new set of built-in
+procedures to execute and debug MIX programs. Each of the @code{mixvm}
+commands described in the previous sections (and in @pxref{mixvm}) have
+a Scheme function counterpart named after it by prepending the prefix
+@code{mix-} to its name. Thus, to load our hello world program, you can
+simply enter
+
+@example
+guile> (mix-load "hello")
+Program loaded. Start address: 3000
+guile>
+@end example
+@noindent
+and run it using @code{mix-run}:
+
+@example
+guile> (mix-run)
+Running ...
+MIXAL HELLO WORLD
+... done
+Elapsed time: 11 /Total program time: 11 (Total uptime: 11)
+guile>
+@end example
+@noindent
+In the same way, you can execute it step by step using the Scheme
+function @code{mix-next} or set a breakpoint:
+
+@example
+guile> (mix-sbp 4)
+Breakpoint set at line 5
+guile>
+@end example
+@noindent
+or, if you one to peek at a register contents:
+
+@example
+guile> (mix-preg 'A)
+rA: + 00 00 00 00 00 (0000000000)
+guile>
+@end example
+
+You get the idea: you have at your disposal all the @code{mixvm} and
+@code{gmixvm} commands by means of @code{mix-} functions. But, in case
+you are wondering, this is only the beginning. You also have at your
+disposal a whole Scheme interpreter, and you can, for instance, define
+new functions combining the @code{mix-} and all other Scheme
+primitives. In the next sections, you'll find examples of how to take
+advantage of the Guile interpreter.
+
+@node Additional functions, Defining new functions, The mixguile shell, Using mixguile
+@subsection Additional MIX Scheme functions
+
+@node Defining new functions, , Additional functions, Using mixguile
+@subsection Definining new functions
+@cindex Scheme functions
+
+Scheme is a powerful language, and you can use it inside @code{mixguile}
+to easily extend the MIX interpreter's capabilities. For example, you
+can easily define a function that loads a file, prints its name,
+executes it and, finally, shows the registers contents, all in one shot:
+
+@example
+guile> (define my-load-and-run @key{RET}
+ (lambda (file) @key{RET}
+ (mix-load file) @key{RET}
+ (display "File loaded: ") @key{RET}
+ (mix-pprog) @key{RET}
+ (mix-run) @key{RET}
+ (mix-preg))) @key{RET}
+guile>
+@end example
+@noindent
+and use it to run your programs:
+
+@example
+guile> (my-load-and-run "hello")
+Program loaded. Start address: 3000
+File loaded: hello.mix
+Running ...
+MIXAL HELLO WORLD
+... done
+Elapsed time: 11 /Total program time: 11 (Total uptime: 33)
+rA: + 00 00 00 00 00 (0000000000)
+rX: + 00 00 00 00 00 (0000000000)
+rJ: + 00 00 (0000)
+rI1: + 00 00 (0000) rI2: + 00 00 (0000)
+rI3: + 00 00 (0000) rI4: + 00 00 (0000)
+rI5: + 00 00 (0000) rI6: + 00 00 (0000)
+guile>
+@end example
+
+
+Or, maybe, you want a function which sets a breakpoint at a specified
+line number before executing it:
+
+@example
+guile> (define my-load-and-run-with-bp
+ (lambda (file line)
+ (mix-load file)
+ (mix-sbp line)
+ (mix-run)))
+guile> (my-load-and-run-with-bp "samples/primes" 10)
+Program loaded. Start address: 3000
+Breakpoint set at line 10
+Running ...
+... stopped: breakpoint at line 10 (address 3001)
+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:
+
+@example
+(define my-load-and-run-with-bp
+ (lambda (file line)
+ (mix-load file)
+ (mix-sbp line)
+ (mix-run)))
+@end example
+
+and load it at the @code{mixguile} prompt:
+
+@example
+guile> (load "functions.scm")
+@end example
+
+
+
+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: