From 2c40b5475f0b968dcd5ac2f6d9e353c9f5463763 Mon Sep 17 00:00:00 2001 From: Jose Antonio Ortega Ruiz Date: Mon, 8 Apr 2002 00:26:37 +0000 Subject: candidate release 1.0 --- doc/mdk.texi | 10 +++++----- doc/mdk_ack.texi | 19 +++++++++++++------ doc/mdk_gstart.texi | 53 ++++++++++++++++++++++++++++++++++------------------ doc/mdk_install.texi | 10 ++++++---- doc/mdk_mixvm.texi | 29 ++++++++++++++++++++++------ doc/mdk_tut.texi | 29 ++++++++++++++-------------- 6 files changed, 97 insertions(+), 53 deletions(-) (limited to 'doc') diff --git a/doc/mdk.texi b/doc/mdk.texi index 495e563..63c2aec 100644 --- a/doc/mdk.texi +++ b/doc/mdk.texi @@ -12,9 +12,9 @@ @end direntry -@set UPDATED September 10th, 2001 -@set EDITION 0.5 -@set VERSION 0.5 +@set UPDATED April, 2002 +@set EDITION 1.0 +@set VERSION 1.0 @set JAO Jose Antonio Ortega Ruiz @set PHILIP Philip E. King @footnotestyle separate @@ -23,7 +23,7 @@ This file documents the the GNU @sc{mdk} utilities for developing programs using Donald Knuth's MIX language. -Copyright (C) 2000, 2001 Free Software Foundation, Inc. +Copyright (C) 2000, 2001, 2002 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, @@ -262,4 +262,4 @@ Copying @contents @bye -$Id: mdk.texi,v 1.17 2001/09/28 23:11:44 jao Exp $ +$Id: mdk.texi,v 1.18 2002/04/08 00:26:38 jao Exp $ diff --git a/doc/mdk_ack.texi b/doc/mdk_ack.texi index cba9251..532bd02 100644 --- a/doc/mdk_ack.texi +++ b/doc/mdk_ack.texi @@ -1,10 +1,10 @@ @c -*-texinfo-*- @c This is part of the GNU MDK Reference Manual. -@c Copyright (C) 2000, 2001 +@c Copyright (C) 2000, 2001, 2002 @c Free Software Foundation, Inc. @c See the file mdk.texi for copying conditions. -@c $Id: mdk_ack.texi,v 1.3 2001/09/16 22:17:33 jao Exp $ +@c $Id: mdk_ack.texi,v 1.4 2002/04/08 00:26:38 jao Exp $ @node Acknowledgments, Installing MDK, Introduction, Top @comment node-name, next, previous, up @@ -33,12 +33,16 @@ Mandrake packages. pointed out various bugs and provided helpful suggestions for improving mixvm. +@item Francesc Xavier Noria (@email{fxn@@retemail.es}) +kindly and thoroughly reviewed the @sc{mdk} documentation, providing +insightful advice. + @item Ying-Chieh Liao (@email{ijliao@@csie.nctu.edu.tw}) tested @sc{mdk} on a FreeBSD system, and developed and maintains a port for it. @item Adrian Bunk (@email{bunk@@fs.tum.de}) -created and maintains the @sc{mdk} Debian packages. +created and maintained the @sc{mdk} Debian packages. @item Christoph von Nathusius (@email{nathusiu@@gmx.net}) tested @sc{mdk} on Windows/Cygwin and reported a bug on pmem. @@ -46,6 +50,10 @@ tested @sc{mdk} on Windows/Cygwin and reported a bug on pmem. @item Stephen Ramsay (@email{sjr3a@@virginia.edu}) tested @sc{mdk} on Sun/Solaris. +@item Johan Swanljung (@email{johanswa@@yahoo.com}) +tested @sc{mdk} on Mac OS X, and helped fix the configuration process +to support this platfom. + @item Jason Uhlenkott also reported the pmem problem. @@ -58,9 +66,8 @@ reported a bug in mixvm's MOVE implementation. @item Milan Bella (@email{milanbella@@hotmail.com}) reported a bug in @sc{mdk} documentation. -@item @sc{mdk} was inspired by Darius Bacon's MIXAL program -(@email{djello@@well.sf.ca.us}) which can be installed in Debian 2.3 as -the package "mixal". +@item @sc{mdk} was inspired by Darius Bacon's +@uref{http://www.accesscom.com/~darius/, MIXAL program}. @end itemize diff --git a/doc/mdk_gstart.texi b/doc/mdk_gstart.texi index c9b936b..f04e5c1 100644 --- a/doc/mdk_gstart.texi +++ b/doc/mdk_gstart.texi @@ -1,10 +1,10 @@ @c -*-texinfo-*- @c This is part of the GNU MDK Reference Manual. -@c Copyright (C) 2000, 2001 +@c Copyright (C) 2000, 2001, 2002 @c Free Software Foundation, Inc. @c See the file mdk.texi for copying conditions. -@c $Id: mdk_gstart.texi,v 1.12 2002/03/19 22:38:13 jao Exp $ +@c $Id: mdk_gstart.texi,v 1.13 2002/04/08 00:26:38 jao Exp $ @node Getting started, mixvm.el, MIX and MIXAL tutorial, Top @chapter Getting started @@ -72,8 +72,11 @@ column in its line, for the first whitespace in the line maks the beginning of the second field), @item an operation mnemonic, which can represent either a MIX instruction -(@code{OUT} and @code{HLT} in lines 6 and 7 above), or an assembly -pseudoinstruction. +(@code{OUT} and @code{HLT} in lines 7 and 8 above), or an assembly +pseudoinstruction (e.g., the @code{ORIG} pseudoinstruction in line +6@footnote{If an @code{ORIG} directive is not used, the program will +be loaded by the virtual machine at address 0. @code{ORIG} allows +allocating the executable code where you see fit.}. @item an optional operand for the (pseudo)instruction, and @item @@ -88,10 +91,12 @@ the operand always starts at a fixed column number, and the use of quotation is therefore unnecessary. As @code{mixasm} releases this requirement, marking the beginning and end of the @code{ALF} operand disambiguates the parser's recognition of this operand when it includes -blanks}. +blanks. Note that double-quotes (") are not part of the MIX character +set, and, therefore, no escape characters are needed within +@code{ALF}'s operands.}. The workings of this sample program should be straightforward if you are -familiar with MIXAL. See TAOCP vol. 1 for a thorought definition or +familiar with MIXAL. See TAOCP vol. 1 for a thorough definition or @ref{MIX and MIXAL tutorial}, for a tutorial. @node Compiling, Running the program, Writing a source file, Getting started @@ -120,7 +125,7 @@ If the source file contains no errors, this will produce a binary file called @file{hello.mix} which can be loaded and run by the MIX virtual machine. The @code{-g} flag tells the assembler to include debug information in the executable file (for a complete description of all -the compilation options, see @ref{mixasm}.) Now, your are ready to run +the compilation options, see @ref{mixasm}). Now, your are ready to run your first MIX program, as described in the following section. @@ -154,12 +159,12 @@ Using the MIX simulators, you can run your MIXAL programs, after compiling them with @code{mixasm} into binary @file{.mix} files. @code{mixvm} can be used either in @dfn{interactive} or @dfn{non-interactive} mode. In the second case, @code{mixvm} will load -your program into memory, execute it (producing any output due to MIXAL -@code{OUT} instructions present in the program), and exit when it -encounters a @code{HLT} instruction. In interactive mode, you will enter -a shell prompt which allows you issuing commands to the running virtual -machine. This commands will permit you loading, running and debugging -programs, as well as inspecting the MIX computer state (register +your program into memory, execute it (producing any output due to +MIXAL @code{OUT} instructions present in the program), and exit when +it encounters a @code{HLT} instruction. In interactive mode, you will +enter a shell prompt which allows you issuing commands to the running +virtual machine. This commands will permit you to load, run and debug +programs, as well as to inspect the MIX computer state (register contents, memory cells contents and so on). @menu @@ -184,7 +189,6 @@ mixvm -r hello @key{RET} @example MIXAL HELLO WORLD -** Execution time: 11 @end example @noindent Since our hello world program uses MIX's device number 19 as @@ -196,10 +200,24 @@ and written its output there@footnote{The device files are stored, by default, in a directory called @file{.mdk}, which is created in your home directory the first time @code{mixvm} is run. You can change this default directory using the command @code{devdir} when running -@code{mixvm} in interactive mode (@pxref{Configuration commands})}. Note -also that the virtual machine reports the execution time of the program, +@code{mixvm} in interactive mode (@pxref{Configuration commands})}. + +The virtual machine can also report the execution time of the program, according to the (virtual) time spent in each of the binary instructions -(@pxref{Execution times}). +(@pxref{Execution times}). Printing of execution time statistics is +activated with the @code{-t} flag; running + +@example +mixvm -t -r hello @key{RET} +@end example + +@noindent +produces the following output: + +@example +MIXAL HELLO WORLD +** Execution time: 11 +@end example Sometimes, you will prefer to store the results of your program in MIX registers rather than writing them to a device. In such cases, @@ -216,7 +234,6 @@ mixvm -d -r hello @example MIXAL HELLO WORLD -** Execution time: 11 rA: + 00 00 00 00 00 (0000000000) rX: + 00 00 00 00 00 (0000000000) rJ: + 00 00 (0000) diff --git a/doc/mdk_install.texi b/doc/mdk_install.texi index c240c57..2c09a52 100644 --- a/doc/mdk_install.texi +++ b/doc/mdk_install.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU MDK Reference Manual. -@c Copyright (C) 2000, 2001 +@c Copyright (C) 2000, 2001, 2002 @c Free Software Foundation, Inc. @c See the file mdk.texi for copying conditions. @@ -114,7 +114,7 @@ you should see a message with the configuration results like the following: @example -*** GNU MDK 0.5 has been successfully configured. *** +*** GNU MDK 1.0 has been successfully configured. *** Type 'make' to build the following utilities: - mixasm (MIX assembler) @@ -208,13 +208,13 @@ GNU MDK has been tested in the following platforms: @itemize @item -Debian GNU/Linux 2.2/2.3 +Debian GNU/Linux 2.2/2.3/3.0 @item Redhat GNU/Linux 7.0 (Agustin Navarro), 6.2 (Roberto Ferrero) @item Mandrake 8.0 (Agustin Navarro) @item -FreeBSD 4.2, 4.3 (Ying-Chieh Liao) +FreeBSD 4.2, 4.3, 4.4, 4.5 (Ying-Chieh Liao) @item Solaris 2.8/gcc 2.95.3 (Stephen Ramsay) @item @@ -225,6 +225,8 @@ Nathusius)@footnote{Caveats: Christoph has only tested @code{mixvm} and functionalities on a first try. If you find problems with history/readline functionality, please try a newer/manually installed readline version.} +@item +Mac OS X 10.1.2 (Johan Swanljung) @end itemize MDK will probably work on any GNU/Linux and BSD platform. If you try it diff --git a/doc/mdk_mixvm.texi b/doc/mdk_mixvm.texi index 2eae874..7992567 100644 --- a/doc/mdk_mixvm.texi +++ b/doc/mdk_mixvm.texi @@ -1,10 +1,10 @@ @c -*-texinfo-*- @c This is part of the GNU MDK Reference Manual. -@c Copyright (C) 2000, 2001 +@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.10 2001/09/26 23:15:55 jao Exp $ +@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 @@ -37,8 +37,8 @@ setting to aid you in debugging your code. For a tutorial description of for each available single letter switch): @example -mixvm [-vhurdq] [--version] [--help] [--usage] [--run] [--dump] - [--noinit] [FILE[.mix]] +mixvm [-vhurdtq] [--version] [--help] [--usage] [--run] [--dump] + [--time] [--noinit] [FILE[.mix]] @end example @noindent @@ -73,6 +73,13 @@ 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: @@ -107,7 +114,8 @@ startup. 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 +prompt@footnote{The default command prompt, @samp{MIX > }, can be +changed using the @code{prompt} command (@pxref{Configuration commands})} @example MIX > @@ -142,7 +150,7 @@ all available commands. * File commands:: Loading and executing programs. * Debug commands:: Debugging programs. * State commands:: Inspecting the virtual machine state. -* Configuration commands:: Storing mixvm settings. +* Configuration commands:: Changing and storing mixvm settings. * Scheme commands:: @end menu @@ -712,6 +720,15 @@ 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 diff --git a/doc/mdk_tut.texi b/doc/mdk_tut.texi index 461fcf6..c2b3ab1 100644 --- a/doc/mdk_tut.texi +++ b/doc/mdk_tut.texi @@ -4,7 +4,7 @@ @c Free Software Foundation, Inc. @c See the file mdk.texi for copying conditions. -@c $Id: mdk_tut.texi,v 1.6 2002/03/19 22:38:13 jao Exp $ +@c $Id: mdk_tut.texi,v 1.7 2002/04/08 00:26:37 jao Exp $ @node MIX and MIXAL tutorial, Getting started, Installing MDK, Top @comment node-name, next, previous, up @@ -793,19 +793,20 @@ counter, while @samp{HLT} usually marks program termination. @cindex exection time @cindex time -When writing MIXAL programs (or any kind of programs, for that matter), -whe shall often be interested in their execution time. Loosely speaking, -we will interested in the answer to the question: how long takes a -program to execute? Of course, this execution time will be a function of -the input size, and the answer to our question is commonly given as the -asymptotic behaviour as a function of the input size. At any rate, to -compute this asymptotic behaviour, we need a measure of how long -execution of a single instruction takes in our (virtual) CPU. Therefore, -each MIX instruction will have an associated execution time, given in -arbitrary units (in a real computer, the value of this unit will depend -on the hardware configuration). When our MIX virtual machine executes -programs, it will give you the value of their execution time based upon -the execution time of each single instruction. +When writing MIXAL programs (or any kind of programs, for that +matter), whe shall often be interested in their execution +time. Loosely speaking, we will interested in the answer to the +question: how long takes a program to execute? Of course, this +execution time will be a function of the input size, and the answer to +our question is commonly given as the asymptotic behaviour as a +function of the input size. At any rate, to compute this asymptotic +behaviour, we need a measure of how long execution of a single +instruction takes in our (virtual) CPU. Therefore, each MIX +instruction will have an associated execution time, given in arbitrary +units (in a real computer, the value of this unit will depend on the +hardware configuration). When our MIX virtual machine executes +programs, it will (optionally) give you the value of their execution +time based upon the execution time of each single instruction. In the following table, the execution times (in the above mentioned arbitrary units) of the MIX instructions are given. -- cgit v1.2.3