mdk_mixvm.texi

汇编语言编程源代码

@c -*-texinfo-*-
@c This is part of the GNU MDK Reference Manual.
@c Copyright (C) 2000, 2001, 2002
@c   Free Software Foundation, Inc.
@c See the file mdk.texi for copying conditions.

@c $Id: mdk_mixvm.texi,v 1.11 2002/04/08 00:26:37 jao Exp $

@node mixvm, gmixvm, mixasm, Top
@comment  node-name,  next,  previous,  up
@chapter @code{mixvm}, the MIX computer simulator

@cindex mixvm

This chapter describes @code{mixvm}, the MIX computer
simulator. @code{mixvm} is a command line interface programme which
simulates the MIX computer (@pxref{The MIX computer}). It is able
to run MIXAL programs (@pxref{MIXAL}) previously compiled with the MIX
assembler (@pxref{mixasm}). The simulator allows inspection of the MIX
computer components (registers, memory cells, comparison flag and overflow
toggle), step by step execution of MIX programmes, and breakpoint
setting to aid you in debugging your code. For a tutorial description of
@code{mixvm} usage, @xref{Running the program}.

@menu
* Invocation::                  Options when invoking @code{mixvm}.
* Commands::                    Commands available in interactive mode.
* Devices::                     MIX block devices implementation.
@end menu

@node Invocation, Commands, mixvm, mixvm
@comment  node-name,  next,  previous,  up
@section Invoking @code{mixvm}

@code{mixvm} can be invoked with the following command line options
(note that, following GNU's conventions, we provide a long option name
for each available single letter switch):

@example
mixvm [-vhurdtq] [--version] [--help] [--usage] [--run] [--dump]
      [--time] [--noinit]  [FILE[.mix]]
@end example

@noindent
The meaning of these options is as follows:

@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 -r
@defoptx --run
Loads the specified @var{FILE} and executes it. After the program
execution, @code{mixvm} exits. @var{FILE} must be the name of a binary
@file{.mix} program compiled with @code{mixasm}. If your program does
not produce any output, use the @code{-d} flag (see below) to peek at
the virtual machine's state after execution.
@end defopt

@defopt -d
@defoptx --dump
This option must be used in conjuction with @code{-r}, and tells
@code{mixvm} to print the value of the virtual machine's registers,
comparison flag and overflow toggle after executing the program named
@var{FILE}. See @xref{Non-interactive mode}, for sample usage.
@end defopt

@defopt -t
@defoptx --time
This option must be used in conjuction with @code{-r}, and tells
@code{mixvm} to print virtual time statistics for the program's
execution.
@end defopt

When run without the @code{-r} flag, @code{mixvm} enters its interactive
mode, showing you a prompt like this one:

@example
MIX >
@end example

@noindent
and waiting for your commands (@pxref{Commands}). If the
optional @var{FILE} argument is given, the file @file{FILE.mix} will be
loaded into the virtual machine memory before entering the interactive
mode. 

The first time @code{mixvm} is invoked, a directory named @file{.mdk} is
created in your home directory. It contains the @code{mixvm}
configuration file, the command history file and (by default) the block
devices files (@pxref{Devices}). Before showing you the command prompt,
@code{mixvm} looks in the @file{~/.mdk} directory for a file named
@code{mixguile.scm}; if it exists, it is read and evaluated by the
embedded Guile interpreter (@pxref{Defining new functions}). You can use
the @code{-q} command line option to skip this file loading:

@defopt -q
@defoptx --noinit
Do not load the Guile initialisation file @code{~/.mdk/mixguile.scm} at
startup. 
@end defopt

@node Commands, Devices, Invocation, mixvm
@comment  node-name,  next,  previous,  up
@section Interactive commands 

You can enter the interactive mode of the MIX virtual machine by simply
invoking @code{mixvm} without arguments. You will then presented a shell
prompt@footnote{The default command prompt, @samp{MIX > }, can be
changed using the @code{prompt} command (@pxref{Configuration commands})}

@example
MIX >
@end example

