;;;
;;; 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 and the halt bit are presently ignored. M-Bus functional locations are being filled in as necessary.

The system currently conses horribly, mainly due to the operation of the disassembler and the 32-bit and wider integer operations. Once the micro-engine and supporting structure is complete and known to be reasonably well understood it is anticipated that a new simulator may be constructed in C.


Before you compile the system, open up romload.lisp and fix the pathnames to all of the romfiles.

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)

To start the simulator, issue the following calls:

    (load-romfiles)
    (microengine-initialize)

At this point it it -strongly- recommended that you disable the memory board with:

    (setf *mem-nubus-slot* 17)

This works by moving it out of the valid range for slot space. Without disabling the memory board, I get runtimes of six and a half hours. With, I get runtimes of 20 minutes. You have been warned.

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 0) will run the microengine until it dies (currently when it tries to display fault code #x8A on the LEDs). This will not work unless you have stepped at least once. After this point, you can dump the contents of the framebuffer with:

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


;;; EOF
