;;;
;;; 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
