diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/.cvsignore | 1 | ||||
| -rw-r--r-- | doc/mdk.texi | 22 | ||||
| -rw-r--r-- | doc/mdk_ack.texi | 4 | ||||
| -rw-r--r-- | doc/mdk_copying.texi | 2 | ||||
| -rw-r--r-- | doc/mdk_gstart.texi | 148 | ||||
| -rw-r--r-- | doc/mdk_index.texi | 4 | ||||
| -rw-r--r-- | doc/mdk_install.texi | 2 | ||||
| -rw-r--r-- | doc/mdk_intro.texi | 4 |
8 files changed, 164 insertions, 23 deletions
diff --git a/doc/.cvsignore b/doc/.cvsignore index 0128ab7..3c56128 100644 --- a/doc/.cvsignore +++ b/doc/.cvsignore @@ -15,6 +15,7 @@ mdk.info-1 mdk.info-2 mdk.info-3 mdk.info-4 +mdk.info-5 mdk.ky mdk.log mdk.pg diff --git a/doc/mdk.texi b/doc/mdk.texi index 6999267..58afc1d 100644 --- a/doc/mdk.texi +++ b/doc/mdk.texi @@ -102,6 +102,7 @@ helpful discussions, as well as actual code (@pxref{mixvm.el}). @menu * Introduction:: +* Acknowledgments:: * Installing MDK:: Installing GNU MDK from the source tarball. * MIX and MIXAL tutorial:: Learn the innards of MIX and MIXAL. * Getting started:: Basic usage of the @sc{mdk} tools. @@ -111,7 +112,6 @@ helpful discussions, as well as actual code (@pxref{mixvm.el}). * mixasm:: Invoking the MIXAL assembler. * Problems:: Reporting bugs. * Copying:: @sc{mdk} licensing terms. -* Acknowledgments:: * Concept Index:: Index of concepts. * Instructions and commands:: Index of MIXAL instructions and MIXVM commands. @@ -132,6 +132,9 @@ helpful discussions, as well as actual code (@pxref{mixvm.el}). + + + @detailmenu --- The Detailed Node Listing --- @@ -187,6 +190,7 @@ Getting started * 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:: Running the program @@ -196,9 +200,15 @@ Running the program Using @code{mixguile} -* The mixguile shell:: -* Additional functions:: -* Defining new functions:: +* The mixguile shell:: Using the Scheme MIX virtual machine. +* Additional functions:: Scheme functions accessing the VM. +* Defining new functions:: Defining your own Scheme functions. +* Hook functions:: + +Hook functions + +* Command hooks:: +* Break hooks:: @code{mixvm}, the MIX computer simulator @@ -235,6 +245,7 @@ Copying @end menu @include mdk_intro.texi +@include mdk_ack.texi @include mdk_install.texi @include mdk_tut.texi @include mdk_gstart.texi @@ -244,7 +255,6 @@ Copying @include mdk_mixasm.texi @include mdk_bugs.texi @include mdk_copying.texi -@include mdk_ack.texi @include mdk_index.texi @include mdk_findex.texi @@ -252,4 +262,4 @@ Copying @contents @bye -$Id: mdk.texi,v 1.13 2001/09/13 00:13:39 jao Exp $ +$Id: mdk.texi,v 1.14 2001/09/16 22:17:33 jao Exp $ diff --git a/doc/mdk_ack.texi b/doc/mdk_ack.texi index 4145694..cba9251 100644 --- a/doc/mdk_ack.texi +++ b/doc/mdk_ack.texi @@ -4,9 +4,9 @@ @c Free Software Foundation, Inc. @c See the file mdk.texi for copying conditions. -@c $Id: mdk_ack.texi,v 1.2 2001/09/14 00:48:29 jao Exp $ +@c $Id: mdk_ack.texi,v 1.3 2001/09/16 22:17:33 jao Exp $ -@node Acknowledgments, Concept Index, Copying, Top +@node Acknowledgments, Installing MDK, Introduction, Top @comment node-name, next, previous, up @unnumbered Acknowledgements diff --git a/doc/mdk_copying.texi b/doc/mdk_copying.texi index bfb6b34..bbcd225 100644 --- a/doc/mdk_copying.texi +++ b/doc/mdk_copying.texi @@ -1,4 +1,4 @@ -@node Copying, Acknowledgments, Problems, Top +@node Copying, Concept Index, Problems, Top @appendix Copying @menu diff --git a/doc/mdk_gstart.texi b/doc/mdk_gstart.texi index 67758f5..14a88d9 100644 --- a/doc/mdk_gstart.texi +++ b/doc/mdk_gstart.texi @@ -4,7 +4,7 @@ @c Free Software Foundation, Inc. @c See the file mdk.texi for copying conditions. -@c $Id: mdk_gstart.texi,v 1.8 2001/09/15 02:14:01 jao Exp $ +@c $Id: mdk_gstart.texi,v 1.9 2001/09/16 22:17:33 jao Exp $ @node Getting started, mixvm.el, MIX and MIXAL tutorial, Top @chapter Getting started @@ -22,6 +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:: @end menu @node Writing a source file, Compiling, Getting started, Getting started @@ -484,7 +485,7 @@ 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 +@node Using mixguile, Using Scheme in mixvm and gmixvm, Running the program, Getting started @section Using @code{mixguile} With @code{mixguile} you can run a MIX simulator embedded in a Guile @@ -497,6 +498,7 @@ using this MIX emulator. * The mixguile shell:: Using the Scheme MIX virtual machine. * Additional functions:: Scheme functions accessing the VM. * Defining new functions:: Defining your own Scheme functions. +* Hook functions:: @end menu @node The mixguile shell, Additional functions, Using mixguile, Using mixguile @@ -620,7 +622,7 @@ list of these additional functions, In the next section, we'll see a sample of using these functions to extend @code{mixguile}'s functionality. -@node Defining new functions, , Additional functions, Using mixguile +@node Defining new functions, Hook functions, Additional functions, Using mixguile @subsection Defining new functions @cindex Scheme functions @@ -720,12 +722,26 @@ 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 +@node Hook functions, , 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 @@ -787,11 +803,9 @@ Stopped at line 6: HLT guile> @end example -You can add any number of hooks to a given command. They will be -executed in the same order as they are registered. 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: +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 @@ -832,3 +846,119 @@ 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 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). 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. + diff --git a/doc/mdk_index.texi b/doc/mdk_index.texi index 9c3a1db..5aaecc4 100644 --- a/doc/mdk_index.texi +++ b/doc/mdk_index.texi @@ -4,9 +4,9 @@ @c Free Software Foundation, Inc. @c See the file mdk.texi for copying conditions. -@c $Id: mdk_index.texi,v 1.4 2001/09/13 00:13:39 jao Exp $ +@c $Id: mdk_index.texi,v 1.5 2001/09/16 22:17:33 jao Exp $ -@node Concept Index, Instructions and commands, Acknowledgments, Top +@node Concept Index, Instructions and commands, Copying, Top @unnumbered Concept Index @cindex tail recursion diff --git a/doc/mdk_install.texi b/doc/mdk_install.texi index a9aa9a8..2874d79 100644 --- a/doc/mdk_install.texi +++ b/doc/mdk_install.texi @@ -4,7 +4,7 @@ @c Free Software Foundation, Inc. @c See the file mdk.texi for copying conditions. -@node Installing MDK, MIX and MIXAL tutorial, Introduction, Top +@node Installing MDK, MIX and MIXAL tutorial, Acknowledgments, Top @comment node-name, next, previous, up @chapter Installing @sc{mdk} diff --git a/doc/mdk_intro.texi b/doc/mdk_intro.texi index 5464980..c86ca18 100644 --- a/doc/mdk_intro.texi +++ b/doc/mdk_intro.texi @@ -4,9 +4,9 @@ @c Free Software Foundation, Inc. @c See the file mdk.texi for copying conditions. -@c $Id: mdk_intro.texi,v 1.4 2001/09/13 00:13:39 jao Exp $ +@c $Id: mdk_intro.texi,v 1.5 2001/09/16 22:17:33 jao Exp $ -@node Introduction, Installing MDK, Top, Top +@node Introduction, Acknowledgments, Top, Top @comment node-name, next, previous, up @unnumbered Introduction @cindex Introduction |