path: root/doc/mdk_mixvm.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.

@node mixvm, gmixvm, mixvm.el, 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 [-vhurd] [--version] [--help] [--usage] [--run] [--dump]
      [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

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. 

@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 

@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). 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]
@deffnx {@code{mixvm} command} ? [command]
Prints a short description of the given @var{command} and its usage. If
@var{command} is omitted, all available commands are described.
@end deffn

@menu
* File commands::               Loading and executing programs.
* Debug commands::              Debugging programs.
* State commands::              Inspecting the virtual machine state.
@end menu

@node File commands, Debug commands, Commands, Commands
@comment  node-name,  next,  previous,  up
@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.
@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.
@end deffn


@node Debug commands, State commands, File commands, Commands
@comment  node-name,  next,  previous,  up
@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
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.
@end deffn

@deffn {debug command} spba 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}.
@end deffn

@deffn {debug command} cbp line_no
Clears a (previously set) breakpoint at the given source file line.
@end deffn

@deffn {debug command} cbpa address
Clears a (previously set) breakpoint at the given memory address.
@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} tron
@deffnx troff
@code{tron} 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 disable with the
@code{troff} command. A typical tracing session could be like this:

@example
MIX > tron
Instruction tracing has been turned ON.
MIX > next
3000: [OUT	3002,0(2:3)]	START	OUT	MSG(TERM)
MIXAL HELLO WORLD                                                     
Elapsed time: 1 /Total program time: 1 (Total uptime: 1)
MIX > next
3001: [HLT	0,0]		HLT
End of program reached at address 3002
Elapsed time: 10 /Total program time: 11 (Total uptime: 11)
MIX > troff
Instruction tracing has been turned OFF.
MIX > 
@end example
@noindent
The executed instruction, as it was translated, is shown between square
brackets after the memory address, and, following it, you can see the
actual MIXAL code that was compiled into the executed instruction.
@end deffn

@code{mixvm} is also able of evaluating w-expressions
(@pxref{W-expressions}) using the following command:

@deffn {debug command} weval WEXP
Evaluates the given w-expression, @var{WEXP}. The w-expression can
contain any currently defined symbol. For instance:

@example
MIX > psym START
+ 00 00 00 46 56 (0000003000)
MIX > weval START(0:1),START(3:4)
+ 56 00 46 56 00 (0939716096)
MIX >
@end example
@end deffn

New symbols can be defined using the @code{ssym} command:
@deffn {debug command} ssym SYM WEXP
Defines the symbol named @var{SYM} with the value resulting from
evaluating @var{WEXP}, an w-expression. The newly defined symbol can be
used in subsequent @code{weval} commands, as part of the expression to
be evaluated. E.g.,

@example
MIX > ssym S 2+23*START
+ 00 00 18 19 56 (0000075000)
MIX > psym S
+ 00 00 18 19 56 (0000075000)
MIX > weval S(3:4)
+ 00 00 19 56 00 (0000081408)
MIX > 
@end example
@end deffn

Finally, if you want to discover which is the decimal value of a MIX
word expressed as five bytes plus sign, you can use

@deffn {debug command} w2d WORD
Computes the decimal value of the given word. @var{WORD} must be
expressed as a sign (+/-) followed by five space-delimited, two-digit
decimal values representing the five bytes composing the word. The
reverse operation (showing the word representation of a decimal value)
can be accomplished with @code{weval}. For instance: 

@example
MIX > w2d - 01 00 00 02 02
-16777346
MIX > weval -16777346
- 01 00 00 02 02 (0016777346)
MIX > 
@end example
@end deffn

@node State commands,  , Debug commands, Commands
@comment  node-name,  next,  previous,  up
@subsection State commands

Inspection and modification of the virtual machine state (memory,
registers, overflow toggle and comparison flag contents) is accomplished
using the following commands:

@deffn {state command} pc
Prints the current value of the program counter, which stores the
address of the next instruction to be executed in a non-halted program.
@end deffn

@deffn {state command} preg [A | X | J | I[1-6]]
@deffnx {state command} pall
@deffnx {state command} sreg A | X | J | I[1-6] value
@code{preg} prints the contents of a given MIX register. For instance,
@w{@code{preg} @var{A}} will print the contents of the A-register. When
invoked without arguments, all registers shall be printed:

