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_mixvm.texi | 813 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 813 insertions(+) create mode 100644 doc/mdk_mixvm.texi (limited to 'doc/mdk_mixvm.texi') diff --git a/doc/mdk_mixvm.texi b/doc/mdk_mixvm.texi new file mode 100644 index 0000000..2e21289 --- /dev/null +++ b/doc/mdk_mixvm.texi @@ -0,0 +1,813 @@ +@c -*-texinfo-*- +@c This is part of the GNU MDK Reference Manual. +@c Copyright (C) 2000, 2001, 2002, 2003, 2004 +@c Free Software Foundation, Inc. +@c See the file mdk.texi for copying conditions. + +@c $Id: mdk_mixvm.texi,v 1.20 2005/09/19 21:29:42 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:: +* 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 be greeted by 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). + +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. 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 +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 > strace 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. The +tracing behaviour is stored as a configuration parameter in @file{~/.mdk}. +@end deffn + +@deffn {debug command} pline [LINE_NUMBER] +Prints the requested source line (or the current one if +@var{line_number} is omitted: + +@example +MIX > load ../samples/hello +Program loaded. Start address: 3000 +MIX > pline +Line 5: START OUT MSG(TERM) +MIX > pline 6 +Line 6: HLT +MIX > +@end example +@end deffn + +@deffn {debug command} pbt [INS_NUMBER] +This command prints a backtrace of executed instructions. Its optional +argument @var{ins_number} is the number of instructions to print. If it +is omitted or equals zero, all executed instructions are printed. For +instance, if you compile and load the following program (@file{bt.mixal}): + +@example + ORIG 0 +BEG JMP *+1 + JMP *+1 +FOO JMP BAR +BAR HLT + END BEG +@end example + +@noindent +you could get the following traces: + +@example +MIX > load bt +Program loaded. Start address: 0 +MIX > next +MIX > pbt +#0 BEG in bt.mixal:2 +MIX > next +MIX > pbt +#0 1 in bt.mixal:3 +#1 BEG in bt.mixal:2 +MIX > run +Running ... +... done +MIX > pbt 3 +#0 BAR in bt.mixal:5 +#1 FOO in bt.mixal:4 +#2 1 in bt.mixal:3 +MIX > pbt +#0 BAR in bt.mixal:5 +#1 FOO in bt.mixal:4 +#2 1 in bt.mixal:3 +#3 BEG in bt.mixal:2 +MIX > +@end example + +Note that the executed instruction trace gives you the label of the +executed line or, if it has no label, its address. +@end deffn + +As you have probably observed, @code{mixvm} prints timing statistics +when running programs. This behaviour can be controlled using the +@code{stime} command (@pxref{Configuration commands}). + +@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, Configuration commands, Debug commands, Commands +@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} pstat +This commands prints the current virtual machine state, which can be one +of the following: +@itemize @minus +@item +No program loaded +@item +Program successfully loaded +@item +Execution stopped (@code{next} executed) +@item +Execution stopped: breakpoint encountered +@item +Execution stopped: conditional breakpoint encountered +@item +Program successfully terminated +@end itemize +@end deffn + +@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} sreg A | X | J | I[1-6] value +@deffnx {state command} preg [A | X | J | I[1-6]] +@deffnx {state command} pall +@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, @code{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 + +@node Configuration commands, Scheme commands, State commands, Commands +@subsection Configuration commands + +This section describes commands that allow you to configure the virtual +machine behaviour. This configuration is stored in the @sc{mdk} +directory @file{~/.mdk}. + +As you can see in their description, some commands print, as a side +effect, informational messages to the standard output (e.g. @code{load} +prints a message telling you the loaded program's start address): these +messages can be enabled/disabled using @code{slog}: + +@deffn {config command} slog on|off +Turns on/off the logging of informational messages. Note that error +messages are always displayed, as well as state messages required using +commands prefixed with @code{p} (@code{preg}, @code{pmem} and the like). +@end deffn + +@deffn {config command} stime on|off +@deffnx {config command} ptime +The @code{stime} command (un)sets the printing of timing statistics, and +@code{ptime} prints their current value: + +@example +MIX > ptime +Elapsed time: 10 /Total program time: 11 (Total uptime: 11) +MIX > +@end example +@end deffn + +@deffn {config command} sedit TEMPLATE +@deffnx {config command} pedit +@code{sedit} sets the command to be used to edit MIXAL source files with +the @code{edit} command. @var{TEMPLATE} must contain the control +characters @code{%s} to mark the place where the source's file name will +be inserted. For instance, if you type + +@example +MIX > sedit emacsclient %s +MIX > +@end example + +issuing the @code{mixvm} command @w{@code{edit foo.mixal}} will invoke +the operating system command @w{@code{emacsclient foo.mixal}}. + +@code{pedit} prints the current value of the edit command template. + +@end deffn + +@deffn {config command} sasm TEMPLATE +@deffnx {config command} pasm +@code{sasm} sets the command to be used to compile MIXAL source files with +the @code{compile} command. @var{template} must contain the control +characters @code{%s} to mark the place where the source's file name will +be inserted. For instance, if you type + +@example +MIX > sasm mixasm -l %s +MIX > +@end example + +issuing the @code{mixvm} command @w{@code{compile foo.mixal}} will invoke +the operating system command @w{@code{mixasm -l foo.mixal}}. + +@code{pasm} prints the current value of the compile command template. + +@end deffn + +@deffn {config command} sddir DIRNAME +@deffnx {config command} pddir +MIX devices (@pxref{Devices}) are implemented as regular files stored, +by default, inside @file{~/.mdk}. The @code{sddir} command lets you +specify an alternative location for storing these device files, while +@code{pddir} prints the current device directory. +@end deffn + +Finally, you can change the default command prompt, @samp{MIX > }, +using the @code{prompt} command: + +@deffn {config command} prompt PROMPT +Changes the command prompt to @var{prompt}. If you want to include +white space(s) at the end of the new prompt, bracket @var{prompt} using +double quotes (e.g., @code{prompt ">> "}). +@end deffn + +@node Scheme commands, , Configuration commands, Commands +@subsection Scheme commands + +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 + +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 input/output. When you request an output operation on any other +(output) device, a file named according to the following table will be +created, 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). The device files are stored, by default, in the +directory @file{~/.mdk}; this location can be changed using the +@code{mixvm} command @code{devdir} (@pxref{Configuration commands}). + +@multitable {the device name} { xx-xx } {filename[x-x].dev} {bin i/o/char } +@item @emph{Device} @tab @emph{No.} @tab @emph{filename} @tab @emph{type and block size} +@item Tape @tab 0-7 @tab @file{tape[0-7].dev} @tab bin i/o - 100 words +@item Disks @tab 8-15 @tab @file{disk[0-7].dev} @tab bin i/o - 100 words +@item Card reader @tab 16 @tab @file{cardrd.dev} @tab char in - 16 words +@item Card writer @tab 17 @tab @file{cardwr.dev} @tab char out - 16 words +@item Line printer @tab 18 @tab @file{printer.dev} @tab char out - 24 words +@item Terminal @tab 19 @tab @code{stdin/stdout} @tab char i/o - 14 words +@item Paper tape @tab 20 @tab @file{paper.dev} @tab char in - 14 words +@end multitable + +Devices of type @i{char} are stored as ASCII files, using one line per +block. For instance, since the card reader has blocks of size 16, that +is, 80 characters, it will be emulated by an ASCII file consisting of +lines with length 80. If the reader finds a line with less than the +required number of characters, it pads the memory with zeroes (MIX +character 'space') to complete the block size. + +Note that the virtual machine automatically converts between the MIX and +ASCII character encodings, so that you can manipulate char device files +with any ASCII editor. In addition, the reader is not case-sensitive, +i.e., it automatically converts lowercase letters to their uppercase +counterparts (since the MIX character set does not include the former). + +The typewriter (device no. 19) lets you use the standard input and +output in your MIXAL programs. For instance, here is a simple 'echo' +program: + +@example +* simple echo program +TERM EQU 19 the typewriter device +BUF EQU 500 input buffer + ORIG 1000 +START IN BUF(TERM) read a block (70 chars) + OUT BUF(TERM) write the read chars + HLT + END START +@end example + +@noindent Input lines longer than 70 characters (14 words) are trimmed. +On the other hand, if you type less than a block of characters, +whitespace (MIX character zero) is used as padding. + -- cgit v1.2.3