@noindent
which indicates that a new virtual machine has been initialised and is
ready to execute your commands. As we have already mentioned, this
command prompt offers you command line editing facilities which are
described in the Readline user's manual (chances are that you are
already familiar with these command line editing capabilities, as they
are present in many GNU utilities, e.g. the @code{bash}
shell)@footnote{The readline functionality will be available if you have
compiled @sc{mdk} with readline support, i.e., if GNU readline is
installed in your system. This is ofte the case in GNU/Linux and BSD
systems}. In a nutshell, readline provides command completion using the
@kbd{TAB} key and command history using the cursor keys. A history file
containing the last commands typed in previous sessions is stored in the
@sc{mdk} configuration directory (@file{~/.mdk}).

As a beginner, your best friend will be the @code{help} command, which
shows you a summary of all available MIX commands and their usage; its
syntax is as follows:

@deffn {@code{mixvm} command} help [command]
Prints a short description of the given @var{command} and its usage. If
@var{command} is omitted, @code{help} prints the short description for
all available commands.
@end deffn

@menu
* File commands::               Loading and executing programs.
* Debug commands::              Debugging programs.
* State commands::              Inspecting the virtual machine state.
* Configuration commands::      Changing and storing mixvm settings.
* Scheme commands::             
@end menu

@node File commands, Debug commands, Commands, Commands
@subsection File commands

You have at your disposal a series of commands that let you load and
execute MIX executable files, as well as manipulate MIXAL source files:

@deffn {file command} load file[.mix]
This command loads a binary file, @var{file.mix} into the virtual
machine memory, and positions the program counter at the beginning of
the loaded program. This address is indicated in the MIXAL source file
as the operand of the @code{END} pseudoinstruction. Thus, if your
@file{sample.mixal} source file contains the line:

@example
     END 3000
@end example

@noindent
and you compile it with @code{mixasm} to produce the binary file
@file{sample.mix}, you will load it into the virtual machine as follows:

@example
MIX > load sample
Program loaded. Start address: 3000
MIX >
@end example

@end deffn

@deffn {file command} run [file[.mix]]
When executed without argument, this command initiates or resumes
execution of instructions from the current program counter
address. Therefore, issuing this command after a successful @code{load},
will run the loaded program until either a @code{HLT} instruction or a
breakpoint is found. If you provide a MIX filename as argument, the
given file will be loaded (as with @code{load} @var{file}) and
executed. If @code{run} is invoked again after program execution
completion (i.e., after the @code{HLT} instruction has been found in a
previous run), the program counter is repositioned and execution starts
again from the beginning (as a matter of fact, a @code{load} command
preserving the currently set breakpoints is issued before resuming
execution).
@end deffn

@deffn {file command} edit [file[.mixal]]
The source file @var{file.mixal} is edited using the editor defined in
the environment variable @var{MDK_EDITOR}. If this variable is not set,
the following ones are tried out in order: @var{X_EDITOR}, @var{EDITOR}
and @var{VISUAL}. If invoked without argument, the source file for the
currently loaded MIX file is edited. The command used to edit source
files can also be configured using the @code{sedit} command
(@pxref{Configuration commands}).
@end deffn

@deffn {file command} compile file[.mixal]
The source file @var{file.mixal} is compiled (with debug information
enabled) using @code{mixasm}. If invoked without argument, the source
file for the currently loaded MIX file is recompiled. The compilation
command can be set using the @code{sasm} command (@pxref{Configuration
commands}). 
@end deffn

@deffn {file command} pprog
@deffnx {file command} psrc
Print the path of the currently loaded MIX program and its source file:

@example
MIX > load ../samples/primes
Program loaded. Start address: 3000
MIX > pprog 
../samples/primes.mix
MIX > psrc
/home/jao/projects/mdk/gnu/samples/primes.mixal
MIx>
@end example
@end deffn

Finally, you can use the @code{quit} command to exit @code{mixvm}:

@deffn {file command} quit
Exit @code{mixvm}, saving the current configuration parameters in
@file{~/.mdk/mixvm.config}.
@end deffn


@node Debug commands, State commands, File commands, Commands
@subsection Debug commands

Sequential execution of loaded programs can be interrupted using the
following debug commands:

@deffn {debug command} next [ins_number]
This command causes the virtual machine to fetch and execute  up to
@var{ins_number} instructions, beginning from the current program
counter position. Execution is interrupted either when the specified
number of instructions have been fetched or a breakpoint is found,
whatever happens first. If run without arguments, one instruction is
executed. If @code{next} is invoked again after program execution
completion (i.e., after the @code{HLT} instruction has been found in a
previous run), the program counter is repositioned and execution starts
again from the beginning (as a matter of fact, a @code{load} command
preserving the currently set breakpoints is issued before resuming
execution).
@end deffn

