mdk_gstart.texi

汇编语言编程源代码

@example
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}.

@node Hook functions, Scheme scripts, Defining new functions, Using mixguile
@subsection Hook functions
@cindex hook function
@cindex pre-hook
@cindex post-hook

Hooks are functions called before or after a given event occurs. In
@code{mixguile}, you can define command and break hooks, which are
associated, respectively, with command execution and program
interruption events. The following sections give you a tutorial on using
hook functions within @code{mixguile}.

@menu
* Command hooks::               
* Break hooks::                 
@end menu

@node Command hooks, Break hooks, Hook functions, Hook functions
@subsubsection Command hooks

In the previous section, we have seen how to extend @code{mixguile}'s
functionality through the use of user defined functions. Frequently,
you'll write new functions that improve in some way the workings of a
built-in @code{mixvm} command, following this pattern:

@enumerate a
@item
Prepare the command execution
@item
Execute the desired command
@item
Perform post execution operations
@end enumerate

We call the functions executed in step (a) @dfn{pre-hook}s, and those of
step @dfn{post-hook}s of the given command. @code{mixguile} lets you
specify pre- and post-hooks for any @code{mixvm} command using the
@code{mix-add-pre-hook} and  @code{mix-add-post-hook} functions, which
take as arguments a symbol naming the command and a function to be
executed before (resp. after) the command. In other words,
@code{mixguile} will execute for you steps (a) and (c) above whenever
you eval (b). The hook functions must take a single argument, which is a
string list of the command's arguments. As an example, let us define the
following hooks for the @code{next} command:

