OpenCores
URL https://opencores.org/ocsvn/eco32/eco32/trunk

Subversion Repositories eco32

[/] [eco32/] [trunk/] [fp/] [implementation/] [mmix/] [README] - Blame information for rev 54

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 15 hellwig
MMIXware sources --- Initial release
2
 
3
Greetings to the courageous souls who will be first on their
4
block to run MMIX programs! I've tested the programs in this directory
5
for several months and I can't find any more bugs, so now it is
6
your turn. I hope you will be able to help me gain experience with
7
lots of different compilers and platforms.
8
 
9
A hardcopy book that contains listings of these programs together
10
with handy cross-indexes on each two-page spread has been published:
11
  MMIXware by Donald E. Knuth
12
  Lecture Notes in Computer Science 1750 (Springer Verlag, Heidelberg, 1999).
13
 
14
All source files are written in CWEB, a well-tested and widely
15
available system (see http://www-cs-faculty.stanford.edu/~knuth/cweb.html).
16
 
17
FILES
18
 
19
boilerplate.w     Legal stuff; says you can copy but not change
20
                  the master sources
21
 
22
mmix-doc.w        Detailed description of the MMIX architecture
23
 
24
mmixal.w          Assembly program; includes detailed description of the
25
                   symbolic assembly language (MMIXAL), as well as
26
                   a full description of the binary executable format
27
 
28
mmix-arith.w      Subroutines to implement 64-bit arithmetic on a
29
                   32-bit computer; includes complete implementation
30
                   of standard IEEE floating binary arithemtic
31
 
32
mmix-sim.w        Program for the simple (non-pipelined) simulator;
33
                   includes detailed description of the runtime
34
                   environment and facilities for online interaction
35
 
36
mmix-io.w         Subroutines to implement rudimentary memory-mapped I/O
37
 
38
mmotype.w         Program to convert binary executables to readable format
39
 
40
abstime.w         Program used to give each MMIX implementation a unique ID
41
 
42
mmmix.w           Driver program for the pipelined meta-simulator
43
 
44
mmix-config.w     Configuration module for the pipelined meta-simulator
45
 
46
mmix-pipe.w       Main logic of the pipelined meta-simulator
47
 
48
mmix-mem.w        Module to change if memory-mapped I/O is added to
49
                  the meta-simulator
50
 
51
copy.mms          Example of MMIXAL I/O: copies a given file to standard output
52
silly.mms         A test program that exercises almost all 256 opcodes
53
silly.run         Command script to use when simulating silly.mms
54
silly.out         The "correct" output of that silly input
55
iotest.mms        Another test, for the I/O routines not used in "copy.mms"
56
crypto.mms, fib.mms, primes.mms, ...: Example programs used in TAOCP 1.3', 1.4'
57
 
58
mmix.mp           METAPOST source for an illustration used in mmix.w
59
mmix.1            METAPOST output from mmix.mp; you don't need to run METAPOST
60
 
61
*.mmconfig        Example configuration files (for experts using mmmix)
62
*.mmix            Example hex program files (for experts using mmmix)
63
 
64
Makefile          UNIX makefile
65
makefile.dos      DOS makefile (for DOS/Windows platforms)
66
 
67
HOW TO GET STARTED
68
 
69
First try "make doc"; this, at least on UNIX-like systems equipped with dvips,
70
should create three PostScript documents called mmix-doc.ps, mmixal.ps, and
71
mmix-sim.ps. Print these files, and move their tables-of-contents
72
pages to the front (those pages appear at the end). Read the introductory
73
parts of those documents, and please report any errors you find to
74
knuth-bug@cs.stanford.edu. If your system is unable to create those documents
75
for some reason, go to
76
   http://www-cs-faculty.stanford.edu/~knuth/mmix.html
77
and download the compressed PostScript files from there.
78
Say "make clean" when you've got hardcopy.
79
 
80
Then try "make mmix", to create the simulator, and "make mmixal" to
81
create the assembler. (Also "make mmotype" will create the MMOtype utility;
82
"make all" makes all three, and it also makes the meta-simulator.)
83
 
84
Then "mmixal -l copy.lst copy.mms" should create the MMIX object file
85
copy.mmo, as well as a symbolic listing file called copy.lst.
86
 
87
Then "mmix copy copy.mms" should simulate MMIX copying the file copy.mms
88
to the standard output on your terminal. In general,
89
    mmix  copy 
90
should copy any given text file to the standard output. The options are
91
explained near the beginning of the documentation for mmix-sim, and
92
you get a summary of all command-line options if you say just "mmix"
93
with no arguments (or with unparsable arguments).
94
 
95
Then "mmixal silly.mms" followed by "mmix -i silly" followed by "i silly.run"
96
should produce about 100K bytes of output that matches silly.out.
97
 
98
Once all this works, you should be able to try programs of your own.
99
 
100
ADVANCED TOPIC: THE PIPELINE SIMULATOR
101
 
102
After you have some experience with the simple simulator, you're ready
103
for the super meta-simulator, "mmmix". This one is a lot more complicated,
104
and the present interface is not especially user-friendly, but it can be used
105
for incredibly interesting tests of programs and hardware configurations.
106
To get started, "make mmmix" and then try this:
107
  home_machine> mmixal hello.mms
108
  home_machine> mmix -Dhello.mmb hello
109
  home_machine> mmmix plain.mmconfig hello.mmb
110
  mmmix> 10000
111
  Running 10000 at time 0
112
  hello, world
113
  Halted at time 405
114
  mmmix> q
115
  Simulation ended at time 406.
116
  Predictions: 0 in agreement, 0 in opposition; 0 good, 0 bad
117
  Instructions issued per cycle:
118
 
119
    1   26
120
[Explanation: First we use the mmixal assembler to create the object
121
file hello.mmo from the symbolic file hello.mms. Then we use the simple
122
mmix simulator to prepare a binary dump file, hello.mmb, which it prepares
123
from hello.mmo. Then we invoke the meta-mmix simulator (mmmix) with
124
the sample configuration file plain.mmconfig and the program file hello.mmb.
125
Then we ask mmmix to "run for up to 10000 cycles". It actually finishes
126
after 405 cycles, having printed out its famous message to the world.]
127
  home_machine> mmix -Dsilly.mmb silly
128
  home_machine> mmmix plain.mmconfig silly.mmb
129
  mmmix> 10000
130
  Running 10000 at time 0
131
  Warning: TRIP at location 000000000000039c
132
  Warning: floating point underflow at location 00000000000003a0
133
  Halted at time 4424
134
  mmmix> q
135
  Simulation ended at time 4425.
136
  Predictions: 183 in agreement, 15 in opposition; 176 good, 22 bad
137
  Instructions issued per cycle:
138
 
139
    1   1760
140
[Explanation: This time we try mmmix on the torture-test program "silly".
141
That program is completely weird, but it does exercise all 256 instructions
142
and comes up with lots of different cases. The "silly" program is so weird,
143
it is semantically incorrect in its use of PREST instructions; hence it
144
cannot be guaranteed to run correctly on all implementations of MMIX.
145
But with a sufficiently large Dcache, as in plain.mmconfig, this bug does
146
not arise, and the program runs through all its paces correctly,
147
including many complicated interrupts and interactions between
148
the register stack and the various caches. You can watch all the gory details
149
by asking for "verbose" output, saying
150
  mmmix> vff
151
  mmmix> 10000
152
although the output file will then be huge. Indeed, it took me a couple days
153
to verify that everything was indeed working as I thought it should.]
154
  home_machine> mmmix test1.mmconfig test1.mmix
155
  mmmix> @8000000000010000
156
  mmmix> b0
157
  mmmix> vff
158
  mmmix> 140
159
  Running 140 at time 0 with breakpoint 0000000000000000
160
  *** Cycle 0
161
   running Write:92  hist=0 state=0
162
   scheduling Write:92 at time 1, state 0
163
        . . . . . .   {lots more}
164
  *** Cycle 137
165
   running ITfiller:93  hist=0 state=3
166
   running Write:92  hist=0 state=0
167
   scheduling Write:92 at time 138, state 0
168
   running Fetch:0  hist=0 state=19
169
   scheduling ITreader:98 at time 138, state 0
170
   scheduling Ireader:98 at time 138, state 0
171
   scheduling Fetch:0 at time 138, state 1
172
   scheduling UNI1:1 at time 138, state 0
173
  Issuing 0: fd000000(noop)* int=x hist=1 state=0 UNI1:1
174
  Write buffer (empty)
175
  Reorder buffer:
176
  0: fd000000(noop)* int=x hist=1 state=0 UNI1:1
177
   5 available rename registers, 2 memory slots
178
  Fetch buffer:
179
  4: fd000000(SWYM)x
180
  8: fd000000(SWYM)x
181
  c: fd000000(SWYM)x
182
  Instruction pointer is 10
183
  Scache locked by Dfiller:94
184
  Scachefill locked by Dfiller:94
185
  mem locked by Sfiller:95
186
  Breakpoint instruction fetched at time 137
187
[This was my first test program. It illustrates a complicated case of
188
virtual address translation; it also illustrates a second way to
189
input programs to mmmix, via the ASCII hexadecimal file "test1.mmix"
190
instead of a binary .mmb file. This second way allows you complete freedom in
191
what you put into memory; there is no canned division into text, data, pool,
192
and stack segments; there is no "Main"; you can try multiprocessing and
193
all other aspects of the hardware. Of course you need to read the
194
documentation before you can fathom what is happening; I've given these
195
samples just to help you know if your program seems to be installed correctly.]
196
 
197
IMPORTANT NOTE
198
 
199
If changes are needed, do NOT change any of the source files. CWEB has
200
a convenient change-file mechanism by which you can make arbitrary
201
modifications, in such a way that your modifications will probably still
202
work when the master source files are improved later. Change files that
203
adapt these sources to other platforms will be distributed in future releases
204
of this software. (See, for example, the change files that come with
205
the CWEB distribution itself.)
206
 

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.