diff options
Diffstat (limited to 'doc/mdk_gstart.texi')
| -rw-r--r-- | doc/mdk_gstart.texi | 239 |
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: |