@example
(define next-pre-hook
  (lambda (arglist)
    (mix-slog #f)))

(define next-post-hook
  (lambda (arglist)
    (display "Stopped at line ")
    (display (mix-src-line-no))
    (display ": ")
    (display (mix-src-line))
    (newline)
    (mix-slog #t)))
@end example
@noindent
In these functions, we are using the function @code{mix-slog} to turn
off the informational messages produced by the virtual machine, since we
are providing our own ones in the post hook function. To install these
hooks, we would write:

@example
(mix-add-pre-hook 'next next-pre-hook)
(mix-add-post-hook 'next next-post-hook)
@end example
@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}: 

@example
guile> (mix-next)
MIXAL HELLO WORLD                                                     
Stopped at line 6:             HLT   
guile> 
@end example

As a second, more elaborated, example, let's define hooks which print
the address and contents of a cell being modified using @code{smem}. The
hook functions could be something like this:

@example
(define smem-pre-hook
  (lambda (arglist)
    (if (eq? (length arglist) 2)
        (begin
          (display "Changing address ")
          (display (car arglist))
          (newline)
          (display "Old contents: ")
          (display (mix-cell (string->number (car arglist))))
          (newline))
        (error "Wrong arguments" arglist))))

(define smem-post-hook
  (lambda (arglist)
    (if (eq? (length arglist) 2)
        (begin
          (display "New contents: ")
          (display (mix-cell (string->number (car arglist))))
          (newline)))))
@end example
@noindent
and we can install them using

@example
(mix-add-pre-hook 'smem smem-pre-hook)
(mix-add-post-hook 'smem smem-post-hook)
@end example
@noindent
Aferwards, a sample execution of @code{mix-smem} would look like this:

@example
guile> (mix-smem 2000 100)
Changing address 2000
Old contents: 0
New contents: 100
guile>
@end example

@cindex global hook

You can add any number of hooks to a given command. They will be
executed in the same order as they are registered. You can also define
global post (pre) hooks, which will be called before (after) any
@code{mixvm} command is executed. Global hook functions must admit two
arguments, namely, a string naming the invoked command and a string list
of its arguments, and they are installed using the Scheme functions
@code{mix-add-global-pre-hook} and @code{mix-add-global-post-hook}. A
simple example of global hook would be:

@example
guile> (define pre-hook
         (lambda (cmd args)
           (display cmd)
           (display " invoked with arguments ")
           (display args)
           (newline)))
guile> (mix-add-global-pre-hook pre-hook)
ok
guile> (mix-pmem 120 125)
pmem invoked with arguments (120-125)
0120: + 00 00 00 00 00 (0000000000)
0121: + 00 00 00 00 00 (0000000000)
0122: + 00 00 00 00 00 (0000000000)
0123: + 00 00 00 00 00 (0000000000)
0124: + 00 00 00 00 00 (0000000000)
0125: + 00 00 00 00 00 (0000000000)
guile>
@end example

Note that if you invoke @code{mixvm} commands within a global hook, its
associated command hooks will be run. Thus, if you have installed both
the @code{next} hooks described earlier and the global hook above,
executing @code{mix-next} will yield the following result:

@example
guile> (mix-next 5)
next invoked with arguments (5)
slog invoked with arguments (off)
MIXAL HELLO WORLD                                                     
Stopped at line 7: MSG         ALF   "MIXAL"
slog invoked with arguments (on)
guile> 
@end example

Adventurous readers may see the above global hook as the beginning of a
command log utility or a macro recorder that saves your commands for
replay.

@node Break hooks,  , Command hooks, Hook functions
@subsubsection Break hooks

@cindex break hook

We have seen in the previous section how to associate hooks to command
execution, but they are not the whole story. You can also associate hook
functions to program interruption, that is, specify functions that
should be called every time the execution of a MIX program is stopped
due to the presence of a breakpoint, either explicit or
conditional. Break hooks take as arguments the line number and memory
address at which the break occurred. A simple hook that logs the line
and address of the breakpoint could be defined as:

@example
(define break-hook
  (lambda (line address)
    (display "Breakpoint encountered at line ")
    (display line)
    (display " and address ")
    (display address)
    (newline)))
@end example
@noindent
and installed for explicit and conditional breakpoints using

@example
(mix-add-break-hook break-hook)
(mix-add-cond-break-hook break-hook)
@end example
@noindent
after that, every time the virtual machine encounters a breakpoint,
@code{break-code} shall be evaluated for you@footnote{You may have
noticed that break hooks can be implemented in terms of command hooks
associated to @code{mix-run} and @code{mix-next}. As a matter of fact,
they @emph{are} implemented this way: take a look at the file
@file{@emph{install_dir}/share/mdk/mix-vm-stat.scm} if you are curious.}.

@node Scheme scripts,  , Hook functions, Using mixguile
@subsection Scheme scripts
@cindex Scheme script
@cindex non-interactive

Another useful way of using @code{mixguile} is writing executable
scripts that perform a set of commands for you. This is done using the
@code{mixguile} switch @code{-s} (being a Guile shell, @code{mixguile}
accepts all the command options of @code{guile}; type @code{mixguile -h}
for a list of all available command options). For instance, if you have
a very useful MIX program @file{foo.mix} which you want to run often,
you don't have to fire a MIX virtual machine, load and run it every
time; you can write a Scheme script instead:

@example
#! /usr/bin/mixguile -s
!#
;;; runprimes: execute the primes.mix program

;; load the file you want to run
(mix-load "../samples/primes")
;; execute it
(mix-run)
;; print the contents of registers
(mix-pall)
;; ...
@end example

Just save the above script to a file named, say, @file{runtest}, make it
executable (@code{chmod +x runtest}), and, well, execute it from the
Unix shell:

@example
$ ./runtest
Program loaded. Start address: 3000
Running ...
... done
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)     
Overflow: F
Cmp: L
$
@end example

Note that this is far more flexible that running programs
non-interactively using @code{mixvm} (@pxref{Non-interactive mode}), for
you can execute any combination of commands you want from a Scheme
script (not just running and dumping the registers). For additional
@code{mixguile} command line options, see @ref{Invoking mixguile}.

@node Using Scheme in mixvm and gmixvm,  , Using mixguile, Getting started
@section  Using Scheme in @code{mixvm} and @code{gmixvm}
@cindex @code{scmf}

In the previous section (@pxref{Using mixguile}) we have seen how the
Guile shell @code{mixguile} offers you the possibility of using Scheme
to manipulate a MIx virtual machine and extend the set of commands
offered by @code{mixvm} and @code{gmixvm}. This possibility is not
limited to the @code{mixguile} shell. Actually, both @code{mixvm} and
@code{gmixvm} incorporate an embedded Guile interpreter, and can
evaluate Scheme expressions. To evaluate a single-line expression at the
@code{mixvm} or @code{gmixvm} command prompt, simply write it and press
return (the command parser will recognise it as a Scheme expression
because it is parenthesized, and will pass it to the Guile
interpreter). A sample @code{mixvm} session using Scheme expressions
could be:

@example
MIX > load hello
Program loaded. Start address: 3000
MIX > (define a (mix-loc))
MIX > run
Running ...
MIXAL HELLO WORLD                                                     
... done
Elapsed time: 11 /Total program time: 11 (Total uptime: 11)
MIX > (mix-pmem a)
3000: + 46 58 00 19 37 (0786957541)
MIX > (mix-pmem (mix-loc))
3002: + 14 09 27 01 13 (0237350989)
MIX >
@end example

You can also load and evaluate a file, using the @code{scmf}
command like this:

@example
MIX> scmf /path/to/file/file.scm
@end example

Therefore, you have at your disposal all the @code{mixguile} goodies
described above (new functions, new command definitions, hooks...)
inside @code{mixvm} and @code{gmixvm}. In other words, these programs
are extensible using Scheme. See @ref{Using mixguile} for examples of
how to do it.