Hacking an emulator is typically a complex project. Even emulating something as simple as the Commodore 64 is actually quite an intensive project, requiring a lot of research to understand the internals of the hardware. Hacking something as complex as a Lisp machine emulator is of an entirely different order compared to a C64 emulator of course. There are literally hundreds of pounds of documentation available, and most of it is either in a custom text format (Visidoc) or in huge PDFs containing grainy scans.
A good description of things to start reading if you're interested in hacking E3 was posted on the Lispm-Hackers list in December 2001. An excerpt (edited for currency) is below:
Dan Moniz <...> writes: > Hi James, > > I'm all set up on kappa and poked around the /home/lispm directory > for docs. Before I go about recursively FTPing all the PDFs and > what not, is there a massive tarball somewhere that I should grab > instead? I have a lengthy train trip coming up and figured this > might be a good time to get some reading in. There's not one particular tarball that you could grab. This is probably because we're not all that organized yet. But I can give you a guide to what's useful. BTW, I hope your trip is a week or two long if you want to finish all these docs... :^) The following files are the essential documentation: http://www.unlambda.com/lispm/explorer-docs/e3-docs/*.txt Those make up the System Software Design Notes, 2nd Rev. This explains the low level details of the Explorer system. It's not a coherent book, but a collection of documents on various topics. http://kappa.unlambda.com/lispm/explorer-docs/e3-docs/E2-proc-gen.pdf.bz2 This is the Explorer II Processor General Description. Just what it says. Not detailed enough for my liking, but it's what we've got. There are some odd-sized pages in this document, so beware if printing. CVS:e3/docs/ti-lispref/lispref-chapter-*.txt From the CVS repository, these are selected chapters from the Explorer Lisp Reference manual, relevant to the lower levels of the system. CVS:e3/docs/funcall-notes.txt Notes I have extracted from the above resources and from list discussions on function calling, which is our current major task (ie, implementing the function calling macroinsns CALL-*). kappa:/home/lispm/00TARBALLS/explorer-lispm-sources.tar.gz This is the tarball of sources to the Explorer System, the OS that ran on Explorers. It never had an official name, unlike Symbolics's Genera. I think its last name was 'Release 6' or the like. There are a couple of files in it that you should take with for reading: explorer-lispm-sources/ucode/*.lisp Particularly lroy-qcom.lisp but the others are important as well. You'll also want a copy of the current E3 sources, I recommend checking them out and pretty printing them from Emacs, then sticking them in a 3-ring binder. The sources aren't exactly beautiful, and they're a little hard to follow at times. Just keep in mind the stuff we're emulating and it'll make more sense. With that huge pile of dead trees you should be plenty busy for a long time. If you have a laptop I'd recommend leaving most everything in electronic form and reading them online. The only thing I would print out for long term use (other than selected Lispm source files) would be the SSDN2. This is a hefty document (it's all scanned pages) so you should probably take it to a local print shop and have them print it double sided, then bind it in separate sections (I cut it in two, the second book starting with chapter 12(?), "Closures"). In two or more sections you can get it spiral bound which is easier to use than comb binding.
Probably the most important thing is to read the sources with a copy of the SSDN2 at your side. Start at app.cc and work your way through the startup process. It may help to run e3 in gdb so you can step your way through it to see what it does. Now that the SSDN2 is checked in as LaTeX source in the CVS repo it's easier than ever to do this.
At the current point in the development process our major focus is on the function calling macroinstructions, and on implementing the macroinstruction set in general. Our process is fairly simple: we implement each instruction necessary in the boot process as they appear, starting with CALL-1-DEST-INDS. This of course means that the instructions are going to be implemented in a weird and haphazard fashion, but the idea is that our software is growing as we learn more about how the system works. Since we don't completely understand the low-level details of the microcode, nor do we have the sources to the microcode, we can't know in advance exactly how the macroinstructions are implemented. Thus development is a process of continual discovery. It is perhaps this particular reason why development progresses so slowly -- because it's far more interesting to learn how the system works than it is to program it.
Commit Policies: As with any collaborative development project using CVS there are always questions about what and when to commit, and how to deal with commit problems. Below is a message from the list regarding commit policy.
From: James A. Crippen Message-ID: <m3hemktf8y.fsf@kappa.unlambda.com> User-Agent: Gnus/5.0808 (Gnus v5.8.8) XEmacs/21.5 (beets) Subject: [LispM-Hackers] Commit Policy Date: 09 Apr 2002 19:16:29 -0800 JM brought up the question of commit policy with me. This is always an interesting issue, and the answer is usually vague. I've worked on both open-source and commercial projects using CVS, and have found a number of rules that help to maintain a happy environment for developers. Here's some basic commit policy rules: * DON'T commit things that won't compile. It's *extremely* frustrating to do a 'cvs update' and then suddenly find that some random part of the program won't compile, preventing you from working on your stuff until you can dike out the breakage or revert the files to older, compilable versions. * DON'T commit binaries (eg, object files, bands, coredumps, etc). Why? Because the CVS repo isn't set up to handle them automatically. If you do really want to add a binary somewhere then please discuss it on the list beforehand. We will decide whether it really needs to be in the repo, and if so where, and how to correctly handle binary files with CVS (which requires special keyword handling). * DON'T commit output. Output belongs on the list, on the webpage, or on personal pages. Not in the repository. Same with debugging dumps. * DON'T commit platform specific things without non-specific handling. Thus, if you're writing code to support FooOS don't commit changes to code without properly conditionalizing the support so that it doesn't show up on every platform. Just because you think 64-bit support would be n34t on the Alpha doesn't mean that people using Vaxen will like it integrated in their build, even if GCC can magically make it work. These are things to think about before you commit something. Does it compile? Is it platform specific with appropriate conditionalization? Is it text-only? Etc... As for when you *should* commit, please commit when you can fulfill the above restrictions. Here's some rules regarding how commits should be done. * Commit regularly. Even if the changes you've made are small, try to commit them. They may not seem important to you but someone else may be encountering a bug that is fixed by your changes. If you commit often you will also avoid development out of sync with the project. Your repo copy will tend to stay in sync better if you keep your commits up to date. * Commit in semantically related chunks. Don't commit the changes you've made in the last week all with one commit. Try to break it up into related chunks and commit each separately. Thus changes to memory management code should be committed separately from the graphics code unless they're obviously related. * Use descriptive commit logs, but keep them short. Don't use the commit logs as a forum for describing your woes and ideas. The commit logs are just a record for why commits are made, and what is included in each commit. If you find yourself writing more than 25 lines of log text then you should take the details to the list as a followup post to your commit log mail message. But don't just use one-liner logs like "Fixes bug #422369." That's useful if you happen to be looking at the bug database (which we don't have yet, but will). But most people do not read commit logs while looking at the bug database. If the bug is simple enough or has a 'name' then describe or name it, *and* include the bug tracking number. * Try not to spam commits. If you've got five thousand and one things you want to commit, please don't commit them all at once if you can. Commit one chunk at a time, then leave the repo alone for a while before you commit the next thing. Some people work in a very distracted fashion, first hacking one thing, then another. They build up a big pile of unrelated changes and then want to commit them all at once. Instead they should commit one thing at a time, then wait for the other developers to evaluate the changes before committing the next set of changes. This keeps other developers from being confused by changes that occur all over the source tree in seemingly random ways, that might introduce new bugs.