Subversion Repositories eco32

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.ps, and

mmix-sim.ps. Print these files, and move their tables-of-contents

pages to the front (those pages appear at the end). Read the introductory

parts of those documents, and please report any errors you find to

knuth-bug@cs.stanford.edu. If your system is unable to create those documents

for some reason, go to

   http://www-cs-faculty.stanford.edu/~knuth/mmix.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  copy 

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:

    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:

    1   1760

[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.)