diff options
Diffstat (limited to 'doc/mdk_gstart.texi')
| -rw-r--r-- | doc/mdk_gstart.texi | 100 |
1 files changed, 50 insertions, 50 deletions
diff --git a/doc/mdk_gstart.texi b/doc/mdk_gstart.texi index f04e5c1..d315279 100644 --- a/doc/mdk_gstart.texi +++ b/doc/mdk_gstart.texi @@ -1,19 +1,19 @@ @c -*-texinfo-*- @c This is part of the GNU MDK Reference Manual. -@c Copyright (C) 2000, 2001, 2002 +@c Copyright (C) 2000, 2001, 2002, 2003 @c Free Software Foundation, Inc. @c See the file mdk.texi for copying conditions. -@c $Id: mdk_gstart.texi,v 1.13 2002/04/08 00:26:38 jao Exp $ +@c $Id: mdk_gstart.texi,v 1.14 2003/06/02 23:20:38 jao Exp $ -@node Getting started, mixvm.el, MIX and MIXAL tutorial, Top +@node Getting started, mixal-mode.el, MIX and MIXAL tutorial, Top @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 and its assembly language MIXAL (as described in Knuth's TAOCP) is -assumed; for a compact reminder, see @ref{MIX and MIXAL tutorial}. +assumed; for a compact reminder, see @ref{MIX and MIXAL tutorial}. @menu * Writing a source file:: A sample MIXAL source file. @@ -22,7 +22,7 @@ assumed; for a compact reminder, see @ref{MIX and MIXAL tutorial}. * Running the program:: Running and debugging your programs. * Using mixguile:: Using the Scheme interpreter to run and debug your programs. -* Using Scheme in mixvm and gmixvm:: +* Using Scheme in mixvm and gmixvm:: @end menu @node Writing a source file, Compiling, Getting started, Getting started @@ -50,7 +50,7 @@ MSG ALF "MIXAL" (9) ALF "LD " (12) END START end of the program (13) @end example - + @noindent MIXAL source files should have the extension @file{.mixal} when used with the @sc{mdk} utilities. As you can see in the above sample, each line in a MIXAL file can be divided into four fields @@ -86,14 +86,14 @@ an optional free text comment. @noindent Lines 9-12 of the @file{hello.mixal} file above also show the second (and last) difference between Knuth's MIXAL definition and ours: the operand of the @code{ALF} pseudoinstruction (a word of five -characters) must be quoted with using ""@footnote{In Knuth's definition, +characters) must be quoted using ""@footnote{In Knuth's definition, the operand always starts at a fixed column number, and the use of quotation is therefore unnecessary. As @code{mixasm} releases this requirement, marking the beginning and end of the @code{ALF} operand disambiguates the parser's recognition of this operand when it includes blanks. Note that double-quotes (") are not part of the MIX character set, and, therefore, no escape characters are needed within -@code{ALF}'s operands.}. +@code{ALF}'s operands.}. The workings of this sample program should be straightforward if you are familiar with MIXAL. See TAOCP vol. 1 for a thorough definition or @@ -200,7 +200,7 @@ and written its output there@footnote{The device files are stored, by default, in a directory called @file{.mdk}, which is created in your home directory the first time @code{mixvm} is run. You can change this default directory using the command @code{devdir} when running -@code{mixvm} in interactive mode (@pxref{Configuration commands})}. +@code{mixvm} in interactive mode (@pxref{Configuration commands})}. The virtual machine can also report the execution time of the program, according to the (virtual) time spent in each of the binary instructions @@ -237,9 +237,9 @@ MIXAL HELLO WORLD 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) +rI1: + 00 00 (0000) rI2: + 00 00 (0000) +rI3: + 00 00 (0000) rI4: + 00 00 (0000) +rI5: + 00 00 (0000) rI6: + 00 00 (0000) Overflow: F Cmp: E @end example @@ -314,10 +314,10 @@ have guessed, the @code{run} command: @example MIX > run Running ... -MIXAL HELLO WORLD +MIXAL HELLO WORLD ... done Elapsed time: 11 /Total program time: 11 (Total uptime: 11) -MIX > +MIX > @end example @noindent Note that now the timing statistics are richer. You obtain the @@ -385,7 +385,7 @@ and @code{help COMMAND} for help on a specific command, e.g. @example MIX > help run run Run loaded or given MIX code file. Usage: run [FILENAME] -MIX > +MIX > @end example @noindent @@ -421,7 +421,7 @@ Current address: 3002 MIX > next MIXAL HELLO WORLD Elapsed time: 1 /Total program time: 1 (Total uptime: 12) -MIX > +MIX > MIX > run Running ... ... done @@ -446,7 +446,7 @@ MIX > sbpa 3001 Breakpoint set at address 3001 MIX > run Running ... -MIXAL HELLO WORLD +MIXAL HELLO WORLD ... stopped: breakpoint at line 8 (address 3001) Elapsed time: 1 /Total program time: 1 (Total uptime: 23) MIX > run @@ -468,7 +468,7 @@ source code lines using the command @code{sbp LINE_NO}, e.g. @example MIX > sbp 4 Breakpoint set at line 7 -MIX > +MIX > @end example @noindent @@ -496,7 +496,7 @@ MIX > psym START: 3000 TERM: 19 MSG: 3002 -MIX > +MIX > @end example Other useful commands for debugging are @code{strace} (which turns on @@ -519,7 +519,7 @@ using this MIX emulator. * Additional functions:: Scheme functions accessing the VM. * Defining new functions:: Defining your own Scheme functions. * Hook functions:: Using command and break hook functions. -* Scheme scripts:: +* Scheme scripts:: @end menu @node The mixguile shell, Additional functions, Using mixguile, Using mixguile @@ -552,7 +552,7 @@ simply enter @example guile> (mix-load "hello") Program loaded. Start address: 3000 -guile> +guile> @end example @noindent and run it using @code{mix-run}: @@ -560,10 +560,10 @@ and run it using @code{mix-run}: @example guile> (mix-run) Running ... -MIXAL HELLO WORLD +MIXAL HELLO WORLD ... done Elapsed time: 11 /Total program time: 11 (Total uptime: 11) -guile> +guile> @end example @noindent In the same way, you can execute it step by step using the Scheme @@ -572,7 +572,7 @@ function @code{mix-next} or set a breakpoint: @example guile> (mix-sbp 4) Breakpoint set at line 5 -guile> +guile> @end example @noindent or, if you one to peek at a register contents: @@ -580,7 +580,7 @@ or, if you one to peek at a register contents: @example guile> (mix-preg 'A) rA: + 00 00 00 00 00 (0000000000) -guile> +guile> @end example You get the idea: you have at your disposal all the @code{mixvm} and @@ -607,7 +607,7 @@ value of a register you can use @code{mix-reg}: @example guile> (mix-reg 'I2) 0 -guile> +guile> @end example @noindent Note that, unlike @code{(mix-preg 'I2)}, the expression @code{(mix-reg @@ -618,9 +618,9 @@ produce any side-effect: guile> (number? (mix-reg 'I2)) #t guile> (number? (mix-preg 'I2)) -rI2: + 00 00 (0000) +rI2: + 00 00 (0000) #f -guile> +guile> @end example In a similar fashion, you can access the memory contents using @@ -631,7 +631,7 @@ guile> (mix-cell 3000) 786957541 guile> (mix-loc) 3002 -guile> +guile> @end example Other functions returning the contents of the virtual machine components @@ -659,7 +659,7 @@ guile> (define my-load-and-run @key{RET} (mix-pprog) @key{RET} (mix-run) @key{RET} (mix-preg))) @key{RET} -guile> +guile> @end example @noindent and use it to run your programs: @@ -669,16 +669,16 @@ guile> (my-load-and-run "hello") Program loaded. Start address: 3000 File loaded: hello.mix Running ... -MIXAL HELLO WORLD +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> +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 @@ -702,7 +702,7 @@ guile> 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: +addresses: @example guile> (define my-run @@ -714,13 +714,13 @@ guile> (define my-run guile> (my-run "hello") Program loaded. Start address: 3000 Running ... -MIXAL HELLO WORLD +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> +guile> @end example @@ -755,8 +755,8 @@ interruption events. The following sections give you a tutorial on using hook functions within @code{mixguile}. @menu -* Command hooks:: -* Break hooks:: +* Command hooks:: +* Break hooks:: @end menu @node Command hooks, Break hooks, Hook functions, Hook functions @@ -814,13 +814,13 @@ hooks, we would write: @noindent Assuming we have put the above expressions in @code{mixguile}'s initialisation file, we would obtain the following results when -evaluating @code{mix-next}: +evaluating @code{mix-next}: @example guile> (mix-next) -MIXAL HELLO WORLD -Stopped at line 6: HLT -guile> +MIXAL HELLO WORLD +Stopped at line 6: HLT +guile> @end example As a second, more elaborated, example, let's define hooks which print @@ -906,10 +906,10 @@ executing @code{mix-next} will yield the following result: guile> (mix-next 5) next invoked with arguments (5) slog invoked with arguments (off) -MIXAL HELLO WORLD +MIXAL HELLO WORLD Stopped at line 7: MSG ALF "MIXAL" slog invoked with arguments (on) -guile> +guile> @end example Adventurous readers may see the above global hook as the beginning of a @@ -995,9 +995,9 @@ Elapsed time: 190908 /Total program time: 190908 (Total uptime: 190908) rA: + 30 30 30 30 30 (0511305630) rX: + 30 30 32 32 39 (0511313959) rJ: + 47 18 (3026) -rI1: + 00 00 (0000) rI2: + 55 51 (3571) -rI3: + 00 19 (0019) rI4: + 31 51 (2035) -rI5: + 00 00 (0000) rI6: + 00 00 (0000) +rI1: + 00 00 (0000) rI2: + 55 51 (3571) +rI3: + 00 19 (0019) rI4: + 31 51 (2035) +rI5: + 00 00 (0000) rI6: + 00 00 (0000) Overflow: F Cmp: L $ @@ -1032,7 +1032,7 @@ Program loaded. Start address: 3000 MIX > (define a (mix-loc)) MIX > run Running ... -MIXAL HELLO WORLD +MIXAL HELLO WORLD ... done Elapsed time: 11 /Total program time: 11 (Total uptime: 11) MIX > (mix-pmem a) |