;;;
;;; 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 and some of the related peripheral hardware (NuPI board
for hard disk support, System Interface Board for partial screen and keyboard
emulation, Memory boards etc.) It is hoped that it will one day be capable of
booting GDOS (the diagnostic operating system).
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, the basic microengine appears to be mostly complete, and
development is concentrating on trying things, seeing what breaks, and figuring
out how to fix them. The Lisp world is booting and provides some interaction
(the keyboard is a little messed up, I can't see the modeline on my computer due
to having a 1280x800 screen, there's no mouse emulation, and so on). GDOS halts
with the message "*** ERROR WHILE OPENNING /dev/monitor FILE ***" and the
number 00000757.
There is now an X interface which is in some ways spectacularly inefficient,
but still a nice thing to have. To set it up, you run (nevermore::start-x) and
(nevermore::init-window). To close it down, run (nevermore::finish-x). While the
X interface is running, the system will not check for keyboard busy-loops (so
that the X interface can do its thing instead).
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.
Note that this only works for output from the STBM, PRIM (MENU), EXPT, and GDOS.
Text output from Lisp uses a different font, and thus doesn't work with the
recognizer.
Another new feature is the addition of a streamlined method for stuffing
keystrokes into the receive buffer. To set it up, do
(nevermore::sib-init-keypress-stuffer). Then, when you run into a keyboard
busy-loop, do (nevermore::sib-keyboard-stuff-keypress <character>), substituting
an appropriate character (digit, upper-case character, #\Tab, or #\Return. This
will put a down-and-up key transition pair into the receive buffer on the System
Interface Board.
Before you start, you may want to edit the three defvars at the top of
nupi-nubus.lisp to reflect the location of your disk images. Yes, you need three
disk images now; the same ones that Meroko uses should suffice.
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 and then
load them:
(setf *rom-file-path* #p"/path/to/E1_eproms/")
(load-romfiles)
And set up your hard drive image files:
(setf *nupi-scsi0-0-disk-file* #p"/path/to/explorerI_diskDumps/explScsi0Dr0.dsk")
(setf *nupi-scsi0-1-disk-file* #p"/path/to/explorerI_diskDumps/explScsi0Dr1.dsk")
(setf *nupi-scsi2-0-disk-file* #p"/path/to/explorerI_diskDumps/explScsi2.dsk")
Next, if you aren't using the CLX interface, initialize the character recognizer
(so you can see what's going on later) and the keypress stuffer (so you can
control what's going on later):
(sib-init-character-recognizer)
(sib-init-keypress-stuffer)
At this point it is time to initialize the X interface if you want it (if you
don't, the old-style keyboard busy-loop break and text screenshot should still
work):
(start-x)
(init-window)
(when you are done with the X interface, call (nevermore::finish-x).)
From here on out, we want to be in the raven package:
(in-package :raven)
Next, reset the microengine to the start state.
(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:
(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 -1) will run the microengine until either
Something Goes Wrong or it hits location 40 (which will happen during the normal
boot sequence). If it does stop at location 40, just (microengine-step) past it
and then use microengine-run-to again.
You can get a graphical representation of the contents of the SIB framebuffer by
issuing the call:
(nevermore::sib-write-screenshot #p"screenshot.bmp")
You can get a textual representation of the contents of the SIB framebuffer (at
east until the Lisp world boots) by issuing the call:
(nevermore::sib-text-screenshot)
If you are in the host debugger, and wish to return to your REPL, execute
(microengine-force-halt) and continue. At present, microengine-force-halt
operates by modifying the next fetched microinstruction to enable the HALT bit,
which will cause microengine-run-to to stop. In the future, this will likely be
changed to involve a separate flag, so as not to interfere with parity checking
and the like.
The emulator can detect when the system is waiting for a keypress within the
STBM, startup menu, and EXPT load. When this occurs and the X interface is not
active, it will break to the debugger from within an I/O handler. At this point
it can be useful to look at a text screenshot (see above) and possibly stuff a
keypress into the receive buffer. The keyboard stuffer is quite limited, and
will only accept digits, upper-case characters, #\Tab, and #\Return key.
(nevermore::sib-keyboard-stuff-keypress #\A)
This should be sufficient to get you started. Now you too can see Nevermore fail
the EXPT tests. Enjoy!
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.
Thanks to Steve Krueger and Paul Fuqua for answering some questions about
various features of the Raven CPU, and to the old unlambda lispm-hackers list
members for getting me into explorer emulation in the first place.
Thanks to... umm... someone for supplying a dump of the last rom in the Raven
set (where'd that email go?).
Thanks to Daniel Seagraves and Brad Parker for their continuing support.
EXPT test status, 2005/Oct/15:
+---+------------------------------------+------+
| 0 | ALU/OBUS | pass |
| 1 | BYTE/BARREL SHIFTER | pass |
| 2 | I-MEMORY | FAIL |
| 3 | PUSHDOWN LIST (PDL) | pass |
| 4 | M-MEMORY | pass |
| 5 | A-MEMORY | pass |
| 6 | MICRO-PROGRAM COUNTER STACK (UPCS) | pass |
| 7 | TAG CLASSIFIER | pass | (somewhat spammy)
| 8 | UNMAPPED ACCESSING | FAIL | (this is new)
| 9 | VMA | pass |
| A | GCVF LOGIC | pass |
| B | DISPATCH | pass |
| C | MACROCODE DECODE | pass |
| D | EVENT POSTING | FAIL |
| E | INSTRUCTION STREAM HARDWARE | pass |
| F | MEMORY CYCLE ABORT | FAIL |
+---+------------------------------------+------+
;;; EOF