@example
MIX > preg
rA: - 00 00 00 00 35 (0000000035)
rX: + 00 00 00 15 40 (0000001000)
rJ: + 00 00 (0000)
rI1: + 00 00 (0000)	rI2: + 00 00 (0000)	
rI3: + 00 00 (0000)	rI4: + 00 00 (0000)	
rI5: + 00 00 (0000)	rI6: + 00 00 (0000)	
MIX > 
@end example

As you can see in the above sample, the contents is printed as the sign
plus the values of the MIX bytes stored in the register and, between
parenthesis, the decimal representation of its module.

@code{pall} prints the contents of all registers plus the comparison
flag and overflow toggle.

Finally, @code{sreg} Sets the contents of the given register to
@var{value}, expressed as a decimal constant. If @var{value} exceeds the
maximum value storable in the given register, @math{VALUE mod
MAXIMU_VALUE} is stored, e.g.

@example
MIX > sreg I1 1000
MIX > preg I1
rI1: + 15 40 (1000)	
MIX > sreg I1 1000000
MIX > preg I1
rI1: + 09 00 (0576)	
MIX > 
@end example

@end deffn


@deffn {state command} pflags
@deffnx {state command} scmp E | G | L
@deffnx {state command} sover F | T
@code{pflags} prints the value of the comparison flag and overflow
toggle of the virtual machine, e.g.

@example
MIX > pflags
Overflow: F
Cmp: E
MIX > 
@end example

@noindent
The values of the overflow toggle are either @var{F} (false) or @var{T}
(true), and, for the comparison flag, @var{E}, @var{G}, @var{L} (equal,
greater, lesser). @code{scmp} and @code{sover} are setters of the
comparison flag and overflow toggle values.
@end deffn

@deffn {state command} pmem from[-to]
@deffnx {state command} smem address value
@code{pmem} prints the contents of memory cells in the address range
@w{[@var{FROM}-@var{TO}]}. If the upper limit @var{to} is omitted, only
the contents of the memory cell with address @var{FROM} is printed, as
in

@example
MIX > pmem 3000
3000: + 46 58 00 19 37 (0786957541)
MIX >
@end example

The memory contents is displayed both as the set of five MIX bytes plus
sign composing the stored MIX word and, between parenthesis, the decimal
representation of the module of the stored value.

@code{smem} sets the content of the memory cell with address
@var{address} to @var{value}, expressed as a decimal constant.

@end deffn

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

@node Devices,  , Commands, mixvm
@comment  node-name,  next,  previous,  up
@section MIX block devices

The MIX computer comes equipped with a set of block devices for
input-output operations (@pxref{Input-output operators}). @code{mixvm}
implements these block devices as disk files, with the exception of
block device no. 19 (typewriter terminal) which is redirected to
standard output. When you request an output operation on any other
(output) device, a file named according to the following table will be
created in the current directory, and the specified MIX words will be
written to the file in binary form (for binary devices) or in ASCII (for
char devices). Files corresponding to input block devices should be
created and filled beforehand to be used by the MIX virtual machine (for
input-output devices this creation can be accomplished by a MIXAL
program writing to the device the required data, or, if you prefer, with
your favourite editor).

@multitable {the device name} { xx-xx } {filename[x-x].dev} {bin  i/o } 
@item @emph{Device}  @tab @emph{No.} @tab @emph{filename} @tab @emph{type}
@item Tape @tab 0-7 @tab @file{tape[0-7].dev} @tab bin i/o
@item Disks @tab 8-15 @tab @file{disk[0-7].dev} @tab bin i/o
@item Card reader @tab 16 @tab @file{cardrd.dev} @tab char in
@item Card writer @tab 17 @tab @file{cardwr.dev} @tab char out
@item Line printer @tab 18 @tab @file{printer.dev} @tab char out
@item Terminal @tab 19 @tab @code{stdout} @tab char out
@item Paper tape @tab 20 @tab @file{paper.dev} @tab char out
@end multitable