Fixing the help system

Currently, the EduMIPS64 user documentation is in bad shape. There are two different sources of documentation:

• The PDF manual, built from LaTeX files;
• The in-application help, made by (.. drum roll ..) text files. 

Both help sources are available in English and Italian. But this diversity means that there are two (actually, four) different places to update; moreover, the in-application help is really not adequate and a bit too simple.

Some time ago, we tried porting the help system to JavaHelp, but we didn't finish the porting and had some trouble in properly converting LaTeX to HTML. Moreover, JavaHelp seems to be dead.

So I asked a question on Stack Overflow, and I got two answers:

• convert LaTeX to ePub and embed an open source ePub viewer;
• use RTF in a JTextPane

To summarize, our requirements for the help system are the following:

• single source, multiple outputs (PDF, in-application help);
• in-application viewer
• optional search in the in-application help
• optional navigation pane in the in-application help

I have been playing a bit with the Sphinx documentation system, and I got two good PDF and single-html outputs, but then the problem was to display HTML in the application. The JEditorPane widget has some basic support for HTML and CSS, but it is way too basic. I'd had to heavily customize the output of Sphinx and I don't want to spend much time on it. Further, Using a basic viewer I'd drop the two optional requirements (search and navigation), or I'd have to code it- boring.

So we are going to try the LaTeX -> epub road, hoping that it works out nicely. In our idea, the new help system should be the only new feature in EduMIPS64 0.5.3.

EDIT: We settled with converting the documentation to reStructured Text and using Sphinx to output both the PDF and a multi-page HTML document, using the epub HTML theme; this HTML docs were then processed with jHelpDev to build a help set for JavaHelp, that even if it is not actively developed, seems to work well - maybe it is a bit slow but works. So probably 0.5.3 will have in-app help based on JavaHelp and with the same contents of the PDF manual.

Improving testability

There are a lot of features that can be integrated or implemented, but we feel that the first thing to do is to create a test suite, in order to be fairly confident that when we change something we do not break anything! After all, people use EduMIPS64 during their exams, and I don't want that someone gets a bad grade (and consequently tries to kill me) because of bad code.

A CPU simulator can be tested in many ways. The main decision we have to make is whether we should do black-box testing (overall functionality) or white-box testing (Java classes, individual or in small sets). So we looked at other CPU simulators in order to see how they solved this problem.

We've been looking at WinMIPS64, WinDLX and DLXView, but found no answer to our questions.

But when we turned to the SPIM MIPS32 Simulator, we found a very rich test suite. It is not surprising, as its author, James Larus, is very smart and wrote a really good presentation on Why write real software in Academia? (suggested reading for people in academia who happen to write software). The simulator is also featured in Appendix A of Hennessy & Patterson's "Computer Architecture: A quantitative approach", a reference book in the field, so it is definitely a good reference and inspiration source.

The Tests directory of SPIM contains 8 assembly test files that, together, amount to ~8500 lines of testing code. It is assembly code, so it is black-box testing.

We can try to reuse some of them, skipping some features (like FPU) and writing some new tests, as we implement a superset of their instruction set, even if the computation model is a bit different (we don't have memory/mapped IO, control registers and other few things).

There is a problem, however: EduMIPS64 is meant to be run as a desktop interactive application, and cannot be run in a CLI and in batch mode.

So we are trying to remove the few dependencies that the core of the simulator has with respect to the User Interface, that are poor design choices, and write a very small CLI frontend for the core, so that the CPU features can be tested without running the UI.

After that, we will try to port some testing code from SPIM to EduMIPS64, adding our own tests.

We will then be ready to integrate and add features to the simulator, knowing that we have a safety net that will catch most of the errors and will allow us to write code without breaking the core features in any (obvious) way.

State of the EduMIPS64 code base

In 2006, a small group of undergraduate students at the University of Catania was taking a course in Computer Architecture; they were not satisfied by existing MIPS64 simulators, so they decided to design and write their own simulator. They called it EduMIPS64 (web site: www.edumips.org), and it was initially conceived as an improved Java clone of WinMIPS64.

Most of the development happened between April and October 2006. Then, development slowed down a bit because the main functionalities were working and the simulator had been adopted as the official tool for Computer Architecture courses at the University of Catania.

There have been a moderate but constant activity through all 2007 and then, finally, in 2008 development came to an halt. The simulator was more mature, but many things still need improvement. Some important features, like FPU support and branch delay slot, have been developed but not released because the code needed to be polished, documented and tested.

This blog post wants to take a snapshot of the current state of the EduMIPS64 code base, in order to facilitate future development efforts.

The current stable version
The last version of EduMIPS64, 0.5.2, was released on 17th April of 2008, and like version 0.5.1 it is mainly a bug-fix release. Version 0.5 was the last major version, i.e. a version that introduced new features (namely, MIPS32 instructions and a few other things).

It can be considered quite stable, as the simulator is routinely used at least at the University of Catania for Computer Architecture exams, and no bugs were reported in the last 3 years.

The trunk
The trunk contains an implementation of the FPU, with a complete FP instruction set, visual representation of FP-related sections of the pipeline.
Moreover, it contains a (non-working) attempt to add in the help a conversion to HTML of the PDF manual.

The branches

• delayslot: contains an implementation of the Branch delay slot;
• editor: contains a (very) basic prototype of a built-in editor;
• new_parser:  a re-engineered parser written to replace the default one, that is difficult to mantain. It was developed as a student project for a Compilers course;
• cache: a re-engineered parser written to replace the one written during the development 
• 0.5: branch where development of the 0.5 series should go

Of these branches, delayslot, new_parser and cache are the ones that most likely will be included in future stable releases.

A note on testability

One of the problems of the EduMIPS64 code base is the lack of automated testing. When we developed it, we were mostly concerned with making it work, and as students it was an ambitious project. We worked day and night and fixed issues when they were raised, either by developers or by users, but we did not fully understand some basic concepts like unit testing, separation of intents, modularity etc..

Future development work needs to be addressed to a suite of unit tests that will work as a safety net for regressions as the development goes on.

Future development

There are many features that are almost ready but have been never released to the public, like the FPU or the branch delay slot.

It is likely that a new version of EduMIPS64, 0.5.3, will be released shortly. It will include some bug fixes and the ability to enable the branch delay slot, in order to get some user feedbacks on it.

After this, probably a 0.9 version with FPU will be released, and this version will also need to be heavily tested by users before a 1.0 stable version will be released.