Site Tools


Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
articles:iicplus_smartport_secrets [2018/06/12 15:44]
M.G. [Booting Slot 6]
articles:iicplus_smartport_secrets [2018/07/05 15:17] (current)
M.G. [The 3.5 Floppy Format]
Line 1: Line 1:
 ====== Apple IIc Plus: SmartPort Secrets ====== ====== Apple IIc Plus: SmartPort Secrets ======
  
-** WORK IN PROGRESS **+Written on 2018/06/12.
  
-I've been actively working on disassembling the Apple IIc Plus firmware in order to find out how its 3.5" firmware works with the unique hardware of the machine to support the "​dumb"​ [[https://​archive.org/​details/​bitsavers_appledisksleSidedERSSep86_1465091|3.5"​ floppy drives]]. 
  
-A lot of it involves knowing how the 3.5 floppies are formatted at the low-level. ​ The Woz state machine is the basis for operations with both the 3.5 and 5.25 floppies, so there are bound to be similarities between the the low level formats, and there are.  In particular, the following are common to both:+I've been actively working on disassembling the Apple IIc Plus firmware in order to find out how its 3.5%%"​%% firmware works with the unique hardware of the machine to support the "​dumb"​ [[https://​archive.org/​details/​bitsavers_appledisksleSidedERSSep86_1465091|3.5"​ floppy drives]]. 
 + 
 +A lot of it involves knowing how the 3.5%%"​%% ​floppies are formatted at the low-level. ​ The Woz state machine is the basis for operations with both the 3.5%%"​%% ​and 5.25%%"​%% ​floppies, so there are bound to be similarities between the the low level formats, and there are.  In particular, the following are common to both:
  
   * Address and data prologues   * Address and data prologues
Line 11: Line 12:
   * 6&2 disk bytes ("​nibbles"​)   * 6&2 disk bytes ("​nibbles"​)
  
-===== The 3.5 Floppy Format =====+===== The 3.5" ​Floppy Format =====
  
-The 3.5 floppy sectors are formatted as follows:+The 3.5%%"​%% ​floppy sectors are formatted as follows:
  
 | Address Field | Data Field | | Address Field | Data Field |
  
-The address field of the 3.5 floppy is as follows+The address field of the 3.5%%"​%% ​floppy is as follows
  
 | 5+ self-syncs | $D5 $AA $96 | TT SS DD FF KK | $DE $AA "​off"​ | | 5+ self-syncs | $D5 $AA $96 | TT SS DD FF KK | $DE $AA "​off"​ |
Line 25: Line 26:
 The data field is: The data field is:
  
-| 5 self-syncs | $D5 $AA $AD | 699 disk bytes | KK KK KK KK | $DE $AA "​off"​ |+| 5 self-syncs | $D5 $AA $AD | SS | 699 disk bytes | KK KK KK KK | $DE $AA "​off"​ | 
 + 
 +In this case, we can see the address and data prologues are the same between the 5.25%%"​%% and 3.5%%"​%% formats. The epilogues are defined differently. ​ In we are used to $DE $AA $EB, but instead of $EB we have "​off"​... this is defined in the official documentation as a "pad byte where the drive electronics were turned off." ​ Code that reads a 3.5%%"​%% disk should not assume the byte contains anything useful. ​ In fact, ProDOS ignores this byte even when reading a 5.25%%"​%% floppy.
  
-In this case, we can see the address and data prologues are the same between ​the 5.25 and 3.5 formats. The epilogues are defined differently. ​ In we are used to $DE $AA $EB, but instead of $EB we have "off"​... this is defined ​in the official documentation as a "pad byte where the drive electronics were turned off." ​ Code that reads a 3.5" disk should not assume ​the byte contains ​anything useful. ​ In factProDOS ignores this byte even when reading a 5.25 floppy.+Unlike ​the 5.25%%"%% floppy address header, the 3.5%%"%% floppy address header ​is coded in 6&2 format and can be decoded from the standard nibble table..  ​E.g. if SS contains $96, the address is for sector 0, if it contains ​$97the address is for sector 1.
  
