MMIXware sources --- Initial release

Greetings to the courageous souls who will be first on their
block to run MMIX programs! I've tested the programs in this directory
for several months and I can't find any more bugs, so now it is
your turn. I hope you will be able to help me gain experience with
lots of different compilers and platforms.

A hardcopy book that contains listings of these programs together
with handy cross-indexes on each two-page spread has been published:
  MMIXware by Donald E. Knuth
  Lecture Notes in Computer Science 1750 (Springer Verlag, Heidelberg, 1999).

All source files are written in CWEB, a well-tested and widely
available system (see http://www-cs-faculty.stanford.edu/~knuth/cweb.html).

FILES

boilerplate.w     Legal stuff; says you can copy but not change
                  the master sources

mmix-doc.w        Detailed description of the MMIX architecture

mmixal.w          Assembly program; includes detailed description of the
                   symbolic assembly language (MMIXAL), as well as
                   a full description of the binary executable format

mmix-arith.w      Subroutines to implement 64-bit arithmetic on a
                   32-bit computer; includes complete implementation
                   of standard IEEE floating binary arithemtic

mmix-sim.w        Program for the simple (non-pipelined) simulator;
                   includes detailed description of the runtime
                   environment and facilities for online interaction

mmix-io.w         Subroutines to implement rudimentary memory-mapped I/O

mmotype.w         Program to convert binary executables to readable format

abstime.w         Program used to give each MMIX implementation a unique ID

mmmix.w           Driver program for the pipelined meta-simulator

mmix-config.w     Configuration module for the pipelined meta-simulator

mmix-pipe.w       Main logic of the pipelined meta-simulator

mmix-mem.w        Module to change if memory-mapped I/O is added to
                  the meta-simulator

copy.mms          Example of MMIXAL I/O: copies a given file to standard output
silly.mms         A test program that exercises almost all 256 opcodes
silly.run         Command script to use when simulating silly.mms
silly.out         The "correct" output of that silly input
iotest.mms        Another test, for the I/O routines not used in "copy.mms"
crypto.mms, fib.mms, primes.mms, ...: Example programs used in TAOCP 1.3', 1.4'

mmix.mp           METAPOST source for an illustration used in mmix.w
mmix.1            METAPOST output from mmix.mp; you don't need to run METAPOST

*.mmconfig        Example configuration files (for experts using mmmix)
*.mmix            Example hex program files (for experts using mmmix)

Makefile          UNIX makefile
makefile.dos      DOS makefile (for DOS/Windows platforms)

HOW TO GET STARTED

First try "make doc"; this, at least on UNIX-like systems equipped with dvips,
should create three PostScript documents called mmix-doc.ps, mmixal-intro.ps,
and mmix-sim-intro.ps. Print these files, and move each table-of-contents
page to the front (those pages appear at the end). Read those documents,
and please report any errors you find to ruckert@cs.hm.edu.
If your system is unable to create those documents for some reason, go to
   http://mmix.cs.hm.edu/doc
for pdf files, or to
   http://www-cs-faculty.stanford.edu/~knuth/mmix-news.html
and download the compressed PostScript files from there.
Say "make clean" when you've got hardcopy.

Then try "make mmix", to create the simulator, and "make mmixal" to
create the assembler. (Also "make mmotype" will create the MMOtype utility;
"make all" makes all three, and it also makes the meta-simulator.)

Then "mmixal -l copy.lst copy.mms" should create the MMIX object file
copy.mmo, as well as a symbolic listing file called copy.lst.

Then "mmix copy copy.mms" should simulate MMIX copying the file copy.mms
to the standard output on your terminal. In general,
    mmix <options> copy <filename>
should copy any given text file to the standard output. The options are
explained near the beginning of the documentation for mmix-sim, and
you get a summary of all command-line options if you say just "mmix"
with no arguments (or with unparsable arguments).

Then "mmixal silly.mms" followed by "mmix -i silly" followed by "i silly.run"
should produce about 100K bytes of output that matches silly.out.

Once all this works, you should be able to try programs of your own.

ADVANCED TOPIC: THE PIPELINE SIMULATOR

After you have some experience with the simple simulator, you're ready
for the super meta-simulator, "mmmix". This one is a lot more complicated,
and the present interface is not especially user-friendly, but it can be used
for incredibly interesting tests of programs and hardware configurations.
To get started, "make mmmix" and then try this:
  home_machine> mmixal hello.mms
  home_machine> mmix -Dhello.mmb hello
  home_machine> mmmix plain.mmconfig hello.mmb
  mmmix> 10000
  Running 10000 at time 0
  hello, world
  Halted at time 405
  mmmix> q
  Simulation ended at time 406.
  Predictions: 0 in agreement, 0 in opposition; 0 good, 0 bad
  Instructions issued per cycle:
    0   380
    1   26
[Explanation: First we use the mmixal assembler to create the object
file hello.mmo from the symbolic file hello.mms. Then we use the simple
mmix simulator to prepare a binary dump file, hello.mmb, which it prepares
from hello.mmo. Then we invoke the meta-mmix simulator (mmmix) with
the sample configuration file plain.mmconfig and the program file hello.mmb.
Then we ask mmmix to "run for up to 10000 cycles". It actually finishes
after 405 cycles, having printed out its famous message to the world.]
  home_machine> mmix -Dsilly.mmb silly
  home_machine> mmmix plain.mmconfig silly.mmb
  mmmix> 10000
  Running 10000 at time 0
  Warning: TRIP at location 000000000000039c
  Warning: floating point underflow at location 00000000000003a0
  Halted at time 4424
  mmmix> q
  Simulation ended at time 4425.
  Predictions: 183 in agreement, 15 in opposition; 176 good, 22 bad
  Instructions issued per cycle:
    0   2655
    1   1770
[Explanation: This time we try mmmix on the torture-test program "silly".
That program is completely weird, but it does exercise all 256 instructions
and comes up with lots of different cases. The "silly" program is so weird,
it is semantically incorrect in its use of PREST instructions; hence it
cannot be guaranteed to run correctly on all implementations of MMIX.
But with a sufficiently large Dcache, as in plain.mmconfig, this bug does
not arise, and the program runs through all its paces correctly,
including many complicated interrupts and interactions between
the register stack and the various caches. You can watch all the gory details
by asking for "verbose" output, saying
  mmmix> vff
  mmmix> 10000
although the output file will then be huge. Indeed, it took me a couple days
to verify that everything was indeed working as I thought it should.]
  home_machine> mmmix test1.mmconfig test1.mmix
  mmmix> @8000000000010000
  mmmix> b0
  mmmix> vff
  mmmix> 140
  Running 140 at time 0 with breakpoint 0000000000000000
  *** Cycle 0
   running Write:92  hist=0 state=0
   scheduling Write:92 at time 1, state 0
        . . . . . .   {lots more}
  *** Cycle 137
   running ITfiller:93  hist=0 state=3
   running Write:92  hist=0 state=0
   scheduling Write:92 at time 138, state 0
   running Fetch:0  hist=0 state=19
   scheduling ITreader:98 at time 138, state 0
   scheduling Ireader:98 at time 138, state 0
   scheduling Fetch:0 at time 138, state 1
   scheduling UNI1:1 at time 138, state 0
  Issuing 0: fd000000(noop)* int=x hist=1 state=0 UNI1:1
  Write buffer (empty)
  Reorder buffer:
  0: fd000000(noop)* int=x hist=1 state=0 UNI1:1
   5 available rename registers, 2 memory slots
  Fetch buffer:
  4: fd000000(SWYM)x
  8: fd000000(SWYM)x
  c: fd000000(SWYM)x
  Instruction pointer is 10
  Scache locked by Dfiller:94
  Scachefill locked by Dfiller:94
  mem locked by Sfiller:95
  Breakpoint instruction fetched at time 137
[This was my first test program. It illustrates a complicated case of
virtual address translation; it also illustrates a second way to
input programs to mmmix, via the ASCII hexadecimal file "test1.mmix"
instead of a binary .mmb file. This second way allows you complete freedom in
what you put into memory; there is no canned division into text, data, pool,
and stack segments; there is no "Main"; you can try multiprocessing and
all other aspects of the hardware. Of course you need to read the
documentation before you can fathom what is happening; I've given these
samples just to help you know if your program seems to be installed correctly.]

IMPORTANT NOTE

If changes are needed, do NOT change any of the source files. CWEB has
a convenient change-file mechanism by which you can make arbitrary
modifications, in such a way that your modifications will probably still
work when the master source files are improved later. Change files that
adapt these sources to other platforms will be distributed in future releases
of this software. (See, for example, the change files that come with
the CWEB distribution itself.)