1926 lines
93 KiB
Plaintext
1926 lines
93 KiB
Plaintext
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
|