From bdee72222da97c3d3c553232dc2a98c035ad1e2f Mon Sep 17 00:00:00 2001 From: Jose Antonio Ortega Ruiz Date: Tue, 18 Sep 2001 22:53:18 +0000 Subject: partial doc update --- NEWS | 27 +++++++++++++++- doc/mdk.texi | 39 +++++++---------------- doc/mdk_bugs.texi | 4 +-- doc/mdk_emixvm.texi | 4 +-- doc/mdk_gmixvm.texi | 4 +-- doc/mdk_gstart.texi | 88 +++++++++++++++++++++++++++++++++++++++++++++++---- doc/mdk_mixasm.texi | 4 +-- doc/mdk_mixguile.texi | 11 +++++++ doc/mdk_mixvm.texi | 30 +++++++++++++++--- 9 files changed, 163 insertions(+), 48 deletions(-) create mode 100644 doc/mdk_mixguile.texi diff --git a/NEWS b/NEWS index f5cd089..354017d 100644 --- a/NEWS +++ b/NEWS @@ -10,11 +10,36 @@ Please send mdk bug reports to bug-mdk@gnu.org. ** Added guile support. New utility 'mixguile'... +** New (g)mixvm commands: + - psrc: print the current program's source file path + - pprog: print the current program's path + - pline: print the current program line + - pstat: print the current virtual machine status + - slog: set on/off the logging of info messages to stdout (or + the command log in gmixvm) + +** For the sake of coherence, the following (g)mixvm commands + have been renamed: + - tracing -> strace + - timing -> stime (set on/off timing), + ptime (print timing stats) + - devdir -> sddir (set the devices dir), + pddir (print the devices dir) + +** In gmixvm, when a font specified in the config file cannot be + loaded, it is removed from the configuration. + +** Bug fix: when the MIX font is changed in gmixvm, the loc widget + font is correctly updated. + ** Bug fix: help messages are now correctly aligned in (g)mixvm. ** Bug fix: timing statitics for the MOVE instruction are correctly computed. +** Bug fix: pressing return at an empty 'MIX >' prompt does not + produce an error message. + --------------------------------------------------------------------------- * Version 0.4.2 (17/08/01) @@ -265,4 +290,4 @@ Copyright (C) 2000, 2001, Free Software Foundation, Inc. --- -$Id: NEWS,v 1.34 2001/09/16 22:17:33 jao Exp $ +$Id: NEWS,v 1.35 2001/09/18 22:53:18 jao Exp $ diff --git a/doc/mdk.texi b/doc/mdk.texi index 58afc1d..420e37c 100644 --- a/doc/mdk.texi +++ b/doc/mdk.texi @@ -107,33 +107,15 @@ helpful discussions, as well as actual code (@pxref{mixvm.el}). * MIX and MIXAL tutorial:: Learn the innards of MIX and MIXAL. * Getting started:: Basic usage of the @sc{mdk} tools. * mixvm.el:: Using @code{mixvm} within Emacs. +* mixasm:: Invoking the MIXAL assembler. * mixvm:: Invoking and using the MIX virtual machine. * gmixvm:: Invoking and using the GTK+ virtual machine. -* mixasm:: Invoking the MIXAL assembler. +* mixguile:: Invoking and using the Scheme virtual machine. * Problems:: Reporting bugs. * Copying:: @sc{mdk} licensing terms. * Concept Index:: Index of concepts. * Instructions and commands:: Index of MIXAL instructions and MIXVM commands. - - - - - - - - - - - - - - - - - - - @detailmenu --- The Detailed Node Listing --- @@ -203,13 +185,18 @@ Using @code{mixguile} * 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:: Using command and break hook functions. +* Scheme scripts:: Hook functions * Command hooks:: * Break hooks:: +@code{mixasm}, the MIXAL assembler + +* Invoking @code{mixasm}:: @code{mixasm} options + @code{mixvm}, the MIX computer simulator * Invocation:: Options when invoking @code{mixvm}. @@ -222,6 +209,7 @@ Interactive commands * Debug commands:: Debugging programs. * State commands:: Inspecting the virtual machine state. * Configuration commands:: Storing mixvm settings. +* Scheme commands:: @code{gmixvm}, the GTK virtual machine @@ -232,10 +220,6 @@ Interactive commands * MIX devices view:: Device output. * Menu and status bars:: Available menu commands. -@code{mixasm}, the MIXAL assembler - -* Invoking @code{mixasm}:: @code{mixasm} options - Copying * GNU General Public License:: @@ -250,9 +234,10 @@ Copying @include mdk_tut.texi @include mdk_gstart.texi @include mdk_emixvm.texi +@include mdk_mixasm.texi @include mdk_mixvm.texi @include mdk_gmixvm.texi -@include mdk_mixasm.texi +@include mdk_mixguile.texi @include mdk_bugs.texi @include mdk_copying.texi @include mdk_index.texi @@ -262,4 +247,4 @@ Copying @contents @bye -$Id: mdk.texi,v 1.14 2001/09/16 22:17:33 jao Exp $ +$Id: mdk.texi,v 1.15 2001/09/18 22:53:18 jao Exp $ diff --git a/doc/mdk_bugs.texi b/doc/mdk_bugs.texi index 65ceb1a..abf9f89 100644 --- a/doc/mdk_bugs.texi +++ b/doc/mdk_bugs.texi @@ -4,9 +4,9 @@ @c Free Software Foundation, Inc. @c See the file mdk.texi for copying conditions. -@c $Id: mdk_bugs.texi,v 1.3 2001/09/13 00:13:39 jao Exp $ +@c $Id: mdk_bugs.texi,v 1.4 2001/09/18 22:53:18 jao Exp $ -@node Problems, Copying, mixasm, Top +@node Problems, Copying, mixguile, Top @chapter Reporting Bugs @cindex bugs @cindex problems diff --git a/doc/mdk_emixvm.texi b/doc/mdk_emixvm.texi index 111e9de..70e2ae5 100644 --- a/doc/mdk_emixvm.texi +++ b/doc/mdk_emixvm.texi @@ -4,9 +4,9 @@ @c Free Software Foundation, Inc. @c See the file mdk.texi for copying conditions. -@c $Id: mdk_emixvm.texi,v 1.3 2001/09/13 00:13:39 jao Exp $ +@c $Id: mdk_emixvm.texi,v 1.4 2001/09/18 22:53:18 jao Exp $ -@node mixvm.el, mixvm, Getting started, Top +@node mixvm.el, mixasm, Getting started, Top @comment node-name, next, previous, up @chapter mixvm.el diff --git a/doc/mdk_gmixvm.texi b/doc/mdk_gmixvm.texi index b5823bb..a1fbb6f 100644 --- a/doc/mdk_gmixvm.texi +++ b/doc/mdk_gmixvm.texi @@ -4,9 +4,9 @@ @c Free Software Foundation, Inc. @c See the file mdk.texi for copying conditions. -@c $Id: mdk_gmixvm.texi,v 1.12 2001/09/13 00:13:39 jao Exp $ +@c $Id: mdk_gmixvm.texi,v 1.13 2001/09/18 22:53:18 jao Exp $ -@node gmixvm, mixasm, mixvm, Top +@node gmixvm, mixguile, mixvm, Top @comment node-name, next, previous, up @chapter @code{gmixvm}, the GTK virtual machine @cindex @code{gmixvm} diff --git a/doc/mdk_gstart.texi b/doc/mdk_gstart.texi index 14a88d9..1ec501f 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.9 2001/09/16 22:17:33 jao Exp $ +@c $Id: mdk_gstart.texi,v 1.10 2001/09/18 22:53:18 jao Exp $ @node Getting started, mixvm.el, MIX and MIXAL tutorial, Top @chapter Getting started @@ -235,7 +235,9 @@ our sample). As you can see, running programs non-interactively has many limitations. You cannot peek the virtual machine's memory contents, not to mention stepping through your program's instructions or setting -breakpoints. Enter interactive mode. +breakpoints@footnote{The @code{mixguile} program allows you to execute +arbitrary combinations of @code{mixvm} commands (using Scheme) +non-interactively. @xref{Scheme scripts}.}. Enter interactive mode. @node Interactive mode, Debugging, Non-interactive mode, Running the program @comment node-name, next, previous, up @@ -498,7 +500,8 @@ 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:: +* Hook functions:: Using command and break hook functions. +* Scheme scripts:: @end menu @node The mixguile shell, Additional functions, Using mixguile, Using mixguile @@ -616,8 +619,7 @@ guile> Other functions returning the contents of the virtual machine components are @code{mix-cmp} and @code{mix-over}, which eval to the value of the comparison flag and the overflow toggle respectively. For a complete -list of these additional functions, -@c see @xref{mixguile----}. +list of these additional functions, @xref{mixguile}. In the next section, we'll see a sample of using these functions to extend @code{mixguile}'s functionality. @@ -722,7 +724,7 @@ 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, , Defining new functions, Using mixguile +@node Hook functions, Scheme scripts, Defining new functions, Using mixguile @subsection Hook functions @cindex hook function @cindex pre-hook @@ -934,6 +936,59 @@ 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). @node Using Scheme in mixvm and gmixvm, , Using mixguile, Getting started @section Using Scheme in @code{mixvm} and @code{gmixvm} @@ -949,7 +1004,26 @@ 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} +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 diff --git a/doc/mdk_mixasm.texi b/doc/mdk_mixasm.texi index 7d08ef9..e2f7b1b 100644 --- a/doc/mdk_mixasm.texi +++ b/doc/mdk_mixasm.texi @@ -4,9 +4,9 @@ @c Free Software Foundation, Inc. @c See the file mdk.texi for copying conditions. -@c $Id: mdk_mixasm.texi,v 1.3 2001/09/13 00:13:39 jao Exp $ +@c $Id: mdk_mixasm.texi,v 1.4 2001/09/18 22:53:18 jao Exp $ -@node mixasm, Problems, gmixvm, Top +@node mixasm, mixvm, mixvm.el, Top @comment node-name, next, previous, up @chapter @code{mixasm}, the MIXAL assembler @cindex @code{mixasm} diff --git a/doc/mdk_mixguile.texi b/doc/mdk_mixguile.texi new file mode 100644 index 0000000..4939f9c --- /dev/null +++ b/doc/mdk_mixguile.texi @@ -0,0 +1,11 @@ +@c -*-texinfo-*- +@c This is part of the GNU MDK Reference Manual. +@c Copyright (C) 2000, 2001 +@c Free Software Foundation, Inc. +@c See the file mdk.texi for copying conditions. + +@c $Id: mdk_mixguile.texi,v 1.1 2001/09/18 22:53:18 jao Exp $ + +@node mixguile, Problems, gmixvm, Top +@chapter @code{mixguile}, the Scheme virtual machine + diff --git a/doc/mdk_mixvm.texi b/doc/mdk_mixvm.texi index 61b7d1c..28976fa 100644 --- a/doc/mdk_mixvm.texi +++ b/doc/mdk_mixvm.texi @@ -4,9 +4,9 @@ @c Free Software Foundation, Inc. @c See the file mdk.texi for copying conditions. -@c $Id: mdk_mixvm.texi,v 1.8 2001/09/17 23:36:45 jao Exp $ +@c $Id: mdk_mixvm.texi,v 1.9 2001/09/18 22:53:18 jao Exp $ -@node mixvm, gmixvm, mixvm.el, Top +@node mixvm, gmixvm, mixasm, Top @comment node-name, next, previous, up @chapter @code{mixvm}, the MIX computer simulator @@ -136,6 +136,7 @@ all available commands. * Debug commands:: Debugging programs. * State commands:: Inspecting the virtual machine state. * Configuration commands:: Storing mixvm settings. +* Scheme commands:: @end menu @node File commands, Debug commands, Commands, Commands @@ -628,7 +629,7 @@ representation of the module of the stored value. @end deffn -@node Configuration commands, , State commands, Commands +@node Configuration commands, Scheme commands, State commands, Commands @subsection Configuration commands This section describes commands that allow you to configure the virtual @@ -704,10 +705,29 @@ specify an alternative location for storing these device files, while @code{pddir} prints the current device directory. @end deffn -@node Scheme commands +@node Scheme commands, , Configuration commands, Commands @subsection Scheme commands -:TODO: guile scripts +If you have compiled @sc{mdk} with @code{libguile} support +(@pxref{Special configure flags}), @code{mixvm} will start and +initialise an embedded Guile Scheme interpret when it is invoked. That +means that you have at your disposal, at @code{mixvm}'s command prompt, +all the Scheme primitives described in @ref{Using mixguile} and +@ref{mixguile}, as well as any other function or hook that you have +defined in the initialisation file @file{~/.mdk/mixguile.scm}. To +evaluate a Scheme function, simply type it at the @code{mixvm} command +prompt (see @ref{Using Scheme in mixvm and gmixvm} for a +sample). Compared to the @code{mixguile} program, this has only one +limitation: the expressions used in @code{mixvm} cannot span more than +one line. You can get over this inconvenience writing your multiline +Scheme expressions in a file and loading it using the @code{scmf} +command: + +@deffn {scheme command} scmf FILE_NAME +Loads the given Scheme file and evaluates it using the embedded Guile +interpreter. +@end deffn + @node Devices, , Commands, mixvm @section MIX block devices -- cgit v1.2.3