diff options
Diffstat (limited to 'doc')
29 files changed, 6292 insertions, 0 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 0000000..b2b73f0 --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,23 @@ +## Process this file with automake to produce Makefile.in + +# Copyright (C) 2000, 2001, 2003, 2004 Free Software Foundation, Inc. +# +# This file is free software; as a special exception the author gives +# unlimited permission to copy and/or distribute it, with or without +# modifications, as long as this notice is preserved. +# +# This program is distributed in the hope that it will be useful, but +# WITHOUT ANY WARRANTY, to the extent permitted by law; without even the +# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + +# $Id: Makefile.am,v 1.11 2004/08/06 12:14:07 jao Exp $ + +SUBDIRS = img +SUFFIXES = .html + +info_TEXINFOS = mdk.texi +mdk_TEXINFOS = mdk_intro.texi mdk_ack.texi mdk_tut.texi mdk_gstart.texi \ + mdk_mixvm.texi mdk_emacs.texi mdk_mixasm.texi mdk_bugs.texi \ + mdk_index.texi mdk_gmixvm.texi mdk_install.texi \ + mdk_mixguile.texi mdk_copying.texi mdk_findex.texi + diff --git a/doc/gendocs.sh b/doc/gendocs.sh new file mode 100755 index 0000000..7b8a3ca --- /dev/null +++ b/doc/gendocs.sh @@ -0,0 +1,285 @@ +#!/bin/sh +# gendocs.sh -- generate a GNU manual in many formats. This script is +# mentioned in maintain.texi. See the help message below for usage details. +# $Id: gendocs.sh,v 1.4 2005/09/20 20:18:58 jao Exp $ +# +# Copyright (C) 2003, 2004, 2005 Free Software Foundation, Inc. +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2, or (at your option) +# any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, you can either send email to this +# program's maintainer or write to: The Free Software Foundation, +# Inc.; 51 Franklin Street, Fifth Floor; Boston, MA 02110-1301, USA. +# +# Original author: Mohit Agarwal. +# Send bug reports and any other correspondence to bug-texinfo@gnu.org. + +prog="`basename \"$0\"`" +srcdir=`pwd` + +scripturl="http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/util/gendocs.sh" +templateurl="http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/util/gendocs_template" + +: ${MAKEINFO="makeinfo"} +: ${TEXI2DVI="texi2dvi -t @finalout"} +: ${DVIPS="dvips"} +: ${DOCBOOK2TXT="docbook2txt"} +: ${DOCBOOK2HTML="docbook2html"} +: ${DOCBOOK2PDF="docbook2pdf"} +: ${DOCBOOK2PS="docbook2ps"} +: ${GENDOCS_TEMPLATE_DIR="."} +unset CDPATH + +rcs_revision='$Revision: 1.4 $' +rcs_version=`set - $rcs_revision; echo $2` +program=`echo $0 | sed -e 's!.*/!!'` +version="gendocs.sh $rcs_version + +Copyright (C) 2005 Free Software Foundation, Inc. +There is NO warranty. You may redistribute this software +under the terms of the GNU General Public License. +For more information about these matters, see the files named COPYING." + +usage="Usage: $prog [OPTION]... PACKAGE MANUAL-TITLE + +Generate various output formats from PACKAGE.texinfo (or .texi or .txi) source. +See the GNU Maintainers document for a more extensive discussion: + http://www.gnu.org/prep/maintain_toc.html + +Options: + -o OUTDIR write files into OUTDIR, instead of manual/. + --docbook convert to DocBook too (xml, txt, html, pdf and ps). + --html ARG pass indicated ARG to makeinfo for HTML targets. + --help display this help and exit successfully. + --version display version information and exit successfully. + +Simple example: $prog emacs \"GNU Emacs Manual\" + +Typical sequence: + cd YOURPACKAGESOURCE/doc + wget \"$scripturl\" + wget \"$templateurl\" + $prog YOURMANUAL \"GNU YOURMANUAL - One-line description\" + +Output will be in a new subdirectory \"manual\" (by default, use -o OUTDIR +to override). Move all the new files into your web CVS tree, as +explained in the Web Pages node of maintain.texi. + +MANUAL-TITLE is included as part of the HTML <title> of the overall +manual/index.html file. It should include the name of the package being +documented. manual/index.html is created by substitution from the file +$GENDOCS_TEMPLATE_DIR/gendocs_template. (Feel free to modify the +generic template for your own purposes.) + +If you have several manuals, you'll need to run this script several +times with different YOURMANUAL values, specifying a different output +directory with -o each time. Then write (by hand) an overall index.html +with links to them all. + +You can set the environment variables MAKEINFO, TEXI2DVI, and DVIPS to +control the programs that get executed, and GENDOCS_TEMPLATE_DIR to +control where the gendocs_template file is looked for. + +Email bug reports or enhancement requests to bug-texinfo@gnu.org. +" + +calcsize() +{ + size="`ls -ksl $1 | awk '{print $1}'`" + echo $size +} + +outdir=manual +html= +PACKAGE= +MANUAL_TITLE= + +while test $# -gt 0; do + case $1 in + --help) echo "$usage"; exit 0;; + --version) echo "$version"; exit 0;; + -o) shift; outdir=$1;; + --docbook) docbook=yes;; + --html) shift; html=$1;; + -*) + echo "$0: Unknown or ambiguous option \`$1'." >&2 + echo "$0: Try \`--help' for more information." >&2 + exit 1;; + *) + if test -z "$PACKAGE"; then + PACKAGE=$1 + elif test -z "$MANUAL_TITLE"; then + MANUAL_TITLE=$1 + else + echo "$0: extra non-option argument \`$1'." >&2 + exit 1 + fi;; + esac + shift +done + +if test -s $srcdir/$PACKAGE.texinfo; then + srcfile=$srcdir/$PACKAGE.texinfo +elif test -s $srcdir/$PACKAGE.texi; then + srcfile=$srcdir/$PACKAGE.texi +elif test -s $srcdir/$PACKAGE.txi; then + srcfile=$srcdir/$PACKAGE.txi +else + echo "$0: cannot find .texinfo or .texi or .txi for $PACKAGE in $srcdir." >&2 + exit 1 +fi + +if test ! -r $GENDOCS_TEMPLATE_DIR/gendocs_template; then + echo "$0: cannot read $GENDOCS_TEMPLATE_DIR/gendocs_template." >&2 + echo "$0: it is available from $templateurl." >&2 + exit 1 +fi + +echo Generating output formats for $srcfile + +cmd="${MAKEINFO} -o $PACKAGE.info $srcfile" +echo "Generating info files... ($cmd)" +eval $cmd +mkdir -p $outdir/ +tar czf $outdir/$PACKAGE.info.tar.gz $PACKAGE.info* +info_tgz_size="`calcsize $outdir/$PACKAGE.info.tar.gz`" +# do not mv the info files, there's no point in having them available +# separately on the web. + +cmd="${TEXI2DVI} $srcfile" +echo "Generating dvi ... ($cmd)" +eval $cmd + +# now, before we compress dvi: +echo Generating postscript... +${DVIPS} $PACKAGE -o +gzip -f -9 $PACKAGE.ps +ps_gz_size="`calcsize $PACKAGE.ps.gz`" +mv $PACKAGE.ps.gz $outdir/ + +# compress/finish dvi: +gzip -f -9 $PACKAGE.dvi +dvi_gz_size="`calcsize $PACKAGE.dvi.gz`" +mv $PACKAGE.dvi.gz $outdir/ + +cmd="${TEXI2DVI} --pdf $srcfile" +echo "Generating pdf ... ($cmd)" +eval $cmd +pdf_size="`calcsize $PACKAGE.pdf`" +mv $PACKAGE.pdf $outdir/ + +cmd="${MAKEINFO} -o $PACKAGE.txt --no-split --no-headers $srcfile" +echo "Generating ASCII... ($cmd)" +eval $cmd +ascii_size="`calcsize $PACKAGE.txt`" +gzip -f -9 -c $PACKAGE.txt >$outdir/$PACKAGE.txt.gz +ascii_gz_size="`calcsize $outdir/$PACKAGE.txt.gz`" +mv $PACKAGE.txt $outdir/ + +cmd="${MAKEINFO} --no-split --html -o $PACKAGE.html $html $srcfile" +echo "Generating monolithic html... ($cmd)" +rm -rf $PACKAGE.html # in case a directory is left over +eval $cmd +html_mono_size="`calcsize $PACKAGE.html`" +gzip -f -9 -c $PACKAGE.html >$outdir/$PACKAGE.html.gz +html_mono_gz_size="`calcsize $outdir/$PACKAGE.html.gz`" +mv $PACKAGE.html $outdir/ + +cmd="${MAKEINFO} --html -o $PACKAGE.html $html $srcfile" +echo "Generating html by node... ($cmd)" +eval $cmd +split_html_dir=$PACKAGE.html +( + cd ${split_html_dir} || exit 1 + tar -czf ../$outdir/${PACKAGE}.html_node.tar.gz -- *.html +) +html_node_tgz_size="`calcsize $outdir/${PACKAGE}.html_node.tar.gz`" +rm -f $outdir/html_node/*.html +mkdir -p $outdir/html_node/ +mv ${split_html_dir}/*.html $outdir/html_node/ +rmdir ${split_html_dir} + +echo Making .tar.gz for sources... +srcfiles=`ls *.texinfo *.texi *.txi *.eps 2>/dev/null` +tar cvzfh $outdir/$PACKAGE.texi.tar.gz $srcfiles +texi_tgz_size="`calcsize $outdir/$PACKAGE.texi.tar.gz`" + +if test -n "$docbook"; then + cmd="${MAKEINFO} -o - --docbook $srcfile > ${srcdir}/$PACKAGE-db.xml" + echo "Generating docbook XML... $(cmd)" + eval $cmd + docbook_xml_size="`calcsize $PACKAGE-db.xml`" + gzip -f -9 -c $PACKAGE-db.xml >$outdir/$PACKAGE-db.xml.gz + docbook_xml_gz_size="`calcsize $outdir/$PACKAGE-db.xml.gz`" + mv $PACKAGE-db.xml $outdir/ + + cmd="${DOCBOOK2HTML} -o $split_html_db_dir ${outdir}/$PACKAGE-db.xml" + echo "Generating docbook HTML... ($cmd)" + eval $cmd + split_html_db_dir=html_node_db + ( + cd ${split_html_db_dir} || exit 1 + tar -czf ../$outdir/${PACKAGE}.html_node_db.tar.gz -- *.html + ) + html_node_db_tgz_size="`calcsize $outdir/${PACKAGE}.html_node_db.tar.gz`" + rm -f $outdir/html_node_db/*.html + mkdir -p $outdir/html_node_db + mv ${split_html_db_dir}/*.html $outdir/html_node_db/ + rmdir ${split_html_db_dir} + + cmd="${DOCBOOK2TXT} ${outdir}/$PACKAGE-db.xml" + echo "Generating docbook ASCII... ($cmd)" + eval $cmd + docbook_ascii_size="`calcsize $PACKAGE-db.txt`" + mv $PACKAGE-db.txt $outdir/ + + cmd="${DOCBOOK2PS} ${outdir}/$PACKAGE-db.xml" + echo "Generating docbook PS... $(cmd)" + eval $cmd + gzip -f -9 -c $PACKAGE-db.ps >$outdir/$PACKAGE-db.ps.gz + docbook_ps_gz_size="`calcsize $outdir/$PACKAGE-db.ps.gz`" + mv $PACKAGE-db.ps $outdir/ + + cmd="${DOCBOOK2PDF} ${outdir}/$PACKAGE-db.xml" + echo "Generating docbook PDF... ($cmd)" + eval $cmd + docbook_pdf_size="`calcsize $PACKAGE-db.pdf`" + mv $PACKAGE-db.pdf $outdir/ +fi + +echo Writing index file... +curdate="`date '+%B %d, %Y'`" +sed \ + -e "s!%%TITLE%%!$MANUAL_TITLE!g" \ + -e "s!%%DATE%%!$curdate!g" \ + -e "s!%%PACKAGE%%!$PACKAGE!g" \ + -e "s!%%HTML_MONO_SIZE%%!$html_mono_size!g" \ + -e "s!%%HTML_MONO_GZ_SIZE%%!$html_mono_gz_size!g" \ + -e "s!%%HTML_NODE_TGZ_SIZE%%!$html_node_tgz_size!g" \ + -e "s!%%INFO_TGZ_SIZE%%!$info_tgz_size!g" \ + -e "s!%%DVI_GZ_SIZE%%!$dvi_gz_size!g" \ + -e "s!%%PDF_SIZE%%!$pdf_size!g" \ + -e "s!%%PS_GZ_SIZE%%!$ps_gz_size!g" \ + -e "s!%%ASCII_SIZE%%!$ascii_size!g" \ + -e "s!%%ASCII_GZ_SIZE%%!$ascii_gz_size!g" \ + -e "s!%%TEXI_TGZ_SIZE%%!$texi_tgz_size!g" \ + -e "s!%%DOCBOOK_HTML_NODE_TGZ_SIZE%%!$html_node_db_tgz_size!g" \ + -e "s!%%DOCBOOK_ASCII_SIZE%%!$docbook_ascii_size!g" \ + -e "s!%%DOCBOOK_PS_GZ_SIZE%%!$docbook_ps_gz_size!g" \ + -e "s!%%DOCBOOK_PDF_SIZE%%!$docbook_pdf_size!g" \ + -e "s!%%DOCBOOK_XML_SIZE%%!$docbook_xml_size!g" \ + -e "s!%%DOCBOOK_XML_GZ_SIZE%%!$docbook_xml_gz_size!g" \ + -e "s,%%SCRIPTURL%%,$scripturl,g" \ + -e "s!%%SCRIPTNAME%%!$prog!g" \ +$GENDOCS_TEMPLATE_DIR/gendocs_template >$outdir/index.html + +echo "Done! See $outdir/ subdirectory for new files." diff --git a/doc/gendocs_template b/doc/gendocs_template new file mode 100644 index 0000000..3fd6fd2 --- /dev/null +++ b/doc/gendocs_template @@ -0,0 +1,100 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<!-- $Id: gendocs_template,v 1.4 2005/09/20 20:18:58 jao Exp $ --> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"> + +<head> +<title>%%TITLE%% - GNU Project - Free Software Foundation (FSF)</title> +<meta http-equiv="content-type" content='text/html; charset=utf-8' /> +<link rel="stylesheet" type="text/css" href="/gnu.css" /> +<link rev="made" href="webmasters@gnu.org" /> +</head> + +<!-- This document is in XML, and xhtml 1.0 --> +<!-- Please make sure to properly nest your tags --> +<!-- and ensure that your final document validates --> +<!-- consistent with W3C xhtml 1.0 and CSS standards --> +<!-- See validator.w3.org --> + +<body> + +<h3>%%TITLE%%</h3> + +<address>Free Software Foundation</address> +<address>last updated %%DATE%%</address> +<p> +<a href="/graphics/gnu-head.jpg"> + <img src="/graphics/gnu-head-sm.jpg" + alt=" [image of the head of a GNU] " + width="129" height="122" /> +</a> +<a href="/philosophy/gif.html">(no gifs due to patent problems)</a> +</p> +<hr /> + +<p>This manual (%%PACKAGE%%) is available in the following formats:</p> + +<ul> + <li><a href="%%PACKAGE%%.html">HTML + (%%HTML_MONO_SIZE%%K characters)</a> - entirely on one web page.</li> + <li><a href="html_node/index.html">HTML</a> - with one web page per + node.</li> + <li><a href="%%PACKAGE%%.html.gz">HTML compressed + (%%HTML_MONO_GZ_SIZE%%K gzipped characters)</a> - entirely on + one web page.</li> + <li><a href="%%PACKAGE%%.html_node.tar.gz">HTML compressed + (%%HTML_NODE_TGZ_SIZE%%K gzipped tar file)</a> - + with one web page per node.</li> + <li><a href="%%PACKAGE%%.info.tar.gz">Info document + (%%INFO_TGZ_SIZE%%K characters gzipped tar file)</a>.</li> + <li><a href="%%PACKAGE%%.txt">ASCII text + (%%ASCII_SIZE%%K characters)</a>.</li> + <li><a href="%%PACKAGE%%.txt.gz">ASCII text compressed + (%%ASCII_GZ_SIZE%%K gzipped characters)</a>.</li> + <li><a href="%%PACKAGE%%.dvi.gz">TeX dvi file + (%%DVI_GZ_SIZE%%K characters gzipped)</a>.</li> + <li><a href="%%PACKAGE%%.ps.gz">PostScript file + (%%PS_GZ_SIZE%%K characters gzipped)</a>.</li> + <li><a href="%%PACKAGE%%.pdf">PDF file + (%%PDF_SIZE%%K characters)</a>.</li> + <li><a href="%%PACKAGE%%.texi.tar.gz">Texinfo source + (%%TEXI_TGZ_SIZE%%K characters gzipped tar file)</a></li> +</ul> + +<p>(This page generated by the <a href="%%SCRIPTURL%%">%%SCRIPTNAME%% +script</a>.)</p> + +<div class="copyright"> +<p> +Return to the <a href="/home.html">GNU Project home page</a>. +</p> + +<p> +Please send FSF & GNU inquiries to +<a href="mailto:gnu@gnu.org"><em>gnu@gnu.org</em></a>. +There are also <a href="/home.html#ContactInfo">other ways to contact</a> +the FSF. +<br /> +Please send broken links and other corrections (or suggestions) to +<a href="mailto:webmasters@gnu.org"><em>webmasters@gnu.org</em></a>. +</p> + +<p> +Copyright (C) 2004 Free Software Foundation, Inc., +51 Franklin Street, Fifth Floor, Boston, MA 02111, USA +<br /> +Verbatim copying and distribution of this entire article is +permitted in any medium, provided this notice is preserved. +</p> + +<p> +Updated: +<!-- timestamp start --> +$Date: 2005/09/20 20:18:58 $ $Author: jao $ +<!-- timestamp end --> +</p> +</div> + +</body> +</html> diff --git a/doc/img/Makefile.am b/doc/img/Makefile.am new file mode 100644 index 0000000..f59647e --- /dev/null +++ b/doc/img/Makefile.am @@ -0,0 +1,16 @@ +## Process this file with automake to produce Makefile.in + +# Copyright (C) 2001, 2004 Free Software Foundation, Inc. +# +# This file is free software; as a special exception the author gives +# unlimited permission to copy and/or distribute it, with or without +# modifications, as long as this notice is preserved. +# +# This program is distributed in the hope that it will be useful, but +# WITHOUT ANY WARRANTY, to the extent permitted by law; without even the +# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + +EXTRA_DIST = ss_mix.jpg ss_mixal.jpg ss_devices.jpg ss_worddlg.jpg \ + ss_mix.txt ss_devform.jpg ss_extprog.jpg ss_symbols.jpg \ + ss_devdir.jpg ss_split.jpg + diff --git a/doc/img/ss_devdir.jpg b/doc/img/ss_devdir.jpg Binary files differnew file mode 100644 index 0000000..009fa43 --- /dev/null +++ b/doc/img/ss_devdir.jpg diff --git a/doc/img/ss_devform.jpg b/doc/img/ss_devform.jpg Binary files differnew file mode 100644 index 0000000..a93e5a0 --- /dev/null +++ b/doc/img/ss_devform.jpg diff --git a/doc/img/ss_devices.jpg b/doc/img/ss_devices.jpg Binary files differnew file mode 100644 index 0000000..ecb3679 --- /dev/null +++ b/doc/img/ss_devices.jpg diff --git a/doc/img/ss_extprog.jpg b/doc/img/ss_extprog.jpg Binary files differnew file mode 100644 index 0000000..f5607de --- /dev/null +++ b/doc/img/ss_extprog.jpg diff --git a/doc/img/ss_mix.jpg b/doc/img/ss_mix.jpg Binary files differnew file mode 100644 index 0000000..8b4080f --- /dev/null +++ b/doc/img/ss_mix.jpg diff --git a/doc/img/ss_mix.txt b/doc/img/ss_mix.txt new file mode 100644 index 0000000..757026e --- /dev/null +++ b/doc/img/ss_mix.txt @@ -0,0 +1,31 @@ +|-----------------------------------------------------------| +| Menu | +|-----------------------------------------------------------| +| | +| | +| | +| | +| MIXVM / MIXAL / Devices | +| | +| | +| | +| | +| | +| | +|-----------------------------------------------------------| +| | +| Command output | +| | +| | +| | +|-----------------------------------------------------------| +| Command prompt | +|-----------------------------------------------------------| +| Status bar | +|-----------------------------------------------------------| + + + + + + diff --git a/doc/img/ss_mixal.jpg b/doc/img/ss_mixal.jpg Binary files differnew file mode 100644 index 0000000..5227b5a --- /dev/null +++ b/doc/img/ss_mixal.jpg diff --git a/doc/img/ss_split.jpg b/doc/img/ss_split.jpg Binary files differnew file mode 100644 index 0000000..66fd4a7 --- /dev/null +++ b/doc/img/ss_split.jpg diff --git a/doc/img/ss_symbols.jpg b/doc/img/ss_symbols.jpg Binary files differnew file mode 100644 index 0000000..6a0e827 --- /dev/null +++ b/doc/img/ss_symbols.jpg diff --git a/doc/img/ss_worddlg.jpg b/doc/img/ss_worddlg.jpg Binary files differnew file mode 100644 index 0000000..fc19000 --- /dev/null +++ b/doc/img/ss_worddlg.jpg diff --git a/doc/mdk.texi b/doc/mdk.texi new file mode 100644 index 0000000..ce86b37 --- /dev/null +++ b/doc/mdk.texi @@ -0,0 +1,248 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename mdk.info +@settitle GNU MIX Development Kit (mdk) +@syncodeindex pg cp +@finalout +@setchapternewpage odd +@c $Id: mdk.texi,v 1.28 2005/09/20 21:00:22 jao Exp $ +@c %**end of header + +@set UPDATED September, 2005 +@set EDITION 1.2.1 +@set VERSION 1.2.1 +@set JAO Jose Antonio Ortega Ruiz +@set PHILIP Philip E. King +@set PIETER Pieter E. J. Pareit +@set MIKE Michael Scholz + +@copying +This manual is for GNU MDK (version @value{VERSION}, @value{UPDATED}), +a set of utilities for developing programs using Donald Knuth's MIX +mythical computer and MIXAL, its assembly language. + +Copyright @copyright{} 2000, 2001, 2002, 2003, 2004, 2005 Free Software Foundation, Inc. + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' +and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled ``GNU Free Documentation +License.'' + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' +@end quotation +@end copying + +@dircategory GNU programming tools +@direntry +* MDK: (mdk). The GNU MIX Development Kit. +@end direntry + + +@footnotestyle separate + +@titlepage +@title GNU MDK +@subtitle GNU MIX Development Kit +@subtitle Edition @value{EDITION}, for GNU @sc{mdk} Version @value{VERSION} +@subtitle @value{UPDATED} +@author by @value{JAO} (@email{jao@@gnu.org}) +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@shortcontents +@contents + +@ifnottex +@node Top, Introduction, (dir), (dir) + +@insertcopying + +GNU MDK was written and designed by @value{JAO}. + +@value{PIETER} is the author of the Emacs @code{MIXAL} mode +(@pxref{MIXAL mode}), and has also contributed many bug fixes. + +@value{PHILIP} has contributed to this package development with many +helpful discussions, as well as actual code (@pxref{GUD integration}). + +@value{MIKE} is the author of the German translation of @sc{mdk}'s +user interface. + +@end ifnottex + +@menu +* Introduction:: +* Acknowledgments:: +* Installing MDK:: Installing GNU MDK from the source tarball. +* MIX and MIXAL tutorial:: Learn the innards of MIX and MIXAL. +* Getting started:: Basic usage of the @sc{mdk} tools. +* Emacs tools:: Programming the MIX using Emacs. +* mixasm:: Invoking the MIXAL assembler. +* mixvm:: Invoking and using the MIX virtual machine. +* gmixvm:: Invoking and using the GTK+ virtual machine. +* mixguile:: Invoking and using the Scheme virtual machine. +* Problems:: Reporting bugs. +* Copying:: @sc{mdk} licensing terms. +* Concept Index:: Index of concepts. +* Instructions and commands:: Index of MIXAL instructions and MIXVM commands. + + + +@detailmenu + --- The Detailed Node Listing --- + +Installing @sc{mdk} + +* Download:: +* Requirements:: +* Basic installation:: +* Emacs support:: +* Special configure flags:: +* Supported platforms:: + +MIX and MIXAL tutorial + +* The MIX computer:: Architecture and instruction set + of the MIX computer. +* MIXAL:: The MIX assembly language. + +The MIX computer + +* MIX architecture:: +* MIX instruction set:: + +MIX instruction set + +* Instruction structure:: +* Loading operators:: +* Storing operators:: +* Arithmetic operators:: +* Address transfer operators:: +* Comparison operators:: +* Jump operators:: +* Input-output operators:: +* Conversion operators:: +* Shift operators:: +* Miscellaneous operators:: +* Execution times:: + +MIXAL + +* Basic structure:: Writing basic MIXAL programs. +* MIXAL directives:: Assembler directives. +* Expressions:: Evaluation of expressions. +* W-expressions:: Evaluation of w-expressions. +* Local symbols:: Special symbol table entries. +* Literal constants:: Specifying an immediate operand. + +Getting started + +* Writing a source file:: A sample MIXAL source file. +* Compiling:: Using @code{mixasm} to compile source + files into binary format. +* Running the program:: Running and debugging your programs. +* Using mixguile:: Using the Scheme interpreter to run and + debug your programs. +* Using Scheme in mixvm and gmixvm:: + +Running the program + +* Non-interactive mode:: Running your programs non-interactively. +* Interactive mode:: Running programs interactively. +* Debugging:: Commands for debugging your programs. + +Using @code{mixguile} + +* The mixguile shell:: Using the Scheme MIX virtual machine. +* Additional functions:: Scheme functions accessing the VM. +* Defining new functions:: Defining your own Scheme functions. +* Hook functions:: Using command and break hook functions. +* Scheme scripts:: + +Hook functions + +* Command hooks:: +* Break hooks:: + +Emacs tools + +* MIXAL mode:: Editing MIXAL files. +* GUD integration:: Invoking @code{mixvm} within Emacs. + +MIXAL mode + +* Basics:: Editing code, font locking and indentation. +* Help system:: Using the interactive help system. +* Compiling and running:: Invoking compiler and/or virtual machine. + +@code{mixasm}, the MIXAL assembler + +* Invoking mixasm:: + +@code{mixvm}, the MIX computer simulator + +* Invocation:: +* Commands:: Commands available in interactive mode. +* Devices:: MIX block devices implementation. + +Interactive commands + +* 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:: + +@code{gmixvm}, the GTK virtual machine + +* Invoking gmixvm:: +* 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. + +@code{mixguile}, the Scheme virtual machine + +* Invoking mixguile:: Command line options. +* Scheme functions reference:: Scheme functions accessing the VM. + +Scheme functions reference + +* mixvm wrappers:: Functions invoking mixvm commands. +* Hooks:: Adding hooks to mixvm commands. +* Additional VM functions:: Functions accessing the MIX virtual machine. + +Copying + +* GNU General Public License:: +* GNU Free Documentation License:: + +@end detailmenu +@end menu + +@include mdk_intro.texi +@include mdk_ack.texi +@include mdk_install.texi +@include mdk_tut.texi +@include mdk_gstart.texi +@include mdk_emacs.texi +@include mdk_mixasm.texi +@include mdk_mixvm.texi +@include mdk_gmixvm.texi +@include mdk_mixguile.texi +@include mdk_bugs.texi +@include mdk_copying.texi +@include mdk_index.texi +@include mdk_findex.texi + +@bye + diff --git a/doc/mdk_ack.texi b/doc/mdk_ack.texi new file mode 100644 index 0000000..807e276 --- /dev/null +++ b/doc/mdk_ack.texi @@ -0,0 +1,63 @@ +@c -*-texinfo-*- +@c This is part of the GNU MDK Reference Manual. +@c Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005 +@c Free Software Foundation, Inc. +@c See the file mdk.texi for copying conditions. + +@c $Id: mdk_ack.texi,v 1.15 2005/09/20 00:26:00 jao Exp $ + +@node Acknowledgments, Installing MDK, Introduction, Top +@comment node-name, next, previous, up +@unnumbered Acknowledgements + +Many people have further contributed to @sc{mdk} by reporting problems, +suggesting various improvements, or submitting actual code. Here is +a list of these people. Help me keep it complete and exempt of errors. + +@itemize @bullet +@item Richard Stallman +suggested various improvements to the documentation and has always +kept an eye on each @sc{mdk} release. + +@item Philip Ellis King +provided MIXAL test programs pinpointing bugs in the first @sc{mdk} +release, and useful discussions as well. Philip has also contributed +with the Emacs port of @code{mixvm} and influenced the @code{gmixvm} GUI +design with insightful comments and prototypes. + +@item Pieter E J Pareit +is the author of the Emacs MIXAL mode, and has also contributed many +bug fixes. + +@item Michael Scholz +is the author of the German translation of @sc{mdk}'s user interface. + +@item Sergey Poznyakoff +provided patches to mixlib/mix_scanner.l improving MIXAL compliance. + +@item Francesc Xavier Noria +kindly and thoroughly reviewed the @sc{mdk} documentation, providing +insightful advice. + +@item Nelson H. F. Beebe +has tested @sc{mdk} in a lot of Unix platforms, suggesting portability +enhancements to the source code. + +@item Agustin Navarro, Ying-Chieh Liao, Adrian Bunk, Baruch Even, and Ronald Cole +ported @sc{mdk} to different platforms, and created and/or maintain +packages for it. + +@item Jason Uhlenkott, Andrew Hood, Aleix Conchillo, Radu Butnaru, Ruslan Batdalov, WeiZheng and Sascha Wilde +reported bugs and suggested fixes to them. + +@item Eli Bendersky, Milan Bella and Jens Seidel reported bugs on the documentation. + +@item Christoph von Nathusius, Stephen Ramsay and Johan Swanljung +tested @sc{mdk} on different platforms, and helped fix the configuration +process in them. + +@item @sc{mdk} was inspired by Darius Bacon's +@uref{http://www.accesscom.com/@/~darius/, MIXAL program}. + +@end itemize + diff --git a/doc/mdk_bugs.texi b/doc/mdk_bugs.texi new file mode 100644 index 0000000..1b18064 --- /dev/null +++ b/doc/mdk_bugs.texi @@ -0,0 +1,24 @@ +@c -*-texinfo-*- +@c This is part of the GNU MDK Reference Manual. +@c Copyright (C) 2000, 2001, 2003, 2004 +@c Free Software Foundation, Inc. +@c See the file mdk.texi for copying conditions. + +@c $Id: mdk_bugs.texi,v 1.6 2004/08/03 13:23:06 jao Exp $ + +@node Problems, Copying, mixguile, Top +@chapter Reporting Bugs +@cindex bugs +@cindex problems +@cindex questions +@cindex suggestions + +If you have any questions, comments or suggestions, please send +electronic mail to @email{jao@@gnu.org, the author}. + +If you find a bug in @sc{mdk}, please send electronic mail to +@email{bug-mdk@@gnu.org, the @sc{mdk} bug list}. + +In your report, please include the version number, which you can find by +running @w{@samp{mixasm --version}}. Also include in your message the +output that the program produced and the output you expected. diff --git a/doc/mdk_copying.texi b/doc/mdk_copying.texi new file mode 100644 index 0000000..8aa5e90 --- /dev/null +++ b/doc/mdk_copying.texi @@ -0,0 +1,866 @@ +@node Copying, Concept Index, Problems, Top +@appendix Copying + +@menu +* GNU General Public License:: +* GNU Free Documentation License:: +@end menu + +GNU MDK is distributed under the GNU General Public License (GPL) and +this manual under the GNU Free Documentation License (GFDL). + +@node GNU General Public License, GNU Free Documentation License, Copying, Copying +@appendixsec GNU General Public License +@cindex GPL, GNU General Public License + +@lowersections + +@center Version 2, June 1991 + +@display +Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc. +51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display + +@unnumberedsec Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software---to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Library General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + +@iftex +@unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION +@end iftex +@ifinfo +@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION +@end ifinfo + +@enumerate +@item +This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The ``Program'', below, +refers to any such program or work, and a ``work based on the Program'' +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term ``modification''.) Each licensee is addressed as ``you''. + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + +@item +You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + +@item +You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + +@enumerate a +@item +You must cause the modified files to carry prominent notices +stating that you changed the files and the date of any change. + +@item +You must cause any work that you distribute or publish, that in +whole or in part contains or is derived from the Program or any +part thereof, to be licensed as a whole at no charge to all third +parties under the terms of this License. + +@item +If the modified program normally reads commands interactively +when run, you must cause it, when started running for such +interactive use in the most ordinary way, to print or display an +announcement including an appropriate copyright notice and a +notice that there is no warranty (or else, saying that you provide +a warranty) and that users may redistribute the program under +these conditions, and telling the user how to view a copy of this +License. (Exception: if the Program itself is interactive but +does not normally print such an announcement, your work based on +the Program is not required to print an announcement.) +@end enumerate + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + +@item +You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + +@enumerate a +@item +Accompany it with the complete corresponding machine-readable +source code, which must be distributed under the terms of Sections +1 and 2 above on a medium customarily used for software interchange; or, + +@item +Accompany it with a written offer, valid for at least three +years, to give any third party, for a charge no more than your +cost of physically performing source distribution, a complete +machine-readable copy of the corresponding source code, to be +distributed under the terms of Sections 1 and 2 above on a medium +customarily used for software interchange; or, + +@item +Accompany it with the information you received as to the offer +to distribute corresponding source code. (This alternative is +allowed only for noncommercial distribution and only if you +received the program in object code or executable form with such +an offer, in accord with Subsection b above.) +@end enumerate + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + +@item +You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + +@item +You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + +@item +Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + +@item +If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + +@item +If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + +@item +The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and ``any +later version'', you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + +@item +If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + +@iftex +@heading NO WARRANTY +@end iftex +@ifinfo +@center NO WARRANTY +@end ifinfo + +@item +BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + +@item +IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. +@end enumerate + +@iftex +@heading END OF TERMS AND CONDITIONS +@end iftex +@ifinfo +@center END OF TERMS AND CONDITIONS +@end ifinfo + +@page +@unnumberedsec How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the ``copyright'' line and a pointer to where the full notice is found. + +@smallexample +@var{one line to give the program's name and an idea of what it does.} +Copyright (C) 19@var{yy} @var{name of author} + +This program is free software; you can redistribute it and/or +modify it under the terms of the GNU General Public License +as published by the Free Software Foundation; either version 2 +of the License, or (at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program; if not, write to the Free Software +Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. +@end smallexample + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + +@smallexample +Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author} +Gnomovision comes with ABSOLUTELY NO WARRANTY; for details +type `show w'. This is free software, and you are welcome +to redistribute it under certain conditions; type `show c' +for details. +@end smallexample + +The hypothetical commands @samp{show w} and @samp{show c} should show +the appropriate parts of the General Public License. Of course, the +commands you use may be called something other than @samp{show w} and +@samp{show c}; they could even be mouse-clicks or menu items---whatever +suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a ``copyright disclaimer'' for the program, if +necessary. Here is a sample; alter the names: + +@smallexample +@group +Yoyodyne, Inc., hereby disclaims all copyright +interest in the program `Gnomovision' +(which makes passes at compilers) written +by James Hacker. + +@var{signature of Ty Coon}, 1 April 1989 +Ty Coon, President of Vice +@end group +@end smallexample + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Library General +Public License instead of this License. + +@raisesections + + + +@node GNU Free Documentation License +@appendixsec GNU Free Documentation License + +@cindex FDL, GNU Free Documentation License +@center Version 1.2, November 2002 + +@display +Copyright @copyright{} 2000,2001,2002 Free Software Foundation, Inc. +51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display + +@enumerate 0 +@item +PREAMBLE + +The purpose of this License is to make a manual, textbook, or other +functional and useful document @dfn{free} in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. + +This License is a kind of ``copyleft'', which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + +@item +APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The ``Document'', below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as ``you''. You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. + +A ``Modified Version'' of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A ``Secondary Section'' is a named appendix or a front-matter section +of the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall +subject (or to related matters) and contains nothing that could fall +directly within that overall subject. (Thus, if the Document is in +part a textbook of mathematics, a Secondary Section may not explain +any mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The ``Invariant Sections'' are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. + +The ``Cover Texts'' are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. + +A ``Transparent'' copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not ``Transparent'' is called ``Opaque''. + +Examples of suitable formats for Transparent copies include plain +@sc{ascii} without markup, Texinfo input format, La@TeX{} input +format, @acronym{SGML} or @acronym{XML} using a publicly available +@acronym{DTD}, and standard-conforming simple @acronym{HTML}, +PostScript or @acronym{PDF} designed for human modification. Examples +of transparent image formats include @acronym{PNG}, @acronym{XCF} and +@acronym{JPG}. Opaque formats include proprietary formats that can be +read and edited only by proprietary word processors, @acronym{SGML} or +@acronym{XML} for which the @acronym{DTD} and/or processing tools are +not generally available, and the machine-generated @acronym{HTML}, +PostScript or @acronym{PDF} produced by some word processors for +output purposes only. + +The ``Title Page'' means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, ``Title Page'' means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +A section ``Entitled XYZ'' means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as ``Acknowledgements'', +``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' +of such a section when you modify the Document means that it remains a +section ``Entitled XYZ'' according to this definition. + +The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. + +@item +VERBATIM COPYING + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + +@item +COPYING IN QUANTITY + +If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + +@item +MODIFICATIONS + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +@enumerate A +@item +Use in the Title Page (and on the covers, if any) a title distinct +from that of the Document, and from those of previous versions +(which should, if there were any, be listed in the History section +of the Document). You may use the same title as a previous version +if the original publisher of that version gives permission. + +@item +List on the Title Page, as authors, one or more persons or entities +responsible for authorship of the modifications in the Modified +Version, together with at least five of the principal authors of the +Document (all of its principal authors, if it has fewer than five), +unless they release you from this requirement. + +@item +State on the Title page the name of the publisher of the +Modified Version, as the publisher. + +@item +Preserve all the copyright notices of the Document. + +@item +Add an appropriate copyright notice for your modifications +adjacent to the other copyright notices. + +@item +Include, immediately after the copyright notices, a license notice +giving the public permission to use the Modified Version under the +terms of this License, in the form shown in the Addendum below. + +@item +Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document's license notice. + +@item +Include an unaltered copy of this License. + +@item +Preserve the section Entitled ``History'', Preserve its Title, and add +to it an item stating at least the title, year, new authors, and +publisher of the Modified Version as given on the Title Page. If +there is no section Entitled ``History'' in the Document, create one +stating the title, year, authors, and publisher of the Document as +given on its Title Page, then add an item describing the Modified +Version as stated in the previous sentence. + +@item +Preserve the network location, if any, given in the Document for +public access to a Transparent copy of the Document, and likewise +the network locations given in the Document for previous versions +it was based on. These may be placed in the ``History'' section. +You may omit a network location for a work that was published at +least four years before the Document itself, or if the original +publisher of the version it refers to gives permission. + +@item +For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve +the Title of the section, and preserve in the section all the +substance and tone of each of the contributor acknowledgements and/or +dedications given therein. + +@item +Preserve all the Invariant Sections of the Document, +unaltered in their text and in their titles. Section numbers +or the equivalent are not considered part of the section titles. + +@item +Delete any section Entitled ``Endorsements''. Such a section +may not be included in the Modified Version. + +@item +Do not retitle any existing section to be Entitled ``Endorsements'' or +to conflict in title with any Invariant Section. + +@item +Preserve any Warranty Disclaimers. +@end enumerate + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section Entitled ``Endorsements'', provided it contains +nothing but endorsements of your Modified Version by various +parties---for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + +@item +COMBINING DOCUMENTS + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections Entitled ``History'' +in the various original documents, forming one section Entitled +``History''; likewise combine any sections Entitled ``Acknowledgements'', +and any sections Entitled ``Dedications''. You must delete all +sections Entitled ``Endorsements.'' + +@item +COLLECTIONS OF DOCUMENTS + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + +@item +AGGREGATION WITH INDEPENDENT WORKS + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an ``aggregate'' if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. + +@item +TRANSLATION + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + +If a section in the Document is Entitled ``Acknowledgements'', +``Dedications'', or ``History'', the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. + +@item +TERMINATION + +You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. + +@item +FUTURE REVISIONS OF THIS LICENSE + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +@uref{http://www.gnu.org/copyleft/}. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License ``or any later version'' applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. +@end enumerate + +@page +@appendixsubsec ADDENDUM: How to use this License for your documents + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +@smallexample +@group + Copyright (C) @var{year} @var{your name}. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.2 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. +@end group +@end smallexample + +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the ``with...Texts.'' line with this: + +@smallexample +@group + with the Invariant Sections being @var{list their titles}, with + the Front-Cover Texts being @var{list}, and with the Back-Cover Texts + being @var{list}. +@end group +@end smallexample + +If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. + +@c Local Variables: +@c ispell-local-pdict: "ispell-dict" +@c End: + diff --git a/doc/mdk_emacs.texi b/doc/mdk_emacs.texi new file mode 100644 index 0000000..e0c6973 --- /dev/null +++ b/doc/mdk_emacs.texi @@ -0,0 +1,136 @@ +@c -*-texinfo-*- +@c This is part of the GNU MDK Reference Manual. +@c Copyright (C) 2003, 2004 +@c Free Software Foundation, Inc. +@c See the file mdk.texi for copying conditions. + +@node Emacs tools, mixasm, Getting started, Top +@chapter Emacs tools + +Everyone writing code knows how important a good editor is. Most +systems already come with Emacs, and excellent programmer's editor. +@sc{mdk} adds support to Emacs for both writing and debugging MIX +programs. A major mode for MIXAL source files eases edition of your +code, while integration with Emacs' debugging interface +(@acronym{GUD}) lets you use @code{mixvm} without leaving your +favourite text editor. + +This chapter shows how to use the Elisp modules included in @sc{mdk}, +assuming that you have followed the installation instructions in +@xref{Emacs support}. + +@menu +* MIXAL mode:: Editing MIXAL files. +* GUD integration:: Invoking @code{mixvm} within Emacs. +@end menu + +@node MIXAL mode, GUD integration, Emacs tools, Emacs tools +@section MIXAL mode + +The module @file{mixal-mode.el} provides a new mode, mixal-mode, for +editing MIXAL source files@footnote{mixal-mode has been developed and +documented by @value{PIETER}}. When everything is installed correctly, +Emacs will select it as the major mode for editing files with extension +@code{.mixal}. You can also activate mixal-mode in any buffer +issuing the Emacs command @code{M-x mixal-mode}. + +@menu +* Basics:: Editing code, font locking and indentation. +* Help system:: Using the interactive help system. +* Compiling and running:: Invoking compiler and/or virtual machine. +@end menu + +@node Basics, Help system, MIXAL mode, MIXAL mode +@comment node-name, next, previous, up +@subsection Basics + +The mode for editing mixal source files is inherited from +fundamental-mode, meaning that all your favorite editing operations +will still work. If you want a short introduction to Emacs, type +@kbd{C-h t} inside Emacs to start the tutorial. + +Mixal mode adds font locking. If you do not have font locking globally +enabled, you can turn it on for mixal-mode by placing the following +line in your @file{.emacs} file: + +@lisp +(add-hook 'mixal-mode-hook 'turn-on-font-lock) +@end lisp + +You can also customize the colors used to colour your mixal code by +changing the requisite faces. This is the list of faces used by +mixal-mode: + +@itemize +@item @var{font-lock-comment-face} +Face to use for comments. +@item @var{mixal-font-lock-label-face} +Face to use for label names. +@item @var{mixal-font-lock-operation-code-face} +Face to use for operation code names. +@item @var{mixal-font-lock-assembly-pseudoinstruction-face} +Face to use for assembly pseudo-instruction names. +@end itemize + +@node Help system, Compiling and running, Basics, MIXAL mode +@comment node-name, next, previous, up +@subsection Help system + +When coding your program, you will be thinking, looking up +documentation and editing files. Emacs already helps you with editing +files, but Emacs can do much more. In particular, looking up +documentation is one of its strong points. Besides the info system +(which you are probably already using), mixal-mode defines commands +for getting particular information about a MIX operation code. + +With @kbd{M-x mixal-describe-operation-code} (or its keyboard shortcut +@kbd{C-h o}) you will get the documentation about a particular MIX +operation code. Keep in mind that these are not assembly (MIXAL) +pseudoinstructions. When the @code{point} is around a MIXAL +pseudoinstruction in your source file, Emacs will recognize it and +will suggest the right MIX operation code. + +@node Compiling and running, , Help system, MIXAL mode +@comment node-name, next, previous, up +@subsection Compiling and running + +After you have written your MIXAL program, you'll probably want to +test it. This can be done with the MIX virtual machine. First you will +need to compile your code into MIX byte code. This can be done within +Emacs with the command @kbd{M-x compile} (@kbd{C-c c}). In case of +compilation errors, you can jump to the offending source code line +with @kbd{M-x next-error}. + +Once the program compiles without errors, you can debug or run +it. To invoke the debugger, use @kbd{M-x mixal-debug} (@kbd{C-c d}). +Emacs will open a @code{GUD} buffer where you can +use the debugging commands described in @xref{mixvm}. + +If you just want to execute the program, you can do so with @kbd{M-x +mixal-run} (@kbd{C-c r}). This will invoke mixvm, +execute the program and show its output in a separate buffer. + +@node GUD integration, , MIXAL mode, Emacs tools +@section GUD integration + +If you are an Emacs user and write your MIXAL programs using this +editor, you will find the elisp program @file{mixvm.el} quite +useful@footnote{@file{mixvm.el} has been kindly contributed by +@value{PHILIP}. @file{mixvm.el} is based on a study of gdb, perldb, and +pdb as found in @file{gud.el}, and @file{rubydb3x.el} distributed with +the source code to the Ruby language.}. @file{mixvm.el} allows running +the MIX virtual machine @code{mixvm} (@pxref{mixvm}) inside an Emacs +@acronym{GUD} buffer, while visiting the MIXAL source file in another +buffer. + +After installing @file{mixvm.el} (@pxref{Emacs support}), you can +initiate an @sc{mdk}/@acronym{GUD} session inside Emacs with the command + +@example +M-x mixvm +@end example + +@noindent +and you will have a @code{mixvm} prompt inside a newly created +@acronym{GUD} buffer. @acronym{GUD} will reflect the current line in the +corresponding source file buffer. diff --git a/doc/mdk_findex.texi b/doc/mdk_findex.texi new file mode 100644 index 0000000..24a269f --- /dev/null +++ b/doc/mdk_findex.texi @@ -0,0 +1,11 @@ +@c -*-texinfo-*- +@c This is part of the GNU MDK Reference Manual. +@c Copyright (C) 2000, 2001, 2003, 2004 +@c Free Software Foundation, Inc. +@c See the file mdk.texi for copying conditions. + +@c $Id: mdk_findex.texi,v 1.3 2004/08/03 13:23:06 jao Exp $ + +@node Instructions and commands, , Concept Index, Top +@unnumbered Instructions and commands +@printindex fn diff --git a/doc/mdk_gmixvm.texi b/doc/mdk_gmixvm.texi new file mode 100644 index 0000000..bddb362 --- /dev/null +++ b/doc/mdk_gmixvm.texi @@ -0,0 +1,394 @@ +@c -*-texinfo-*- +@c This is part of the GNU MDK Reference Manual. +@c Copyright (C) 2000, 2001, 2003, 2004 +@c Free Software Foundation, Inc. +@c See the file mdk.texi for copying conditions. + +@c $Id: mdk_gmixvm.texi,v 1.18 2004/08/03 13:23:06 jao Exp $ + +@node gmixvm, mixguile, mixvm, Top +@comment node-name, next, previous, up +@chapter @code{gmixvm}, the GTK virtual machine +@cindex @code{gmixvm} +@cindex GUI +@cindex GTK+ + +This chapter describes the graphical MIX virtual machine emulator +shipped with @sc{mdk}. In addition to having all the command-oriented +functionalities of the other virtual machines (@code{mixvm} and +@code{mixguile}), @code{gmixvm} offers you a graphical interface +displaying the status of the virtual machine, the source code of the the +downloaded programs and the contents of the MIX devices. + +@menu +* Invoking gmixvm:: +* 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 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 [-vhuq] [--version] [--help] [--usage] [--noinit] +@end example +@noindent +at your command prompt, where the options have the following meanings: + +@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 -q +@defoptx --noinit +Do not load the Guile initialisation file @code{~/.mdk/mixguile.scm} at +startup. This file contains any local Scheme code to be executed by the +embedded Guile interpreter at startup (@pxref{Using Scheme in mixvm and +gmixvm}). +@end defopt + +Typing @code{gmixvm} or @code{gmixvm -q} at your command prompt, the +main window will appear, offering you a graphical interface to run and +debug your MIX programs. + +@ifinfo +@image{img/ss_mix, 400pt} +@end ifinfo + +@ifhtml +@image{../img/ss_mix, 400pt} +@end ifhtml + +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 +These three windows can be detached from the notebook, using either +the penultimate toolbar button (which detachs the currently visible +notebook page) or the menu entries under @code{@w{View->Detached windows}}. + +@ifhtml +Here is an screenshot showing how @code{gmixvm} looks like when running +with a couple of detached windows: + +@image{../img/ss_split, 420pt} + +@end ifhtml + +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. 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 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 @code{@w{Settings->Change font->Command +prompt}} and @code{@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). + +If you click any register entry, you will be prompted for a new register's +contents. + +@ifhtml +The next figure shows the enter word dialog. + +@image{../img/ss_worddlg, 250pt} + +@end ifhtml + +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. + +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 @code{@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 Source, shows you the MIXAL source of +the currently loaded MIX file. + +@ifhtml +@image{../img/ss_mixal, 400pt} +@end ifhtml + +The information is presented in four columns. The first column +displays little icons showing the current program pointer and any set +breakpoints. The second and third columns show the address and memory +contents of the compiled MIX instruction, while the last one displays +its corresponding MIXAL representation, together with the source file +line number. You can set/unset breakpoints by clicking on any line +that has an associated memory address. + +You can change the font used to display the MIXAL source code +using the @code{@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. + +@ifhtml + +@image{../img/ss_devices, 400pt} + +@end ifhtml + +Input device contents is read from files located in the @file{~/.mdk} +directory, and the output is also written to 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) is 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 @code{@w{Settings->Device output}} +menu command for each binary device. + +You can change the font used to display the devices content +using the @code{@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 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. The font used to display this list can be +customised using the meny entry @code{@w{Settings->Change font->Symbol +list}}. + +@ifhtml + +@image{../img/ss_symbols, 250pt} + +@end ifhtml + +@end deffn + +@deffn View @w{Toolbar(s)} +Toggles the toolbar(s) in the @code{gmixvm} window(s) (when notebook +pages are detached, each one has its own toolbar). +@end deffn + +@deffn View @w{Detached windows} @w{Virtual machine} +@deffnx View @w{Detached windows} Source +@deffnx View @w{Detached windows} Devices + +These toggles let you detach (or re-attach) the corresponding notebook +page. + +@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, Virtual machine, Source, Devices and +Symbol list). There is also an entry (@code{All}) to change all fonts +at once. +@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. + +@ifhtml +@image{../img/ss_devform, 250pt} +@end ifhtml + +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). + +@ifhtml +@image{../img/ss_devdir, 250pt} +@end ifhtml + +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. + +@ifhtml +@image{../img/ss_extprog, 250pt} +@end ifhtml + +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. diff --git a/doc/mdk_gstart.texi b/doc/mdk_gstart.texi new file mode 100644 index 0000000..9eab3f6 --- /dev/null +++ b/doc/mdk_gstart.texi @@ -0,0 +1,1058 @@ +@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_gstart.texi,v 1.17 2004/08/01 21:43:29 jao Exp $ + +@node Getting started, Emacs tools, MIX and MIXAL tutorial, Top +@chapter Getting started +@cindex tutorial + +In this chapter, you will find a sample code-compile-run-debug session +using the @sc{mdk} utilities. Familiarity with the MIX mythical computer +and its assembly language MIXAL (as described in Knuth's TAOCP) is +assumed; for a compact reminder, see @ref{MIX and MIXAL tutorial}. + +@menu +* Writing a source file:: A sample MIXAL source file. +* Compiling:: Using @code{mixasm} to compile source + files into binary format. +* Running the program:: Running and debugging your programs. +* Using mixguile:: Using the Scheme interpreter to run and + debug your programs. +* Using Scheme in mixvm and gmixvm:: +@end menu + +@node Writing a source file, Compiling, Getting started, Getting started +@section Writing a source file +@cindex MIXAL +@cindex source file +@cindex .mixal file + +MIXAL programs can be written as ASCII files with your editor of choice. +Here you have the mandatory @emph{hello world} as written in the MIXAL +assembly language: + +@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) + HLT halt execution (8) +MSG ALF "MIXAL" (9) + ALF " HELL" (10) + ALF "O WOR" (11) + ALF "LD " (12) + END START end of the program (13) +@end example + +@noindent MIXAL source files should have the extension @file{.mixal} +when used with the @sc{mdk} utilities. As you can see in the above +sample, each line in a MIXAL file can be divided into four fields +separated by an arbitrary amount of whitespace characters (blanks and or +tabs). While in Knuth's definition of MIXAL each field must start at a +fixed pre-defined column number, the @sc{mdk} assembler loosens this +requirement and lets you format the file as you see fit. The only +restrictions retained are for comment lines (like 1-4) which must begin +with an asterisk (*) placed at column 1, and for the label field (see +below) which, if present, must also start at column 1. The four fields +in each non-comment line are: + +@itemize @minus +@item +an optional label, which either refers to the current memory address (as +@code{START} and @code{MSG} in lines 7 and 9) or a defined symbol +(@code{TERM}) (if present, the label must always start at the first +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 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 +an optional free text comment. +@end itemize + +@noindent Lines 9-12 of the @file{hello.mixal} file above also show the +second (and last) difference between Knuth's MIXAL definition and ours: +the operand of the @code{ALF} pseudoinstruction (a word of five +characters) must be quoted using ""@footnote{In Knuth's definition, +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. 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 thorough definition or +@ref{MIX and MIXAL tutorial}, for a tutorial. + +@node Compiling, Running the program, Writing a source file, Getting started +@section Compiling +@cindex compiling +@cindex binary programs +@cindex virtual machine +@cindex assembler +@cindex @code{mixasm} + +Three simulators of the MIX computer, called @code{mixvm}, @code{gmixvm} +and @code{mixguile}, are included in the @sc{mdk} tools. They are able to +run binary files containing MIX instructions written in their binary +representation. You can translate MIXAL source files into this binary +form using @code{mixasm}, the MIXAL assembler. So, in order to compile +the @file{hello.mixal} file, you can type the following command at your +shell prompt: + +@example +mixasm hello @key{RET} +@end example + +@cindex .mix file + +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. Unless the @code{mixasm} option @code{-O} is provided, the +assembler will 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 your first MIX program, as +described in the following section. + + +@node Running the program, Using mixguile, Compiling, Getting started +@section Running the program +@cindex @code{mixvm} +@cindex non-interactive mode +@cindex interactive mode + +MIX is a mythical computer, so it is no use ordering it from your +favorite hardware provider. @sc{mdk} provides three software simulators of +the computer, though. They are + +@itemize @bullet +@item +@code{mixvm}, a command line oriented simulator, +@item +@code{gmixvm}, a GTK based graphical interface to @code{mixvm}, and +@item +@code{mixguile}, a Guile shell with a built-in MIX simulator. +@end itemize + +All three simulators accept the same set of user commands, but offer a +different user interface, as noted above. In this section we shall +describe some of these commands, and show you how to use them from +@code{mixvm}'s command line. You can use them as well at @code{gmixvm}'s +command prompt (@pxref{gmixvm}), or using the built-in Scheme primitives +of @code{mixguile} (@pxref{Using mixguile}). + +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 to load, run and debug +programs, as well as to inspect the MIX computer state (register +contents, memory cells contents and so on). + +@menu +* Non-interactive mode:: Running your programs non-interactively. +* Interactive mode:: Running programs interactively. +* Debugging:: Commands for debugging your programs. +@end menu + +@node Non-interactive mode, Interactive mode, Running the program, Running the program +@comment node-name, next, previous, up +@subsection Non-interactive mode +@cindex non-interactive mode + +To make @code{mixvm} work in non-interactive mode, use the @code{-r} +flag. Thus, to run our @file{hello.mix} program, simply type + +@example +mixvm -r hello @key{RET} +@end example + +@noindent at your command prompt, and you will get the following output: + +@example +MIXAL HELLO WORLD +@end example + +@noindent Since our hello world program uses MIX's device number 19 as +its output device (@pxref{Writing a source file}), the output is +redirected to the shell's standard output. Had you used any other MIX +output devices (disks, drums, line printer, etc.), @code{mixvm} would +have created a file named after the device used (e.g. @file{disk4.dev}) +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})}. + +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}). 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, +@code{mixvm}'s @code{-d} flag is your friend: it makes @code{mixvm} to +dump the contents of its registers and flags after executing the loaded +program. For instance, typing the following command at your shell's +prompt + +@example +mixvm -d -r hello +@end example + +@noindent you will obtain the following output: + +@example +MIXAL HELLO WORLD +rA: + 00 00 00 00 00 (0000000000) +rX: + 00 00 00 00 00 (0000000000) +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) +Overflow: F +Cmp: E +@end example + +@noindent which, in addition to the program's outputs and execution +time, gives you the contents of the MIX registers and the values of the +overflow toggle and comparison flag (admittedly, rather uninteresting in +our sample). + +As you can see, running programs non-interactively has many +limitations. You cannot peek the virtual machine's memory contents, not +to mention stepping through your program's instructions or setting +breakpoints@footnote{The @code{mixguile} program allows you to execute +arbitrary combinations of @code{mixvm} commands (using Scheme) +non-interactively. @xref{Scheme scripts}.}. Enter interactive mode. + +@node Interactive mode, Debugging, Non-interactive mode, Running the program +@comment node-name, next, previous, up +@subsection Interactive mode +@cindex interactive mode + +To enter the MIX virtual machine interactive mode, simply type + +@example +mixvm @key{RET} +@end example + +@noindent at your shell command prompt. This command enters the +@code{mixvm} command shell. You will be presented the following command +prompt: + +@example +MIX > +@end example + +@noindent The virtual machine is initialised and ready to accept your +commands. The @code{mixvm} command shell uses GNU's readline, so that +you have at your disposal command completion (using @key{TAB}) and +history functionality, as well as other line editing shortcuts common to +all utilities using this library (for a complete description of +readline's line editing usage, see @ref{Command Line +Editing,,,Readline}.) + +@cindex @code{load} +Usually, the first thing you will want to do is loading a compiled MIX +program into memory. This is acomplished by the @code{load} command, +which takes as an argument the name of the @file{.mix} file to be +loaded. Thus, typing + +@example +MIX > load hello @key{RET} +Program loaded. Start address: 3000 +MIX > +@end example + +@noindent will load @file{hello.mix} into the virtual machine's memory +and set the program counter to the address of the first instruction. You +can obtain the contents of the program counter using the command +@code{pc}: + +@cindex @code{pc} +@example +MIX > pc +Current address: 3000 +MIX > +@end example + +@cindex @code{run} +After loading it, you are ready to run the program, using, as you surely +have guessed, the @code{run} command: + +@example +MIX > run +Running ... +MIXAL HELLO WORLD +... done +Elapsed time: 11 /Total program time: 11 (Total uptime: 11) +MIX > +@end example + +@noindent Note that now the timing statistics are richer. You obtain the +elapsed execution time (i.e., the time spent executing instructions +since the last breakpoint), the total execution time for the program up +to now (which in our case coincides with the elapsed time, since there +were no breakpoints), and the total uptime for the virtual machine (you +can load and run more than one program in the same +session)@footnote{Printing of timing statistics can be disabled using +the command @code{timing} (@pxref{Configuration commands}).}. After +running the program, the program counter will point to the address after +the one containing the @code{HLT} instruction. In our case, asking the +value of the program counter after executing the program will give us + +@example +MIX > pc +Current address: 3002 +MIX > +@end example + +@cindex @code{pmem} +@noindent You can check the contents of a memory cell giving its address +as an argument of the command @code{pmem}, like this + +@example +MIX > pmem 3001 +3001: + 00 00 00 02 05 (0000000133) +MIX > +@end example + +@noindent +and convince yourself that address 3001 contains the binary +representation of the instruction @code{HLT}. An address range of the +form FROM-TO can also be used as the argument of @code{pmem}: + +@example +MIX > pmem 3000-3006 +3000: + 46 58 00 19 37 (0786957541) +3001: + 00 00 00 02 05 (0000000133) +3002: + 14 09 27 01 13 (0237350989) +3003: + 00 08 05 13 13 (0002118477) +3004: + 16 00 26 16 19 (0268542995) +3005: + 13 04 00 00 00 (0219152384) +3006: + 00 00 00 00 00 (0000000000) +MIX > +@end example + +@cindex @code{preg} +@noindent +In a similar manner, you can look at the contents of the MIX registers +and flags. For instance, to ask for the contents of the A register you +can type + +@example +MIX > preg A +rA: + 00 00 00 00 00 (0000000000) +MIX > +@end example + +@cindex @code{help} +@noindent +Use the comand @code{help} to obtain a list of all available commands, +and @code{help COMMAND} for help on a specific command, e.g. + +@example +MIX > help run +run Run loaded or given MIX code file. Usage: run [FILENAME] +MIX > +@end example + +@noindent +For a complete list of commands available at the MIX propmt, +@xref{mixvm}. In the following subsection, you will find a quick tour +over commands useful for debugging your programs. + +@node Debugging, , Interactive mode, Running the program +@comment node-name, next, previous, up +@subsection Debugging commands + +@cindex @code{next} +The interactive mode of @code{mixvm} lets you step by step execution of +programs as well as breakpoint setting. Use @code{next} to step through +the program, running its instructions one by one. To run our +two-instruction @file{hello.mix} sample you can do the following: + +@example +MIX > load hello +Program loaded. Start address: 3000 +MIX > pc +Current address: 3000 +MIX > next +MIXAL HELLO WORLD +Elapsed time: 1 /Total program time: 1 (Total uptime: 1) +MIX > pc +Current address: 3001 +MIX > next +End of program reached at address 3002 +Elapsed time: 10 /Total program time: 11 (Total uptime: 11) +MIX > pc +Current address: 3002 +MIX > next +MIXAL HELLO WORLD +Elapsed time: 1 /Total program time: 1 (Total uptime: 12) +MIX > +MIX > run +Running ... +... done +Elapsed time: 10 /Total program time: 11 (Total uptime: 22) +MIX > +@end example +@noindent +(As an aside, the above sample also shows how the virtual machine +handles cummulative time statistics and automatic program restart). + +@cindex @code{sbpa} +@cindex breakpoints + +You can set a breakpoint at a given address using the command +@code{sbpa} (set breakpoint at address). When a breakpoint is set, +@code{run} will stop before executing the instruction at the given +address. Typing @code{run} again will resume program execution. Coming +back to our hello world example, we would have: + +@example +MIX > sbpa 3001 +Breakpoint set at address 3001 +MIX > run +Running ... +MIXAL HELLO WORLD +... stopped: breakpoint at line 8 (address 3001) +Elapsed time: 1 /Total program time: 1 (Total uptime: 23) +MIX > run +Running ... +... done +Elapsed time: 10 /Total program time: 11 (Total uptime: 33) +MIX > +@end example + +@cindex @code{sbp} +@cindex breakpoints +@noindent +Note that, since we compiled @file{hello.mixal} with debug info +enabled, the virtual machine is able to tell us the line in the +source file corresponding to the breakpoint we are setting. As a +matter of fact, you can directly set breakpoints at source code lines +using the command @code{sbp LINE_NO}, e.g. + +@example +MIX > sbp 4 +Breakpoint set at line 7 +MIX > +@end example + +@noindent +@code{sbp} sets the breakpoint at the first meaningful source code line; +thus, in the above example we have requested a breakpoint at a line +which does not correspond to a MIX instruction and the breakpoint is set +at the first line containing a real instruction after the given one. To +unset breakpoints, use @code{cbpa ADDRESS} and @code{cbp LINE_NO}, or +@code{cabp} to remove all currently set breakpoints. You can also set +conditional breakpoints, i.e., tell @code{mixvm} to interrupt program +execution whenever a register, a memory cell, the comparison flag or the +overflow toggle change using the commands @w{@code{sbp[rmco]}} +(@pxref{Debug commands}). + +@cindex @code{psym} +MIXAL lets you define symbolic constants, either using the @code{EQU} +pseudoinstruction or starting an instruction line with a label (which +assigns to the label the value of the current memory address). Each +MIXAL program has, therefore, an associated symbol table which you can +inspect using the @code{psym} command. For our hello world sample, you +will obtain the following output: + +@example +MIX > psym +START: 3000 +TERM: 19 +MSG: 3002 +MIX > +@end example + +Other useful commands for debugging are @code{strace} (which turns on +tracing of executed intructions), @code{pbt} (which prints a backtrace +of executed instructions) and @code{weval} (which evaluates +w-expressions on the fly). For a complete description of all available +MIX commands, @xref{mixvm}. + +@node Using mixguile, Using Scheme in mixvm and gmixvm, Running the program, Getting started +@section Using @code{mixguile} + +With @code{mixguile} you can run a MIX simulator embedded in a Guile +shell, that is, using Scheme functions and programs. As with +@code{mixvm}, @code{mixguile} can be run both in interactive and +non-interactive modes. The following subsections provide a quick tour on +using this MIX emulator. + +@menu +* The mixguile shell:: Using the Scheme MIX virtual machine. +* Additional functions:: Scheme functions accessing the VM. +* Defining new functions:: Defining your own Scheme functions. +* Hook functions:: Using command and break hook functions. +* Scheme scripts:: +@end menu + +@node The mixguile shell, Additional functions, Using mixguile, Using mixguile +@subsection The @code{mixguile} shell +@cindex Scheme +@cindex @code{mixguile} +@cindex REPL + +If you simply type + +@example +mixguile @key{RET} +@end example +@noindent +at the command prompt, you'll be presented a Guile shell prompt like +this + +@example +guile> +@end example +@noindent +At this point, you have entered a Scheme read-eval-print loop (REPL) +which offers you all the Guile functionality plus a new set of built-in +procedures to execute and debug MIX programs. Each of the @code{mixvm} +commands described in the previous sections (and in @pxref{mixvm}) have +a Scheme function counterpart named after it by prepending the prefix +@code{mix-} to its name. Thus, to load our hello world program, you can +simply enter + +@example +guile> (mix-load "hello") +Program loaded. Start address: 3000 +guile> +@end example +@noindent +and run it using @code{mix-run}: + +@example +guile> (mix-run) +Running ... +MIXAL HELLO WORLD +... done +Elapsed time: 11 /Total program time: 11 (Total uptime: 11) +guile> +@end example +@noindent +In the same way, you can execute it step by step using the Scheme +function @code{mix-next} or set a breakpoint: + +@example +guile> (mix-sbp 4) +Breakpoint set at line 5 +guile> +@end example +@noindent +or, if you one to peek at a register contents: + +@example +guile> (mix-preg 'A) +rA: + 00 00 00 00 00 (0000000000) +guile> +@end example + +You get the idea: you have at your disposal all the @code{mixvm} and +@code{gmixvm} commands by means of @code{mix-} functions. But, in case +you are wondering, this is only the beginning. You also have at your +disposal a whole Scheme interpreter, and you can, for instance, define +new functions combining the @code{mix-} and all other Scheme +primitives. In the next sections, you'll find examples of how to take +advantage of the Guile interpreter. + +@node Additional functions, Defining new functions, The mixguile shell, Using mixguile +@subsection Additional MIX Scheme functions + +The @code{mix-} function counterparts of the @code{mixvm} commands don't +return any value, and are evaluated only for their side-effects +(possibly including informational messages to the standard output and/or +error stream). When writting your own Scheme functions to manipulate the +MIX virtual machine within @code{mixguile} (@pxref{Defining new +functions}), you'll probably need Scheme functions returning the value +of the registers, memory cells and so on. Don't worry: @code{mixguile} +also offers you such functions. For instance, to access the (numerical) +value of a register you can use @code{mix-reg}: + +@example +guile> (mix-reg 'I2) +0 +guile> +@end example +@noindent +Note that, unlike @code{(mix-preg 'I2)}, the expression @code{(mix-reg +'I2)} in the above example evaluates to a Scheme number and does not +produce any side-effect: + +@example +guile> (number? (mix-reg 'I2)) +#t +guile> (number? (mix-preg 'I2)) +rI2: + 00 00 (0000) +#f +guile> +@end example + +In a similar fashion, you can access the memory contents using +@code{(mix-cell)}, or the program counter using @code{(mix-loc)}: + +@example +guile> (mix-cell 3000) +786957541 +guile> (mix-loc) +3002 +guile> +@end example + +Other functions returning the contents of the virtual machine components +are @code{mix-cmp} and @code{mix-over}, which eval to the value of the +comparison flag and the overflow toggle respectively. For a complete +list of these additional functions, @xref{mixguile}. + +In the next section, we'll see a sample of using these functions to +extend @code{mixguile}'s functionality. + +@node Defining new functions, Hook functions, Additional functions, Using mixguile +@subsection Defining new functions +@cindex Scheme functions + +Scheme is a powerful language, and you can use it inside @code{mixguile} +to easily extend the MIX interpreter's capabilities. For example, you +can easily define a function that loads a file, prints its name, +executes it and, finally, shows the registers contents, all in one shot: + +@example +guile> (define my-load-and-run @key{RET} + (lambda (file) @key{RET} + (mix-load file) @key{RET} + (display "File loaded: ") @key{RET} + (mix-pprog) @key{RET} + (mix-run) @key{RET} + (mix-preg))) @key{RET} +guile> +@end example +@noindent +and use it to run your programs: + +@example +guile> (my-load-and-run "hello") +Program loaded. Start address: 3000 +File loaded: hello.mix +Running ... +MIXAL HELLO WORLD +... done +Elapsed time: 11 /Total program time: 11 (Total uptime: 33) +rA: + 00 00 00 00 00 (0000000000) +rX: + 00 00 00 00 00 (0000000000) +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) +guile> +@end example + + +Or, maybe, you want a function which sets a breakpoint at a specified +line number before executing it: + +@example +guile> (define my-load-and-run-with-bp + (lambda (file line) + (mix-load file) + (mix-sbp line) + (mix-run))) +guile> (my-load-and-run-with-bp "samples/primes" 10) +Program loaded. Start address: 3000 +Breakpoint set at line 10 +Running ... +... stopped: breakpoint at line 10 (address 3001) +Elapsed time: 1 /Total program time: 1 (Total uptime: 45) +guile> +@end example + +As a third example, the following function loads a program, runs it and +prints the contents of the memory between the program's start and end +addresses: + +@example +guile> (define my-run + (lambda (file) + (mix-load file) + (let ((start (mix-loc))) + (mix-run) + (mix-pmem start (mix-loc))))) +guile> (my-run "hello") +Program loaded. Start address: 3000 +Running ... +MIXAL HELLO WORLD +... done +Elapsed time: 11 /Total program time: 11 (Total uptime: 11) +3000: + 46 58 00 19 37 (0786957541) +3001: + 00 00 00 02 05 (0000000133) +3002: + 14 09 27 01 13 (0237350989) +guile> +@end example + + +As you can see, the possibilities are virtually unlimited. Of course, +you don't need to type a function definition each time you start +@code{mixguile}. You can write it in a file, and load it using Scheme's +@code{load} function. For instance, you can create a file named, say, +@file{functions.scm} with your definitions (or any Scheme expression) +and load it at the @code{mixguile} prompt: + +@example +guile> (load "functions.scm") +@end example + +Alternatively, you can make @code{mixguile} to load it for you. When +@code{mixguile} starts, it looks for a file named @file{mixguile.scm} in +your MDK configuration directory (@file{~/.mdk}) and, if it exists, +loads it before entering the REPL. Therefore, you can copy your +definitions in that file, or load the @file{functions.scm} file in +@file{mixguile.scm}. + +@node Hook functions, Scheme scripts, Defining new functions, Using mixguile +@subsection Hook functions +@cindex hook function +@cindex pre-hook +@cindex post-hook + +Hooks are functions called before or after a given event occurs. In +@code{mixguile}, you can define command and break hooks, which are +associated, respectively, with command execution and program +interruption events. The following sections give you a tutorial on using +hook functions within @code{mixguile}. + +@menu +* Command hooks:: +* Break hooks:: +@end menu + +@node Command hooks, Break hooks, Hook functions, Hook functions +@subsubsection Command hooks + +In the previous section, we have seen how to extend @code{mixguile}'s +functionality through the use of user defined functions. Frequently, +you'll write new functions that improve in some way the workings of a +built-in @code{mixvm} command, following this pattern: + +@enumerate a +@item +Prepare the command execution +@item +Execute the desired command +@item +Perform post execution operations +@end enumerate + +We call the functions executed in step (a) @dfn{pre-hook}s, and those of +step @dfn{post-hook}s of the given command. @code{mixguile} lets you +specify pre- and post-hooks for any @code{mixvm} command using the +@code{mix-add-pre-hook} and @code{mix-add-post-hook} functions, which +take as arguments a symbol naming the command and a function to be +executed before (resp. after) the command. In other words, +@code{mixguile} will execute for you steps (a) and (c) above whenever +you eval (b). The hook functions must take a single argument, which is a +string list of the command's arguments. As an example, let us define the +following hooks for the @code{next} command: + +@example +(define next-pre-hook + (lambda (arglist) + (mix-slog #f))) + +(define next-post-hook + (lambda (arglist) + (display "Stopped at line ") + (display (mix-src-line-no)) + (display ": ") + (display (mix-src-line)) + (newline) + (mix-slog #t))) +@end example +@noindent +In these functions, we are using the function @code{mix-slog} to turn +off the informational messages produced by the virtual machine, since we +are providing our own ones in the post hook function. To install these +hooks, we would write: + +@example +(mix-add-pre-hook 'next next-pre-hook) +(mix-add-post-hook 'next next-post-hook) +@end example +@noindent +Assuming we have put the above expressions in @code{mixguile}'s +initialisation file, we would obtain the following results when +evaluating @code{mix-next}: + +@example +guile> (mix-next) +MIXAL HELLO WORLD +Stopped at line 6: HLT +guile> +@end example + +As a second, more elaborated, example, let's define hooks which print +the address and contents of a cell being modified using @code{smem}. The +hook functions could be something like this: + +@example +(define smem-pre-hook + (lambda (arglist) + (if (eq? (length arglist) 2) + (begin + (display "Changing address ") + (display (car arglist)) + (newline) + (display "Old contents: ") + (display (mix-cell (string->number (car arglist)))) + (newline)) + (error "Wrong arguments" arglist)))) + +(define smem-post-hook + (lambda (arglist) + (if (eq? (length arglist) 2) + (begin + (display "New contents: ") + (display (mix-cell (string->number (car arglist)))) + (newline))))) +@end example +@noindent +and we can install them using + +@example +(mix-add-pre-hook 'smem smem-pre-hook) +(mix-add-post-hook 'smem smem-post-hook) +@end example +@noindent +Aferwards, a sample execution of @code{mix-smem} would look like this: + +@example +guile> (mix-smem 2000 100) +Changing address 2000 +Old contents: 0 +New contents: 100 +guile> +@end example + +@cindex global hook + +You can add any number of hooks to a given command. They will be +executed in the same order as they are registered. You can also define +global post (pre) hooks, which will be called before (after) any +@code{mixvm} command is executed. Global hook functions must admit two +arguments, namely, a string naming the invoked command and a string list +of its arguments, and they are installed using the Scheme functions +@code{mix-add-global-pre-hook} and @code{mix-add-global-post-hook}. A +simple example of global hook would be: + +@example +guile> (define pre-hook + (lambda (cmd args) + (display cmd) + (display " invoked with arguments ") + (display args) + (newline))) +guile> (mix-add-global-pre-hook pre-hook) +ok +guile> (mix-pmem 120 125) +pmem invoked with arguments (120-125) +0120: + 00 00 00 00 00 (0000000000) +0121: + 00 00 00 00 00 (0000000000) +0122: + 00 00 00 00 00 (0000000000) +0123: + 00 00 00 00 00 (0000000000) +0124: + 00 00 00 00 00 (0000000000) +0125: + 00 00 00 00 00 (0000000000) +guile> +@end example + +Note that if you invoke @code{mixvm} commands within a global hook, its +associated command hooks will be run. Thus, if you have installed both +the @code{next} hooks described earlier and the global hook above, +executing @code{mix-next} will yield the following result: + +@example +guile> (mix-next 5) +next invoked with arguments (5) +slog invoked with arguments (off) +MIXAL HELLO WORLD +Stopped at line 7: MSG ALF "MIXAL" +slog invoked with arguments (on) +guile> +@end example + +Adventurous readers may see the above global hook as the beginning of a +command log utility or a macro recorder that saves your commands for +replay. + +@node Break hooks, , Command hooks, Hook functions +@subsubsection Break hooks + +@cindex break hook + +We have seen in the previous section how to associate hooks to command +execution, but they are not the whole story. You can also associate hook +functions to program interruption, that is, specify functions that +should be called every time the execution of a MIX program is stopped +due to the presence of a breakpoint, either explicit or +conditional. Break hooks take as arguments the line number and memory +address at which the break occurred. A simple hook that logs the line +and address of the breakpoint could be defined as: + +@example +(define break-hook + (lambda (line address) + (display "Breakpoint encountered at line ") + (display line) + (display " and address ") + (display address) + (newline))) +@end example +@noindent +and installed for explicit and conditional breakpoints using + +@example +(mix-add-break-hook break-hook) +(mix-add-cond-break-hook break-hook) +@end example +@noindent +after that, every time the virtual machine encounters a breakpoint, +@code{break-code} shall be evaluated for you@footnote{You may have +noticed that break hooks can be implemented in terms of command hooks +associated to @code{mix-run} and @code{mix-next}. As a matter of fact, +they @emph{are} implemented this way: take a look at the file +@file{@emph{install_dir}/share/mdk/mix-vm-stat.scm} if you are curious.}. + +@node Scheme scripts, , Hook functions, Using mixguile +@subsection Scheme scripts +@cindex Scheme script +@cindex non-interactive + +Another useful way of using @code{mixguile} is writing executable +scripts that perform a set of commands for you. This is done using the +@code{mixguile} switch @code{-s} (being a Guile shell, @code{mixguile} +accepts all the command options of @code{guile}; type @code{mixguile -h} +for a list of all available command options). For instance, if you have +a very useful MIX program @file{foo.mix} which you want to run often, +you don't have to fire a MIX virtual machine, load and run it every +time; you can write a Scheme script instead: + +@example +#! /usr/bin/mixguile -s +!# +;;; runprimes: execute the primes.mix program + +;; load the file you want to run +(mix-load "../samples/primes") +;; execute it +(mix-run) +;; print the contents of registers +(mix-pall) +;; ... +@end example + +Just save the above script to a file named, say, @file{runtest}, make it +executable (@code{chmod +x runtest}), and, well, execute it from the +Unix shell: + +@example +$ ./runtest +Program loaded. Start address: 3000 +Running ... +... done +Elapsed time: 190908 /Total program time: 190908 (Total uptime: 190908) +rA: + 30 30 30 30 30 (0511305630) +rX: + 30 30 32 32 39 (0511313959) +rJ: + 47 18 (3026) +rI1: + 00 00 (0000) rI2: + 55 51 (3571) +rI3: + 00 19 (0019) rI4: + 31 51 (2035) +rI5: + 00 00 (0000) rI6: + 00 00 (0000) +Overflow: F +Cmp: L +$ +@end example + +Note that this is far more flexible that running programs +non-interactively using @code{mixvm} (@pxref{Non-interactive mode}), for +you can execute any combination of commands you want from a Scheme +script (not just running and dumping the registers). For additional +@code{mixguile} command line options, see @ref{Invoking mixguile}. + +@node Using Scheme in mixvm and gmixvm, , Using mixguile, Getting started +@section Using Scheme in @code{mixvm} and @code{gmixvm} +@cindex @code{scmf} + +In the previous section (@pxref{Using mixguile}) we have seen how the +Guile shell @code{mixguile} offers you the possibility of using Scheme +to manipulate a MIx virtual machine and extend the set of commands +offered by @code{mixvm} and @code{gmixvm}. This possibility is not +limited to the @code{mixguile} shell. Actually, both @code{mixvm} and +@code{gmixvm} incorporate an embedded Guile interpreter, and can +evaluate Scheme expressions. To evaluate a single-line expression at the +@code{mixvm} or @code{gmixvm} command prompt, simply write it and press +return (the command parser will recognise it as a Scheme expression +because it is parenthesized, and will pass it to the Guile +interpreter). A sample @code{mixvm} session using Scheme expressions +could be: + +@example +MIX > load hello +Program loaded. Start address: 3000 +MIX > (define a (mix-loc)) +MIX > run +Running ... +MIXAL HELLO WORLD +... done +Elapsed time: 11 /Total program time: 11 (Total uptime: 11) +MIX > (mix-pmem a) +3000: + 46 58 00 19 37 (0786957541) +MIX > (mix-pmem (mix-loc)) +3002: + 14 09 27 01 13 (0237350989) +MIX > +@end example + +You can also load and evaluate a file, using the @code{scmf} +command like this: + +@example +MIX> scmf /path/to/file/file.scm +@end example + +Therefore, you have at your disposal all the @code{mixguile} goodies +described above (new functions, new command definitions, hooks...) +inside @code{mixvm} and @code{gmixvm}. In other words, these programs +are extensible using Scheme. See @ref{Using mixguile} for examples of +how to do it. + diff --git a/doc/mdk_index.texi b/doc/mdk_index.texi new file mode 100644 index 0000000..68f3c48 --- /dev/null +++ b/doc/mdk_index.texi @@ -0,0 +1,14 @@ +@c -*-texinfo-*- +@c This is part of the GNU MDK Reference Manual. +@c Copyright (C) 2000, 2001, 2003, 2004 +@c Free Software Foundation, Inc. +@c See the file mdk.texi for copying conditions. + +@c $Id: mdk_index.texi,v 1.7 2004/08/03 13:23:06 jao Exp $ + +@node Concept Index, Instructions and commands, Copying, Top +@unnumbered Concept Index + +@cindex tail recursion +@printindex cp + diff --git a/doc/mdk_install.texi b/doc/mdk_install.texi new file mode 100644 index 0000000..08a44e2 --- /dev/null +++ b/doc/mdk_install.texi @@ -0,0 +1,287 @@ +@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. + +@node Installing MDK, MIX and MIXAL tutorial, Acknowledgments, Top +@comment node-name, next, previous, up +@chapter Installing @sc{mdk} + +@menu +* Download:: +* Requirements:: +* Basic installation:: +* Emacs support:: +* Special configure flags:: +* Supported platforms:: +@end menu + +@node Download, Requirements, Installing MDK, Installing MDK +@comment node-name, next, previous, up +@section Download the source tarball + +GNU @sc{mdk} is distributed as a source tarball available for download in +the following @acronym{URL}s: + +@itemize @bullet +@item +@url{ftp://ftp.gnu.org/pub/gnu/mdk} +@item +@uref{http://www.gnu.org/prep/ftp.html, GNU mirrors} +@item +@uref{http://sourceforge.net/project/showfiles.php?group_id=13897} +@end itemize + +The above sites contain the latest stable releases of @sc{mdk}. The +development branch is available at: + +@itemize @bullet +@item +@uref{https://savannah.gnu.org/cvs/?group_id=118} +@end itemize + +After you have downloaded the source tarball, unpack it in a directory +of your choice using the command: + +@example +tar xfvz mdk-X.Y.tar.gz +@end example + +@noindent +where @var{X.Y} stands for the downloaded version (the current stable +release being version @value{VERSION}). + +@node Requirements, Basic installation, Download, Installing MDK +@comment node-name, next, previous, up +@section Requirements + +In order to build and install @sc{mdk}, you will need the following +libraries installed in your system: + +@itemize @minus +@item +@uref{http://www.gtk.org, GLIB 2.4.0} (required) +@item +@uref{http://www.gnu.org/software/flex/flex.html, GNU Flex 2.5} (required) +@item +@uref{http://www.gtk.org, GTK 2.4.0} (optional) +@item +@uref{http://ftp.gnome.org/pub/GNOME/sources/libglade/2.4/, Libglade +2.4.0} +(optional) +@item +@uref{http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html, GNU +Readline} +(optional) +@item +@uref{http://www.gnu.org/software/guile, GNU Libguile 1.6} (optional) +@end itemize + +If present, readline and history are used to provide command completion +and history management to the command line MIX virtual machine, @code{mixvm}. +GTK+ and libglade are needed if you want to build the graphical +interface to the MIX virtual machine, @code{gmixvm}. Finally, if +libguile is found, the @sc{mdk} utilities will be compiled with Guile +support and will be extensible using Scheme. + +@strong{Please note}: you need both the libraries @emph{and} the +headers; this means both the library package and the @file{-dev} package +if you do not compile your libraries yourself (ex: installing +@file{libgtk2.0-0} and @file{libgtk2.0-0-dev} on Debian). + +@node Basic installation, Emacs support, Requirements, Installing MDK +@comment node-name, next, previous, up +@section Basic installation + +@sc{mdk} uses GNU Autoconf and Automake tools, and, therefore, should +be built and installed without hassle using the following commands +inside the source directory: + +@example +./configure +make +make install +@end example + +@noindent +where the last one must be run as root. + +The first command, @code{configure}, will setup the makefiles for your +system. In particular, @code{configure} will look for GTK+ and libglade, +and, if they are present, will generate the appropiate makefiles for +building the @code{gmixvm} graphical user interface. Upon completion, +you should see a message with the configuration results like the +following: + +@example +*** GNU MDK 1.2 has been successfully configured. *** + +Type 'make' to build the following utilities: + - mixasm (MIX assembler) + - mixvm (MIX virtual machine, with readline support, + with guile support) + - gmixvm (mixvm GTK+ GUI, with guile support) + - mixguile (the mixvm guile shell) +@end example + +@noindent +where the last lines may be missing if you lack the above mentioned +libraries. + +The next command, @code{make}, will actually build the @sc{mdk} programs +in the following locations: + +@itemize @minus +@item +@file{mixutils/mixasm} +@item +@file{mixutils/mixvm} +@item +@file{mixgtk/gmixvm} +@item +@file{mixguile/mixguile} +@end itemize + +You can run these programs from within their directories, but I +recommend you to install them in proper locations using @code{make +install} from a root shell. + +@node Emacs support, Special configure flags, Basic installation, Installing MDK +@comment node-name, next, previous, up +@section Emacs support + +@sc{mdk} includes extensive support for Emacs. Upon installation, all +the elisp code is installed in @file{PREFIX/share/mdk}, where +@file{PREFIX} stands for your installation root directory (e.g. +@file{/usr/local}). You can copy the elisp files to a directory that +is in your load-path, or you can add the above directory to it. +Assuming that the installing prefix is @file{/usr/local}, +you can do it by adding to your @file{.emacs} file the following line: + +@lisp +(setq load-path (cons "/usr/local/share/mdk" load-path)) +@end lisp + +@code{MIXAL} programs can be written using Emacs and the elisp program +@file{share/mdk/mixal-mode.el}, contributed by @value{PIETER}. It +provides font locking, interactive help, compiling assistance and +invocation of the @code{MIX} virtual machine via a new major mode +called @code{mixal-mode}. To start @code{mixal-mode} automatically +whenever you edit a @code{MIXAL} source file, add the following lines +to your @file{.emacs} file: + +@lisp +(autoload 'mixal-mode "mixal-mode" t) +(add-to-list 'auto-mode-alist '("\\.mixal\\'" . mixal-mode)) +@end lisp + +In addition, @code{mixvm} can be run within an Emacs @acronym{GUD} +buffer using the elisp program @file{share/mdk/mixvm.el}, contributed +by @value{PHILIP}. @file{mixvm.el} provides an interface between +@sc{mdk}'s @code{mixvm} and Emacs, via @acronym{GUD}. Place this file +in your load-path, optionally adding the following line to your +@file{.emacs} file: + +@lisp +(autoload 'mixvm "mixvm" "mixvm/gud interaction" t) +@end lisp + + +@node Special configure flags, Supported platforms, Emacs support, Installing MDK +@comment node-name, next, previous, up +@section Special configure flags + +You can fine-tune the configuration process using the following +switches with configure: + +@defopt @w{--enable-gui[=yes|no]} +@defoptx --disable-gui +Enables/disables the build of the MIX virtual machine GUI +(@code{gmixvm}). If the required libraries are missing +(@pxref{Requirements}) the configure script with automatically disable +this feature. +@end defopt + +@defopt @w{--with-guile[=yes|no]} +@defoptx --without-guile +Enables/disables the Guile support for @code{mixvm} and @code{gmixvm}, +and the build of @code{mixguile}. If the +required libraries are missing (@pxref{Requirements}) the configure +script with automatically disable this feature. +@end defopt + +@defopt @w{--with-readline[=yes|no]} +@defoptx --without-readline +Enables/disables the GNU Readline support for @code{mixvm}. If the +required libraries are missing (@pxref{Requirements}) the configure +script with automatically disable this feature. +@end defopt + +For additional, boilerplate configure options, see the @file{INSTALL} +file, or run + +@example +configure --help +@end example + +@node Supported platforms, , Special configure flags, Installing MDK +@comment node-name, next, previous, up +@section Supported platforms + +GNU MDK has been tested in the following platforms: + +@itemize +@item +Debian GNU/Linux 2.2, 2.3, 3.0, 3.1, 3.2 +@item +Redhat GNU/Linux 8.0 (Ronald Cole), 7.0 (Agustin Navarro), 6.2 +(Roberto Ferrero) +@item +Mandrake 8.0 (Agustin Navarro) +@item +FreeBSD 4.2, 4.3, 4.4, 4.5 (Ying-Chieh Liao), 5.2 +@item +Solaris 2.8/gcc 2.95.3 (Stephen Ramsay) +@item +MS Windows 98 SE/Cygwin 1.1.8-2 (Christoph von +Nathusius)@footnote{Caveats: Christoph has only tested @code{mixvm} and +@code{mixasm} on this platform, using @code{gcc} 2.95.3-2, @code{GLIB} +1.2.10 and @code{GNUreadline} 4.1-2. He has reported missing history +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) +@item +AMD Athlon, GNU/Linux version 2.4.2-2smp (Red Hat 7.1 (Seawolf)) (N. +H. F. Beebe) +@item +Apple PowerPC G3, GNU/Linux 2.2.18-4hpmac (Red Hat Linux/PPC +2000 Q4) (N. H. F. Beebe) +@item +DEC Alpha, GNU/Linux 2.2.19-6.2.1 (Red Hat 6.2) (N. H. F. Beebe) +@item +Compaq/DEC Alpha OSF/1 4.0F [ONLY after adding rsync's snprintf() +implementation] (N. H. F. Beebe) +@item +IBM PowerPC AIX 4.2 (N. H. F. Beebe) +@item +Intel Pentium III, GNU/Linux 2.4.9-31smp (Red Hat 7.2 (Enigma)) (N. H. +F. Beebe) +@item +SGI Origin 200, IRIX 6.5 (N. +H. F. Beebe) +@item +Sun SPARC, GNU/Linux 2.2.19-6.2.1 (Red Hat 6.2) (N. H. F. Beebe) +@item +Sun SPARC, Solaris 2.8 (N. H. F. Beebe) +@end itemize + +@sc{mdk} will probably work on any GNU/Linux or BSD platform. If you +try it in a platform not listed above, please send a mail to +@email{jao@@gnu.org, the author}. + + + + diff --git a/doc/mdk_intro.texi b/doc/mdk_intro.texi new file mode 100644 index 0000000..b4ce2ad --- /dev/null +++ b/doc/mdk_intro.texi @@ -0,0 +1,70 @@ +@c -*-texinfo-*- +@c This is part of the GNU MDK Reference Manual. +@c Copyright (C) 2000, 2001, 2003, 2004 +@c Free Software Foundation, Inc. +@c See the file mdk.texi for copying conditions. + +@c $Id: mdk_intro.texi,v 1.8 2004/08/03 13:23:06 jao Exp $ + +@node Introduction, Acknowledgments, Top, Top +@comment node-name, next, previous, up +@unnumbered Introduction +@cindex Introduction + +In his book series @cite{The Art of Computer Programming} (published by +Addison Wesley), D. Knuth uses an imaginary computer, the MIX, and its +associated machine-code and assembly languages to ilustrate the +concepts and algorithms as they are presented. + +The MIX's architecture is a simplified version of those found in real +CISC CPUs, and the MIX assembly language (MIXAL) provides a set of +primitives that will be very familiar to any person with a minimum +experience in assembly programming. The MIX/MIXAL definition is powerful +and complete enough to provide a virtual development platform for +writing quite complex programs, and close enough to real computers to be +worth using when learning programming techniques. At any rate, if you +want to learn or improve your programming skills, a MIX development +environment would come in handy. + +The @sc{mdk} package aims at providing such virtual development +environment on a GNU box. Thus, @sc{mdk} offers you a set of utilities +to simulate the MIX computer and to write, compile, run and debug MIXAL +programs. As of version @value{VERSION}, @sc{mdk} includes +the following programs: + +@table @code +@item mixasm +MIXAL assembler. Assembler which translates MIXAL source files into +programs that can be run (and debugged) by @code{mixvm}, @code{mixguile} +or @code{gmixvm}. +@item mixvm +MIX virtual machine. Emulation of the MIX computer with a @acronym{CLI}. +@item gmixvm +A GTK+ GUI for the MIX virtual machine. Provides all of @code{mixvm} +functionality accessible through a graphical interface. +@item mixguile +A Guile shell, with an embedded MIX virtual machine and built-in +commands to manipulate it using Scheme. +@item mixal-mode.el +An Emacs major mode for MIXAL source files editing, providing syntax +highlighting, documentation lookup and invocation of @code{mixvm} +within Emacs. +@item mixvm.el +This elisp program allows running @code{mixvm} inside an Emacs GUD +buffer, providing concurrent edition and debugging of MIXAL programs. +@end table + +@code{mixvm} and @code{gmixvm} implement a simulator of the MIX +computer, giving you a virtual machine for executing and debugging MIX +programs. These binary programs could be written by hand, but it is +easier to produce them compiling MIXAL source files, using the MIXAL +assembler @code{mixasm}. On the other hand, @code{mixguile} offers you +the possibility of manipulating a MIX virtual machine through a set of +Scheme functions, so that you can use this programming language to +interact with the virtual machine. In addition, @code{mixvm} and +@code{gmixvm} are also able to interpret Scheme scripts (using an +embedded Guile interpreter), that is, you can use Scheme as an extension +language to add new functionalities to these programs. + +This manual gives you a tutorial of MIX and MIXAL, and a thorough +description of the use of the @sc{mdk} utilities. diff --git a/doc/mdk_mixasm.texi b/doc/mdk_mixasm.texi new file mode 100644 index 0000000..fa144a7 --- /dev/null +++ b/doc/mdk_mixasm.texi @@ -0,0 +1,89 @@ +@c -*-texinfo-*- +@c This is part of the GNU MDK Reference Manual. +@c Copyright (C) 2000, 2001, 2003, 2004 +@c Free Software Foundation, Inc. +@c See the file mdk.texi for copying conditions. + +@c $Id: mdk_mixasm.texi,v 1.10 2004/08/05 21:32:46 jao Exp $ + +@node mixasm, mixvm, Emacs tools, Top +@comment node-name, next, previous, up +@chapter @code{mixasm}, the MIXAL assembler +@cindex @code{mixasm} +@cindex MIXAL +@cindex assembler + +MIX programs, as executed by @code{mixvm}, are composed of binary +instructions loaded into the virtual machine memory as MIX +words. Although you could write your MIX programs directly as a series +of words in binary format, you have at your disposal a more friendly +assembly language, MIXAL (@pxref{MIXAL}) which is compiled into binary +form by @code{mixasm}, the MIXAL assembler included in @sc{mdk}. In this +chapter, you will find a complete description of @code{mixasm} options. + +@menu +* Invoking mixasm:: +@end menu + +@node Invoking mixasm, , mixasm, mixasm +@comment node-name, next, previous, up +@section Invoking @code{mixasm} + +In its simplest form, @code{mixasm} is invoked with a single argument, +which is the name of the MIXAL file to be compiled, e.g. + +@example +mixasm hello +@end example + +@noindent +will compile either @file{hello} or @file{hello.mixal}, producing a +binary file named @file{hello.mix} if no errors are found. + +In addition, @code{mixasm} 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 +mixasm [-vhulO] [-o OUTPUT_FILE] [--version] [--help] [--usage] + [--ndebug] [--output=OUTPUT_FILE] [--list[=LIST_FILE]] file +@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 -O +@defoptx --ndebug +Do not include debugging information in the compiled file, saving +space but disallowing breakpoint setting at source level and symbol +table inspection under @code{mixvm}. +@end defopt + +@defopt -o output_file +@defoptx --output=output_file +By default, the given source file @var{file.mixal} is compiled into +@var{file.mix}. You can provide a different name for the output file +using this option. +@end defopt + +@defopt -l +@defoptx @w{--list[=list_file]} +@cindex .mls file +This option causes @code{mixasm} to produce, in addion to the +@file{.mix} file, an ASCII file containing a summary of the compilation +results. The file is named after the MIXAL source file, changing its +extension to @file{.mls} if no argument is provided; otherwise, the +listing file is named according to the argument. +@end defopt diff --git a/doc/mdk_mixguile.texi b/doc/mdk_mixguile.texi new file mode 100644 index 0000000..2d6ac65 --- /dev/null +++ b/doc/mdk_mixguile.texi @@ -0,0 +1,445 @@ +@c -*-texinfo-*- +@c This is part of the GNU MDK Reference Manual. +@c Copyright (C) 2000, 2001, 2003, 2004 +@c Free Software Foundation, Inc. +@c See the file mdk.texi for copying conditions. + +@c $Id: mdk_mixguile.texi,v 1.5 2004/08/03 13:23:06 jao Exp $ + +@node mixguile, Problems, gmixvm, Top +@chapter @code{mixguile}, the Scheme virtual machine +@cindex @code{mixguile} + +This chapter provides a reference to using @code{mixguile} and the +Scheme function library giving access to the MIX virtual machine in the +@sc{mdk} emulators (@code{mixguile}, @code{mixvm} and @code{gmixvm}). See +@ref{Using mixguile} for a tutorial, step by step introduction to +@code{mixguile} and using Scheme as an extension language for the +@sc{mdk} MIX virtual machines. + +@menu +* Invoking mixguile:: Command line options. +* Scheme functions reference:: Scheme functions accessing the VM. +@end menu + +@node Invoking mixguile, Scheme functions reference, mixguile, mixguile +@section Invoking @code{mixguile} +@cindex @code{mixguile} options + +Invoking @code{mixguile} without arguments will enter the Guile REPL +(read-eval-print loop) after loading, if it exists, the user's +initialisation file (@file{~/.mdk/mixguile.scm}). + +@code{mixguile} accepts the same command line options than Guile: + +@example +mixguile [-s SCRIPT] [-c EXPR] [-l FILE] [-e FUNCTION] [-qhv] + [--help] [--version] +@end example + +The meaning of these options is as follows: + +@defopt -h +@defoptx --help +Prints usage summary and exits. +@end defopt + +@defopt -v +@defoptx --version +Prints version and copyleft information and exits. +@end defopt + +@defopt -s SCRIPT +Loads Scheme code from @var{script}, evaluates it and exits. This option +can be used to write executable Scheme scripts, as described in +@ref{Scheme scripts}. +@end defopt + +@defopt -c EXPR +Evaluates the given Scheme expression and exits. +@end defopt + +@defopt -l FILE +Loads the given Scheme file and enters the REPL (read-eval-print loop). +@end defopt + +@defopt -e FUNCTION +After reading the script, executes the given function using the provided +command line arguments. For instance, you can write the following Scheme +script: + +@example +#! /usr/bin/mixguile \ +-e main -s +!# + +;;; execute a given program and print the registers. + +(define main + (lambda (args) + ;; load the file provided as a command line argument + (mix-load (cadr args)) + ;; execute it + (mix-run) + ;; print the contents of registers + (mix-pall))) + +@end example +@noindent +save it in a file called, say, @file{foo}, make it executable, and run +it as + +@example +$ ./foo hello +@end example +@noindent +This invocation will cause the evaluation of the @code{main} function +with a list of command line parameters as its argument (@code{("./foo" +"hello")} in the above example. Note that command line options to +mixguile must be written in their own line after the @code{\} symbol. +@end defopt + +@defopt -q +Do not load user's initialisation file. When @code{mixguile} starts up, +it looks for a file named @file{mixguile.scm} in the user's @sc{mdk} +configuration directory (@file{~/.mdk}), and loads it if it exists. This +option tells @code{mixguile} to skip this initialisation file loading. +@end defopt + + +@node Scheme functions reference, , Invoking mixguile, mixguile +@section Scheme functions reference + +As we have previously pointed out, @code{mixguile} embeds a MIX virtual +machine that can be accessed through a set of Scheme functions, that is, +of a Scheme library. Conversely, @code{mixvm} and @code{gmixvm} contain +a Guile interpreter, and are able to use this same Scheme library, as +well as all the other Guile/Scheme primitives and any user defined +function. Therefore, you have at your disposal a powerful programming +language, Scheme, to extend the @sc{mdk} virtual machine emulators (see +@ref{Using Scheme in mixvm and gmixvm} for samples of how to do it). + +The following subsections describe available functions the MIX/Scheme +library. + +@menu +* mixvm wrappers:: Functions invoking mixvm commands. +* Hooks:: Adding hooks to mixvm commands. +* Additional VM functions:: Functions accessing the MIX virtual machine. +@end menu + +@node mixvm wrappers, Hooks, Scheme functions reference, Scheme functions reference +@subsection @code{mixvm} command wrappers + +For each of the @code{mixvm} commands listed in @ref{Commands}, there is +a corresponding Scheme function named by prefixing the command name with +@code{mix-} (e.g., @code{mix-load}, @code{mix-run} and so on). These +command wrappers are implemented using a generic command dispatching +function: + +@defun mixvm-cmd command argument +Dispatchs the given @var{command} to the MIX virtual appending the +provided @var{argument}. Both @var{command} and @code{argument} must be +strings. The net result is as writing "@var{command} @var{argument}" at +the @code{mixvm} or @code{gmixvm} command prompt. +@end defun + +For instance, you can invoke the @code{run} command at the @code{mixvm} +prompt in three equivalent ways: + +@example +MIX > run hello +MIX > (mix-run "hello") +MIX > (mixvm-cmd "run" "hello") +@end example +@noindent +(only the two last forms can be used at the @code{mixguile} prompt or +inside a Scheme script). + +The @code{mix-} functions evaluate to a unspecified value. If you want +to check the result of the last @code{mixvm} command invocation, use the +@code{mix-last-result} function: + +@defun mix-last-result +Returns @var{#t} if the last @code{mixvm} command invocation was +successful, @var{#f} otherwise. +@end defun +@noindent +Using this function, we could improve the script for running a program +presented in the previous section by adding error checking: + + +@example +#! /usr/bin/mixguile \ +-e main -s +!# + +;;; Execute a given program and print the registers. + +(define main + (lambda (args) + ;; load the file provided as a command line argument + (mix-load (cadr args)) + ;; execute it if mix-load succeeded + (if (mix-last-result) (mix-run)) + ;; print the contents of registers if the above commands succeded + (if (mix-last-result) (mix-pall)))) +@end example + +Please, refer to @ref{Commands} for a list of available commands. Given +the description of a @code{mixvm}, it is straightforward to use its +Scheme counterpart and, therefore, we shall not give a complete +description of these functions here. Instead, we will only mention those +wrappers that exhibit a treatment of their differing from that of their +command counterpart. + +@defun mix-preg [register] +@defunx mix-sreg register value +The argument @var{register} of these functions can be either a string or +a symbol representing the desired register. For instance, the following +invocations are equivalent: + +@example +(mix-preg 'I1) +(mix-preg "I1") +@end example +@end defun + +@defun mix-pmem from [to] +The command @code{pmem} takes a single argument which can be either a +cell number or a range of the form @code{FROM-TO}. This function takes +one argument to ask for a single memory cell contents, or two parameters +to ask for a range. For instance, the following commands are equivalent: + +@example +MIX > pmem 10-12 +0010: + 00 00 00 00 00 (0000000000) +0011: + 00 00 00 00 00 (0000000000) +0012: + 00 00 00 00 00 (0000000000) +MIX > (mix-pmem 10 12) +0010: + 00 00 00 00 00 (0000000000) +0011: + 00 00 00 00 00 (0000000000) +0012: + 00 00 00 00 00 (0000000000) +MIX > +@end example +@end defun + +@defun mix-sover #t|#f +The command @code{sover} takes as argument either the string @code{T} or +the string @code{F}, to set, respectively, the overflow toggle to true +or false. Its Scheme counterpart, @code{mix-sover}, takes as argument +a Scheme boolean value: @code{#t} (true) or @code{#f}. +@end defun + +For the remaining functions, you simply must take into account that when +the command arguments are numerical, the corresponding Scheme function +takes as arguments Scheme number literals. On the other hand, when the +command argument is a string, the argument of its associated Scheme +function will be a Scheme string. By way of example, the following +invocations are pairwise equivalent: + +@example +MIX > load ../samples/hello +MIX > (mix-load "../samples/hello") + +MIX > next 5 +MIX > (mix-next 5) +@end example + +@node Hooks, Additional VM functions, mixvm wrappers, Scheme functions reference +@subsection Hook functions + +Hooks are functions evaluated before or after executing a @code{mixvm} +command (or its corresponding Scheme function wrapper), or after an +explicit or conditional breakpoint is found during the execution of a +MIX program. The following functions let you install hooks: + +@defun mix-add-pre-hook command hook +Adds a function to the list of pre-hooks associated with the give +@var{command}. @var{command} is a string naming the corresponding @code{mixvm} +command, and @var{hook} is a function which takes a single argument: a +string list of the commands arguments. The following scheme code defines +a simple hook and associates it with the @code{run} command: + +@example +(define run-hook + (lambda (args) + (display "argument list: ") + (display args) + (newline))) +(mix-add-pre-hook "run" run-hook) +@end example + +Pre-hooks are executed, in the order they are added, before invoking the +corresponding command (or its associated Scheme wrapper function). +@end defun + +@defun mix-add-post-hook command hook +Adds a function to the list of pre-hooks associated with the give +@var{command}. The arguments have the same meaning as in +@code{mix-add-pre-hook}. +@end defun + +@defun mix-add-global-pre-hook hook +@defunx mix-add-global-post-hook hook +Global pre/post hooks are executed before/after any @code{mixvm} command +or function wrapper invocation. In this case, @var{hook} takes two +arguments: a string with the name of the command being invoked, and a +string list with its arguments. +@end defun + +@defun mix-add-break-hook hook +@defunx mix-add-cond-break hook +Add a hook funtion to be executed when an explicit (resp. conditional) +breakpoint is encountered during program execution. @var{hook} is a +function taking two arguments: the source line number where the hook has +occurred, and the current program counter value. The following code +shows a simple definition and installation of a break hook: + +@example +(define break-hook + (lambda (line address) + (display "Breakpoint at line ") (display line) + (display " and address ") (display address) + (newline))) +(mix-add-break-hook break-hook) +@end example + +Break hook functions are entirely implemented in Scheme using regular +post-hooks for the @code{next} and @code{run} commands. If you are +curious, you can check the Scheme source code at +@file{@emph{prefix}/share/mdk/mixguile-vm-stat.scm} (where @emph{prefix} +stands for your root install directory, usualy @code{/usr} or +@code{/usr/local}. +@end defun + + +See @ref{Hook functions} for further examples on using hook functions. + + +@node Additional VM functions, , Hooks, Scheme functions reference +@subsection Additional VM functions + +When writing non-trivial Scheme extensions using the MIX/Scheme library, +you will probably need to evaluate the contents of the virtual machine +components (registers, memory cells and so on). For instance, you may +need to store the contents of the @code{A} register in a variable. The +Scheme functions described so far are of no help: you can print the +contents of @code{A} using @code{(mix-preg 'A)}, but you cannot define a +variable containing the contents of @code{A}. To address this kind of +problems, the MIX/Scheme library provides the following additional +functions: + +@defun mixvm-status +@defunx mix-vm-status +Return the current status of the virtual machine, as a number +(@code{mixvm-status}) or as a symbol (@code{mix-vm-status}). Posible +return values are: +@multitable {aamixvmaastatusaa} {aamixvmastatusaaaaaaa} {return valuesaaaaaaaaaaaaaaaaaaaaaaaaaa} +@item @code{(mixvm-status)} @tab @code{(mix-vm-status)} @tab +@item 0 @tab MIX_ERROR @tab Loading or execution error +@item 1 @tab MIX_BREAK @tab Breakpoint encountered +@item 2 @tab MIX_COND_BREAK @tab Conditional breakpoint +@item 3 @tab MIX_HALTED @tab Execution terminated +@item 4 @tab MIX_RUNNING @tab Execution stopped after @code{next} +@item 5 @tab MIX_LOADED @tab Program successfully loaded +@item 6 @tab MIX_EMPTY @tab No program loaded +@end multitable +@end defun + +@defun mix-vm-error? +@defunx mix-vm-break? +@defunx mix-vm-cond-break? +@defunx mix-vm-halted? +@defunx mix-vm-running? +@defunx mix-vm-loaded? +@defunx mix-vm-empty? +Predicates asking whether the current virtual machine status is +@code{MIX_ERROR}, @code{MIX_BREAK}, etc. +@end defun + +@defun mix-reg register +@defunx mix-set-reg! register value +@code{mix-reg} evaluates to a number which is the contents of the +specified @var{register}. @code{mix-set-reg} sets the contents of the +given @var{register} to @var{value}. The register can be specified +either as a string (@code{"A"}, @code{"X"}, etc.) or as a symbol +(@code{'A}, @code{'X}, etc.). For instance, + +@example +guile> (mix-reg 'A) +2341 +guile> (mix-set-reg! "A" 2000) +ok +guile> (define reg-a (mix-reg 'A)) +guile> (display reg-a) +2000 +guile> +@end example +@end defun + +@defun mix-cell cell_no +@defunx mix-set-cell! cell_no value +Evaluate and set the contents of the memory cell number +@var{cell_no}. Both @var{cell_no} and @var{value} are Scheme numbers. +@end defun + +@defun mix-loc +Evaluates to the value of the location counter (i.e., the address of the +next instruction to be executed). +@end defun + +@defun mix-over +@defunx mix-set-over! #t|#f +@code{mix-over} evaluates to @code{#t} if the overflow toggle is set, +and to @code{#f} otherwise. The value of the overflow toggle can be +modified using @code{mix-set-over!}. +@end defun + +@defun mix-cmp +@defunx mix-set-cmp! 'L|'E|'G +Evaluate and set the comparison flag. Possible values are the scheme +symbols @code{L} (lesser), @code{E} (equal) and @code{G} (greater). +@end defun + +@defun mix-up-time +Evaluates to the current virtual machine uptime. +@end defun + +@defun mix-lap-time +Evaluates to the current virtual machine lapsed time, i.e., the time +elapsed since the last @code{run} or @code{next} command. +@end defun + +@defun mix-prog-time +Evaluates to the total time spent executing the currently loaded program. +@end defun + +@defun mix-prog-name +Evaluates to a string containing the basename (without any leading path) +of the currently loaded MIX program. +@end defun + +@defun mix-prog-path +Evaluates to a string containing the full path to the currently loaded +MIX program. +@end defun + +@defun mix-src-path +Evaluates to a string containing the full path to the source file of the +currently loaded MIX program. +@end defun + +@defun mix-src-line [lineno] +@defunx mix-src-line-no +@code{mix-src-line-no} evaluates to the current source file number +during the execution of a program. @code{mix-src-line} evaluates to a +string containing the source file line number @var{lineno}; when +invoked without argument, it evaluates to @code{(mix-src-line +(mix-src-line-no))}. +@end defun + +@defun mix-ddir +Evaluates to a string containing the full path of the current device +directory. +@end defun 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. + diff --git a/doc/mdk_tut.texi b/doc/mdk_tut.texi new file mode 100644 index 0000000..0fabe89 --- /dev/null +++ b/doc/mdk_tut.texi @@ -0,0 +1,1319 @@ +@c -*-texinfo-*- +@c This is part of the GNU MDK Reference Manual. +@c Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005 +@c Free Software Foundation, Inc. +@c See the file mdk.texi for copying conditions. + +@c $Id: mdk_tut.texi,v 1.14 2005/09/20 00:26:00 jao Exp $ + +@node MIX and MIXAL tutorial, Getting started, Installing MDK, Top +@comment node-name, next, previous, up +@chapter MIX and MIXAL tutorial +@cindex MIX +@cindex MIXAL + +In the book series @cite{The Art of Computer Programming}, by D. Knuth, +a virtual computer, the MIX, is used by the author (together with the +set of binary instructions that the virtual CPU accepts) to illustrate +the algorithms and skills that every serious programmer should +master. Like any other real computer, there is a symbolic assembler +language that can be used to program the MIX: the MIX assembly language, +or MIXAL for short. In the following subsections you will find a tutorial +on these topics, which will teach you the basics of the MIX architecture +and how to program a MIX computer using MIXAL. + +@menu +* The MIX computer:: Architecture and instruction set + of the MIX computer. +* MIXAL:: The MIX assembly language. +@end menu + +@node The MIX computer, MIXAL, MIX and MIXAL tutorial, MIX and MIXAL tutorial +@comment node-name, next, previous, up +@section The MIX computer + +In this section, you will find a description of the MIX computer, +its components and instruction set. + +@menu +* MIX architecture:: +* MIX instruction set:: +@end menu + +@node MIX architecture, MIX instruction set, The MIX computer, The MIX computer +@comment node-name, next, previous, up +@subsection MIX architecture +@cindex byte +@cindex MIX byte +@cindex word +@cindex MIX word +@cindex MIX architecture +@cindex MIX computer +@cindex register +@cindex MIX register +@cindex field specification +@cindex fspec +@cindex instruction +@cindex MIX instruction +@cindex address +@cindex memory cell +@cindex cell +@cindex memory +@cindex index + +The basic information storage unit in the MIX computer is the +@dfn{byte}, which stores positive values in the range 0-63 . Note that a +MIX byte can be then represented as 6 bits, instead of the common 8 bits +for a @emph{regular} byte. Unless otherwise stated, we shall use the +word @dfn{byte} to refer to a MIX 6-bit byte. + +A MIX @dfn{word} is defined as a set of 5 bytes plus a sign. The bytes +within a word are numbered from 1 to 5, being byte number one the most +significant one. The sign is denoted by index 0. Graphically, + +@example + ----------------------------------------------- +| 0 | 1 | 2 | 3 | 4 | 5 | + ----------------------------------------------- +| +/- | byte | byte | byte | byte | byte | + ----------------------------------------------- +@end example +@noindent +Sample MIX words are @samp{- 12 00 11 01 63} and @samp{+ 12 11 34 43 +00}. + +You can refer to subfields within a word using a @dfn{field +specification} or @dfn{fspec} of the form ``(@var{L}:@var{R})'', where +@var{L} denotes the first byte, and @var{R} the last byte of the +subfield. +When @var{L} is zero, the subfield includes the word's +sign. An fspec can also be represented as a single value @code{F}, given +by @code{F = 8*L + R} (thus the fspec @samp{(1:3)}, denoting the first +three bytes of a word, is represented by the integer 11). + +The MIX computer stores information in @dfn{registers}, that can store +either a word or two bytes and sign (see below), and @dfn{memory cells}, +each one containing a word. Specifically, the MIX computer has 4000 +memory cells with addresses 0 to 3999 (i.e., two bytes are enough to +address a memory cell) and the following registers: + +@cindex rA +@cindex rX +@cindex rJ +@cindex rIn +@cindex register + +@table @asis +@item @code{rA} +A register. General purpose register holding a word. Usually its +contents serves as the operand of arithmetic and storing instructions. +@item @code{rX} +X register. General purpose register holding a word. Often it acts as an +extension or a replacement of @samp{rA}. +@item @code{rJ} +J (jump) register. This register stores positive two-byte values, +usually representing a jump address. +@item @code{rI1}, @code{rI2}, @code{rI3}, @code{rI4}, @code{rI5}, @code{rI6} +Index registers. These six registers can store a signed two-byte +value. Their contents are used as indexing values for the computation of +effective memory addresses. +@end table + +@cindex @sc{ov} +@cindex @sc{cm} +@cindex @code{un} +@cindex overflow toggle +@cindex comparison indicator +@cindex input-output devices +@noindent +In addition, the MIX computer contains: + +@itemize @minus +@item +An @dfn{overflow toggle} (a single bit with values @dfn{on} or +@dfn{off}). In this manual, this toggle is denoted @sc{ov}. +@item +A @dfn{comparison indicator} (having three values: @dfn{EQUAL}, +@dfn{GREATER} or @dfn{LESS}). In this manual, this indicator is denoted +@sc{cm}, and its possible values are abbreviated as @dfn{E}, @dfn{G} and +@dfn{L}. +@item +Input-output block devices. Each device is labelled as @code{un}, where +@code{n} runs from 0 to 20. In Knuth's definition, @code{u0} through +@code{u7} are magnetic tape units, @code{u8} through @code{15} are disks +and drums, @code{u16} is a card reader, @code{u17} is a card writer, +@code{u18} is +a line printer and, @code{u19} is a typewriter terminal, and @code{u20}, +a paper tape. Our implementation maps these devices to disk files, +except for @code{u19}, which represents the standard output. +@end itemize + +As noted above, the MIX computer communicates with the external world by +a set of input-output devices which can be ``connected'' to it. The +computer interchanges information using blocks of words whose length +depends on the device at hand (@pxref{Devices}). These words are +interpreted by the device either as binary information (for devices +0-16), or as representing printable characters (devices 17-20). In the +last case, each MIX byte is mapped onto a character according to the +following table: + +@multitable {00} {C} {00} {C} {00} {C} {00} {C} +@item 00 @tab @tab 01 @tab A @tab 02 @tab B @tab 03 @tab C +@item 04 @tab D @tab 05 @tab E @tab 06 @tab F @tab 07 @tab G +@item 08 @tab H @tab 09 @tab I @tab 10 @tab ~ @tab 11 @tab J +@item 12 @tab K @tab 13 @tab L @tab 14 @tab M @tab 15 @tab N +@item 16 @tab O @tab 17 @tab P @tab 18 @tab Q @tab 19 @tab R +@item 20 @tab [ @tab 21 @tab # @tab 22 @tab S @tab 23 @tab T +@item 24 @tab U @tab 25 @tab V @tab 26 @tab W @tab 27 @tab X +@item 28 @tab Y @tab 29 @tab Z @tab 30 @tab 0 @tab 31 @tab 1 +@item 32 @tab 2 @tab 33 @tab 3 @tab 34 @tab 4 @tab 35 @tab 5 +@item 36 @tab 6 @tab 37 @tab 7 @tab 38 @tab 8 @tab 39 @tab 9 +@item 40 @tab . @tab 41 @tab , @tab 42 @tab ( @tab 43 @tab ) +@item 44 @tab + @tab 45 @tab - @tab 46 @tab * @tab 47 @tab / +@item 48 @tab = @tab 49 @tab $ @tab 50 @tab < @tab 51 @tab > +@item 52 @tab @@ @tab 53 @tab ; @tab 54 @tab : @tab 55 @tab ' +@end multitable +@noindent +The value 0 represents a whitespace. The characters @code{~}, @code{[} and +@code{#} correspond to symbols not representable as ASCII characters +(uppercase delta, sigma and gamma, respectively), and byte values 56-63 +have no associated character. + +Finally, the MIX computer features a virtual CPU which controls the +above components, and which is able to execute a rich set of +instructions (constituting its machine language, similar to those +commonly found in real CPUs), including arithmetic, logical, storing, +comparison and jump instructions. Being a typical von Neumann computer, +the MIX CPU fetchs binary instructions from memory sequentially (unless +a jump instruction is found), and stores the address of the next +instruction to be executed in an internal register called @dfn{location +counter} (also known as program counter in other architectures). + +The next section, @xref{MIX instruction set}, gives a complete description +of the available MIX binary instructions. + +@node MIX instruction set, , MIX architecture, The MIX computer +@comment node-name, next, previous, up +@subsection MIX instruction set +@cindex instruction set + +The following subsections fully describe the instruction set of the MIX +computer. We begin with a description of the structure of binary +instructions and the notation used to refer to their subfields. The +remaininig subsections are devoted to describing the actual instructions +available to the MIX programmer. + +@menu +* Instruction structure:: +* Loading operators:: +* Storing operators:: +* Arithmetic operators:: +* Address transfer operators:: +* Comparison operators:: +* Jump operators:: +* Input-output operators:: +* Conversion operators:: +* Shift operators:: +* Miscellaneous operators:: +* Execution times:: +@end menu + +@node Instruction structure, Loading operators, MIX instruction set, MIX instruction set +@comment node-name, next, previous, up +@subsubsection Instruction structure + +MIX @dfn{instructions} are codified as words with the following subfield +structure: + +@multitable @columnfractions .15 .20 .65 +@item @emph{Subfield} @tab @emph{fspec} @tab @emph{Description} +@item ADDRESS @tab (0:2) +@tab The first two bytes plus sign are the @dfn{address} field. Combined +with the INDEX field, denotes the memory address to be used by the +instruction. +@item INDEX @tab (3:3) +@tab The third byte is the @dfn{index}, normally used for indexing the +address@footnote{The actual memory address the instruction refers to, is +obtained by adding to ADDRESS the value of the @samp{rI} register +denoted by INDEX.}. +@item MOD @tab (4:4) +@tab Byte four is used either as an operation code modifier or as a field +specification. +@item OPCODE @tab (5:5) +@tab The last (least significant) byte in the word denotes the operation +code. +@end multitable + +@noindent +or, graphically, + +@example + ------------------------------------------------ +| 0 | 1 | 2 | 3 | 4 | 5 | + ------------------------------------------------ +| ADDRESS | INDEX | MOD | OPCODE | + ------------------------------------------------ +@end example + +For a given instruction, @samp{M} stands for +the memory address obtained after indexing the ADDRESS subfield +(using its INDEX byte), and @samp{V} is the contents of the +subfield indicated by MOD of the memory cell with address @samp{M}. For +instance, suppose that we have the following contents of MIX registers +and memory cells: + +@example +[rI2] = + 00 63 +[31] = - 10 11 00 11 22 +@end example +@noindent +where @samp{[n]} denotes the contents of the nth memory cell and +@samp{[rI2]} the contents of register @samp{rI2}@footnote{In general, +@samp{[X]} will denote the contents of entity @samp{X}; thus, by +definition, @w{@samp{V = [M](MOD)}}.}. Let us consider the binary +instruction @w{@samp{I = - 00 32 02 11 10}}. For this instruction we +have: + +@example +ADDRESS = - 00 32 = -32 +INDEX = 02 = 2 +MOD = 11 = (1:3) +OPCODE = 10 + +M = ADDRESS + [rI2] = -32 + 63 = 31 +V = [M](MOD) = (- 10 11 00 11 22)(1:3) = + 00 00 10 11 00 +@end example + +Note that, when computing @samp{V} using a word and an fspec, we apply +a left padding to the bytes selected by @samp{MOD} to obtain a +complete word as the result. + +In the following subsections, we will +assign to each MIX instruction a mnemonic, or symbolic name. For +instance, the mnemonic of @samp{OPCODE} 10 is @samp{LD2}. Thus we can +rewrite the above instruction as + +@example +LD2 -32,2(1:3) +@end example +@noindent +or, for a generic instruction: + +@example +MNEMONIC ADDRESS,INDEX(MOD) +@end example +@noindent +Some instructions are identified by both the OPCODE and the MOD +fields. In these cases, the MOD will not appear in the above symbolic +representation. Also when ADDRESS or INDEX are zero, they can be +omitted. Finally, MOD defaults to (0:5) (meaning the +whole word). + +@node Loading operators, Storing operators, Instruction structure, MIX instruction set +@comment node-name, next, previous, up +@subsubsection Loading operators +@cindex loading operators + +The following instructions are used to load memory contents into a +register. + +@ftable @code +@item LDA +Put in rA the contents of cell no. M. +OPCODE = 8, MOD = fspec. @code{rA <- V}. +@item LDX +Put in rX the contents of cell no. M. +OPCODE = 15, MOD = fspec. @code{rX <- V}. +@item LDi +Put in rIi the contents of cell no. M. +OPCODE = 8 + i, MOD = fspec. @code{rIi <- V}. +@item LDAN +Put in rA the contents of cell no. M, with opposite sign. +OPCODE = 16, MOD = fspec. @code{rA <- -V}. +@item LDXN +Put in rX the contents of cell no. M, with opposite sign. +OPCODE = 23, MOD = fspec. @code{rX <- -V}. +@item LDiN +Put in rIi the contents of cell no. M, with opposite sign. +OPCODE = 16 + i, MOD = fspec. @code{rIi <- -V}. +@end ftable + +In all the above load instructions the @samp{MOD} field selects the +bytes of the memory cell with address @samp{M} which are loaded into the +requisite register (indicated by the @samp{OPCODE}). For instance, the +word @w{@samp{+ 00 13 01 27 11}} represents the instruction + +@example +LD3 13,1(3:3) + ^ ^ ^ ^ + | | | | + | | | --- MOD = 27 = 3*8 + 3 + | | --- INDEX = 1 + | --- ADDRESS = 00 13 + --- OPCODE = 11 +@end example +Let us suppose that, prior to this instruction execution, the state of +the MIX computer is the following: + +@example +[rI1] = - 00 01 +[rI3] = + 24 12 +[12] = - 01 02 03 04 05 +@end example +@noindent +As, in this case, @w{@samp{M = 13 + [rI1] = 12}}, we have + +@example +V = [M](3:3) = (- 01 02 03 04 05)(3:3) + = + 00 00 00 00 03 +@end example +@noindent +(note that the specified subfield is left-padded with null bytes to +complete a word). Hence, the MIX state, after the instruction execution, +will be + +@example +[rI1] = - 00 01 +[rI3] = + 00 03 +[12] = - 01 02 03 04 05 +@end example + +To further illustrate loading operators, the following table shows the +contents of @samp{rX} after different @samp{LDX} instructions: + +@table @samp +@item LDX 12(0:0) [rX] = - 00 00 00 00 00 +@item LDX 12(0:1) [rX] = - 00 00 00 00 01 +@item LDX 12(3:5) [rX] = + 00 00 03 04 05 +@item LDX 12(3:4) [rX] = + 00 00 00 03 04 +@item LDX 12(0:5) [rX] = - 01 02 03 04 05 +@end table + + +@node Storing operators, Arithmetic operators, Loading operators, MIX instruction set +@comment node-name, next, previous, up +@subsubsection Storing operators +@cindex storing operators + +The following instructions are the inverse of the load +operations: they are used to store a subfield of a register +into a memory location. Here, MOD represents the subfield of the memory +cell that is to be overwritten with bytes from a register. These bytes +are taken beginning by the rightmost side of the register. + +@ftable @code +@item STA +Store rA. OPCODE = 24, MOD = fspec. @code{V <- rA}. +@item STX +Store rX. OPCODE = 31, MOD = fspec. @code{V <- rX}. +@item STi +Store rIi. OPCODE = 24 + i, MOD = fspec. @code{V <- rIi}. +@item STJ +Store rJ. OPCODE = 32, MOD = fspec. @code{V <- rJ}. +@item STZ +Store zero. OPCODE = 33, MOD = fspec. @code{V <- 0}. +@end ftable + +By way of example, consider the instruction @samp{STA 1200(2:3)}. It +causes the MIX to fetch bytes no. 4 and 5 of register A and copy them to +bytes 2 and 3 of memory cell no. 1200 (remember that, for these +instructions, MOD specifies a subfield of @emph{the memory +address}). The other bytes of the memory cell retain their +values. Thus, if prior to the instruction execution we have + +@example +[1200] = - 20 21 22 23 24 +[rA] = + 01 02 03 04 05 +@end example +@noindent +we will end up with + +@example +[1200] = - 20 04 05 23 24 +[rA] = + 01 02 03 04 05 +@end example + +As a second example, @samp{ST2 1000(0)} will set the sign of +@samp{[1000]} to that of @samp{[rI2]}. + +@node Arithmetic operators, Address transfer operators, Storing operators, MIX instruction set +@comment node-name, next, previous, up +@subsubsection Arithmetic operators +@cindex arithmetic operators + +The following instructions perform arithmetic operations between rA and +rX register and memory contents. + +@ftable @code +@item ADD +Add and set OV if overflow. OPCODE = 1, MOD = fspec. +@w{@code{rA <- rA +V}}. +@item SUB +Sub and set OV if overflow. OPCODE = 2, MOD = fspec. +@w{@code{rA <- rA - V}}. +@item MUL +Multiply V times rA and store the 10-bytes product in rAX. +OPCODE = 3, MOD = fspec. @w{@code{rAX <- rA x V}}. +@item DIV +rAX is considered a 10-bytes number, and it is divided by V. +OPCODE = 4, MOD = fspec. @w{@code{rA <- rAX / V}}, @code{rX} <- reminder. +@end ftable + +In all the above instructions, @samp{[rA]} is one of the operands +of the binary arithmetic operation, the other being @samp{V} (that is, +the specified subfield of the memory cell with address @samp{M}), padded +with zero bytes on its left-side to complete a word. In multiplication +and division, the register @samp{X} comes into play as a right-extension +of the register @samp{A}, so that we are able to handle 10-byte numbers +whose more significant bytes are those of @samp{rA} (the sign of this +10-byte number is that of @samp{rA}: @samp{rX}'s sign is ignored). + +Addition and substraction of MIX words can give rise to overflows, since +the result is stored in a register with room to only 5 bytes (plus +sign). When this occurs, the operation result modulo @w{1,073,741,823} +(the maximum value storable in a MIX word) is stored in @samp{rA}, and +the overflow toggle is set to TRUE. + +@node Address transfer operators, Comparison operators, Arithmetic operators, MIX instruction set +@comment node-name, next, previous, up +@subsubsection Address transfer operators +@cindex address transfer operators + +In these instructions, @samp{M} (the address of the instruction after +indexing) is used as a number instead of as the address of a memory +cell. Consequently, @samp{M} can have any valid word value (i.e., it's +not limited to the 0-3999 range of a memory address). + +@ftable @code +@item ENTA +Enter @samp{M} in [rA]. OPCODE = 48, MOD = 2. @code{rA <- M}. +@item ENTX +Enter @samp{M} in [rX]. OPCODE = 55, MOD = 2. @code{rX <- M}. +@item ENTi +Enter @samp{M} in [rIi]. OPCODE = 48 + i, MOD = 2. @code{rIi <- M}. +@item ENNA +Enter @samp{-M} in [rA]. OPCODE = 48, MOD = 3. @code{rA <- -M}. +@item ENNX +Enter @samp{-M} in [rX]. OPCODE = 55, MOD = 3. @code{rX <- -M}. +@item ENNi +Enter @samp{-M} in [rIi]. OPCODE = 48 + i, MOD = 3. @code{rIi <- -M}. +@item INCA +Increase [rA] by @samp{M}. OPCODE = 48, MOD = 0. @code{rA <- rA + M}. +@item INCX +Increase [rX] by @samp{M}. OPCODE = 55, MOD = 0. @code{rX <- rX + M}. +@item INCi +Increase [rIi] by @samp{M}. OPCODE = 48 + i, MOD = 0. @code{rIi <- rIi + M}. +@item DECA +Decrease [rA] by @samp{M}. OPCODE = 48, MOD = 1. @code{rA <- rA - M}. +@item DECX +Decrease [rX] by @samp{M}. OPCODE = 55, MOD = 1. @code{rX <- rX - M}. +@item DECi +Decrease [rIi] by @samp{M}. OPCODE = 48 + i, MaOD = 0. @code{rIi <- rIi - M}. +@end ftable + +In the above instructions, the subfield @samp{ADDRESS} acts as an +immediate (indexed) operand, and allow us to set directly the contents +of the MIX registers without an indirection to the memory cells (in a +real CPU this would mean that they are faster that the previously +discussed instructions, whose operands are fetched from memory). So, if +you want to store in @samp{rA} the value -2000 (- 00 00 00 31 16), you +can use the binary instruction @w{+ 31 16 00 03 48}, or, symbolically, + +@example +ENNA 2000 +@end example +@noindent +Used in conjuction with the store operations (@samp{STA}, @samp{STX}, +etc.), these instructions also allow you to set memory cells contents to +concrete values. + +Note that in these address transfer operators, the @samp{MOD} field is +not a subfield specificator, but serves to define (together with +@samp{OPCODE}) the concrete operation to be performed. + +@node Comparison operators, Jump operators, Address transfer operators, MIX instruction set +@comment node-name, next, previous, up +@subsubsection Comparison operators +@cindex comparison operators + +So far, we have learned how to move values around between the MIX +registers and its memory cells, and also how to perform arithmetic +operations using these values. But, in order to write non-trivial +programs, other functionalities are needed. One of the most common is +the ability to compare two values, which, combined with jumps, will +allow the execution of conditional statements. +The following instructions compare the value of a register with @samp{V}, and +set the @sc{cm} indicator to the result of the comparison (i.e. to +@samp{E}, @samp{G} or @samp{L}, equal, greater or lesser respectively). + +@ftable @code +@item CMPA +Compare [rA] with V. OPCODE = 56, MOD = fspec. +@item CMPX +Compare [rX] with V. OPCODE = 63, MOD = fspec. +@item CMPi +Compare [rIi] with V. OPCODE = 56 + i, MOD = fspec. +@end ftable + +As explained above, these instructions modify the value of the MIX +comparison indicator; but maybe you are asking yourself how do you use +this value: enter jump operators, in the next subsection. + +@node Jump operators, Input-output operators, Comparison operators, MIX instruction set +@comment node-name, next, previous, up +@subsubsection Jump operators +@cindex jump operators + +The MIX computer has an internal register, called the @dfn{location +counter}, which stores the address of the next instruction to be fetched +and executed by the virtual CPU. You cannot directly modify the contents +of this internal register with a load instruction: after fetching the +current instruction from memory, it is automatically increased in one +unit by the MIX. However, there is a set of instructions (which we call +jump instructions) which can alter the contents of the location counter +provided some condition is met. When this occurs, the value of the next +instruction address that would have been fetched in the absence of the +jump is stored in @samp{rJ} (except for @code{JSJ}), and the location +counter is set to the value of @samp{M} (so that the next instruction is +fetched from this new address). Later on, you can return to the point +when the jump occurred reading the address stored in @samp{rJ}. + +The MIX computer provides the following jump instructions: +With these instructions you force a jump to the specified address. Use +@samp{JSJ} if you do not care about the return address. + +@ftable @code +@item JMP +Unconditional jump. OPCODE = 39, MOD = 0. +@item JSJ +Unconditional jump, but rJ is not modified. OPCODE = 39, MOD = 1. +@end ftable + +These instructions check the overflow toggle to decide whether to jump +or not. + +@ftable @code +@item JOV +Jump if OV is set (and turn it off). OPCODE = 39, MOD = 2. +@item JNOV +Jump if OV is not set (and turn it off). OPCODE = 39, MOD = 3. +@end ftable + +In the following instructions, the jump is conditioned to the contents of the +comparison flag: + +@ftable @code +@item JL +Jump if @w{@code{[CM] = L}}. OPCODE = 39, MOD = 4. +@itemx JE +Jump if @w{@code{[CM] = E}}. OPCODE = 39, MOD = 5. +@itemx JG +Jump if @w{@code{[CM] = G}}. OPCODE = 39, MOD = 6. +@itemx JGE +Jump if @code{[CM]} does not equal @code{L}. OPCODE = 39, MOD = 7. +@itemx JNE +Jump if @code{[CM]} does not equal @code{E}. OPCODE = 39, MOD = 8. +@itemx JLE +Jump if @code{[CM]} does not equal @code{G}. OPCODE = 39, MOD = 9. +@end ftable + +You can also jump conditioned to the value stored in the MIX registers, +using the following instructions: + +@ftable @code +@item JAN +@itemx JAZ +@itemx JAP +@itemx JANN +@itemx JANZ +@itemx JANP +Jump if the content of rA is, respectively, negative, zero, positive, +non-negative, non-zero or non-positive. +OPCODE = 40, MOD = 0, 1, 2, 3, 4, 5. +@item JXN +@itemx JXZ +@itemx JXP +@itemx JXNN +@itemx JXNZ +@itemx JXNP +Jump if the content of rX is, respectively, negative, zero, positive, +non-negative, non-zero or non-positive. +OPCODE = 47, MOD = 0, 1, 2, 3, 4, 5. +@item JiN +@itemx JiZ +@itemx JiP +@itemx JiNN +@itemx JiNZ +@itemx JiNP +Jump if the content of rIi is, respectively, negative, zero, positive, +non-negative, non-zero or non-positive. +OPCODE = 40 + i, MOD = 0, 1, 2, 3, 4, 5. +@end ftable + + +@node Input-output operators, Conversion operators, Jump operators, MIX instruction set +@comment node-name, next, previous, up +@subsubsection Input-output operators +@cindex input-output operators + +As explained in previous sections (@pxref{MIX architecture}), the MIX +computer can interact with a series of block devices. To that end, you +have at your disposal the following instructions: + +@ftable @code +@item IN +Transfer a block of words from the specified unit to memory, starting at +address M. +OPCODE = 36, MOD = I/O unit. +@item OUT +Transfer a block of words from memory (starting at address M) to the +specified unit. +OPCODE = 37, MOD = I/O unit. +@item IOC +Perfom a control operation (given by M) on the specified unit. +OPCODE = 35, MOD = I/O unit. +@item JRED +Jump to M if the specified unit is ready. +OPCODE = 38, MOD = I/O unit. +@item JBUS +Jump to M if the specified unit is busy. +OPCODE = 34, MOD = I/O unit. +@end ftable +@noindent +In all the above instructions, the @samp{MOD} subfile must be in the +range 0-20, since it denotes the operation's target device. The +@samp{IOC} instruction only makes sense for tape devices (@samp{MOD} = +0-7 or 20): it shifts the read/write pointer by the number of words +given by @samp{M} (if it equals zero, the tape is rewound)@footnote{In +Knuth's original definition, there are other control operations +available, but they do not make sense when implementing the block +devices as disk files (as we do in @sc{mdk} simulator). For the same +reason, @sc{mdk} devices are always ready, since all input-output +operations are performed using synchronous system calls.}. + + +@node Conversion operators, Shift operators, Input-output operators, MIX instruction set +@comment node-name, next, previous, up +@subsubsection Conversion operators +@cindex conversion operators + +The following instructions convert between numerical values and their +character representations. + +@ftable @code +@item NUM +Convert rAX, assumed to contain a character representation of a number, +to its numerical value and store it in rA. +OPCODE = 5, MOD = 0. +@item CHAR +Convert the number stored in rA to a character representation and store +it in rAX. +OPCODE = 5, MOD = 1. +@end ftable +@noindent +Digits are represented in MIX by the range of values 30-39 (digits +0-9). Thus, if the contents of @samp{rA} and @samp{rX} are, for instance, + +@example +[rA] = + 30 30 31 32 33 +[rX] = + 31 35 39 30 34 +@end example +@noindent +the represented number is 0012315904, and @samp{NUM} will store this +value in @samp{rA} (i.e., we end up with @samp{[rA]} = @w{+ 0 46 62 52 +0} = 12315904). + +If any byte in @samp{rA} or @samp{rB} does not belong to the range +30-39, it is interpreted by @samp{NUM} as the digit obtained by taking +its value modulo 10. E.g. values 0, 10, 20, 30, 40, 50, 60 all represent the +digit 0; 2, 12, 22, etc. represent the digit 2, and so on. For +instance, the number 0012315904 mentioned above could also be +represented as + +@example +[rA] = + 10 40 31 52 23 +[rX] = + 11 35 49 20 54 +@end example + +@samp{CHAR} performs the inverse operation, using only the values 30 +to 39 for representing digits 0-9. + +@node Shift operators, Miscellaneous operators, Conversion operators, MIX instruction set +@comment node-name, next, previous, up +@subsubsection Shift operators +@cindex shift +@cindex shift operators + +The following instructions perform byte-wise shifts of the contents of +@samp{rA} and @samp{rX}. + +@ftable @code +@item SLA +@itemx SRA +@itemx SLAX +@itemx SRAX +@itemx SLC +@itemx SRC +Shift rA or rAX left, right, or rAX circularly (see example below) +left or right. M specifies the number of bytes to be shifted. +OPCODE = 6, MOD = 0, 1, 2, 3, 4, 5. +@end ftable +@noindent +If we begin with, say, @samp{[rA]} = @w{- 01 02 03 04 05}, we would +have the following modifications to @samp{rA} contents when performing +the instructions on the left column: + +@multitable {SLA 00} {[rA] = - 00 00 00 00 00} +@item SLA 2 @tab [rA] = - 03 04 05 00 00 +@item SLA 6 @tab [rA] = - 00 00 00 00 00 +@item SRA 1 @tab [rA] = - 00 01 02 03 04 +@end multitable +@noindent +Note that the sign is unaffected by shift operations. On the other +hand, @samp{SLC}, @samp{SRC}, @samp{SLAX} and @samp{SRAX} treat +@samp{rA} and @samp{rX} as a single 10-bytes register (ignoring again +the signs). For instance, if we begin with @samp{[rA]} = @w{+ 01 02 03 +04 05} and @samp{[rX]} = @w{- 06 07 08 09 10}, we would have: + +@multitable {SLC 00} {[rA] = - 00 00 00 00 00} {[rA] = - 00 00 00 00 00} +@item SLC 3 @tab [rA] = + 04 05 06 07 08 @tab [rX] = - 09 10 01 02 03 +@item SLAX 3 @tab [rA] = + 04 05 06 07 08 @tab [rX] = - 09 10 00 00 00 +@item SRC 4 @tab [rA] = + 07 08 09 10 01 @tab [rX] = - 02 03 04 05 06 +@item SRAX 4 @tab [rA] = + 00 00 00 00 01 @tab [rX] = - 02 03 04 05 06 +@end multitable + +@node Miscellaneous operators, Execution times, Shift operators, MIX instruction set +@comment node-name, next, previous, up +@subsubsection Miscellaneous operators +@cindex miscellaneous operators + +Finally, we list in the following table three miscellaneous MIX +instructions which do not fit in any of the previous subsections: + +@ftable @code +@item MOVE +Move MOD words from M to the location stored in rI1. +OPCODE = 7, MOD = no. of words. +@item NOP +No operation. OPCODE = 0, MOD = 0. +@item HLT +Halt. Stops instruction fetching. OPCODE = 5, MOD = 2. +@end ftable +@noindent +The only effect of executing @samp{NOP} is increasing the location +counter, while @samp{HLT} usually marks program termination. + +@node Execution times, , Miscellaneous operators, MIX instruction set +@comment node-name, next, previous, up +@subsubsection Execution times + +@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 (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. + +@multitable {INSSSS} {01} {INSSSS} {01} {INSSSS} {01} {INSSSS} {01} +@item @code{NOP} @tab 1 @tab @code{ADD} @tab 2 @tab @code{SUB} +@tab 2 @tab @code{MUL} @tab 10 +@item @code{DIV} @tab 12 @tab @code{NUM} @tab 10 @tab @code{CHAR} +@tab 10 @tab @code{HLT} @tab 10 +@item @code{SLx} @tab 2 @tab @code{SRx} @tab 2 @tab @code{LDx} +@tab 2 @tab @code{STx} @tab 2 +@item @code{JBUS} @tab 1 @tab @code{IOC} @tab 1 @tab @code{IN} +@tab 1@tab @code{OUT} @tab 1 +@item @code{JRED} @tab 1 @tab @code{Jx} @tab 1 @tab @code{INCx} +@tab 1 @tab @code{DECx} @tab 1 +@item @code{ENTx} @tab 1 @tab @code{ENNx} @tab 1 @tab @code{CMPx} +@tab 1 @tab @code{MOVE} @tab 1+2F +@end multitable + +In the above table, 'F' stands for the number of blocks to be moved +(given by the @code{FSPEC} subfield of the instruction); @code{SLx} and +@code{SRx} are a short cut for the byte-shifting operations; @code{LDx} +denote all the loading operations; @code{STx} are the storing +operations; @code{Jx} stands for all the jump operations, and so on with +the rest of abbreviations. + +@node MIXAL, , The MIX computer, MIX and MIXAL tutorial +@comment node-name, next, previous, up +@section MIXAL +@cindex MIXAL +@cindex MIX assembly language +@cindex assembly + +In the previous sections we have listed all the available MIX binary +instructions. As we have shown, each instruction is represented by a +word which is fetched from memory and executed by the MIX virtual +CPU. As is the case with real computers, the MIX knows how to decode +instructions in binary format (the so--called machine language), but a +human programmer would have a tough time if she were to write her +programs in machine language. Fortunately, the MIX computer can be +programmed using an assembly language, MIXAL, which provides a symbolic +way of writing the binary instructions understood by the imaginary MIX +computer. If you have used assembler languages before, you will find +MIXAL a very familiar language. MIXAL source files are translated +to machine language by a MIX assembler, which produces a binary file (the +actual MIX program) which can be directly loaded into the MIX memory and +subsequently executed. + +In this section, we describe MIXAL, the MIX assembly language. The +implementation of the MIX assembler program and MIX computer simulator +provided by @sc{mdk} are described later on (@pxref{Getting started}). + +@menu +* Basic structure:: Writing basic MIXAL programs. +* MIXAL directives:: Assembler directives. +* Expressions:: Evaluation of expressions. +* W-expressions:: Evaluation of w-expressions. +* Local symbols:: Special symbol table entries. +* Literal constants:: Specifying an immediate operand. +@end menu + +@node Basic structure, MIXAL directives, MIXAL, MIXAL +@comment node-name, next, previous, up +@subsection Basic program structure + +The MIX assembler reads MIXAL files line by line, producing, when +required, a binary instruction, which is associated to a predefined +memory address. To keep track of the current address, the assembler +maintains an internal location counter which is incremented each time an +instruction is compiled. In addition to MIX instructions, you can +include in MIXAL file assembly directives (or pseudoinstructions) +addressed at the assembler itself (for instance, telling it where the +program starts and ends, or to reposition the location counter; see below). + +MIX instructions and assembler directives@footnote{We shall call them, +collectively, MIXAL instructions.} are written in MIXAL (one per +source file line) according to the following pattern: + +@example +[LABEL] MNEMONIC [OPERAND] [COMMENT] +@end example + +@noindent +where @samp{OPERAND} is of the form + +@example +[ADDRESS][,INDEX][(MOD)] +@end example + +Items between square brackets are optional, and + +@table @code +@item LABEL +is an alphanumeric identifier (a @dfn{symbol}) which gets the current +value of the location counter, and can be used in subsequent +expressions, +@item MNEMONIC +is a literal denoting the operation code of the instruction +(e.g. @code{LDA}, @code{STA}; see @pxref{MIX instruction set}) or an +assembly pseudoinstruction (e.g. @code{ORG}, @code{EQU}), +@item ADDRESS +is an expression evaluating to the address subfield of the instruction, +@item INDEX +is an expression evaluating to the index subfield of the instruction, which +defaults to 0 (i.e., no use of indexing) and can only be used when +@code{ADDRESS} is present, +@item MOD +is an expression evaluating to the mod subfield of the instruction. Its +default value, when omitted, depends on @code{OPCODE}, +@item COMMENT +any number of spaces after the operand mark the beggining of a comment, +i.e. any text separated by white space from the operand is ignored by +the assembler (note that spaces are not allowed within the +@samp{OPERAND} field). +@end table + +Note that spaces are @emph{not} allowed between the @code{ADDRESS}, +@code{INDEX} and @code{MOD} fields if they are present. White space is +used to separate the label, operation code and operand parts of the +instruction@footnote{In fact, Knuth's definition of MIXAL restricts the +column number at which each of these instruction parts must start. The +MIXAL assembler included in @sc{mdk}, @code{mixasm}, does not impose +such restriction.}. + +We have already listed the mnemonics associated will each MIX +instructions; sample MIXAL instructions representing MIX instructions +are: +@example +HERE LDA 2000 HERE represents the current location counter + LDX HERE,2(1:3) this is a comment + JMP 1234 +@end example + +@node MIXAL directives, Expressions, Basic structure, MIXAL +@comment node-name, next, previous, up +@subsection MIXAL directives + +MIXAL instructions can be either one of the MIX machine instructions +(@pxref{MIX instruction set}) or one of the following assembly +pseudoinstructions: + +@ftable @code +@item ORIG +Sets the value of the memory address to which following instructions +will be allocated after compilation. +@item EQU +Used to define a symbol's value, e.g. @w{@code{SYM EQU 2*200/3}}. +@item CON +The value of the given expression is copied directly into the current +memory address. +@item ALF +Takes as operand five characters, constituting the five bytes of a word +which is copied directly into the current memory address. +@item END +Marks the end of the program. Its operand gives the start address for +program execution. +@end ftable + +The operand of @code{ORIG}, @code{EQU}, @code{CON} and @code{END} can be +any expression evaluating to a constant MIX word, i.e., either a simple +MIXAL expression (composed of numbers, symbols and binary operators, +@pxref{Expressions}) or a w-expression (@pxref{W-expressions}). + +All MIXAL programs must contain an @code{END} directive, with a twofold +end: first, it marks the end of the assembler job, and, in the second +place, its (mandatory) operand indicates the start address for the +compiled program (that is, the address at which the virtual MIX machine +must begin fetching instructions after loading the program). It is also +very common (although not mandatory) to include at least an @code{ORIG} +directive to mark the initial value of the assembler's location counter +(remember that it stores the address associated with each compiled MIX +instruction). Thus, a minimal MIXAL program would be + +@example + ORIG 2000 set the initial compilation adress + NOP this instruction will be loaded at adress 2000 + HLT and this one at address 2001 + END 2000 end of program; start at address 2000 +this line is not parsed by the assembler +@end example +@noindent +The assembler will generate two binary instructions (@code{NOP} (@w{+ 00 +00 00 00 00}) and @code{HLT} (+ 00 00 02 05)), which will be loaded at +addresses 2000 and 2001. Execution of the program will begin at address +2000. Every MIXAL program should also include a @code{HLT} instruction, +which will mark the end of program execution (but not of program +compilation). + +The @code{EQU} directive allows the definition of symbolic names for +specific values. For instance, we could rewrite the above program as +follows: + +@example +START EQU 2000 + ORIG START + NOP + HLT + END START +@end example +@noindent +which would give rise to the same compiled code. Symbolic constants (or +symbols, for short) can also be implicitly defined placing them in the +@code{LABEL} field of a MIXAL instruction: in this case, the assembler +assigns to the symbol the value of the location counter before compiling +the line. Hence, a third way of writing our trivial program is + +@example + ORIG 2000 +START NOP + HLT + END START +@end example + +The @code{CON} directive allows you to directly specify the contents of +the memory address pointed by the location counter. For instance, when +the assembler encounters the following code snippet + +@example + ORIG 1150 + CON -1823473 +@end example +@noindent +it will assign to the memory cell number 1150 the contents @w{- 00 06 61 +11 49} (which corresponds to the decimal value -1823473). + +Finally, the @code{ALF} directive let's you specify the memory contents +as a set of five (optionally quoted) characters, which are translated by +the assembler to their byte values, conforming in that way the binary +word that is to be stored in the corresponding memory cell. This +directive comes in handy when you need to store printable messages in a +memory address, as in the following example @footnote{In the original +MIXAL definition, the @code{ALF} argument is not quoted. You can write +the operand (as the @code{ADDRESS} field) without quotes, but, in this +case, you must follow the alignment rules of the original MIXAL +definition (namely, the @code{ADDRESS} must start at column 17).}: + +@example + OUT MSG MSG is not yet defined here (future reference) +MSG ALF "THIS " MSG gets defined here + ALF "IS A " + ALF "MESSA" + ALF "GE. " +@end example +@noindent +The above snippet also shows the use of a @dfn{future reference}, that +is, the usage of a symbol (@code{MSG} in the example) prior of its actual +definition. The MIXAL assembler is able to handle future references +subject to some limitations which are described in the following section +(@pxref{Expressions}). + +@cindex comments + +Any line starting with an asterisk is treated as a comment and ignored +by the assembler. + +@example +* This is a comment: this line is ignored. + * This line is an error: * must be in column 1. +@end example + +As noted in the previous section, comments can also be located after the +@code{OPERAND} field of an instruction, separated from it by white +space, as in + +@example +LABEL LDA 100 This is also a comment +@end example + +@node Expressions, W-expressions, MIXAL directives, MIXAL +@comment node-name, next, previous, up +@subsection Expressions +@cindex operator +@cindex binary operator +@cindex unary operator +The @code{ADDRESS}, @code{INDEX} and @code{MOD} fields of a MIXAL +instruction can be expressions, formed by numbers, identifiers and +binary operators (@code{+ - * / // :}). @code{+} and @code{-} can also +be used as unary operators. Operator precedence is from left to right: +there is no other operator precedence rule, and parentheses cannot be +used for grouping. A stand-alone asterisk denotes the current memory +location; thus, for instance, + +@example + 4+2** +@end example + +@noindent +evaluates to 6 (4 plus 2) times the current memory location. White space +is not allowed within expressions. + +The special binary operator @code{:} has the same meaning as in fspecs, +i.e., + +@example +A:B = 8*A + B +@end example +@noindent +while @code{A//B} stands for the quotient of the ten-byte number @w{@code{A} 00 +00 00 00 00} (that is, A right-padded with 5 null bytes or, what amounts +to the same, multiplied by 64 to the fifth power) divided by +@code{B}. Sample expressions are: + +@example +18-8*3 = 30 +14/3 = 4 +1+3:11 = 4:11 = 43 +1//64 = (01 00 00 00 00 00)/(00 00 00 01 00) = (01 00 00 00 00) +@end example +@noindent +Note that all MIXAL expressions evaluate to a MIX word (by definition). + +All symbols appearing within an expression must be previously defined. Future +references are only allowed when appearing standalone (or modified by +an unary operator) in the @code{ADDRESS} part of a MIXAL instruction, +e.g. + +@example +* OK: stand alone future reference + STA -S1(1:5) +* ERROR: future reference in expression + LDX 2-S1 +S1 LD1 2000 +@end example + +@node W-expressions, Local symbols, Expressions, MIXAL +@comment node-name, next, previous, up +@subsection W-expressions +@cindex w-expressions + +Besides expressions, as described above (@pxref{Expressions}), the MIXAL +assembler is able to handle the so called @dfn{w-expressions} as the +operands of the directives @code{ORIG}, @code{EQU}, @code{CON} and +@code{END} (@pxref{MIXAL directives}). The general form of a +w-expression is the following: + +@example + WEXP = EXP[(EXP)][,WEXP] +@end example +@noindent +where @code{EXP} stands for an expression and square brackets denote +optional items. Thus, a w-expression is made by an expression, followed +by an optional expression between parenthesis, followed by any number +of similar constructs separated by commas. Sample w-expressions are: + +@example +2000 +235(3) +S1+3(S2),3000 +S1,S2(3:5),23 +@end example + +W-expressions are evaluated from left to right as follows: + +@itemize +@item +Start with an accumulated result @samp{w} equal to 0. +@item +Take the first expression of the comma-separated list and evaluate +it. For instance, if the w-expression is @samp{S1+2(2:4),2000(S2)}, we +evaluate first @samp{S1+2}; let's suppose that @samp{S1} equals +265230: then @samp{S1+2 = 265232 = + 00 01 00 48 16}. +@item +Evaluate the expression within parenthesis, reducing it to an f-spec +of the form @samp{L:R}. In our previous example, the expression +between parenthesis already has the desired form: 2:4. +@item +Substitute the bytes of the accumulated result @samp{w} designated by +the f-spec using those of the previous expression value. In our sample, +@samp{w = + 00 00 00 00 00}, and we must substitute bytes 2, 3 and 4 of +@samp{w} using values from 265232. We need 3 bytes, and we take the +least significant ones: 00, 48, and 16, and insert them in positions +2, 3 and 4 of @samp{w}, obtaining @samp{w = + 00 00 48 16 00}. +@item +Repeat this operation with the remaining terms, acting on the new +value of @samp{w}. In our example, if, say, @samp{S2 = 1:1}, we must +substitute the first byte of @samp{w} using one byte (the least +significant) from 2000, that is, 16 (since 2000 = + 00 00 00 31 16) +and, therefore, we obtain @samp{w = + 16 00 48 16 00}; summing up, we +have obtained @samp{265232(1:4),2000(1:1) = + 16 00 48 16 00 = +268633088}. +@end itemize + +As a second example, in the w-expression +@example +1(1:2),66(4:5) +@end example +@noindent +we first take two bytes from 1 (00 and 01) and store them as bytes 1 and +2 of the result (obtaining @w{@samp{+ 00 01 00 00 00}}) and, afterwards, +take two bytes from 66 (01 and 02) and store them as bytes 4 and 5 of +the result, obtaining @w{@samp{+ 00 01 00 01 02}} (262210). The process +is repeated for each new comma-separated example. For instance: + +@example +1(1:1),2(2:2),3(3:3),4(4:4) = 01 02 03 04 00 +@end example + +As stated before, w-expressions can only appear as the operands of MIXAL +directives taking a constant value (@code{ORIG}, @code{EQU}, @code{CON} +and @code{END}). Future references are @emph{not} allowed within +w-expressions (i.e., all symbols appearing in a w-expression must be +defined before it is used). + +@node Local symbols, Literal constants, W-expressions, MIXAL +@comment node-name, next, previous, up +@subsection Local symbols +@cindex local symbols + +Besides user defined symbols, MIXAL programmers can use the so called +@dfn{local symbols}, which are symbols of the form @code{[1-9][HBF]}. A +local symbol @code{nB} refers to the address of the last previous +occurrence of @code{nH} as a label, while @code{nF} refers to the next +@code{nH} occurrence. Unlike user defined symbols, @code{nH} can appear +multiple times in the @code{LABEL} part of different MIXAL +instructions. The following code shows an instance of local symbols' +usage: + +@example +* line 1 +1H LDA 100 +* line 2: 1B refers to address of line 1, 3F refers to address of line 4 + STA 3F,2(1B//2) +* line 3: redefinition of 1H +1H STZ +* line 4: 1B refers to address of line 3 +3H JMP 1B +@end example + +Note that a @code{B} local symbol never refers to a definition in its +own line, that is, in the following program: + +@example + ORIG 1999 +ST NOP +3H EQU 69 +3H ENTA 3B local symbol 3B refers to 3H in previous line + HLT + END ST +@end example +@noindent +the contents of @samp{rA} is set to 69 and @emph{not} to 2001. An +specially tricky case occurs when using local symbols in conjunction +with @code{ORIG} pseudoinstructions. To wit@footnote{The author wants to +thank Philip E. King for pointing these two special cases of local +symbol usage to him.}, + +@example + ORIG 1999 +ST NOP +3H CON 10 + ENT1 * + LDA 3B +** rI1 is 2001, rA is 10. So far so good! +3H ORIG 3B+1000 +** at this point 3H equals 2003 +** and the location counter equals 3000. + ENT2 * + LDX 3B +** rI2 contains 3000, rX contains 2003. + HLT + END ST +@end example + +@node Literal constants, , Local symbols, MIXAL +@comment node-name, next, previous, up +@subsection Literal constants +@cindex literal constants + +MIXAL allows the introduction of @dfn{literal constants}, which are +automatically stored in memory addresses after the end of the program by +the assembler. Literal constants are denoted as @code{=wexp=}, where +@code{wexp} is a w-expression (@pxref{W-expressions}). For instance, the +code + +@example +L EQU 5 + LDA =20-L= +@end example + +causes the assembler to add after the program's end an instruction +with contents 15 (@samp{20-L}), and to assemble the above code as the +instruction @w{@code{ LDA a}}, where @code{a} stands for the address +in which the value 15 is stored. In other words, the compiled code is +equivalent to the following: + +@example +L EQU 5 + LDA a +@dots{} +a CON 20-L + END start +@end example + |
