-
Notifications
You must be signed in to change notification settings - Fork 2
/
README
136 lines (114 loc) · 6.47 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
This readme contains a few explanations to the project-layout and other things
one should know when working with GIMMIX.
Project layout:
===============
- build
This directory will be created automatically and contains all files and
folders that are generated during build- or runtime.
- build/coverage
The script runcov.sh puts the coverage-information into this directory. To
view it, open build/coverage/index.html with your favorite browser.
- build/testresults
The script runtests.sh puts all test-results into this directory.
- build/tests
The build-procedure puts various files that are generated from the mms-files
into this directory. Most of them are not very interesting, but sometimes it
is useful to view the *.lst files to see the addresses of all instructions
together with the written code (i.e. including comments etc., not just the
disassembled instructions).
- doc
This directory contains the TeX-sources, images and so on and the final PDF
of the master thesis and the abstract. It does also hold some documents
related to the project that have been created or collected during the
development of GIMMIX. Especially, the blog.txt should be mentioned, because
it describes the development process and lists a few noteworthy things. Some
of them have not been considered important enough to be mentioned in the
thesis, but might still be interesting.
- include
As the name suggests, it contains all header files of the code. Thus,
"-I include" is passed to gcc.
- lib
This folder contains some libraries that are used in GIMMIX. The subfolder
getline holds the getline-library written by Chris Thewalt. The other two
libraries have been created by me, because the code is used in multiple
programs.
- org
This folder contains MMIXware version 20110305 with only slight
modifications. The organization of the files and folders has been improved a
bit to be more clear. Additionally, as mentioned in the thesis, MMIX-SIM and
MMIX-PIPE have been extended by the postcommands-module and MMIX-PIPE stops
when executing a TRAP 0,0,0.
- src
This directory contains the sources of GIMMIX.
- testgen
The directory testgen contains all test-generation-programs. As said in the
thesis, these are either C programs or Ruby scripts. Additionally, it
contains the Ruby script regenerate.rb, which generates all test-programs
and stores them into the corresponding folder in tests/ (it will overwrite
the existing ones).
- tests
This directory contains all test programs. As described in the thesis, the
folders cli, diff, kernel and user have special meanings and contain the
automatized tests. The folder manual holds various programs that utilize the
yet present devices. Most of them have been written for fun :-)
It should be mentioned that the build-system passes the mms-files through the
C preprocessor before assembling them. Thus, the include-directive can be
used to include library routines, for example. Currently, there are the files
io.mmi and string.mmi that provide a few routines, that are included in some
of the test programs.
- tools
The directory tools is used for various tools used in the project. It holds
the assembler gimmixal, which is currently simply a copy of the generated
C code from mmixal.w in MMIXware. Second, the tool gimmo2mmx converts
mmo-files to the ASCII format understood by GIMMIX and MMIX-PIPE. It has
been taken from a previous approach of GIMMIX and has been written by Mr.
Geisse. The tool gimmx2bin has been written by me and converts a mmx-file
to a binary file that can be used as a ROM. Since the ASCII format is
considered temporary, this converter has not been built for eternity as well.
The tool hostarith has been written for testing purposes and allows the user
to explore the arithmetic provided by C99 and the host platform. Last but not
least, the tools-directory contains the tool abstime to generate the
timestamp for rN and some Ruby scripts to produce the coverage HTML pages.
- unittests
Probably, you've guessed it. This directory contains the unit tests and the
test "framework".
Building and using GIMMIX:
==========================
To build GIMMIX, please go at first to the subdirectory org and run "make". You
can also do a "make doc" to build the PDFs, but that's not required. Actually,
GIMMIX is independent of MMIXware, but to be able to run programs on MMIX-PIPE,
the test-build-system uses MMIX-SIM to produce the mmb-files that are required
to run user-programs on MMIX-PIPE. Therefore, without building MMIX-SIM before
building GIMMIX, make will complain that MMIX-SIM does not exist. Note that you
need the program ctangle to build MMIXware (if you have a debian-based system,
you'll find it in the package texlive-binaries).
As soon as MMIXware has been built, you can go back into the root-directory and
type "make". This will build the whole project. This should work out of box
with a typical Linux system (it has been tested with a fresh installation of
Ubuntu 10.04). But note that you need the Ruby interpreter to be able to
regenerate the test-programs or produce the coverage-information.
To run GIMMIX, you can of course simply start the executable build/gimmix. But
when developing GIMMIX, its more convenient to use one of various make-targets
to do so. This will ensure that build/gimmix (and all other stuff) is up to
date. For example, use "make debug PROG=user/alignment" to debug (run GIMMIX
interactively) the user-program tests/user/alignment.mms. Or use
"make debugx PROG=kernel/exceptions1" to debug the specified kernel-program.
Furthermore, you can set the environment-variable PARAMS to pass additional
parameters to every run of GIMMIX (which will be handled by the makefile). To
see all options, please take a look in Makefile.
Besides running a program in GIMMIX, you can execute runtests.sh to run the
automatized program tests and execute runcov.sh to generate the coverage
information. Finally, "make test" can be used to run the unit tests.
To make use of the gdb-stub, you need a modified version of gdb for MMIX. Thanks
to the work of Martin Ruckert, a modified version of gdb 6.4.50 is available.
You can download it here: http://math.cs.hm.edu/mmix/bin/index.html
After unpacking it to /opt/mmix, you can do something like:
$ ./build/gimmix ... -p 1234 &
$ /opt/mmix/bin/mmix-gdbtui
(gdb) target remote localhost:1234
...
Contact:
========
If you have any questions or suggestions, please do not hesitate to write me an
email:
Nils Asmussen <[email protected]>