path: root/doc/mdk_gmixvm.texi

@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_gmixvm.texi,v 1.12 2001/09/13 00:13:39 jao Exp $

@node gmixvm, mixasm, mixvm, Top
@comment  node-name,  next,  previous,  up
@chapter @code{gmixvm}, the GTK virtual machine
@cindex @code{gmixvm}
@cindex GUI
@cindex GTK+

@menu
* Invoking @code{gmixvm}::      Invoking the GTK+ interface.
* 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 @code{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 @key{RET}
@end example

@noindent
at your command prompt. The @code{gmixvm} main window will appear,
offering you a graphical interface to run and debug your MIX programs.

@image{img/ss_mix, 400pt}

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
The application can run in two modes: non-split (the above windows are
placed in a notebook in the main window) or split mode (the windows are
detached from the main one, and can be hidden individually). You can
choose the display mode using the corresponding command from the
@code{View} menu.

@ifnotinfo
Here is an screenshot showing how @code{gmixvm} looks like when running
in split mode:

@image{img/ss_split, 420pt}

@end ifnotinfo

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 (in split mode, these widgets occupy the
whole main window's space between the menu and status bars). 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 @code{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 @w{Settings->Change font->Command
prompt} and @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).

Clicking any register entry, you will be prompted for a new register's
contents.

@ifnotinfo
The next figure shows the enter word dialog.

@image{img/ss_worddlg, 250pt}

@end ifnotinfo

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.

@ifnotinfo
The next figure shows the enter address dialog.

@image{img/ss_goto, 200pt}

@end ifnotinfo


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 @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 MIXAL, shows you the MIXAL source of
the currently loaded MIX file. As shown in the next figure, the
information is presented in two columns.

@image{img/ss_mixal, 400pt}

The first column shows the address and memory contents of the compiled
MIX instruction, while the second one displays its corresponding MIXAL
representation, together with the source file line number. The current
location of the location counter is highlighted in grey, while any set
breakpoint is marked in red. You can set/unset breakpoints by clicking
on any line in this view which has an associated memory address.

The colors used to mark the location pointer line and the breakpoints
can be customized with the @w{Settings->Colors...} menu command. When you
click on this menu item, a dialog showing the current line colors will
appear. 
@ifnotinfo
The following figure shows the change color dialog.

@image{img/ss_colors, 250pt}

@end ifnotinfo
Clicking on any of the colors will produce a color selection dialog for
choosing a new color for the given element. In this way, you can change
the foreground and background colors used for drawing the current line,
the lines where breakpoints have been set and plain MIXAL code lines.

You can change the font used to display the MIXAL source code
using the @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. 

@ifnotinfo

@image{img/ss_devices, 400pt}

@end ifnotinfo

Input device contents is read from files located in the @file{~/.gmivm}
directory, and the output is also written in 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) shall be 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 @w{Settings->Device output}
menu command for each binary device.

You can change the font used to display the devices content
using the @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 View @w{Toolbar(s)}
Toggles the toolbar(s) in the @code{gmixvm} window(s) (in split mode
there are multiple windows and, hence, multiple toolbars).
@end deffn

@deffn View MIX
@deffnx View MIXAL
@deffnx View Devices

These toggles are available when running @code{gmixvm} in split mode,
and let you turn on/off the visibility of the corresponding
@code{gmixvm} windows.

@end deffn

@deffn View @w{Split windows}
@deffnx View @w{One window}

Change the mode between one and split windows.

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

@ifnotinfo

@image{img/ss_symbols, 250pt}

@end ifnotinfo

@end deffn

@deffn Settings Colors...
Lets you change the colors used to mark the current and breakpoint lines
in the MIXAL tab, as well as the colors used for plain source lines.
@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, MIX, MIXAL and devices).
@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.

@ifnotinfo
@image{img/ss_devform, 250pt}
@end ifnotinfo

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

@ifnotinfo
@image{img/ss_devdir, 250pt}
@end ifnotinfo

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.

@ifnotinfo
@image{img/ss_extprog, 250pt}
@end ifnotinfo

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.