@deffn {debug command} sbp line_number
@deffnx {debug command} cbp line_no
Sets a breakpoint at the specified source file line number. If the line
specified corresponds to a command or to a MIXAL pseudoinstruction which
does not produce a MIX instruction in the binary file (such as
@code{ORIG} or @code{EQU}) the breakpoint is set at the first source
code line giving rise to a MIX instruction after the specified
one. Thus, for our sample @file{hello.mixal} file:

@example
*                                                        (1)
* hello.mixal: say 'hello world' in MIXAL                (2)
*                                                        (3)
* label ins    operand     comment                       (4)
TERM    EQU    19          the MIX console device number (5)
        ORIG   1000        start address                 (6)
START   OUT    MSG(TERM)   output data at address MSG    (7)
...
@end example

@noindent
trying to set a breakpoint at line 5, will produce the following result:

@example
MIX > sbp 5
Breakpoint set at line 7
MIX > 
@end example

@noindent
since line 7 is the first one compiled into a MIX instruction (at
address 3000). In order to @code{sbp} to work, the source file must be
compiled using the @code{-g} flags, which tells @code{mixasm} to include
debug information in the binary @file{.mix} file.

The command @code{cbp} clears a (previously set) breakpoint at the given
source file line.
@end deffn

@deffn {debug command} spba address
@deffnx {debug command} cbpa address
Sets a breakpoint at the given memory @var{address}. The argument must
be a valid MIX memory address, i.e., it must belong into the range
@w{[0-3999]}. Note that no check is performed to verify that the
specified address is reachable during program execution. No debug
information is needed to set a breakpoint by address with @code{sbpa}.
The command @code{cbpa} clears a (previously set) breakpoint at the
given memory address.
@end deffn

@deffn {debug command} sbpr A | X | J | Ii
@deffnx {debug command} cbpr A | X | J | Ii
Sets a conditional breakpoint on the specified register change. For
instance, 

@example
sbpr I1
@end example

@noindent
will cause an interruption during program execution whenever the
contents or register @code{I1} changes. A previously set breakpoint is
cleared using the @code{cbpr} command.
@end deffn

@deffn {debug command} sbpm address
@deffnx {debug command} cbpm address
Sets a conditional breakpoint on the specified memory cell change. The
argument must be a valid MIX memory address, i.e., it must belong into
the range @w{[0-3999]}. For instance,

@example
sbpm 1000
@end example

@noindent
will cause an interruption during program execution whenever the
contents or of the memory cell number 1000 changes. A previously set
breakpoint is cleared using the @code{cbpm} command.
@end deffn

@deffn {debug command} sbpo 
@deffnx {debug command} cbpo 
Sets/clears a conditional breakpoint on overflow toggle change.
@end deffn

@deffn {debug command} sbpc 
@deffnx {debug command} cbpc 
Sets/clears a conditional breakpoint on comparison flag change.
@end deffn

@deffn {debug command} cabp
Clears all currently set breakpoints.
@end deffn

@deffn {debug command} psym [symbol_name]
MIXAL programs can define symbolic constants, using either the
@code{EQU} pseudoinstruction or a label at the beginning of a
line. Thus, in the program fragment

@example
VAR     EQU  2168
        ORIG 4000
START   LDA  VAR
@end example

@noindent
the symbol @code{VAR} stands for the value 2168, while @code{START} is
assigned the value 4000. When MIXAL programs are compiled using the
@code{-g} flag (which tells @code{mixasm} to include debug information
in the binary @file{.mix} file), the symbol table can be consulted from
the @code{mixvm} command line using @code{psym} followed by the name of
the symbol whose contents you are interested in. When run without
arguments, @code{psym} will print all defined symbols and their values.
@end deffn

The virtual machine can also show you the instructions it is executing,
using the following commands:

@deffn {debug command} strace [on|off]
@code{strace on} enables instruction tracing. When tracing is enabled,
each time the virtual machine executes an instruction (due to your
issuing a @code{run} or @code{next} command), it is printed in its
canonical form (that is, with all expressions evaluated to their
numerical values) and, if the program was compiled with debug
information, as it was originally typed in the MIXAL source
file. Instruction tracing is disabled with @code{strace off}
command. A typical tracing session could be like this:

@example
MIX > strace on
MIX > next