Add documentation of the process for emulating an A2 hard drive.

[apple2] / docs / emulating-a2hssc.txt

  EMULATING THE APPLE HIGH SPEED SCSI CARD: AN EXERCISE IN DIGITAL ARCHAEOLOGY

                                by James Hammons

    ~~==< Brought to you in Glorious 80-Column Monospace-o-Vision(TM) >==~~


Motivations
-----------

While reading 4am's Twitter feed one day, he talked about his "Pitch Dark" hard 
drive image, which looked incredibly cool and like something that I would very 
much be interested in.  But in reading about it, I came across a seemingly 
throwaway line about how all decent emulators can run them, which, sadly, 
Apple2 could not at the time.  And so, in order to save Apple2 from indecency 
(and because I wanted to see if I could get 4am's "Pitch Dark" to work because 
it looked cool and interesting), I set about for finding some documentation on 
how hard drives interfaced to Apple IIs--and ran into a complete dearth of 
information.  There were little things sprinkled around here and there, but 
nothing of any deep, satisfying, technical significance.


In Order To Run A Hard Drive Image, You Must First Create The Universe
----------------------------------------------------------------------

While it's a nice bit of hyperbole, it's not exactly true that you have to 
first create the Universe, as fortunately, that part has largely been taken 
care of.  However, you still have to figure out how to emulate it if you are 
keen on running a hard drive image on your emulator of choice.  And in so 
doing, you have to figure what the requirements are; what the minimal pieces 
are that are required to have a functioning hard drive system; you also have to 
figure out how that system talks to the emulated computer.  And that all 
requires information.  I wasn't asking for much, but something along the lines 
of Jim Sather's "Understanding The Apple IIe" for hard drives would have been a 
nice thing to have.


The Next Part, In Which Nice Things To Have Are Not Forthcoming
---------------------------------------------------------------

Unfortunately, Jim Sather, and nobody else as far as I can tell, ever wrote 
such a document, and so I did what any lazy programmer would do: I took a look 
at some other project's source--in this case, AppleWin's source.  I didn't 
really *want* to look at it, having looked at it before and recoiled in horror 
at the sight, but, my search-fu apparently being not up to the task of finding 
relevant information drove me to it.  And looking at it didn't really provide 
any illumination; to me it looked like some kind of hacky thing and I wasn't 
interested in that kind of approach at all--so I abandoned the idea.  As I dug 
a little deeper into the minute literature that existed as such on the subject, 
I learned that pretty much any time you wanted to hook up a hard drive to your 
Apple II, you had to use an interface card, and typically that meant some kind 
of SCSI card.  And looking here, there was no shortage of SCSI cards that you 
could use to hook up your hard drive therewith.

So, that being a promising looking path to pursue on the road to this 
particular perdition, the question then became, which one should I choose?  At 
first I thought the RAMFast card would fit the bill as it seemed to be very 
popular, but there was literally no technical infomation on the thing.  The 
Apple SCSI card looked promising, but then I saw that it "ghosted" a slot, 
meaning that it would have to occupy two consecutive slots in order to work and 
I didn't much care for that.  And so, after looking at, and rejecting, card 
after card for pretty much the same reason, I settled on the Apple High Speed 
SCSI card for a few reasons--one, it was purportedly fast; two, it worked on 
the Apple IIe (as well as the IIgs, but I didn't really care that much about 
that to be honest); three, it had a users manual that wasn't completely devoid 
of technical information; four, it had a schematic; and five, it had a firmware 
image.  This looked like a promising start--how hard could it be to make this 
work?


Things Aren't Exactly Hard, But They Aren't Exactly Soft Either
---------------------------------------------------------------

One of the necessary things that I didn't have out of all of that was good 
information on how the thing worked.  I knew that it was a SCSI card, and I 
knew that it talked to the SCSI bus using an NCR 53C80 chip, but I had no idea 
exactly how.  But I did have something that *did* know how to talk to it: the 
firmware for the card.

Now when you take a look at the firmware, the first thing you notice is that 
it's 32K in size--which is *much* larger than the typical 256 bytes that you 
encounter when looking at Apple II card drivers.  It also happens to be quite a 
bit larger than the 2K "bonus" space that Apple II cards have available to them 
in the $C800 to $CFFF address space.  So what gives?

Fortunately for me, Apple2 has a built-in disassembler (which will probably 
stay in for all time, as it turns out to be a very useful thing to have on 
hand), and so I split that out into a stand-alone command line driven program, 
called d65c02, in order to be able to disassemble such things as device driver 
firmware blobs.  It isn't fancy, it doesn't do any analysis on what is code and 
what is data, but it gets the job done in turning incomprehensible binary 
gibberish (except to certain mad geniuses who will go heretofore unnamed) into 
human readable ASCII gibberish.  Thus I used said tool to disassemble the 
firmware blob.

Pulling up the results in my text editor, I could see that at least the front 
of the listing looked like it could plausibly be code that would go into the 
usual 256 byte card slot address space of $Cx00 to $CxFF, where x ranges from 1 
to 7 depending on the slot number.  Looking further, I could see this first 256 
bytes of code was repeated three times, meaning that this was a good candidate 
for the slot device code.  I could also see that it was written as relocatable 
code, and it contained this little tidbit:

001B: A9 60     LDA  #$60     ; Stuff an RTS into RAM somewhere
001D: 8D F8 07  STA  $07F8
0020: 20 F8 07  JSR  $07F8    ; Jump there and return in order to get evidence
                              ; of where in memory we did it from
0023: BA        TSX           ; Retrieve the stack pointer
0024: BD 00 01  LDA  $0100,X  ; Get the hi byte of the address we just pushed on
                              ; the stack in order to come back here
0027: 8D F8 07  STA  $07F8    ; & save it for later perusal

which meant that it was an excellent candidate for the slot device code.  But 
why should that be?


A Short Digression Into Why Slot Code Must Be Relocatable
---------------------------------------------------------

Slot code must be relocatable because such a card may be installed into any 
given slot in an Apple II--which means its code will show up anywhere from 
$C100 to $C700 (it always shows up on a page boundary).  By virtue of this, it 
also means that the I/O address for the card will also show up in the 
corresponding $C090 to $C0F0 address range (it always shows up on a 16-byte 
boundary).  And so, because of this, you have to write your slot code in such a 
way that it will work regardless of which slot it's installed in, which means 
the code must be relocatable--which ultimately means you can't use any JMP 
instructions to addresses in your driver, and you can't use absolute addressing 
to refer to stuff in the slot address space.

So, using the above code, a clever coder can figure out what slot their code is 
executing in and they can then use that knowledge to figure out which is the 
proper I/O range to use for the card.  All this being necessary in order to 
make a seamless experience for the end user of the card.


The Next Part, In Which 32K Is Still Larger Than 256
----------------------------------------------------

So, in looking at the code that comes after the Code Which Looks Like It 
Belongs In Slot Memory (which makes the wonderful acronym CWLLIBISM), I noticed 
that it seemed to be organized in 1K chunks.  And further persual of said 
chunks made it seem very likely that they resided in the $CC00 to $CFFF memory 
space.  However, the "extra" memory space given to cards to use starts 1K 
earlier--at $C800.  What could this mean?

Well, in looking at the schematic for the card, one not only finds the 32K ROM 
chip, but also an 8K static RAM.  Which means that it's very likely that the 
address space from $C800 to $CBFF is mapped to that 8K static RAM.  But 8K is 
larger than 1K; how does that work?

As it turns out, it's bank switched, but I didn't know it at the time--we'll 
get to that eventually.  In the meantime, with further perusal of the code (the 
code gets perused quite a bit), it seems very likely that the 1K address range 
from $C800 to $CBFF is said RAM as that range is written to by the 1K code 
chunks quite frequently.

Finding that the code in the firmware is divvied up into 1K chunks would seem 
to imply that it's bank switched into the $CC00 to $CFFF range.  And in looking 
at the CWLLIBISM, we see the following:

005C: A9 0B     LDA  #$0B     ; Get 11 in the accumulator
005E: AE 08 C8  LDX  $C808    ; Get offset to proper I/O space in X
0061: 5A        PHY           ; Save Y on the stack for later
0062: A8        TAY           ; Copy the accumulator to Y
0063: 29 1F     AND  #$1F     ; Strip off the upper three bits
0065: 9D 6E C0  STA  $C06E,X  ; & write to card I/O location $E

which implies it heavily.  Taking the number put into the accumulator and then 
masking out the lower 5 bits creates a range that goes from 0 to 31, which is 
32 distinct values, which corresponds to 32 1K chunks of code.

The above code, which is part of the initialization of the card, heavily 
implies that it's selecting a 1K chunk of code from bank 11 (counting from 
zero, naturally) to put into the $CC00 to $CFFF address range.  And so we get 
to(*) look there for a start.

(*) While changing 'have to' to 'get to' can make life awesome in many ways, 
this is far from a universal truth.  'Getting to' have one's arm amputated is 
never, ever awesome


The Next Part, In Which We Sadly Bid Adeiu To CWLLIBISM
-------------------------------------------------------

But before we do that, in order to understand what's going on in those wicked 
little 1K chunks of code, we should first take a closer look at CWLLIBISM.  So 
let's jump in:

0000: A2 20     LDX  #$20     ; The bytes after the LDX # identify this card as
0002: A2 00     LDX  #$00     ; being capable of SmartPort calls, and the $82 at
0004: A2 03     LDX  #$03     ; $FB further identifies it as a SCSI card ($2)
0006: A2 00     LDX  #$00     ; that supports extended calls ($8).

The way that I was able to find out that this seemingly useless bit of code was 
a way of identifying SmartPort capable cards was in the serendipitous find of 
the "Technical Manual for the Apple SCSI Card"(*), which, while helpful in some 
ways, was almost completely useless in trying to figure out the what the card 
I/O addresses did.

(*) No relation to the Apple High Speed SCSI Card

0008: 2C 58 FF  BIT  $FF58    ; Check byte in ROM (usually, an RTS lives here)
000B: 70 05     BVS  $0012    ; Bit 6 set?  >> $12 (which means, this branch
                              ; will be taken...)

This little tidbit checks a ROM location that usually carries an RTS (at least 
it does in the Apple IIe), which is $60.  Which means that the following BVS 
will always be taken and skip over the following:

000D: 38        SEC           ; ProDOS entry point
000E: B0 01     BCS  $0011    ; Branch over the following CLC
0010: 18        CLC           ; SmartPort DISPATCH
0011: B8        CLV           ; Signal we're doing normal I/O, not init code

So this clever little bit here, according to the "Technical Manual for the 
Apple SCSI Card", sets some flags so that later on in the firmware, it can 
discern whether it's being called from ProDOS (in which the carry flag will be 
set) or if it's a SmartPort call (in which the carry flag will be clear).  
Either way, the overflow flag is cleared to let the firmware know that this is 
a request to talk to the drive, and not initialization.  Initialization skips 
over this code and ends up here:

0012: D8        CLD           ; Clear the decimal flag, to prevent bad math
0013: 08        PHP           ; Save the carry & overflow flags for later
0014: 78        SEI           ; Turn IRQs off
0015: AD FF CF  LDA  $CFFF    ; Turn INTC8ROM off (puts card in $C800-CFFF)
0018: 8D 00 CC  STA  $CC00    ; ???

This bit of code is a bit of housekeeping; making sure the decimal flag isn't 
set so that ADC & SBC both work as expected, saving the flags register so that 
the firmware code later can determine whether it's an initialization call or a 
regular I/O call, making sure that IRQs don't happen while in the firmware 
code, and turning on the "extra" addresses in the $C800 to $CFFF range.

