URL
https://opencores.org/ocsvn/eco32/eco32/trunk
Subversion Repositories eco32
[/] [eco32/] [tags/] [eco32-0.23/] [fp/] [implementation/] [mmix/] [README] - Rev 321
Go to most recent revision | Compare with Previous | Blame | View Log
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 <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 2665
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.)
Go to most recent revision | Compare with Previous | Blame | View Log