;;;
;;; README for Project Nevermore
;;;
;;; Assorted notes on the purpose, usage, maintenance, history, and future of the Nevermore system.
;;;


The Nevermore system is, at present, an experimental simulator for the Explorer I (Raven) microcoded CPU. It is hoped that sufficient progress will be made that some other pieces of Explorer hardware can be simulated as well.

The original core of this project was the result of my desire to have a working disassembler for the Raven microcode. After my second attempt in C, I realized that the best output format would be as close to the original input format as I could manage. The third attempt was again in C, and ran afoul of the list and symbol manipulation required when putting together a prototype for such a disassembler. The fourth attempt was written over the course of Nov. 7 through 9, 2003 in CMUCL. This was successful enough that over the Sunday and following Monday I was looking through the disassembly of the boot PROM and figuring out how certain parts of the code functioned.

On the Tuesday of that next week, I decided that the only way to answer some questions as to what parts of the code was doing was to write a simulator, so I laid out the first versions of microengine-step and friends. I am writing this on Saturday the 15th of November, 2003, and progress has been rapid over the past week.


The boot PROM starts off with some self-test code for the CPU, which excersizes most or all of the on-board hardware and memories, which has been very useful since the code is quite unambiguous as to what behavior it expects from the system.

As things stand now, most of the basic structure of the ALU, BYTE, and JUMP instructions is functional. The ALU operations are being filled in as they are encountered. BYTE instructions do not yet support the rotation direction flag, but are otherwise complete. Not all conditions or ALU operations are simulated, and parity checking is presently ignored. M-Bus functional locations are being filled in as necessary.


There has been a recent reorganization involving moving most of the Raven-specific code to a new package. There are still a few places where further cleanup is needed (mostly around the nubus implementation). Note that the microengine control is now in the :raven package, while the ROM loader and screenshot functions are still in :nevermore.

A new feature is the addition of the ability to dump a screenshot as text. After loading the ROMs, do (nevermore::sib-init-character-recognizer). Then, when you run into a keyboard busy-loop, do (nevermore::sib-text-screenshot). This will print a 126 by 61 character representation of the contents of the framebuffer.

Before you start, edit nupi-handle-command-drive-read in nupi-nubus.lisp to reflect the location of your disk image. If you can't start any of the diagnostics, you will probably have to edit the image file with a hex editor to set the diagnostic flag on a few partitions.

The instructions below need updating.


The system now has an ASDF definition for :nevermore in nevermore.asd. The usual deal applies:

    (load "nevermore.asd")
    (asdf:operate 'asdf:load-op :nevermore)

At this point, switch to the nevermore package:

    (in-package :nevermore)

Now set the value of *rom-file-path* to the location of your ROM files:

    (setf *rom-file-path* #p"/home/nyef/src/lisp/aek/E1_eproms/")

To start the simulator, issue the following calls:

    (load-romfiles)
    (microengine-initialize)

To have the simulator execute a single microinstruction, call microengine-step with no arguments:

    (microengine-step)

The system should respond by printing:

    L-0 Inhibited.
    L-0 ((M-0 TEST-SYNCH) SETZ)

If it doesn't, something went wrong.

To have the simulator execute a number of instructions in turn, call microengine-run-to with an argument of the micro-pc to stop at (it will also stop at locations 18 and 40):

    (microengine-run-to 85)

The function microengine-step will output the disassembly of the instruction interpreted, and the disassembly of the next instruction to interpret (after applying any OA-register effects). The return value is the address of the next instruction to be read from I-Memory (either the PROM or the real memory space).

The invocation (microengine-run-to 171) will run the microengine until shortly before the start of M-Memory tests.

The invocation (microengine-run-to 395) will run the microengine until the start of the multiply/divide tests.

The invocation (microengine-run-to 40) will run the microengine until it dies (currently when it tries to display fault code #x8A on the LEDs). After this point, you can dump the contents of the framebuffer with:

    (sib-write-screenshot #p"screenshot.bmp")


Keyboard keycodes to remember: 0x24 is '1', 0x50 is 'A', 0x5b is Enter, 0x68 is 'Z'. Keycodes are assigned on a qwerty layout, and increase to the right. The high bit of the keycode byte indicates a down transition on the key if it is set and an up transition if it is clear.


Thanks to the following people of freenode #lisp for helping me make nevermore faster when I was seriously thinking about switching to C for speed:

    Krystof, rtoy_, mucit, chandler, antifuchs, frodef, bdowning, rahul, Xach.

;;; EOF