The store to $CC00 is mysterious, as it's a ROM location and stores to ROM 
locations are usually void and of null effect.  This likely means that it's 
some kind of soft-switch that controls something in card, but exactly what 
would require a few things that I don't have, namely: the contents of the two 
PALs on the card (which sit between the address lines of the slot and the rest 
of the card), and a description of what the ports on the Sandwich II do (the 
chip that sits between the Apple IIe proper and the NCR 53C80).  So, moving 
right along:

001B: A9 60     LDA  #$60     ; See where we're executing from
001D: 8D F8 07  STA  $07F8
0020: 20 F8 07  JSR  $07F8
0023: BA        TSX
0024: BD 00 01  LDA  $0100,X  ; Get the address we just pushed on the stack
0027: 8D F8 07  STA  $07F8    ; Save it

We've seen this already, this is the code that determines which slot it's 
sitting in.  Say, for example, that it's sitting in slot 7; the byte that it 
will retrieve from the stack will be $C7 (for the sake of completeness, the lo 
byte will be $22--as to why, this is left as an exercise for the reader).  In 
order to turn that into something that it can use to hit the proper slot I/O 
addresses, it does the following:

002A: 29 0F     AND  #$0F     ; Get the lo nybble
002C: 0A        ASL  A        ; Multiply it x16
002D: 0A        ASL  A
002E: 0A        ASL  A
002F: 0A        ASL  A
0030: 18        CLC
0031: 69 20     ADC  #$20     ; Add $20 to it for some reason
0033: AA        TAX           ; & stick in the X register

The important part of the $C7 hi byte of the address we found through 
cleverness and trickery is the slot number, which will always fall in the lower 
4 bits.  And, in order to be useful to find the correct slot I/O address range, 
that slot number needs to be multiplied by 16, as each of the slot I/O address 
ranges cover exactly sixteen bytes.  Note that masking off the bottom 4 bits, 
as is done with the AND #$0F instruction, is unnecessary as the four ASL A 
instructions after it will necessarily shift the top four bits out of the 
picture.

The one thing that stands out as not typical of this kind of device driver code 
is the adding of $20 to the index.  Typically, writers of this kind of I/O code 
will use $C080 to $C08F (plus the contents of the X register to reach the 
correct slot I/O range) as the base address for slot I/O, but, for some reason, 
the writers of this card's firmware chose to use $C060 to $C06F, thus 
necessitating the addition of $20 to the value in the X register to reach the 
correct range for slot I/O.

0034: A9 00     LDA  #$00     ;
0036: 9D 6E C0  STA  $C06E,X  ; Select bank #0 (register $E, lower 5 bits)
0039: A9 0F     LDA  #$0F
003B: 9D 6F C0  STA  $C06F,X  ; Store a $F in register $F
003E: 8E 08 C8  STX  $C808    ; Put slot # at $C808 (banked RAM in $C800-CBFF)
0041: 9C 09 C8  STZ  $C809    ; Put zero at $C809
0044: 9C F2 C8  STZ  $C8F2    ; & $C8F2

One thing I forgot to mention is that the Apple High Speed SCSI card is only 
usable by enhanced Apple IIe and IIgs machines, and that's because it relies on 
instructions only found in the 65C02 like STZ and PHY; a regular 6502 will not 
even remotely do the same things that those instructions do on the 65C02--so 
they're right out.

At any rate, the above code does some writing to the slot I/O address range and 
sets up some values in the card's static RAM, including saving the contents of 
the X register for later.

0047: A2 22     LDX  #$22     ; Transfer 35 bytes from ZP ($40) to $C82D
0049: B5 40     LDA  $40,X
004B: 9D 2D C8  STA  $C82D,X
004E: CA        DEX
004F: 10 F8     BPL  $0049

This bit of code transfers 35 bytes in page zero RAM to the card's static RAM, 
presumably to restore them later.

0051: AD F8 07  LDA  $07F8    ; Get original $Cx byte again
0054: 8D 01 C8  STA  $C801    ; Put it in $C801
0057: A9 61     LDA  #$61     ;
0059: 8D 00 C8  STA  $C800    ; Put $61 in $C800 (= $Cx61)
005C: A9 0B     LDA  #$0B
005E: AE 08 C8  LDX  $C808    ; Get X from $C808

This little bit of code sets up for the code that comes below; it sets up 
locations $C800-1 as a location for an indirect jump that seems to happen a lot 
in the 1K chunks that come later.  The address it sets up as the jump target is 
the code that comes next:

0061: 5A        PHY           ; Save Y (follow on bank, passed in by caller)
0062: A8        TAY           ; Save A register
0063: 29 1F     AND  #$1F     ; Mask off the lower 5 bits
0065: 9D 6E C0  STA  $C06E,X  ; First time, select bank 11:0 (I/O register $E)
0068: 98        TYA           ; Restore the A register
0069: 29 E0     AND  #$E0     ; Mask off the upper 3 bits
006B: 4A        LSR  A        ; & shift them down
006C: 4A        LSR  A
006D: 4A        LSR  A
006E: 4A        LSR  A
006F: A8        TAY           ; Use as an index into a table (Y x 2)

What this does is save the Y register on the stack, then separates the 
accumulator into a upper 3-bit part and a lower 5-bit part.  The lower 5 bits 
go into I/O slot register $E, which presumably selects which 1K chunk of code 
will appear in the $CC00 to $CFFF address range while the upper 3 bits are used 
as an index into a table that appears near the end of each 1K chunk:

0070: B9 F0 CF  LDA  $CFF0,Y  ; Get address of current 1K bank
0073: 85 54     STA  $54      ; & stuff it into $54/55
0075: B9 F1 CF  LDA  $CFF1,Y
0078: 85 55     STA  $55

So it uses the Y register as index into the current selected bank's $CFF0 
address range and stuffs them into $54 and $55, so that it can jump to the 
address at some point.

007A: AD F8 07  LDA  $07F8    ; Get original $Cx byte again
007D: A8        TAY           ; Put it in Y
007E: 48        PHA           ; Put it to the stack
007F: A9 86     LDA  #$86
0081: 48        PHA           ; Push $86: return address is now $Cx87

What this does is set up the stack for what I'm going to name (for lack of a 
better term, or any at all to be honest) an "RTS call".  This takes advantage 
of how the CPU uses the stack to return execution to the instruction after a 
JSR instruction: when the CPU encounters a JSR opcode, it pushes the the 
location of the program counter, plus two, onto the stack before loading the 
program counter with the address that comes after the JSR.  When an RTS opcode 
is then encountered, it restores the program counter from the stack and adds 
one to it before resuming execution.

The upshot of this is that you can transfer execution of a program from one 
place to the next, without using JMP, JSR or branch instructions by simulating 
this behavior--which also turns out to be a necessity when you're writing 
relocatable code.  So what the above code does is set up the stack so that it 
will jump to location $Cx87 when it encounters an RTS.

0082: 5A        PHY           ; Push $Cx
0083: A9 8B     LDA  #$8B     ; Push $8B: return address is now $Cx8C
0085: 48        PHA

Similarly, this code sets up the stack so it will jump to $Cx8C when it 
encounters an RTS as well.  So it will go there first, then to $Cx87 second 
when the routine first called via RTS call, er, uh, returns.

0086: 60        RTS           ; First time, will "return" to $Cx8C

Thus, this first RTS transfers control to the JMP ($0054) down below, which was 
set up above as an address somewhere in a 1K code chunk.  Since the code that 
goes into the 1K code chunk is a JMP instruction, once that code returns, it 
will then find the address that was pushed on the stack earlier, and execute 
the following code:

0087: 68        PLA           ; After the $CCxx block is done, it comes here
0088: 9D 6E C0  STA  $C06E,X  ; Restore last block (one passed in Y reg)
008B: 60        RTS           ; & return to calling code in that block

This code pops the Y register that was saved way back up at location $Cx61 and 
uses it to set the I/O register at $E, which, presumably, is the bank switch 
I/O address for the card.  This will turn out to be of vital importance later, 
but we'll leave it for now.  The RTS, finally, returns from initialization and 
back from whence it came.

008C: 6C 54 00  JMP  ($0054)  ; Jump to the $CCxx block code

This indirect JMP instruction, called up above via RTS call, kicks things off.

008F-00FA: 00                 ; $6B worth of zeroes
00FB: 82 00 00 BF 0D          ; ID/offset bytes

So these bytes that look like a bit of detritus actually do serve a useful 
function in ProDOS.  The $0D at the very end serves as an offset from the 
beginning of the code to the ProDOS entry point, which in this case works out 
to $Cx0D.  It also serves as the entry point for SmartPort calls (by adding 3 
to it), which works out to $Cx10.

Further, the "Technical Manual for the Apple SCSI Card" says the following 
about the byte at $FB: "An additional byte, at $CnFB, should contain $82, 
indicating that the device is the SCSI card ($2) and that it supports extended 
calls ($8)."  This just happens to be one of a small handful of those 
aforementioned tiny bits of useful information that I was able to glean from 
that source.

And so, at last, we come to the realization that this is definitely the slot 
ROM code, and thus CWLLIBISM becomes CWSISM (Code Which Sits In Slot Memory).


And Now For Something Not Quite So Completely Different
-------------------------------------------------------

And with that digression into CWSISM, we turn our attention back to the 1K 
chunk of initialization code that sits in bank 11.  In looking at the table 
that we discovered sits at $CFF0, we find the following in the 11th (counting 
from zero) 1K chunk:

CFF0: 00 CC
CFF2: 91 CE
CFF4: 9A CD
CFF6: 00 00 00 00 00 00 00 00 00 00

This tells us that there are only three valid addresses in the table (as the 
zeroes will take you nowhere), and that further, they are $CC00, $CE91 and 
$CD9A.  And since the CWSISM set up the $Cx61 dispatch call with $0B (at 
$Cx5C), it will pick the zeroeth address in that list, namely, $CC00.  So, 
looking at the code that lies there, what we see looks promising:

CC00: 68        PLA          ; Discard the 2nd return path (bank switch back)
CC01: 68        PLA
CC02: 68        PLA          ; Discard the follow on bank #, as there is none

Since this is initialization code, we can discard the RTS call from the stack 
since we aren't calling this code from another bank.  Which also means that we 
can discard that parameter which tells the RTS call what bank to select before 
returning.

CC03: 86 5E     STX  $5E     ; Save slot # (+$20) in $5E
CC05: 9C 93 C8  STZ  $C893   ; Zero out $C893 & $5D
CC08: 64 5D     STZ  $5D
CC0A: 20 C1 CC  JSR  $CCC1   ; Test for GS hardware + DMA switch

This is basically housekeeping, and the routine called at $CCC1 tests if the 
card is running on an Apple IIgs and sets bit 6 of zero page location $5D if it 
detects that.  It also checks the physical DMA on/off switch on the card as 
well; if it's set, it sets bit 5 of $5D.  The following bit of code checks $5D 
to see if bit 6 is clear and skips the instructions at $CC11 to $CC19 if 
so--and since I'm emulating an Enhanced Apple IIe, it *will* skip those 
instructions:

CC0D: 24 5D     BIT  $5D     ; Check if bit 6 of $5D is set (means it's a GS)
CC0F: 50 0B     BVC  $CC1C   ; Skip over if not set (it's not a IIgs)
CC11: AD 36 C0  LDA  $C036   ; IIgs Speed Reg.
CC14: 8D 96 C8  STA  $C896   ; Save it for later...
CC17: 09 80     ORA  #$80    ; Set speed to 2.8 MHz
CC19: 8D 36 C0  STA  $C036   ; & modify

Luckily there exists a very good techinical reference manual for the Apple 
IIgs; unluckily, it's a bit hard to track down.  But once you do, the 
information in it is quite good.  The above bit of code shows that the card 
firmware shifts the IIgs into high gear while running on the card.  However, we 
don't really care about that bit of code; which is why we spent so much time 
explaining what it does.

CC1C: 68        PLA          ; Get flags from slot init

Way back in CWSISM, at slot location $Cx13, there was an innocuous looking PHP 
instuction; here is where we finally take a look at the contents of it.

CC1D: A8        TAY          ; Save them in Y
CC1E: 29 04     AND  #$04    ; Check if I flag is set
CC20: F0 05     BEQ  $CC27   ; Skip if I is not set
CC22: A9 80     LDA  #$80    ; Else, signal I flag is set ($80 -> $C893)
CC24: 8D 93 C8  STA  $C893

Here we look at the interrupt disable bit in the processor flags that we saved 
earlier; if it's not set we skip on over to the next bit of code below.  
Otherwise, the code sets $80 into memory location $C983 to signal that 
initialization code was called with the I flag set.

CC27: 98        TYA          ; Restore flags from Y
CC28: 09 04     ORA  #$04    ; Set I flag
CC2A: 48        PHA          ; Push them to the stack
CC2B: 28        PLP          ; & restore flags for real

Since we need to get the values of the overflow and carry flags back, which 
were set way back in CWSISM at addresses $Cx0D through $Cx11, we have to 
retrieve them from the Y register, then push them onto the stack and then use a 
PLP to get them back into the flags register proper.  Along the way, we set the 
interrupt disable flag at $CC28 (the ORA #$04 instruction).

And in looking at code as we're doing here, it's hard not to look at it with a 
critical eye and notice that the coder could have saved a byte by deleting the 
ORA #$04 (which takes two bytes) and putting an SEI after the PLP (which takes 
one byte).  And, since we don't have any source code to look at, we may never 
know what the intention was; though it's quite likely that this was just a 
simple oversight.

CC2C: 50 09     BVC  $CC37   ; If SmartPort call, skip over

Here we see that if the card firmware was called via the SmartPort vector at 
$Cx10, the overflow flag would be clear and we would skip over the following.  
But, since the flag was definitely set, we know that we will execute what 
follows:

CC2E: BA        TSX          ; Slot init & regular ProDOS dispatch get here
CC2F: 8E 07 C8  STX  $C807   ; Save stack pointer in $C807
CC32: A9 0F     LDA  #$0F
CC34: 4C 5F CF  JMP  $CF5F   ; Jump to bank 15:0 for rest of init

This saves the stack pointer and sets up to jump to a new bank, which means we 
won't be coming back here.  Onward:

CF5F: A6 5E     LDX  $5E     ; Restore slot # (+$20) in X
CF61: A0 0B     LDY  #$0B    ; Y gets loaded with bank to return to on RTS
CF63: 6C 00 C8  JMP  ($C800) ; & go!

There are variants of this piece of code throughout every 1K bank of firmware 
code.  And since we took a good long look at CWSISM, we know that CWSISM set up 
location $C800 and $C801 to point to the card slot I/O location of $Cx61, and 
suddenly it becomes clear what that bit of code does.

Since the firmware code bounces around a lot in different banks (as we will 
discover shortly), it needs a mechanism to get back to the place that called it 
in the first place.  The problem is this: once a new 1K bank of code is 
switched into the $CC00 to $CFFF address space, there's no way for the 65C02 to 
get back to the caller with a simple RTS; any code that attempted to do so 
would end up executing the wrong code as the 65C02 knows nothing about bank 
switching and has no built-in mechanism to handle such things.

And so, by virtue of this, the code needs a way to do this manually.  Which is 
why the $Cx61 code in CWSISM saves the bank number on stack, and then sets up a 
pair of RTS calls which first, sets the correct bank and calls the correct 
function number in that bank and second, sets the bank to the bank that made 
the call in the first place before executing a final RTS which then goes back 
to the correct address.

And since we saw up above that it passed $0F into the calling routine (well, 
actually, it jumped there), we know that it's going to call function #0 in bank 
15.  As it turns out, the function table for bank 15 looks like this:

CFF0: 00 CC
CFF2: 00 00 00 00 00 00 00 00 00 00 00 00 00 00

which means bank 15 only contains one function, and it starts at $CC00.


The Next Part, In Which We Peruse Bank 15
-----------------------------------------

The story so far: we started in slot ROM, set up a bunch of variables, then 
bounced to bank 11, and just now bounced to bank 15.

CC00: A9 40     LDA  #$40
CC02: 8D 09 C8  STA  $C809   ; Put $40 into $C809
CC05: 8D 32 BF  STA  $BF32   ; & $BF32(!)
CC08: 9C 0A C8  STZ  $C80A   ; Zero out $C80A

So far this is all normal housekeeping boilerplate, though putting the value 
$40 into RAM at address $BF32 makes me raise an eyebrow (to this day, I still 
have no idea what that's supposed to do).  So then we come to the heart of the 
matter:

CC0B: A9 03     LDA  #$03
CC0D: 20 AF CF  JSR  $CFAF   ; Call bank 3:0 (enumerate all connected drives)

Here is the first proper JSR into bank switched code, and in taking a cursory 
glance at the code there, well...  It's a bit of a Gordian knot.  So we'll 
ignore the stones in the field for now, and keep on plowing ahead:

CC10: AE 08 C8  LDX  $C808   ; Restore slot # (+$20) to X
CC13: A5 4F     LDA  $4F
CC15: F0 03     BEQ  $CC1A   ; Skip over if call was successful ($4F == 0)
CC17: 4C F0 CC  JMP  $CCF0   ; Else, do a LDA #2B, JMP $CFAF to bank 11:1

So here the code retrieves the slot I/O offset in X from the location set way 
back in CWSISM, then checks what looks like some kind of error condition.  If 
it fails, it skips on over to function 1 in bank 11; otherwise, it keeps going 
here:

CC1A: 24 5D     BIT  $5D     ; Are we running on a IIgs?
CC1C: 70 05     BVS  $CC23   ; If so, skip over & keep going

Since we're not running on a IIgs, this branch is not taken and thus it can be 
safely ignored.  Continuing on:

CC1E: A9 4B     LDA  #$4B    ; Else, jump to bank 11:2 (normal success path)
CC20: 4C AF CF  JMP  $CFAF
;
CFAF: A6 5E     LDX  $5E     ; Restore slot (+$20) in X
CFB1: A0 0F     LDY  #$0F    ; Make sure we come back here...
CFB3: 6C 00 C8  JMP  ($C800) ; & go!!

So what this means is that if the function call to bank 3:0 succeeded, the code 
will then bounce to function 2 in bank 11.  And, as we saw above, function 2 
starts at $CD9A in bank 11.


The Next Part, In Which Be Bounce Back To Bank 11 And Find Something Familiar
-----------------------------------------------------------------------------

So far, this little expedition is proving to be circuituitous, but not 
impenetrable.  And it makes sense that we would come back to bank 11, as that's 
where the initialization code sent us in the first place.  And so, pressing on, 
we find:

CD9A: 86 5E     STX  $5E     ; Save X in $5E
CD9C: A9 01     LDA  #$01    ; Put 1 in $43, $44
CD9E: 85 43     STA  $43
CDA0: 85 44     STA  $44
CDA2: 64 46     STZ  $46     ; Zero out $46, $47, $48, $49
CDA4: 64 47     STZ  $47
CDA6: 64 48     STZ  $48
CDA8: 64 49     STZ  $49
CDAA: A9 08     LDA  #$08    ; Put $08 in $41
CDAC: 85 41     STA  $41
CDAE: 64 40     STZ  $40     ; Zero out $40, $42
CDB0: 64 42     STZ  $42

This is again more housekeeping boilerplate, initializing a bunch of zero page 
locations.  Then we find this:

CDB2: A9 09     LDA  #$09
CDB4: 20 5F CF  JSR  $CF5F   ; Call bank 9:0 (directly)

So this calls function 0 in bank 9, which lives at $CC00.  And looking through 
that code, well, let's just put that aside for now as it's long and involved 
and will require a fair amount of study.  Continuing:

CDB7: A5 4F     LDA  $4F
CDB9: D0 0C     BNE  $CDC7   ; Fail if $4F is non-zero

This looks at the error flag we saw up above in bank 15, and jumps to function 
1 in this bank if the error flag is non-zero.

CDBB: AD 01 08  LDA  $0801   ; Get byte @ $801 (!)
CDBE: F0 07     BEQ  $CDC7   ; Fail if it's zero

Now here is something interesting!  Why this is interesting is because when 
booting from a floppy disk, the disk driver typically loads at least one sector 
(256 bytes of data) into location $800.  So we can deduce that the above call 
into function 0 in bank 9 is loading something similar from the hard drive into 
memory at a similar address.  With this bit of knowledge, we can see up above 
where it puts address $800 into zero page locations $40 and $41 that those 
locations must be a loading address.

CDC0: AD 00 08  LDA  $0800   ; Get byte @ $800 (!)
CDC3: C9 01     CMP  #$01
CDC5: F0 03     BEQ  $CDCA   ; Keep going if it's equal to 1
CDC7: 4C 91 CE  JMP  $CE91   ; Else, jump to function 1 (failure point)

Again, this interesting because with floppy disks, the first byte of the first 
sector loaded into memory at $800 contains the number of sectors that the 
floppy driver should load into memory; this looks eerily similar--only in this 
case, it will jump to the failure path if it sees it wanting more than one 
block.  Assuming all is well, we then have this:

CDCA: 8D 09 C8  STA  $C809   ; Put a 1 into $C809
CDCD: AD F8 07  LDA  $07F8   ; Get $7F8
CDD0: 0A        ASL  A       ; x16
CDD1: 0A        ASL  A
CDD2: 0A        ASL  A
CDD3: 0A        ASL  A
CDD4: AA        TAX          ; Store it in X
CDD5: A9 00     LDA  #$00    ; Stuff 0 in $C035 (GS location?)
CDD7: 8D 35 C0  STA  $C035
CDDA: 8D 01 CC  STA  $CC01   ; What does this do?
CDDD: 4C 01 08  JMP  $0801   ; Run the code from block 0

And here we see it hand off execution to data that it pulled from the hard 
drive by jumping to $801, and thus we see that this must be the end of the hard 
drive boot logic.  As far as the firmware is concerned, its initialization job 
of bootstrapping the hard drive is concluded.

However, we still really don't know anything that tells us what the slot I/O 
addresses do (aside from location $E) and we still have no idea how the card 
talks to the hard drive.  At least we have a pretty good idea of where to look.


What Are All These Eels, And What Are They Doing In My Hovercraft
-----------------------------------------------------------------

So at last we get to take a look at function 0 in bank 3.  And, much like a 
hovercraft full of eels, it's a twisty mass of slippery, squirming code.  And, 
looking at it more closely, it does a bunch of things which don't make much 
sense until you understand other code, which bounces around to lots of other 
banks.  And a lot of it is opaque unless you somewhat understand what the ports 
on the NCR 53C80 do and how the SCSI protocol works.

So while we have an excellent start on understanding, for the most part, the 
broad outlines of how the card works, we are still stuck with a profound lack 
of critical knowledge on how the thing talks to the the hard drive and, 
conversely, how the hard drive talks to the card.  And without that knowledge, 
we perish.


The Next Part, In Which We Are Not Ready To Perish
--------------------------------------------------

Fortunately, the NCR 5380 and, by extension, the 53C80 is well documented and 
said documentation is readily available, and so I availed myself of it.  I took 
another look at the schematic for the card and noticed that the 53C80 had three 
address lines on it, which implied that it had eight ports for controlling it.  
Unfortunately, there's an error on the schematic in which they have the address 
lines hooked up in reverse, and this caused me no small amount of consternation.

It seemed obvious that those eight ports were hooked up to the slot I/O 
addresses, and also seemed very plausible, after having looked at and analyzed 
a lot of code heretofore unmentioned, that it was connected to the lower half 
of that address space.  So, in order to confirm my suspicions, I started 
writing the hard drive emulator.

This started out, simply, as a bunch of statements that output human readable 
words to a log file whenever the slot I/O addresses were accessed by the card 
firmware; I used the firmware's access to the slot I/O to tell me what it said 
and what it was listening for.  Well, that, and some code to properly handle 
the bank selection of the ROM space as well.  In this way, I was able to 
enlarge my understanding of what the card expected to see as well as what the 
ports that weren't connected to the 53C80 (which were likely connected to the 
Sandwich II) might be up to.

So in fits and starts, I used the code that writes to the Mode Register of the 
53C80 to get the code to successfully... do something.  It was at that point I 
could see that it was getting through the initialization phase of the card's 
firmware as Apple2 would be able to boot a floppy image inserted into a drive 
in slot 6 at that point.  But in tracing the reads and writes to the slot I/O 
address space in the log I could see that it was getting through the card's 
firmware in a failure mode.  It was progress, of a sort.  Even failure tells 
you something.

And what it told me was that I needed to dig into the SCSI specification to 
figure out how the protocol worked.  Looking back I can see that I was getting 
through to the MESSAGE phase and, because of the way I was responding to that 
message, that the firmware would then send an ABORT message, but that's all 
pretty much meaningless as I haven't explained anything about the SCSI protocol 
and how it works.

And here, while there is a lot of information about the latter day iterations 
of the SCSI protocol, there wasn't much pertaining to the kind of SCSI that the 
Apple High Speed SCSI card spoke, which in its case, has been retroactively 
labeled SCSI-1.

And when looking at the SCSI protocol, the first thing that hits you is that 
it's a very well designed, robust protocol and it's nothing short of a minor 
miracle that it survived and still survives to this day.  However, the 
documentation on how it *really* works is a bit lacking.  Yes, you can discover 
that there are nine phases, and the first three are fairly easy to understand; 
it's what comes after that where things get murky.


Talk SCSI To Me
---------------

So here is a crash course in the SCSI-1 protocol.  The SCSI bus is engineered 
such that it allows for eight devices to connect to said bus; devices connected 
to the bus can have Initiator and/or Target roles.  Devices can talk to each 
other by passing messages over this bus, however only one pair of devices can 
use the bus at any one time.  In order to prevent deadlock from happening when 
more than one device attempts to take control of the bus, there is an enforced 
hierarchy of devices wherein they all have a unique ID; a device that contends 
for use of the bus at the same time as another device wins this contention if 
and only if its device ID is higher than the other device's ID (1 in this case 
being the highest, and 128 being the lowest).  The bus is an 8-bit parallel 
data bus that is controlled by a variety of signals (and these are typically 
called "lines").

In contending for and utilizing the bus, there are nine phases that all SCSI 
devices must understand and negotiate.  They are as follows:

 -  Bus Free
 -  Arbitration
 -  Selection
 -  Message In
 -  Message Out
 -  Data In
 -  Data Out
 -  Command
 -  Status

In the Bus Free phase, as one might expect, no devices are using the bus.  This 
is the ground state of the SCSI protocol, the phase from whence all 
communication starts and where it all ends.  Any device that wishes to talk to 
another device on the bus must start here.

Once a device sees that the bus is free, it can enter the Arbitration phase as 
an Initiator; it does so by first setting the bit that corresponds to its 
device ID on the data bus.  If another device tries to do this at the same 
time, the device with the lower ID will remove its bit from the data bus and 
try again when it detects that the bus is free again.  When the Initiator has 
waited a certain amount of time with no other contention, it then asserts the 
SEL line and goes into the Selection phase.

In the Selection phase, the Initiator sets the bit that corresponds to the 
device ID it wants to talk to (the Target) on the data bus.  Every other device 
on the bus, by virtue of the asserted SEL line, knows it's in the Selection 
phase and can see the device ID bits being asserted on the data bus; if none of 
the bits match its own ID, it will stay silent.  If the Target device doesn't 
respond in a timely manner, the device that tried "calling" it drops the bits 
it asserted on the data bus and drops the SEL line.  Otherwise, if the Target 
device sees its ID on the data bus, it responds by asserting the BSY (BuSY) 
line.

The device that started all of this (the Initiator) then drops the SEL line and 
the Initiator and Target devices then enter the next phase.  What phase that is 
took some teasing out of lots of different papers, datasheets and manuals--as 
well as much trial and error in the emulation code.  And what I found was this: 
once the devices are in the Selection phase, they typically(*) dance through 
the following set of phases, in order, before being done with their 
transaction: Message Out(**), Command, Data In/Out, Status, Message In.

(*) One exception to this is the TEST UNIT READY command, which will skip the 
Data In/Out phase

(**) Note that the qualifiers "In" and "Out" come strictly from the perspective 
of the Initiator

Once the devices have successfully negotiated the Message In phase at the end 
of their phase dance, the Target device drops the BSY line and the bus is then 
free again for another transaction.

One thing I forgot to mention is that each phase transition, once the devices 
are in the Selection phase, is punctuated by a REQ/ACK handshake.  Typically, 
the Target asserts and drops the REQ line while the Initiator asserts and drops 
the ACK line.  Basically, when the Target is ready to move to a different 
phase, it will assert the REQ line; the Initiator will see this and then assert 
the ACK line.  Once the Target sees the ACK line asserted, it will drop the REQ 
line; the Initiator, seeing this, will then drop the ACK line.  And thus hands 
are shaken, and all are in agreement as to where they are and what they are 
doing.

One interesting consequence of this kind of handshaking is that it means that 
every phase past Arbitration is driven by the Target device.


By Your Command
---------------

And so having deciphered the proper steps in the post-Selection phase dance, we 
come as last to the heart of the matter: the Command phase.  Commands come in a 
few different flavors: the six byte, the ten byte and the twelve byte.  The 
flavor is given by the top three bits of first byte while the command itself is 
given by the bottom five bits.  Treating those top three bits as a number from 
zero to seven, the flavors fall into the following groups:

six byte: 0
ten byte: 1, 2
twelve byte: 5

Yes, 3, 4, 6 and 7 are all missing, and, for the purposes of this crash course, 
can be safely ignored(*).

(*) For the terminally curious, 3 and 4 are (were?) "reserved", and 6 and 7 are 
for "vendor specific" commands

Having now discerned their form, the question arises: just what do these 
commands do?  Basically, they tell the Target what the Initiator wants from it.
For example, let's say that the Initiator wants to know if a device on the bus 
is ready to receive commands.  It would send out, during the Command phase, a 
TEST UNIT READY command which has the following form:

00 00 00 00 00 00

Assuming the device receiving this command actually is ready to receive 
commands, it would then send back a status message (in the Message In phase 
following the Status phase) saying "Good" (which, in this case, is coded as 
$00).

Other commands follow basically the same form; only instead of going directly 
to the Status phase, as the TEST UNIT READY command does, it will go into 
either the Data In or Data Out phase before going to the Status 
phase--depending on what the command does.  For example, a READ command will go 
to the Data In phase, because the Initiator is requesting data from the Target; 
likewise, a WRITE command will go to the Data Out phase because the Initiator 
wants to send data to the Target.


Back To Our Regularly Scheduled Analysis
----------------------------------------

So, before we diverged into a crash course of the SCSI-1 protocol, we were 
looking at where I had been able to have the card's firmware return back to the 
Apple IIe's Autostart program, but in a failure mode.  Which, while ultimately 
unsatisfying, *was* a step in the right direction.

So I could see that with my hard-coded responses to the firmware's inquiries, I 
was getting an IDENTIFY message ($80) followed by an ABORT message ($06).  It 
was a this point I could also see that I was going to have to start writing the 
actual hard drive device emulator code as well, as trying to keep track of all 
the phase changes in the slot I/O register code was turning into an 
impenetrable mess and wasn't going to be fruitful in the long run.

This also necessitated a closer look at the code for function 0 in bank 3.  I 
took copious notes on where the code went and what it did, and eventually found 
that almost everything, at some point, seemed to end up calling function 0 in 
bank 16.


All Roads Lead To Bank 16:0
---------------------------

The one thing I was trying to figure out from this code was: what was the 
failure mode that would get you out cleanly?  Because in order for the code 
that called here to work properly, it would have to have some kind of clean 
failure mode to indicate that there was no drive present at this device ID; 
also in my first attempts to get the firmware code to successfully run (for 
some value of "successfully" > 0), it would hang up somewhere in this code.  
And that meant, since I didn't understand the SCSI chip, that I would have to 
understand the SCSI chip and how it worked to have any hope of untangling the 
tangled mass of code here.

So before we take a quick look at that, let's take a look at the top level code 
that lives at function 0, bank 16.  At first glance, it doesn't look all that 
bad:

CC00: 8D 00 CD  STA  $CD00   ; Write to $CD00 (what does it do?)
CC03: 20 D0 CD  JSR  $CDD0   ; Clear DMA bit (1) from reg. $2, init some stuff
CC06: 20 CE CE  JSR  $CECE   ; Check if reg. $4 has 0, 2 (/SEL) or 4 (/I/O)
CC09: B0 16     BCS  $CC21   ; If failure, skip over

This is pretty straightforward stuff; the routine at $CECE will set the carry 
flag if slot I/O register $4 is not exactly one of: 0, 2, or 4.  If the carry 
is set, it bypasses the following sections of code:

CC0B: 20 42 CF  JSR  $CF42   ; Check if bit 7 in $C893 is set (success == yes)
CC0E: 20 24 CC  JSR  $CC24   ; Do Arbitration phase
CC11: B0 03     BCS  $CC16   ; If Arbitration timed out, jump over Selection

It wasn't obvious when I first encountered this code, but, once I delved into 
the SCSI protocol I was able to figure out that the code at $CC24 was 
negotiating the Arbitration phase.

CC13: 20 7A CC  JSR  $CC7A   ; Do Selection phase

Likewise, it was not obvious that the code at $CC7A was negotiating the 
Selection phase--but I was able to figure out that the code could cleanly exit 
this bank (in a failure mode, naturally) if the BSY line was not asserted.

CC16: 20 58 CF  JSR  $CF58   ; Check if bit 7 in $C893 is set (success = yes)
CC19: B0 06     BCS  $CC21   ; Skip over if it failed

Since the address at $C893 got loaded with $80 way back in function 0 in bank 
11, the carry flag will be clear and we will execute the following:

CC1B: 20 E4 CC  JSR  $CCE4   ; Do SCSI communication with target
CC1E: 20 A0 CD  JSR  $CDA0   ; Do nothing if $C88F is nonzero, else check on
                             ; $C8EC

The code at $CCE4 was quite mystifying for some time, even after I had educated 
myself on the intricacies of the SCSI protocol and the ins and outs of the NCR 
53C80's ports.  I wasn't able to make sense of this until I was able to 
understand the phases after Selection and how they were expected to be 
negotiated.

CC21: 4C 18 CE  JMP  $CE18   ; Do some post cleanup before returning

The code at $CE18 basically does some error checking and cleanup before 
returning back to whence it came; it's fairly easy to digest.  But before we 
dig into subroutines of bank 16:0, we need to take a short digression into how 
the ports of the 53C80 work.


A Somewhat Brief Digression Into The 53C80's Ports
--------------------------------------------------

And so, having avoided looking into the 53C80 and how it works up until this 
point, we find we can no longer avoid it and thus, finally bite the bullet.  
The 53C80 has eight ports (also called registers) with which the Apple IIe's 
CPU can communicate.  They are:

$0 - Data on the SCSI bus
$1 - Initiator Command
$2 - Mode
$3 - Target Command
$4 - Current SCSI Bus Status (R), Select Enable (W)
$5 - Bus and Status (R), Start DMA Send (W)
$6 - Input Data (R), Start DMA Target Receive (W)
$7 - Reset Parity/Interrupt (R), Start DMA Initiator Receive (W)

Note too that there is a one-to-one correspondence with the port numbers as 
they appear on the 53C80 and their location in the slot I/O address range.  
What follows is an explanation of what the registers do:

Register $0 is pretty much what it says it is; data on the SCSI bus will appear 
here barring this caveat: it only works when bit 0 of register $1 (ASSERT DATA 
BUS) is set.  Which bring us to...

Register $1 is used to monitor and assert signals on the SCSI bus.  The bits 
are:

7    6              5             4    3    2    1    0
RST  AIP/TEST MODE  LA/DIFF ENBL  ACK  BSY  SEL  ATN  DATA BUS

RST (ReSeT) sets the RST signal on the SCSI bus and resets the internal state 
of the 53C80; it stays in the reset state until this bit is cleared.  AIP/TEST 
MODE (Arbitration In Progress) is a bit that is split between two functions: 
when read, it signals whether or not the Arbitration phase is in progress; when 
a one is written to it, it disables all output from the chip (zero restores 
output).  LA/DIFF ENABL (Lost Arbitration) is another split signal: when read, 
it signals whether or not Arbitration was lost; writing has no effect.  ACK 
(ACKnowledge) sets or clears the ACK line, BSY (BuSY), SEL (SELect), ATN 
(ATteNtion) and DATA BUS all do the same.

The important thing to note here is that by setting the ATN line on the SCSI 
bus, the initiator signals to the Target that it wants to send a message and 
so, at the appropriate time, the Target will then assert the MSG and C/D lines 
in response.

Register $2 controls various modes of the 53C80, as well as whether or not 
certain interrupts will be triggered.  The bits are:

7      6       5         4          3           2        1     0
BLOCK  TARGET  ENABLE    ENABLE     ENABLE EOP  MONITOR  DMA   ARBITRATE
MODE   MODE    PARITY    PARITY     INTERRUPT   BUSY     MODE
DMA            CHECKING  INTERRUPT

The only two of real interest are bits 1 (DMA MODE) and 0 (ARBITRATE); the 
former sets the chip into DMA mode, readying it for a DMA transfer while the 
latter tells the chip to start the Arbitration phase.

Register $3 is used mainly if the chip is operating in Target mode, as all the 
lines controlled by it are typically only controllable by the Target device.  
The only exception is when the Initiator is sending data to the Target; in that 
case, bits 0, 1 and 2 must match the lines being asserted by the Target.  The 
bits are (where X means unused):

7               6  5  4  3    2    1    0
LAST BYTE SENT  X  X  X  REQ  MSG  C/D  I/O

Register $4 is another split register.  When read, it returns the state of the 
following lines on the SCSI bus:

7    6    5    4    3    2    1    0
RST  BSY  REQ  MSG  C/D  I/O  SEL  DBP

When written to, it enables an interrupt to occur if the device ID written to 
the SCSI bus is present, BSY is clear and SEL is set.

The important thing about this register is that it allows monitoring of the 
MSG, C/D and I/O lines of the SCSI bus.  These three bits are what the Target 
uses to signal moves from phase to phase; without these three bits it would be 
impossible, as an initiator, to figure out what to do once in the Selection 
phase.

And with three bits, you would expect there to be eight phases controlled here, 
but only six are controlled from these signals--having MSG set to 1 while C/D 
is set to 0 is an illegal combination, and that knocks two of the combinations 
right out of contention.  Each legal combination corresponds to a phase, and 
this is, as it turns out, vital information:

Data Out:  MSG = 0, C/D = 0, I/O = 0 (0)
Data In: MSG = 0, C/D = 0, I/O = 1 (1)
Command: MSG = 0, C/D = 1, I/O = 0 (2)
Status: MSG = 0, C/D = 1, I/O = 1 (3)
Message Out: MSG = 1, C/D = 1, I/O = 0 (6)
Message In: MSG = 1, C/D = 1, I/O = 1 (7)

Note that there's nothing magical about the order of these three lines; they 
could be in any order whatsoever and they would still work the same way.  The 
only reason that they are presented this way is one, this is how they are laid 
out in the NCR 53C80 chip (in this register in particular) and two, this is 
order that they are used in the firmware.

Register $5 is--you guessed it--another split register.  When read, it returns 
some internal state registers as well as a couple more SCSI bus lines:

7       6        5        4       3      2      1    0
END OF  DMA      PARITY   IRQ     PHASE  BUSY   ATN  ACK
DMA     REQUEST  ERROR    ACTIVE  MATCH  ERROR

When written to, it initiates a DMA send transfer from memory to the SCSI bus.

Register $6, another split register, when read, holds data coming from the SCSI 
bus during a DMA transfer.  When written to, it initiates a DMA receive 
transfer from the SCSI bus (the Target) to memory.

And finally, register $7 is yet another split register, that when read, resets 
the internal PARITY ERROR, IRQ ACTIVE and BUSY ERROR bits in register $5; when 
written to in initiates a DMA receive transfer from the SCSI bus (the 
Initiator) to memory.


Back To Bank 16
---------------

So, with that info-dump out of the way, let's return back to the first 
subroutine of the initial code of bank 16:0.  We start with the routine at 
$CC24:

CC24: 9E 63 C0  STZ  $C063,X ; Zero reg $3 (Target Command)
CC27: 20 2F CF  JSR  $CF2F   ; Toggle bit 7 of reg. $E (ON-off-ON)
CC2A: AD DA C8  LDA  $C8DA   ; Get SCSI ID of initiator device
CC2D: 9D 60 C0  STA  $C060,X ; & put it in reg. $0 (Output Data)
;
CC30: 9E 62 C0  STZ  $C062,X ; Zero out reg. $2 (Mode)
CC33: A9 01     LDA  #$01
CC35: 9D 62 C0  STA  $C062,X ; Set bit 0 (ARBITRATE) of reg. $2

This code zeroes out the Target Command register, then toggles bit 7 of 
register $E on, then off, then back on.  It then puts the SCSI ID of the 
initiator device into the SCSI Data Bus register, then clears and sets the 
ARBITRATE bit of the Mode register.  This is the start of the Arbitrate phase.

CC38: BD 6C C0  LDA  $C06C,X ; Get reg. $C
CC3B: 89 10     BIT  #$10    ; Check bit 4
CC3D: D0 05     BNE  $CC44   ; Skip over this if it's set
CC3F: 20 0C CF  JSR  $CF0C   ; Toggle bit 7 of register $E ON-off-ON
                             ; # of times before C is set is in $C817/8
CC42: B0 2E     BCS  $CC72   ; Signal failure is C is set

There is a lot of this code and variants thereof sprinkled liberally throughout 
the firmware code.  I'm still not sure what bit 4 of register $C is a signal 
for, but it seems clear that it indicates some kind of error condition because 
whenever it's not set, it toggles bit 7 of register $E and will eventually, 
when this has happened enough times, signal an error and exit.

CC44: 3C 61 C0  BIT  $C061,X ; Check bit 6 (AIP) of reg. $1
CC47: 50 E7     BVC  $CC30   ; Try again if it's not set

This little bit of code checks the AIP (Arbitration In Progress) bit, and loops 
back to try again if it's not set.

CC49: EA        NOP          ; Do a small delay
CC4A: EA        NOP
CC4B: A9 20     LDA  #$20
CC4D: 3D 61 C0  AND  $C061,X ; Check if bit 5 (LA) of reg. $1 is set
CC50: D0 DE     BNE  $CC30   ; Try again if it's set

After checking to see if the AIP bit is set, it then waits a short amount of 
time before checking to see if the LA (Lost Arbitration) bit is set; if it's 
set, it loops back to try again.

CC52: BD 60 C0  LDA  $C060,X ; Get reg. $0
CC55: 4D DA C8  EOR  $C8DA   ; EOR it with what we put there to begin with
CC58: F0 05     BEQ  $CC5F   ; If it's the same, bypass (we won arbitration)
CC5A: CD DA C8  CMP  $C8DA   ; Otherwise, see if the EORed value is >= orig
CC5D: B0 D1     BCS  $CC30   ; Try again if so

Here we look at the data on the SCSI bus and see if there were any other 
devices attempting to arbitrate at the same time.  If there were, and their 
SCSI ID was higher than ours, then loop back and try again; otherwise, we won 
arbitration and continue on:

CC5F: A9 20     LDA  #$20
CC61: 3D 61 C0  AND  $C061,X ; Check if bit 5 (LA) of reg. $1 is set
CC64: D0 CA     BNE  $CC30   ; Try again if so

We check the LA bit one more time to ensure it's not set; if it is, then loop 
back and try again.

CC66: A9 06     LDA  #$06    ; Set bits 1-2 (ASSERT /ATN, /SEL) of reg. $1
CC68: 1D 61 C0  ORA  $C061,X
CC6B: 29 9F     AND  #$9F    ; And clear bits 5-6 (TEST MODE, DIFF ENBL) of $1
CC6D: 9D 61 C0  STA  $C061,X
CC70: 18        CLC          ; Signal success
CC71: 60        RTS          ; & return

Now that we've won the Arbitration phase, we assert the ATN and SEL lines and 
make sure that the TEST MODE and DIFF ENBL lines are dropped.  By setting the 
ATN line, we signal to the Target that we want to go to the Message Out phase 
after the Selection phase is done.  Once that's done, we signal success and 
return.

CC72: A9 80     LDA  #$80
CC74: 8D 8F C8  STA  $C88F
CC77: 4C 91 CD  JMP  $CD91   ; Signal failure

This bit is called if the code that checks register $C fails; this is the only 
failure path for the Arbitration phase code.


A Fine SELECTion Of Devices
---------------------------

Now that the Initiator (us) has won the Arbitration phase, it's time to see if 
the device we want to talk to exists, and is ready and able to talk.

CC7A: 9E 64 C0  STZ  $C064,X ; Zero out reg. $4 (Select Enable)
CC7D: AD DA C8  LDA  $C8DA   ; Host ID
CC80: 0D DB C8  ORA  $C8DB   ; Target ID
CC83: 9D 60 C0  STA  $C060,X ; Store $C8DA & DB (ORed) into reg. $0 (Data Bus)
CC86: A9 41     LDA  #$41    ; Set bits 0 (DATA BUS) & 6 (TEST MODE) in reg. $1
CC88: 1D 61 C0  ORA  $C061,X ; Then clear bits 5-6 (DIFF ENBL, TEST MODE) in $1
CC8B: 29 9F     AND  #$9F
CC8D: 9D 61 C0  STA  $C061,X

The code here clears the Select Enable register to ensure no IRQs are generated 
during the Select phase, then puts both the Initiator's SCSI ID and the 
Target's SCSI ID into the 53C80's data register.  It then does something that 
doesn't seem to make any sense, as it sets the DATA BUS ENABLE and TEST MODE 
bits.  The former puts the 53C80's data register onto the SCSI data bus, while 
the latter disables all outputs of the 53C80.  Maybe this was necessary because 
of the Sandwich II chip and the way it was hooked up to the slot I/O bus and 
the 53C80, but there's no way to know for sure without access to actual 
hardware.

After this, it disables the TEST MODE bit, which then enables the outputs of 
the 53C80, and thus the Target's SCSI ID is then visible to all the devices 
connected to the SCSI bus.

CC90: A9 FE     LDA  #$FE    ; Clear bit 0 (ARBITRATE) in reg. $2
CC92: 3D 62 C0  AND  $C062,X
CC95: 9D 62 C0  STA  $C062,X
CC98: A9 02     LDA  #$02    ; Set bit 1 (DMA MODE) in reg. $2
CC9A: 1D 61 C0  ORA  $C061,X
CC9D: 9D 61 C0  STA  $C061,X
CCA0: AD DC C8  LDA  $C8DC   ; Get $C8DC, set hi bit, save in $C821
CCA3: 09 80     ORA  #$80
CCA5: 8D 21 C8  STA  $C821
CCA8: A9 F7     LDA  #$F7    ; Clear bit 3 (ASSERT /BSY) in reg. $1
CCAA: 3D 61 C0  AND  $C061,X
CCAD: 9D 61 C0  STA  $C061,X

This is all pretty straightforward stuff.  It clears the ARBITRATE bit, sets 
the DMA MODE bit, and clears BSY (if it was set before; more likely than not, 
it will have been cleared already).  It also sets bit 7 of $C8DC and saves it 
in $C821, but it's not clear just why yet.

CCB0: 20 51 CD  JSR  $CD51   ; Wait for bit 6 (/BSY) of reg. $4 to be set
CCB3: 90 03     BCC  $CCB8   ; Skip over JSR if success
CCB5: 20 75 CD  JSR  $CD75   ; Shorter wait for bit 6 in reg. $4 to be set

This bit of code waits for the Target to assert the BSY line; if it fails after 
the first attempt, it will try again with a shorter wait time.

CCB8: A9 FB     LDA  #$FB    ; Clear bit 2 (ASSERT /SEL) in reg. $1
CCBA: 3D 61 C0  AND  $C061,X
CCBD: 9D 61 C0  STA  $C061,X
CCC0: 90 10     BCC  $CCD2   ; Skip over if the JSR was successful

This code drops the SEL line, and depending on whether or not the Target 
asserted the BSY line, will either drop through to the failure path or skip 
over to the success path.

CCC2: A9 FE     LDA  #$FE    ; Clear bit 0 (DATA BUS) in reg. $1
CCC4: 3D 61 C0  AND  $C061,X
CCC7: 9D 61 C0  STA  $C061,X
CCCA: A9 81     LDA  #$81    ; Put $81 in $C88F
CCCC: 8D 8F C8  STA  $C88F
CCCF: 4C 91 CD  JMP  $CD91   ; Signal failure

This is the only failure path in the Selection phase code, but, unlike the 
Arbitration phase code, this code path will *not* lock up waiting for signals.  
It will wait only so long for the Target to assert the BSY line before giving 
up and signalling failure.  It will also bail out of this bank completely, so 
it will not try any further communication--for now.

CCD2: A9 9D     LDA  #$9D    ; Clear bits 1, 5-6 (TEST, DIFF E., DMA) in $1
CCD4: 3D 61 C0  AND  $C061,X
CCD7: 9D 61 C0  STA  $C061,X
CCDA: A9 FE     LDA  #$FE    ; Then clear bit 0 (DATA BUS) in $1
CCDC: 3D 61 C0  AND  $C061,X
CCDF: 9D 61 C0  STA  $C061,X
CCE2: 18        CLC          ; Signal success
CCE3: 60        RTS          ; & return

Otherwise, the code clears TEST MODE, DIFF ENBL and DMA MODE before clearing 
DATA BUS, signalling success and returning.


The Next Part, In Which We Find Ourselves In A Maze Of Twisty Code
------------------------------------------------------------------

Now that we've successfully navigated the Selection phase, it's time to talk 
SCSI.  For the sake of brevity, we will refer to this code as The Code That 
Comes After Selection, or TCTCAS for short.  This bit of code calls a bunch of 
other code which in turns calls even more code; keeping it all straight was 
quite the challenge.

CCE4: BD 6C C0  LDA  $C06C,X ; Get $C
CCE7: 89 10     BIT  #$10    ; Is bit 4 set?
CCE9: D0 05     BNE  $CCF0   ; Skip ahead if so
CCEB: 20 0C CF  JSR  $CF0C   ; Else, toggle bit 7 of $E (ON-off-ON) w/countdown
CCEE: B0 40     BCS  $CD30   ; Exit if countdown hit zero

Here again we see the boilerplate checking of bit 4 of register $C.

CCF0: BD 64 C0  LDA  $C064,X ; Get reg. $4
CCF3: 29 42     AND  #$42    ; Are bits 1 (/SEL) & 6 (/BSY) clear?
CCF5: F0 3A     BEQ  $CD31   ; If so, we're done (jump down, signal error)

Here we're checking the BSY and SEL lines; if both have been dropped after the 
last phase, we jump down to $CD31 and do some final checking before exiting.

CCF7: C9 40     CMP  #$40    ; Is only bit 6 (/BSY) set?
CCF9: D0 E9     BNE  $CCE4   ; Loop back if not...

The second check looks to see if only BSY is set; if not it loops back to the 
start of this subroutine, otherwise it continues on:

CCFB: BD 62 C0  LDA  $C062,X ; Clear bit 1 (DMA MODE) of reg. $2
CCFE: A8        TAY
CCFF: 29 FD     AND  #$FD
CD01: 9D 62 C0  STA  $C062,X
CD04: 98        TYA          ; Then restore its previous state
CD05: 1D 62 C0  ORA  $C062,X
CD08: 9D 62 C0  STA  $C062,X

This little bit of code toggles DMA MODE line off then on if it was set to 
begin with, otherwise it does nothing.  Well, it doesn't *do* nothing, but the 
effect is null and void.

CD0B: BD 64 C0  LDA  $C064,X ; Is bit 5 (/REQ) of reg. $4 clear?
CD0E: A8        TAY
CD0F: 29 20     AND  #$20
CD11: F0 D1     BEQ  $CCE4   ; Loop back if so...

This checks to see if the REQ line has been asserted by the target yet, and if 
not, loop back to the beginning of the subroutine.

CD13: AD 1F C8  LDA  $C81F   ; Save $C81F in $C820 (last 3-bit pattern we saw)
CD16: 8D 20 C8  STA  $C820

Here we save the last phase that was seen in $C820.

CD19: 98        TYA          ; Restore reg. $4 from Y
CD1A: 29 1C     AND  #$1C    ; Keep only bits 2-4 (/I/O, /C/D, /MSG)
CD1C: 8D 1F C8  STA  $C81F   ; & save in $C81F

Earlier we saved the contents of register $4 (which holds the MSG, C/D and I/O 
bits) in the Y register, now we retrieve them and mask off the MSG, C/D and I/O 
bits and save them for later.  By virtue of this, every time we get here the 
previous value that was in $C81F must be different than the last value we saw 
here.

As to why: when I first encountered this code, I approached it the way I 
usually approach unknown code: by feeding it zeroes.  However, when I did that, 
these lines of code caused a failure mode later on.  And so I had to dig a 
little deeper into all things SCSI and 53C80 to figure out why--we'll see why 
that caused a failure later on.

CD1F: 4A        LSR  A
CD20: 8D 2B C8  STA  $C82B   ; & put /2 in $C82B

Here we shift it right one bit and stuff it into $C82B; this is also a clever 
way of making it into an index for a jump table.

CD23: A8        TAY          ; & use as index into jump table
CD24: 4A        LSR  A       ; & /2 again
CD25: 9D 63 C0  STA  $C063,X ; Write it to reg. $3 (Target Command)

Here we put it into the Y register and then shift it to the right one more time 
to set the bits in the Target Command register properly.  The Initiator needs 
to set this register properly at each phase change, otherwise the 53C80 will 
signal a phase match error.

CD28: 20 48 CD  JSR  $CD48   ; Use Y as idx to jump table and go there

So here the code uses the three phase bits (MSG, C/D and I/O) as an index into 
a jump table to handle the six phases after the Selection phase (Data Out, Data 
In, Command, Status, Message Out, Message In).  We'll have more to say about 
this shortly.

CD2B: 2C 06 C8  BIT  $C806   ; Is bit 7 of $C806 clear?
CD2E: 10 B4     BPL  $CCE4   ; Loop back if so...
CD30: 60        RTS

This simply checks bit 7 of $C806, which only gets set under very specific 
circumstances; those being that MSG, C/D and I/O are all asserted (Message In 
phase), and that the value returned from the Target is a "Good" message, and 
that the prior phase was either Message In, Message Out, or Status.

CD31: AD 8F C8  LDA  $C88F   ; Get $C88F
CD34: D0 08     BNE  $CD3E   ; If $C88F is != 0, just return
CD36: A9 82     LDA  #$82    ; Stuff $82 into $C88F
CD38: 8D 8F C8  STA  $C88F
CD3B: 4C 91 CD  JMP  $CD91   ; Signal failure (?) & return
CD3E: 80 F0     BRA  $CD30

This is the code path taken if the BSY and SEL lines are dropped.  It signals 
that something went wrong before returning.


The Next Part, In Which Things Start To Make Sense
--------------------------------------------------

So TCTCAS is, as it turns out, where the Target drives the Initiator; which in 
this case is the hard drive driving the card.  As I mentioned up above, when I 
first started poking around at this code, I was feeding it zeroes at first as a 
place to start seeing if I could get it to do something meaningful.  However, 
when you try that, you run into the following bit of code which says, "No, 
fuggetaboutit."

CEE5: AD 1F C8  LDA  $C81F   ; Get the current MSG, C/D, I/O values
CEE8: CD 20 C8  CMP  $C820   ; Compare it to the previous values
CEEB: D0 05     BNE  $CEF2   ; If they're different, skip over
CEED: A9 27     LDA  #$27    ; (This is ignored by the jump target)
CEEF: 4C 6C CE  JMP  $CE6C   ; Else, do a soft, then a hard reset of the card
CEF2: ...

And so, after looking over the SCSI documentation for the umpteenth time, I 
realized that what it was saying is that you can't do a Data Out phase directly 
after the Selection phase; it has to be Something Else. And this is because 
$C81F gets initialized with zero (which corresponds to the Data Out 
phase)--which means starting with zero Won't Work.

As luck would have it, however, we know that in the Selection phase, it 
asserted the ATN line, which in turn tells the Target to assert the MSG and C/D 
lines (but not I/O).  Which means that we *know* that the Target will first go 
to the Message Out phase, every time.

And so, by writing the hard drive emulator to properly respond to the MSG, C/D 
and I/O lines I got it to handshake the Message Out phase properly.  But I 
could see that after that, it wasn't exiting; it was running through another 
round of seeing what was in MSG, C/D and I/O and running the appropriate 
handler.

Now I was a bit stuck here, as there was *no* documentation on how a Target 
device, such as a hard drive, would drive the handshaking for the Initiator 
device.  And it wasn't clear what phase the firmware was expecting to come 
next, so guessing wasn't likely to yield positive results.

So, by the serendipitous luck of the Search Engine gods, I stumbled upon a page 
which looked like a scan of a book mixed with some bespoke images made by 
someone whose primary language was not English.  One of the images, which had 
misaligned text set next to it, was, however, suggestive.  It showed a sequence 
of phases that went from Bus Free to Arbitration to Selection to Message Out to 
Command to Data In to Status to Message In to Bus Free.  This was the first 
time I had seen anything like this; in all of the SCSI literature that I had 
surveyed, there was nothing beyond the vaguest hints that there was a typical 
order to the phases.  Sure, they would say that one *could* go from one phase 
to another, and how the handshaking worked, but there was *nothing* saying that 
there was a definite order to the phases that should be observed.

So, as I said, this image was highly suggestive.  Could this be the key to the 
whole thing that I was missing?

I had set things up in the hard drive emulation to go to the Message Out phase 
after the Selection phase, and so I added code to go to the Command phase after 
that.  I could see that the firmware was sending something in the Command phase 
at this point, which was the following six bytes: 00 00 00 00 00 00.  And 
looking that up in the SCSI literature showed that to be the TEST UNIT READY 
command.  But the firmware was still looking for more.

From what I saw in the logs, it didn't look like it was going for a Data In 
phase next, so I set it up to go to the Status phase, and that got things going 
a little bit further.  To me, this looked like it should be the end of the 
dance, but the firmware was *still* looking for more.

But even though a byte was sent from the Target to the Initiator during the 
Status phase, it seemed that the Status reponse was actually sent in the 
Message In phase.  Once I had coded this into the hard drive emulation, I could 
see the TEST UNIT READY command going into TCTCAS and coming out of it in a 
non-failure mode.

The dance has steps, and they must be followed in order.


Dancing In The Dark
-------------------

However, something is still not quite right; my assumption--that all the 
firmware needed to do to see if there was a drive on the bus was to probe 
through to the Selection phase and then, if anything responded, to see if it 
successfully responded to the TEST UNIT READY command--turned out to be wrong.  
How wrong?  Let's take a look back at the code in bank 3:0 which attempts to 
enumerate all devices it can see on the SCSI bus:

CC55: A0 07     LDY  #$07
CC57: 8C 73 C8  STY  $C873   ; Save Y in $C873
CC5A: 9C DC C8  STZ  $C8DC   ; Zero out $C8DC
CC5D: B9 F4 CF  LDA  $CFF4,Y ; Get SCSI ID from table into A
CC60: CD DA C8  CMP  $C8DA   ; Compare it to our SCSI ID (default is $01)
CC63: F0 1F     BEQ  $CC84   ; Skip over if it's equal (don't query our SCSI ID)

