;;;
;;; 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. JUMP instructions do not yet support reading or writing I-Memory, or an M-Source, but are otherwise 
complete. ALU operations do not support writing to Tag memory, and not all of the output-bus controls are even understood 
let alone implemented, but most of the structure is in place there as well. 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.


There is as yet no system definition for Nevermore, either defsystem or asdf, nor does Nevermore establish its own package. 
Presently, the system consists of a number of source files, to be compiled and loaded in this order: dise1uc.lisp, 
raven-variables.lisp, raven-functional.lisp, raven-memory.lisp, raven-microengine.lisp.

To start the simulator, issue the following calls:

    (load-prom-memory #p"/path/to/prom_combined")
    (microengine-initialize)

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

    (microengine-step)

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:

    (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, which 
currently fail.

Once the system passes its self-tests, it will almost certainly start looking to the NuBus interface for memory 
and SIB boards.


;;; EOF
