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.texi100
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)