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 <nils@script-solution.de>