diff --git a/README.md b/README.md
index 539ec64..6f16ebf 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,4 @@
-Aiie!
-=====
+# Aiie!
Aiie! is an Apple //e emulator, written ground-up for the Teensy
3.6.
@@ -8,19 +7,17 @@ The name comes from a game I used to play on the Apple //e back
around 1986 - Ali Baba and the Forty Thieves, published by Quality
Software in 1981.
-http://crpgaddict.blogspot.com/2013/07/game-103-ali-baba-and-forty-thieves-1981.html
+[http://crpgaddict.blogspot.com/2013/07/game-103-ali-baba-and-forty-thieves-1981.html](http://crpgaddict.blogspot.com/2013/07/game-103-ali-baba-and-forty-thieves-1981.html)
When characters in the game did damage to each other, they exclaimed
something like "HAH! JUST A SCRATCH!" or "AAARGH!" or "OH MA, I THINK
ITS MY TIME" [sic]. One of these exclamations was "AIIYEEEEE!!"
-Build log:
-----------
+## Build log:
- https://hackaday.io/project/19925-aiie-an-embedded-apple-e-emulator
+ [https://hackaday.io/project/19925-aiie-an-embedded-apple-e-emulator](https://hackaday.io/project/19925-aiie-an-embedded-apple-e-emulator)
-Getting the ROMs
-================
+# Getting the ROMs
As with many emulators, you have to go get the ROMs yourself. I've got
the ROMs that I dumped out of my Apple //e. You can probably get yours
@@ -44,8 +41,7 @@ The MD5 sums of those files are:
From those, the appropriate headers will be automatically generated by
"make roms" (or any other target that relies on the ROMs).
-Building (for the Teensy)
-=========================
+# Building (for the Teensy)
The directory 'teensy' contains 'teensy.ino' - the Arduino development
environment project file. You'll need to open that up and compile from
@@ -73,8 +69,7 @@ I compile this with optimization set to "Faster" for the Teensy 3.6 at
better video performance, all the way up to 240MHz, but still not
perfect. Do as you see fit :)
-Environment and Libraries
--------------------------
+## Environment and Libraries
I built this with arduino 1.8.5 and TeensyDuino 1.40.
@@ -85,7 +80,7 @@ SPI; EEPROM; Time; Keypad.
I'm also using these libraries that don't come with TeensyDuino:
-### SdFat ###
+### SdFat
SD card support - accelerated for the Teensy, and with long filename support.
@@ -95,8 +90,7 @@ SD card support - accelerated for the Teensy, and with long filename support.
-Running (on the Teensy)
-=======================
+# Running (on the Teensy)
The reset/menu button brings up a BIOS menu:
@@ -117,27 +111,23 @@ The reset/menu button brings up a BIOS menu:
Prioritize Display/Audio
-Reset
------
+## Reset
This is the same as control-reset on the actual hardware. If you
want to execute the Apple //e self-test, then hold down the two
joystick buttons; hit the reset/menu key; and select "Reset".
-Cold Reboot
------------
+## Cold Reboot
This resets much of the hardware to a default state and forces a
reboot. (You can get the self-test using this, too.)
-Drop to Monitor
----------------
+## Drop to Monitor
"Drop to Monitor" tries fairly hard to get you back to a monitor
prompt. Useful for debugging, probably not for much else.
-Display
--------
+## Display
"Display" has four values, and they're only really implemented for
text and hi-res modes (not for lo-res modes). To describe them, I have
@@ -164,8 +154,7 @@ between them.
The last mode is "Monochrome" which looks like the original "Monitor
II", a black-and-green display.
-Debug
------
+## Debug
This has several settings:
@@ -180,16 +169,14 @@ This has several settings:
... these are all fairly self-explanatory.
-Insert/Eject Disk1/2 HD1/2
---------------------------
+## Insert/Eject Disk1/2 HD1/2
Fairly self-explanatory. Disks may be .dsk, .po, or .nib images
(although .nib images aren't very heavily tested, particularly for
write support). Hard drives are raw 32MB files, whose filenames must
end in .img.
-Suspend and Restore
--------------------
+## Suspend and Restore
The Teensy can be fully suspended and restored - including what disks
are inserted. It's a full VM hibernation. It currently writes to a
@@ -198,8 +185,7 @@ to be able to select from multiple suspend/restore files
eventually. It wouldn't be terribly hard; it's just that the BIOS
interface is very limited.)
-Prioritize Display/Audio
-------------------------
+## Prioritize Display/Audio
Any Apple emulator needs real-time support for audio. The hardware is
very direct: when a particular memory location ($C030) is read from or
@@ -239,27 +225,40 @@ the CPU that also means the audio will be very messed up.
So this BIOS option lets you choose whether you want good audio or good video.
-Building (on a Mac)
-===================
+# Building (on a Mac)
While this isn't the purpose of the emulator, it is functional, and is
my first test target for most of the work. With MacOS 10.11.6 and
Homebrew, you can build and run it like this:
+```
$ make
$ ./aiie-sdl /path/to/disk.dsk
+```
As the name implies, this requires that SDL is installed and in
/usr/local/lib. I've done that with Homebrew like this
+```
$ brew install sdl2
+```
-Mockingboard
-============
+# Building (on Linux)
+
+I've been experimenting with Aiie running under a handmade OS on a Raspberry Pi Zero W; the hardware is decent, and cheap. I just don't want Linux in the way. So I built JOSS (see [https://hackaday.io/project/19925-aiie-an-embedded-apple-e-emulator/log/87286-entry-18-pi-zero-w-and-joss](my Hackaday page about JOSS)).
+
+Well, performance under JOSS is poor, so I built a Linux framebuffer wrapper for Aiie so that I can do performance testing on the Zero W, directly between JOSS and Linux.
+
+```
+$ make linuxfb
+$ ./linuxfb
+```
+
+# Mockingboard
Mockingboard support is slowly taking shape, based on the schematic in
the Apple II Documentation Project:
@@ -272,8 +271,7 @@ and run the speaker at full tilt; but maybe that's primarily a
function of the throughput to the display, and adding the Mockingboard
support won't require further sacrifice...
-VM
-==
+# VM
The virtual machine architecture is broken in half - the virtual and
physical pieces. There's the root VM object (vm.h), which ties
@@ -306,34 +304,36 @@ some sort of Prefs class:
-CPU
-===
+# CPU
-The CPU is a 65C02, not quite complete; it supports all of the 65C02
-documented opcodes but not the undocumented ones here:
+The CPU is a full and complete 65C02. It supports all of the 65C02
+documented and undocumented opcodes:
http://www.oxyron.de/html/opcodes02.html
-The timing of the CPU is also not quite correct. It's close, but
+The timing of the CPU is close to, but not quite, correct. It
doesn't count cycles due to page boundary crossings during branch
-instructions. (See the "cycle count footnotes" in cpu.cpp.)
+instructions, for example. (See the "cycle count footnotes" in cpu.cpp.)
-The CPU passes the 6502 functional test from here:
+The CPU passes all of the the 6502 tests from here, including the undocumented ADC and SBC handling of Decimal mode and the overflow flag:
https://github.com/Klaus2m5/6502_65C02_functional_tests
-... which is included in binary form in the test harness (see the .h
-files in util/ for notes).
-testharness.basic should reach "test number 240", hang for a while,
-and then exit.
+Doing a
+
+```
+$ make test
+```
+
+will build the test harness and execute the three tests that encompass all others. (There are more tests in the **tests/** directory - only 3 of them are truly unique.) Two of the tests should emit
+
+ All tests successful!
+
+while the third says
+
+ Test complete. Result: passed
+
-testharness.verbose should show that it gets through 43 tests, test
-240, and then loops repeatedly for a while (exiting at a somewhat
-arbitrary point).
-testharness.extended currently fails (hanging at 0x733) because I
-haven't implemented the undocumented opcodes. It should get to address
-0x24a8 and hang. Some day I'll finish implementing all of the
-undocumented opcodes :)