From 300160e73da486946ae513f1d039dcd7b85ff17c Mon Sep 17 00:00:00 2001 From: Jose Antonio Ortega Ruiz Date: Mon, 20 Mar 2006 22:46:46 +0000 Subject: Version 1.2.1 imported git-archimport-id: mdk@sv.gnu.org/mdk--devel--1--patch-1 --- doc/mdk_gmixvm.texi | 394 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 394 insertions(+) create mode 100644 doc/mdk_gmixvm.texi (limited to 'doc/mdk_gmixvm.texi') diff --git a/doc/mdk_gmixvm.texi b/doc/mdk_gmixvm.texi new file mode 100644 index 0000000..bddb362 --- /dev/null +++ b/doc/mdk_gmixvm.texi @@ -0,0 +1,394 @@ +@c -*-texinfo-*- +@c This is part of the GNU MDK Reference Manual. +@c Copyright (C) 2000, 2001, 2003, 2004 +@c Free Software Foundation, Inc. +@c See the file mdk.texi for copying conditions. + +@c $Id: mdk_gmixvm.texi,v 1.18 2004/08/03 13:23:06 jao Exp $ + +@node gmixvm, mixguile, mixvm, Top +@comment node-name, next, previous, up +@chapter @code{gmixvm}, the GTK virtual machine +@cindex @code{gmixvm} +@cindex GUI +@cindex GTK+ + +This chapter describes the graphical MIX virtual machine emulator +shipped with @sc{mdk}. In addition to having all the command-oriented +functionalities of the other virtual machines (@code{mixvm} and +@code{mixguile}), @code{gmixvm} offers you a graphical interface +displaying the status of the virtual machine, the source code of the the +downloaded programs and the contents of the MIX devices. + +@menu +* Invoking gmixvm:: +* MIXVM console:: Using @code{mixvm} commands. +* MIX virtual machine:: The MIX virtual machine window. +* MIXAL source view:: Viewing the MIXAL source code. +* MIX devices view:: Device output. +* Menu and status bars:: Available menu commands. +@end menu + +@node Invoking gmixvm, MIXVM console, gmixvm, gmixvm +@comment node-name, next, previous, up +@section Invoking @code{gmixvm} + +If you have built @sc{mdk} with GTK+ support (@pxref{Installing MDK}), a +graphical front-end for the MIX virtual machine will be available in +your system. You can invoke it by typing + +@example +gmixvm [-vhuq] [--version] [--help] [--usage] [--noinit] +@end example +@noindent +at your command prompt, where the options have the following meanings: + +@defopt -v +@defoptx --version +Prints version and copyleft information and exits. +@end defopt + +@defopt -h +@defoptx --help +@defoptx -u +@defoptx --usage +Prints a summary of available options and exits. +@end defopt + +@defopt -q +@defoptx --noinit +Do not load the Guile initialisation file @code{~/.mdk/mixguile.scm} at +startup. This file contains any local Scheme code to be executed by the +embedded Guile interpreter at startup (@pxref{Using Scheme in mixvm and +gmixvm}). +@end defopt + +Typing @code{gmixvm} or @code{gmixvm -q} at your command prompt, the +main window will appear, offering you a graphical interface to run and +debug your MIX programs. + +@ifinfo +@image{img/ss_mix, 400pt} +@end ifinfo + +@ifhtml +@image{../img/ss_mix, 400pt} +@end ifhtml + +Apart from the menu and status bars, we can distinguish two zones (or +halves) in this main window. In the upper half of @code{gmixvm}'s main +window there is a notebook with three pages, namely, + +@itemize +@item +a MIX virtual machine view, which shows you the registers, flags, memory +contents and time statistics of the virtual machine; +@item +a MIXAL source view, which shows the MIXAL file and lets you manage +breakpoints; +@item +a Devices view, which shows you the output to character based MIX block +devices. +@end itemize + +@noindent +These three windows can be detached from the notebook, using either +the penultimate toolbar button (which detachs the currently visible +notebook page) or the menu entries under @code{@w{View->Detached windows}}. + +@ifhtml +Here is an screenshot showing how @code{gmixvm} looks like when running +with a couple of detached windows: + +@image{../img/ss_split, 420pt} + +@end ifhtml + +On the other hand, the main window's lower half presents you a +@code{mixvm} command prompt and a logging area where results of the +issued commands are presented. These widgets implement a @code{mixvm} +console which offers almost the same functionality as its +@acronym{CLI} counterpart. + +When @code{gmixvm} is run, it creates a directory named @file{.mdk} in +your home directory (if it does not already exist). The @file{.mdk} +directory contains the program settings, the device files used by your +MIX programs (@pxref{Devices}), and a command history file. + +The following sections describe the above mentioned components of +@code{gmixvm}. + +@node MIXVM console, MIX virtual machine, Invoking gmixvm, gmixvm +@comment node-name, next, previous, up +@section MIXVM console + +In the lower half of the @code{gmixvm} main window, you will find a +command text entry and, above it, an echo area. These widgets offer you +the same functionality as its @acronym{CLI} counterpart, @code{mixvm} +(@pxref{mixvm}). You can issue almost all @code{mixmv} commands at the +@code{gmixvm}'s command prompt in order to manipulate the MIX virtual +machine. Please refer to @xref{mixvm}, for a description of these +commands, and to @xref{Getting started}, for a tutorial on using the MIX +virtual machine. The command prompt offers command line completion for +partially typed commands using the @key{TAB} key; e.g., if you type + +@example +lo @key{TAB} +@end example +@noindent +the command is automatically completed to @code{load}. If multiple +completions are available, they will be shown in the echo area. Thus, +typing + +@example +p @key{TAB} +@end example +@noindent +will produce the following output on the echo area: + +@example +Completions: +pc psym preg pflags pall +pmem +@end example +@noindent +which lists all the available commands starting with @code{p}. In +addition, the command prompt maintains a history of typed commands, +which can be recovered using the arrow up and down keys. As mentioned +above, a file containing previous sessions' commands is stored in the +configuration directory @file{~/.mdk}, and reloaded every time you start +@code{gmixvm}. + +You can change the font used to display the issued commands and the +messages in the echo area using the @code{@w{Settings->Change font->Command +prompt}} and @code{@w{Settings->Change font->Command log}} menu commands. + +@node MIX virtual machine, MIXAL source view, MIXVM console, gmixvm +@comment node-name, next, previous, up +@section MIX virtual machine + +The first notebook's page displays the current status of the virtual +machine. There you can find the registers' contents, the value of the +comparison and overflow flags, the location pointer, a list with all MIX +memory cells and their contents, and the time statistics (including +total uptime, elapsed time since the last run command and total +execution time for the currently loaded MIX program). + +If you click any register entry, you will be prompted for a new register's +contents. + +@ifhtml +The next figure shows the enter word dialog. + +@image{../img/ss_worddlg, 250pt} + +@end ifhtml + +In the same manner, click on any address of the memory cells list to be +prompted for the new contents of the clicked cell. If you click the +address column's title, a dialog asking you for a memory address will +appear; if you introduce a valid address, this will be the first cell +displayed in the scrollable list after you click the OK button. + +The register contents are shown as a list of MIX bytes plus sign. If you +place the mouse pointer over any of them, the decimal value of this MIX +word will appear inside a tooltip. + +You can change the font used to display the MIX virtual machine contents +using the @code{@w{Settings->Change font->MIX}} menu command. + +@node MIXAL source view, MIX devices view, MIX virtual machine, gmixvm +@comment node-name, next, previous, up +@section MIXAL source view + +The second notebook's page, dubbed Source, shows you the MIXAL source of +the currently loaded MIX file. + +@ifhtml +@image{../img/ss_mixal, 400pt} +@end ifhtml + +The information is presented in four columns. The first column +displays little icons showing the current program pointer and any set +breakpoints. The second and third columns show the address and memory +contents of the compiled MIX instruction, while the last one displays +its corresponding MIXAL representation, together with the source file +line number. You can set/unset breakpoints by clicking on any line +that has an associated memory address. + +You can change the font used to display the MIXAL source code +using the @code{@w{Settings->Change font->MIXAL}} menu command. + +@node MIX devices view, Menu and status bars, MIXAL source view, gmixvm +@comment node-name, next, previous, up +@section MIX devices view + +The last notebook page, dubbed Devices, shows you the output/input +to/from MIX block devices (the console, line printer, paper tape, +disks, card and tapes @pxref{Devices}) produced by the running +program. + +@ifhtml + +@image{../img/ss_devices, 400pt} + +@end ifhtml + +Input device contents is read from files located in the @file{~/.mdk} +directory, and the output is also written to files at the same +location. Note that device tabs will appear as they are used by the MIX +program being run, and that loading a new MIX program will close all +previously open devices. + +The input/output for binary block devices (tapes and disks) is a list +of MIX words, which can be displayed either in decimal or word format +(e.g. @w{- 67} or @w{- 00 00 00 01 03}). The format used by +@code{gmixvm} can be configured using the @code{@w{Settings->Device output}} +menu command for each binary device. + +You can change the font used to display the devices content +using the @code{@w{Settings->Change font->Devices}} menu command. + +@node Menu and status bars, , MIX devices view, gmixvm +@comment node-name, next, previous, up +@section Menu and status bars + +The menu bar gives you access to the following commands: + +@deffn File Load... +Opens a file dialog that lets you specify a binary MIX file to be loaded +in the virtual machine's memory. It is equivalent to the @code{mixvm}'s +@code{load} command (@pxref{File commands}). +@end deffn + +@deffn File Edit... +Opens a file dialog that lets your specify a MIXAL source file to be +edited. It is equivalent to the @code{mixvm}'s @code{edit} command +(@pxref{File commands}). The program used for editing can be specified +using the menu entry @code{@w{Settings->External programs}}, or using the +@code{mixvm} command @code{sedit}. +@end deffn + +@deffn File Compile... +Opens a file dialog that lets your specify a MIXAL source file to be +compiled. It is equivalent to the @code{mixvm}'s @code{compile} command +(@pxref{File commands}). The command used for compiling can be specified +using the menu entry @code{@w{Settings->External programs}}, or using the +@code{mixvm} command @code{sasm}. +@end deffn + +@deffn File Exit +Exits the application. +@end deffn + +@deffn Debug Run +Runs the currently loaded MIX program, up to the next breakpoint. It is +equivalent to the @code{mixvm}'s @code{run} command (@pxref{Debug +commands}). +@end deffn + +@deffn Debug Next +Executes the next MIX instruction. It is equivalent to the +@code{mixvm}'s @code{next} command (@pxref{Debug commands}). +@end deffn + +@deffn Debug @w{Clear breakpoints} +Clears all currently set breakpoints. It is equivalent to the +@code{mixvm}'s @code{cabp} command. +@end deffn + +@deffn Debug Symbols... +Opens a dialog showing the list of symbols defined in the currently +loaded MIX program. The font used to display this list can be +customised using the meny entry @code{@w{Settings->Change font->Symbol +list}}. + +@ifhtml + +@image{../img/ss_symbols, 250pt} + +@end ifhtml + +@end deffn + +@deffn View @w{Toolbar(s)} +Toggles the toolbar(s) in the @code{gmixvm} window(s) (when notebook +pages are detached, each one has its own toolbar). +@end deffn + +@deffn View @w{Detached windows} @w{Virtual machine} +@deffnx View @w{Detached windows} Source +@deffnx View @w{Detached windows} Devices + +These toggles let you detach (or re-attach) the corresponding notebook +page. + +@end deffn + +@deffn Settings @w{Change font} +Lets you change the font used in the various @code{gmixv} widgets +(i.e. commad prompt, command log, Virtual machine, Source, Devices and +Symbol list). There is also an entry (@code{All}) to change all fonts +at once. +@end deffn + +@deffn Settings @w{Device output...} +Opens a dialog that lets you specify which format shall be used to show +the contents of MIX binary block devices. + +@ifhtml +@image{../img/ss_devform, 250pt} +@end ifhtml + +The available formats are decimal (e.g. @w{-1234}) and MIX word +(e.g. @w{- 00 00 00 19 18}). +@end deffn + +@deffn Settings @w{Devices dir...} +Opens a dialog that lets you choose where the MIX device files will be +stored (@file{~/.mdk} is the default location). + +@ifhtml +@image{../img/ss_devdir, 250pt} +@end ifhtml + +You can also specify the devices directory using the @code{mixvm} +command @code{sddir} (@pxref{Configuration commands}). + +@end deffn + +@deffn Settings @w{External programs...} +This menu command opens a dialog that lets you specify the commands used +for editing and compiling MIXAL source files. + +@ifhtml +@image{../img/ss_extprog, 250pt} +@end ifhtml + +The commands are specified as template strings, where the control +substring @code{%s} will be substituted by the actual file name. Thus, +if you want to edit programs using @code{vi} running in an @code{xterm}, +you must enter the command template @code{@w{xterm -e vi %s}} in the +corresponding dialog entry. These settings can also be changed using the +@code{mixvm} commands @code{sedit} and @code{sasm} (@pxref{Configuration +commands}). +@end deffn + + +@deffn Settings Save +Saves the current settings. +@end deffn + +@deffn Settings @w{Save on exit} +Mark this checkbox if you want @code{gmixvm} to save its settings +every time you quit the program. +@end deffn + +@deffn Help About... +Shows information about @code{gmixvm}'s version and copyright. +@end deffn + +On the other hand, the status bar displays the name of the last loaded +MIX file. In addition, when the mouse pointer is over a MIXAL source +file line that contains symbols, a list of these symbols with their +values will appear in the status bar. -- cgit v1.2.3