So here it's looping through all eight SCSI IDs, starting with the lowest 
priority and working its way up to the highest (for reference, the table at 
$CFF4 has the following values: $01, $02, $04, $08, $10, $20, $40, $80).  It 
compares the SCSI ID from the table to the SCSI ID of the card, and skips over 
the following code (down to $CC84) if it's the same.

CC65: 8D DB C8  STA  $C8DB   ; Else, put SCSI ID to look at in $C8DB
CC68: 64 4F     STZ  $4F     ; Zero out $4F (error flag)
CC6A: 20 5F CF  JSR  $CF5F   ; Do TEST UNIT READY (calls bank 16:0)

This is the code that I was now able to successfully navigate with my hard 
drive emulation.  It emulated exactly one SCSI ID, and that one ID returned 
here successfully (every other ID, obviously with nothing connected to the bus, 
returned failure).  However, I could see from the log file that it was trying 
to issue some more commands--which was puzzling, but told me that I needed to 
dig even deeper into the code.

CC6D: A5 4F     LDA  $4F     ; Get error code
CC6F: D0 0F     BNE  $CC80   ; Skip over if error occurred

This is fairly straightforward; it checks the error code returned from the call 
we made to bank 16:0, and if it's anything but zero, skip over the following 
code:

CC71: EE 0D C8  INC  $C80D   ; Success means add one to $C80D (# of devices)
CC74: 20 9F CC  JSR  $CC9F   ; & call Function 1 in this bank (INQUIRY + MORE)
CC77: 90 0B     BCC  $CC84   ; Check next ID if C == 0

So here we increment a counter, which we suppose to be a count of the number of 
valid devices we have found on the SCSI bus.  And here, we come to the 
realization that it isn't just hard drives that can talk to the Apple High 
Speed SCSI card, it's also printers, scanners, tape drives and whatnot.  And 
so, it makes perfect sense that TEST UNIT READY is only the first step in 
discovering if a device is a hard drive or not because here, it calls function 
1 of bank 3 (the bank we're currently in) which is what issues more commands to 
figure out what the device it's talking to actually *is*.

CC79: A9 99     LDA  #$99    ; Else, stuff $99 into $C887
CC7B: 8D 87 C8  STA  $C887
CC7E: 80 17     BRA  $CC97   ; & signal success

So if the call to $CC9F (INQUIRY + MORE) returned with the carry flag set, it 
stuffs a magic number into $C887, signals success and returns.

CC80: C9 80     CMP  #$80    ; Was error $80?
CC82: F0 16     BEQ  $CC9A   ; Signal NoDrive error if so

This is where it lands if the TEST UNIT READY call returned a non-zero result 
in the "error code" memory location. if it equals $80, it puts the ProDOS error 
code for a "NoDrive" error into the error code and returns.

CC84: AC 73 C8  LDY  $C873   ; Restore Y
CC87: 88        DEY          ; Done looking at all IDs?
CC88: 10 CD     BPL  $CC57   ; Go back if not.

Here we decrement the counter and loop back if we haven't looked at all eight 
(except for the card's) SCSI IDs.  Otherwise, we've finished, and fall through 
to the following:

CC8A: A9 77     LDA  #$77    ; Else, stuff $77 into $C80A & $C887
CC8C: 8D 0A C8  STA  $C80A
CC8F: 8D 87 C8  STA  $C887
CC92: AD 0D C8  LDA  $C80D   ; Did we find any devices?
CC95: F0 03     BEQ  $CC9A   ; Signal NoDrive if not
CC97: 64 4F     STZ  $4F     ; Else, signal success
CC99: 60        RTS          ; & return

So here it stuffs the magic number $77 into $C887 and $C80A; it also checks the 
"number of devices found" memory location, and signals a "NoDrive" error if the 
count is equal to zero.

CC9A: A9 28     LDA  #$28    ; Return $28 (NoDrive) in $4F
CC9C: 85 4F     STA  $4F
CC9E: 60        RTS

This is the landing location for the various failure modes seen up above; it 
simply puts the ProDOS "NoDrive" error into the error flag and returns.

So now I get to figure out what the commands are in that call to 3:1 that are 
causing the card to return in a failure mode.


The Test Is Easy, When You Have The Answer Key
----------------------------------------------

At this point, even though I had the hard drive emulation doing a proper dance 
through the TEST UNIT COMMAND, it was in a very crude state and couldn't really 
do anything else.  And so I had to take a closer look at the seemingly 
impenetrable code that set up a bunch of memory locations before calling bank 
16:0 to see if I could make sense of it.

Rather than go through every last one, I will go through part of the first such 
piece of code, as it's instructive:

CD0E: 20 A4 CF  JSR  $CFA4   ; Set $60/1 to $C923, $56/7 to $C92F
CD11: 20 B9 CF  JSR  $CFB9   ; Put $C9C3 into $C92F/30, zero $C931
CD14: A9 12     LDA  #$12    ; Put $12 into $C923
CD16: 8D 23 C9  STA  $C923
CD19: 9C 24 C9  STZ  $C924   ; Zero out $C924-6, $C928
CD1C: 9C 25 C9  STZ  $C925
CD1F: 9C 26 C9  STZ  $C926
CD22: 9C 28 C9  STZ  $C928
CD25: A9 1E     LDA  #$1E    ; Put $1E in $C927, $C933 (length of reply, 30)
CD27: 8D 27 C9  STA  $C927
CD2A: 8D 33 C9  STA  $C933

So we can see right off the bat that it's setting up zero page locations $60 
and $61 to point to memory at $C923, and that it sets up six bytes at that 
location with the following:

C923: 12 00 00 00 1E 00

Reaching back to our crash course on SCSI commands, we can see by the first 
byte, since the top three bits are all zero, that this must be a six-byte 
command.  And after that, uh, well, we don't really know much of anything.  So 
after digging around some more for something even remotely relevant, I found a 
document dealing with SCSI-2 and SCSI-3 hard disk interfacing--which told me, 
first of all, that $12 was the INQUIRY command, and second, that the fifth byte 
in the command was the length of the message that the Initiator was expecting 
back from the target in response to this command.  Progress!

CD2D: 20 CB CF  JSR  $CFCB   ; Call bank 16:0 (Do INQUIRY command)
CD30: A5 4F     LDA  $4F
CD32: F0 05     BEQ  $CD39   ; Skip over if no error

And this, as we now know, does the phase to phase dance from start to finish, 
and checks the resulting error code to do any necessary error handling.  But 
what of the response?  How do we know what to say from our emulated hard disk 
back to the firmware?  The hard disk interface document had something that 
looked plausible, if overlong (it seems that latter day SCSI drives are 
expected to return 148 bytes instead of 30).  So I expected that I could adapt 
that to suit the purposes of the emulation.

It was obvious that I had to write code to handle more than just the TEST UNIT 
READY command, and that it had to be able to send and receive data over the 
SCSI bus, which it, in its current state, couldn't do.  Eventually I was able 
to get that working and I could see that the firmware was successfully 
negotiating the INQUIRY command *and* coming to the conclusion that it was 
talking to a hard disk.  More progress!

And, as it turns out, this first call in bank 3:1 is what determines what the 
device we're talking to actually is, and it sets up appropriate memory 
locations to signal that to other parts of the firmware.  This is another one 
of those places where the "Technical Manual for the Apple SCSI Card" had a 
useful tidbit, namely a small table that looked something like this:

Code  Device Type
------------------------------
$03   Nonspecific SCSI
$05   CD-ROM
$06   Direct-access tape drive
$07   Hard disk
$08   Scanner
$09   Printer

These device codes are different from the device codes that the INQUIRY command 
returns, and this bit of code also does the translation from one to the other.


The Next Part, In Which More Progress Is Made
---------------------------------------------

And so, in using similar analysis in the other parts of the code called by bank 
3:1, I was able to discern that after the INQUIRY command, it was calling the 
MODE SENSE, MODE SELECT, READ CAPACITY and READ commands afterward.  And since 
I didn't know exactly what these commands returned, I used the time honored 
method of returning messages consisting of all zeroes.

And, in fixing up the hard drive emulation to respond to these commands, I 
could see the firmware was making it all the way through the bank 3:1 code 
successfully, and not in a failure mode.  It didn't boot anything yet, as I 
hadn't written the code to load a hard disk image much less dole it out over 
the SCSI bus, but it was a good result and I could finally see the end of this 
Herculean task coming into view.

However, I could see from the log file that something still wasn't quite right.


The Next Part, In Which Things Start Getting LUN-ey
---------------------------------------------------

The problem was one of too much success.  It wasn't going through the set of 
INQUIRY, MODE SENSE, MODE SELECT, READ CAPACITY and READ commands just once, it 
was doing it *eight* times.  And in looking for the culprit, I found the 
following tidbit:

CCE5: EE DC C8  INC  $C8DC   ; Increment a counter
CCE8: AD DC C8  LDA  $C8DC
CCEB: C9 08     CMP  #$08
CCED: D0 B0     BNE  $CC9F   ; Loop back if we haven't checked 8 times yet

It wasn't obvious on first examination, but I eventually figured out that 
location $C8DC was being put into byte one of every command being sent over the 
SCSI bus--as I could see the INQUIRY command was changing every time it was 
called like so:

12 00 00 00 1E 00
12 20 00 00 1E 00
12 40 00 00 1E 00
12 60 00 00 1E 00
12 80 00 00 1E 00
12 A0 00 00 1E 00
12 C0 00 00 1E 00
12 E0 00 00 1E 00

And so, after more digging into the hard disk interface document, I could see 
that the field being modified was called the Logical Unit Number, or LUN for 
short.  Further, hard disks conforming to the SCSI-2 and SCSI-3 had a 
commandment, that being as follows:

The LUN Shall Be Zero, And Zero Shall The LUN Be.  It Shall Be No Other Number 
Save For Zero, For Any Other Number Shall Be An Abomination Before The Drive.

Well, going by simple logic, it would appear that the SCSI-1 protocol was not 
bound by such a rule, and so you could have eight Logical Units for each SCSI 
device on the bus.  But this presents an interesting challenge.  We need to 
tell the firmware to pound sand for all but one LUN.


Failure Is An Option
--------------------

And so I found myself in the position of needing to have the hard drive 
emulation fail in a meaningful way; which sounds like an oxymoron but really 
isn't.  I needed to code the hard drive emulation to respond with a CHECK SENSE 
message, which is how, I eventually discovered, that you signal an error 
condition in the SCSI protocol.  When I did this, the firmware then sent a 
REQUEST SENSE command, which I wasn't sure how to craft a response that would 
signal failure for an invalid LUN.  Responding with all zeroes didn't signal 
failure as I hoped it would, so it was back to the hard disk interface document 
to find the missing information.

There I found out that byte two of the response is a four-bit "Sense Key", and 
that zero corresponds to "No Sense", which means the command was successful.  
Which, as it turns out, is no way to signal failure.  The one that fit the bill 
was five, which corresponds to "Illegal Request".

And so it seems that 16 Sense Keys was not enough for the designers of the SCSI 
protocol, so those Sense Keys correspond to broad categories.  To give even 
more fine-grained responses to what went wrong, there are at least two more 
eight-bit bytes called the "Additional Sense Code" and "Additional Sense Code 
Qualifier", which, taken together, provide for 65,536 different combinations.  
And, in the interface document, I found $08 $00 which corresponds to "Logical 
Unit Communication Failure" which seemed like a reasonable message for this 
failure mode.

Coding up the meaningful failure path and running the emulation showed that 
this mostly satisfied the firmware; it would almost get all the way to the 
point where it attempted to read block zero from the hard drive in a 
non-failure mode, but there was still a small problem.


Every Problem Is Small, From A Certain Point Of View
----------------------------------------------------

There is a call in the bank 3:1 code that calls bank 4:0 to read a block from 
the disk and do some analysis on what it finds.  The logs also showed that this 
code was also doing a lot of writing to slot I/O register $F.  Much of it being 
calls to the following brief routine:

CFB4: AD 86 C8  LDA  $C886   ; Get the value in $C886
CFB7: 4A        LSR  A       ; Shift the hi nybble to the lo nybble
CFB8: 4A        LSR  A
CFB9: 4A        LSR  A
CFBA: 4A        LSR  A
CFBB: 09 08     ORA  #$08    ; Set the high bit of the lo nybble
CFBD: 9D 6F C0  STA  $C06F,X ; & store it in slot I/O register $F
CFC0: 60        RTS

This was some highly suggestive code, and what it suggested was that it was 
using three bits of a value set up elsewhere which made for eight combinations.
The only significant loose end, as far as the hardware was concerned, was the 
8K static RAM; in all of the analysis I had done up to this point, it *seemed* 
that only 1K of it was ever used.  But this code suggested otherwise.

It was suggesting that slot I/O register $F was a bank select soft switch for 
the 8K static RAM; once I coded it up as such, the firmware was then completely 
satisfied and would get all the way to where it attempted to read block zero 
from the hard drive in a non-failure mode.


The End Is Nigh
---------------

And so, having studiously and painstakingly laid the foundation for the actual 
purpose of the hard drive emulation--that being the transfer of data to and 
from the thing--I came at last to the part where I had to actually write code 
to have real data flowing to and from the emulated hard disk.  And this, as it 
turns out, was the least interesting part of the whole thing; getting the 
contents of files into memory and parsing them is a really trivial thing and 
usually quite boring.

So in writing this bit of code, I used 4am's "Pitch Dark" hard drive image, and 
added the necessary code to serve up appropriate slices of it in response to 
the firmware's READ command.  And, of course, after running the new emulation 
it failed to load anything.

It was then that I remembered that I sent back messages of all zeroes to 
requests from commands, for the most part, with a few exceptions.  One of these 
that was sure to cause problems without a proper response was the READ CAPACITY 
command.  When the firmware inquired about the size of the hard drive, the 
emulator would happily tell it that it had zero capacity--which meant that any 
attempted reads by the firmware would be out of range.

So I coded up a proper response for the size of the hard drive image I was 
using and fired up the emulator and...  It still didn't work.  The logs told me 
that it was sending a ten-byte command, and one I hadn't seen before, which was 
basically the ten-byte variant of the READ command.  Once I had *that* coded up 
properly, I fired up the emulator and after a few seconds, found myself in the 
monitor.

What?  Why?  How does this even--

To quell the questions that were pooling up in my head I wrote some hooks into 
the emulator to trigger a code trace at the appropriate time; that being where 
the code transfered control to memory address $801, the ostensible location 
where the firmware allegedly read from block zero and placed it in memory at 
$800.  And I knew that it was getting to that point successfully because the 
firmware doesn't get there unless everything is working on the SCSI bus as it 
should, and the trace in the log file confirmed this.

There are worse things than being dumped into the Apple II monitor; at least I 
could poke around memory and disassemble things to try to figure out what was 
going wrong.  And I could see that the block that was loaded into memory was 
looking at the slot ROM for a certain value that caused it to take a branch 
that landed it in a crash zone.  This made no sense whatsoever.

Fortunately for me though, I have the ability to disassemble a snapshot of any 
memory range that I desire--so I disassembled the entire block from $800 to 
$9FF.  And what I saw there was still strange; near the end of the block it 
just kind of ran out of instructions, like something was missing.  And looking 
near the middle of the block, I saw something eerily similar to what I saw at 
the end.

Then I realized it wasn't similar, it was *identical*.  Looking through the 
hard drive emulator code, I was not surprised to find this:

static uint8_t * buf;
static uint8_t bufPtr;

Yes, I had made a rookie mistake of using too small of a value for my buffer 
pointer; it was loading the correct block, but, because the buffer pointer was 
only eight bits wide, it only copied the first 256 bytes out of the hard drive 
image *twice*.

As embarrassing as this was, it was also good news, as it meant that firmware 
bootstrap code was working; it was reading real data from the hard drive 
emulation and running correctly.  Which meant that once I fixed the size of my 
buffer pointer, the emulated hard drive should boot up correctly.

And once I coded up the fix and started up the emulator once more, after six or 
so seconds, "Pitch Dark" came up on the screen and it was glorious...


Sic Transit Gloria Mundi
------------------------

I was able to navigate forward and back through the various games on the hard 
drive image; I could even view the artwork that came with each one.  And lo and 
behold: the games worked!

I was playing through a bit Wishbringer when I got to a point where I wanted to 
save my game.  And, even though there was no WRITE command hooked up yet, I 
tried it anyway and got a nice hard lockup on the emulator.  This would never 
do--to have a hard disk that was read-only--so I coded up the WRITE command 
handler.

And upon booting up the hard drive, it looked like it was OK, only there were 
problems; namely, while you could navigate through the various games, you could 
not launch them.  As a matter of fact, the only game that *could* be launched 
was Zork I, which was the first game to pop up on the menu.  So after looking 
the code, I noticed that there was an asymmetry in the ports used for reading 
and writing to the SCSI bus.  Which requires a brief digression into data 
transference.


To DMA, Or Not To DMA, That Is The Question
-------------------------------------------

As it turns out, I was finally able to figure out that the physical DMA on/off 
switch on the card was wired to bit 6 of slot I/O register $C.  I further found 
out that, since I was defaulting to zero for any unknown bit in the slot I/O 
registers, that it was treating the DMA switch as if it were in the off 
position.  However, even so, the firmware was still treating this as a DMA 
transfer.

And, looking at the 53C80 manual, I could see that it supported three distinct 
kinds of bus I/O: Programmed I/O (or PIO for short), Direct Memory Access (or 
DMA for short) and Pseudo DMA.  Of these three, PIO is the slowest, as it 
relies 100% on handshaking on the SCSI bus for data transfer, while DMA is the 
fastest, as all you need to do is set some registers and tell the 53C80 to go 
and it handles the transfer all in the background without the need for any 
intervention from the CPU whatsoever. But what the firmware was doing, in this 
DMA switch in the off position mode, was Pseudo DMA.

How it works for reading data from the SCSI bus is that the CPU monitors bit 6 
(DMA REQ) in the slot I/O register $5, then reads the data that shows up in 
slot I/O register $6 when the DMA REQ bit is asserted.  For this kind of 
transfer to work, however, there must be some kind of address decoding that 
will assert the DACK (Dma ACKnowledge) line once the data is read.  Because 
this code works, we can logically deduce that the read to slot I/O register $6 
is wired to produce this signal, even if we can't prove it conclusively through 
the schematic of the card.

Writing works in a similar manner by monitoring the DMA REQ line, but instead 
of writing to slot I/O register $6 (which is a trigger for starting a DMA 
transfer) it writes to slot I/O register $0.  And, as we inferred through logic 
about the setting of the DACK line in the reading case, we can similarly infer 
that the DACK line is being set in a similar manner in the writing case.

The upshot is, even though Pseudo DMA transfers are still CPU intensive, they 
are faster than PIO transfers.  And when it comes to relatively slow CPUs like 
the 65C02, faster is better.


And They All Lived Happily Ever After-ish
-----------------------------------------

So in looking at the code for the WRITE command, I could see that I had it 
using register $6 for the data transfer, which, as we can see from the short 
digression above, won't work.  Fixing this to look at the correct register ($0) 
brought things into alignment, and a thorough test of "Pitch Dark" confirmed 
that I had indeed solved the problem.

So, in the final analysis, I was finally able to restore decency to Apple2 and 
play "Pitch Dark" on it to boot.  But was it worth it?  In my opinion the 
answer is an unequivocal "yes", and not just because it enables the use of hard 
drive images in emulators.

The reason this little exercise in digital archaeology was worth the effort 
expended is that it underscores a problem that seems to have gone largely 
underappreciated: the early microcomputers, in some respects, are very well 
documented; however, in many others, they are not--and the knowledge of exactly 
how they worked is in danger of disappearing.  The fact that the documentation 
for the Apple High Speed SCSI card is of a consumer oriented nature with very 
little technical content was of little use in figuring out how it really 
worked, and shows a marked contrast to the early days of Apple where they 
published very detailed information about their computers and how they worked, 
including schematics and source code.

All that is to say that unless those of us who still remember these artifacts 
and have the ability to analyze them to tease out their inner workings actually 
*do* so, these things *will* disappear, and they will pass out of human memory 
forever.


--------------
v1.0: 6/3/2019
v1.1: 1/10/2020