-Unlike the 5.25 floppy address header, the 3.5 floppy address header is coded in 6&2 format and can be decoded from the standard nibble table.. ​ E.g. if SS contains $96, the address is for sector ​0, if it contains $97, the address is for sector 1.+The 699 disk bytes encode a 12-byte ​sector ​tag + 512 data bytes.
  
 ===== The 5.25 Floppy Format ===== ===== The 5.25 Floppy Format =====
  
-The disk format we are all used to with the 5 1/4 floppies is well-explained in __[[http://​www.classiccmp.org/​cini/​pdf/​Apple/​Beneath%20Apple%20DOS.pdf|Beneath Apple DOS]]__. ​ To summarize what a sector header looks like for one:+The disk format we are all used to with the 5.25%%"​%% ​floppies is well-explained in __[[http://​www.classiccmp.org/​cini/​pdf/​Apple/​Beneath%20Apple%20DOS.pdf|Beneath Apple DOS]]__. ​ To summarize what a sector header looks like for one:
  
 | self-syncs | $D5 $AA $96 | VV VV TT TT SS SS KK KK | $DE $AA $EB | | self-syncs | $D5 $AA $96 | VV VV TT TT SS SS KK KK | $DE $AA $EB |
  
-In the case of the 5.25 floppy, the volume, track, and sector are encoded in the 4&4 format - each byte is split into the odd and even bits, interleaved with ones and written to the disk.  Decoding involves reading the first byte, shifting it, and ANDing it with the second byte.+In the case of the 5.25%%"​%% ​floppy, the volume, track, and sector are encoded in the 4&4 format - each byte is split into the odd and even bits, interleaved with ones and written to the disk.  Decoding involves reading the first byte, shifting it, and ANDing it with the second byte.
  
 ===== What's in an Aux Firmware Bank, Anyway? ===== ===== What's in an Aux Firmware Bank, Anyway? =====
Line 77: Line 80:
 </​code>​ </​code>​
  
-Note my comments reflecting my surprise at finding this buried in the Apple IIc Plus firmware. ​ This is code that clearly reads the 4 values from the address field of a 5.25 floppy. ​ But why is it here?  I left that question in my head as I continued disassembly.+Note my comments reflecting my surprise at finding this buried in the Apple IIc Plus firmware. ​ This is code that clearly reads the 4 values from the address field of a 5.25%%"​%% ​floppy. ​ But why is it here?  I left that question in my head as I continued disassembly.
  
 ===== Things that Lurk in the ROM ===== ===== Things that Lurk in the ROM =====
Line 93: Line 96:
 </​code>​ </​code>​
  
-Okay, that's very interesting. ​ The SmartPort code clearly expects and special cases a reference to slot 6, which as we know is used for 5.25 floppies in the IIc Plus (and %%//%%c).+Okay, that's very interesting. ​ The SmartPort code clearly expects and special cases a reference to slot 6, which as we know is used for 5.25%%"​%% ​floppies in the IIc Plus (and %%//%%c).
  
 Well, time to go poking around. Well, time to go poking around.
  
-===== Booting ​Slot 6 =====+===== Just How Does the IIc Plus Boot Slot 6=====
  
 On a hunch, I decided to go looking at the boot code for the machine. ​ It starts like this: On a hunch, I decided to go looking at the boot code for the machine. ​ It starts like this:
Line 157: Line 160:
  
 <​code>​ <​code>​
-        ​sec                                     ; this is the "​Intelligent Disk Device"​ entry point+LC50A:  ​sec                                     ; this is the "​Intelligent Disk Device"​ entry point
         bcs     ​LC50E ​                          ; ​         bcs     ​LC50E ​                          ; ​
-        ​clc                                     ; this is the SmartPort entry point+LC50D:  ​clc                                     ; this is the SmartPort entry point
 LC50E: ​ lda     #​$C5 ​                           ; a slot 5 reference LC50E: ​ lda     #​$C5 ​                           ; a slot 5 reference
 LC510: ​ sta     ​$07F8 ​                          ; save in screen hole LC510: ​ sta     ​$07F8 ​                          ; save in screen hole
Line 196: Line 199:
         jsr     ​LC64E ​                          ; call slot 6 ProDOS block device driver         jsr     ​LC64E ​                          ; call slot 6 ProDOS block device driver
         eor     #​$28 ​                           ; see if A=$28, the error code for no device connected         eor     #​$28 ​                           ; see if A=$28, the error code for no device connected
-        bne     ​LC775 ​                          ; if no error, don't exit yet+        bne     ​LC775 ​                          ; if not that error, don't exit yet
         rts                                     ; ​         rts                                     ; ​
 LC775: ​ bit     ​LC0E9 ​                          ; IWM - turn on drive motor of the unit we just accessed LC775: ​ bit     ​LC0E9 ​                          ; IWM - turn on drive motor of the unit we just accessed
Line 204: Line 207:
 </​code>​ </​code>​
  
-OK, so now we could look at $C58E, but I already know what's there, it's code that's been in every Apple %%//​%%c: ​ a routine to generate a denibbilizing ​routine ​that 5.25 boot sectors expect to be present.+OK, so now we could look at $C58E, but I already know what's there, it's code that's been in every Apple %%//​%%c: ​ a routine to generate a denibbilizing ​table in page 3 that 5.25%%"​%% ​boot sectors expect to be present.
  
 When that returns, we go back to the code in slot 6 that brought us here, that mostly looks like the original %%//%%c boot code. When that returns, we go back to the code in slot 6 that brought us here, that mostly looks like the original %%//%%c boot code.
  
-So, about that device command $FF?  I suspect ​it's "go boot that thing if possible"​+===== Look Ma, No DOS! ===== 
 + 
 +OK, we found what looks like a nice little ProDOS block device and SmartPort driver in the IIc Plus ROM, but does it work? 
 + 
 +Well, it turns out that's really easy to test. The IIc Plus has a built-in mini-assembler that is up to the task.  So let's test the block device interface. ​ So I'll reboot the machine without a disk in the drive, so we know that the we are just using the firmware. ​ For testing, I then inserted a formatted ProDOS disk. 
 + 
 +<​code>​ 
 +]CALL -151 
 +*! 
 +!300:LDX #5 
 +! LDA 320,X 
 +! STA 42,X 
 +! DEX 
 +! BPL 302 
 +! JSR C64E 
 +! STA 330 
 +! STX 331 
 +! STY 332 
 +! RTS 
 +
 +*320:00 60 00 10 02 00 
 +</​code>​ 
 + 
 +What we have here is a small routine to set up a block device call and do it through the entry point we found. ​ At $320, I've asked for the STATUS call ($00) for slot 6, drive 1 ($60 in terms of ProDOS unit numbers). ​ I've also set up the buffer address to $1000 and block number to $0002. ​ We don't need them for the STATUS call, but they will be handy later. ​ Finally, after the call completes, we put the values of A, X, and Y somewhere we can read them.  The A register always contains an error code, $00 if no error. ​ For STATUS, X and Y contain the low and high bytes of the number of blocks on the device. 
 + 
 +Ready for action: 
 + 
 +<​code>​ 
 +*300G 
 +*330.332 
 +0330- 00 18 01 
 +
 +</​code>​ 
 + 
 +Success! ​ $0118 blocks were indicated for the device. ​ That's 280 in decimal, and exactly how many blocks are on a standard Apple II 5.25%%"​%% floppy disk.  
 + 
 +So does it read a disk? 
 + 
 +<​code>​ 
 +*320:01 
 +*300G 
 +*330 
 +300- 00 
 +*1000.100F 
 +1000- 00 00 03 00 FC 50 52 4F 
 +1008- 44 4F 53 2E 32 2E 34 2E 
 +
 +</​code>​ 
 + 
 +That's exactly what we expect to see at block two of this disk, which is the first volume directory block. ​ The contents are two bytes for the link to the previous block (none), two bytes for the link to the next block (block 3), a byte for the storage type ($F) and name length ($C) of the volume, followed by the volume name, which in this case is ''​PRODOS.2.4.2''​. 
 + 
 +There are two more commands we can test, WRITE ($02) and FORMAT ($03): 
 + 
 + 
 +<​code>​ 
 +*320:02 
 +*300G 
 +*330 
 +300- 00 
 +*320:03 
 +*300G 
 +</​code>​ 
 + 
 +Well... I now have a freshly-blanked disk.  The formatting code appears to use the "​hyper"​ method, it took very little time at all. 
 + 
 +So, about that device command $FF?  I initially suspected that it's "go boot that thing if possible" ​since it appears in the boot ROM, however this is not borne out by testing: 
 + 
 +<​code>​ 
 +*320:FF 
 +*300G 
 +*330 
 +300- 00 
 +*1000.100F 
 +1000- 00 00 00 00 00 00 00 00 
 +1008- 00 00 00 00 00 00 00 00 
 +</​code>​ 
 + 
 +It appears that it just reads the block, and nothing else.  So the boot code reads block 0, and then goes to the old boot code to read track 0, sector 0.  The net effect is that all of block 0 is in RAM at $0800, though. 
 + 
 +===== ProDOS Driver Tricks ===== 
 + 
 +Now the question is, what happens when we replace the Disk II driver in ProDOS with the firmware driver? ​ It's actually pretty easy to find out. 
 + 
 +ProDOS keeps a device driver address table at $BF10-$BF1F in the Global Page.  The first 16 bytes are for each slot's drive 1, and the second are for each slot's drive 2.  Normally, the address for a Disk II is $D000, which is the address for the RAM-based driver within ProDOS itself. 
 + 
 +So, to change the driver to the firmware driver we simply do (after booting ProDOS): 
 + 
 +<​code>​ 
 +*BF1C:4E C6 
 +*BF2C:4E C6 
 +*CAT,S6 
 + 
 +/​PRODOS.2.4.2 
 + 
 + ​NAME ​          ​TYPE ​ BLOCKS ​ MODIFIED 
 + 
 + ​VIEW.README ​    ​BAS ​      ​1 ​ 15-SEP-16 
 +*BITSY.BOOT ​     SYS       ​1 ​ 15-SEP-16 
 +*QUIT.SYSTEM ​    ​SYS ​      ​1 ​ 15-SEP-16 
 +*BASIC.SYSTEM ​   SYS      21  30-AUG-16 
 +*COPYIIPLUS.8.4 ​ SYS      56  28-FEB-89 
 +*CAT.DOCTOR ​     SYS      28  22-FEB-90 
 +... 
 +</​code>​ 
 + 
 +Success! 
 + 
 +===== What About SmartPort? ===== 
 + 
 +SmartPort has a lot of capabilities,​ and rather than write code to display everything it can tell us, I [[https://​github.com/​mgcaret/​davex-mg-utils/​commit/​75fb9020ba04f3abc16a5dd2cfd6857a102a0961|modified]] the Davex deschw command to do it instead. ​ Here's a screenshot of it running on one of my machines: 
 + 
 +{{:​articles:​iicplus_smartport.jpg?​nolink&​400|}} 
 + 
 +It looks like it doesn'​t give good values for some of the device details, but it shows that it basically works. 
 + 
 +Cool. 
 + 
 +===== Conclusion =====
  
 +That a secret device driver has been lurking in the Apple IIc Plus for decades without anything being written on it is... amazing. ​ I'd like to think I was the first person outside of Apple to know about it, but who knows?
  
-More to come...+In any case, it's one hell of an Easter egg.
  
 +It also goes to show the twists and turns that reverse engineering old computers can take.  I was originally attempting to understand the 3.5%%"​%% floppy code in the Apple IIc Plus, and along that journey, I got to take a subquest and discover something completely unexpected.
  
 +---
  
 +I'd like to thank [[http://​leon.bottou.org/​start|Léon Bottou]], whose additional work on understanding the MIG chip and subsequent development of a [[https://​github.com/​leonbottou/​kegs-universal|working Apple IIc Plus emulation]] gave me motivation to continue disassembling the Apple IIc Plus code and provided an easy testbed to work with before trying it out on real hardware.