!pr1
!lm12
!rm75
ProDOS and Clock Drivers, with a...........Bob Sander-Cederlof
Commented Listing of ProDOS $F142-$F1BE

ProDOS is a new operating system which Apple expects to release to the public during the first quarter of 1984.  I am told that new computers and disk drives will be shipped with ProDOS rather than DOS 3.3.  Version 1.0 is already available to licensed developers (I have it).

Apple has released massive amounts of documentation to licensed developers, and has even been offering a full day class at $225 per seat in various cities around the country.  I attended the Dallas class on October 21st.  Even with all the help they are giving, there are still a lot of unclear details that can only be illuminated by well-commented assembly listings of the actual ProDOS code.  Apple will never publish these, so we will do it ourselves.

My first serious foray into ProDOS began at the request of Dan Pote, Applied Engineering.  Dan wanted me to modify the firmware of his Timemaster clock card so that it automatically had full compatibility with ProDOS.  Dan wanted all programs, even protected ones, which boot under ProDOS, to be able to read the date and time from his card.  Also, he wanted ProDOS to time/date stamp the files in the directory with his card, just as it does with Thunderclock.  (No small task, it turned out.)

ProDOS, when booting, searches the slots for a Thunderclock.  If it finds one, it marks a bit in the machine ID byte (MACHID, bit 0 of $BF98 = 1); it plugs two bytes at $F14D and F150 with $CN, where N is the slot number; and it stores a JMP opcode ($4C) at $BF06.

$BF06 is a standard vector to whatever clock routine is installed.  If no Thunderclock was found, an RTS opcode will be stored there.

The ProDOS boot slot search looks for these Thunderclock ID bytes:

       $CN00 = $08
       $CN02 = $28
       $CN04 = $58
       $CN08 = $70

After booting, ProDOS loads and executes the program called STARTUP.  The standard STARTUP program searches the slots for various cards and displays a list of what it finds.  Unfortunately this list seldom agrees with the true configuration in any of my computers.  For one thing, STARTUP examines different bytes than the boot search does.  In looking for a clock card, STARTUP wants:

       $CN00 = $08
       $CN01 = $78
       $CN02 = $28

If you do not have a Thunderclock, but do have some other clock, you have several options.  What I did for Dan was change the firmware of Timemaster so that it emulates Thunderclock.  ProDOS is convinced it has a Thunderclock, but you are saved the extra expense, and you gain extra features.

Another approach is to write a program which installs your own clock driver inside ProDOS.  Mike Owen, of Austin, Texas, did this for Dan.  After ProDOS boots it loads the first type SYS file it can find in the directory whose name ends with ".SYSTEM".  Normally this is "BASIC.SYSTEM", which then proceeds to execute STARTUP.  However, you can set up your disk with CLOCK.SYSTEM before BASIC.SYSTEM in the directory.

Write CLOCK.SYSTEM so that it begins at $2000, because all type SYS files load there.  The program should mark the clock ID bit in MACHID, punch a JMP opcode at $BF06, and look at the address in $BF07,BF08.  That address is the beginning of the clock driver inside the language card.  Right now that address is $F142, but it could change.

Your program should write enable the language card by two "LDA $C081" instructions in a row, and then copy your clock driver into the space starting at that address.  You can use up to 124 bytes.  If your driver has references to the clock slot, be sure to modify them to the actual slot you are using.  If your driver has internal references, be sure to modify them to point to the actual addresses inside the new physical location.

It is standard practice in peripheral firmware to  use the following code to find out which slot the card is in:

       JSR $FF58     A Guaranteed $60 (RTS opcode)
       TSX           Stack pointer
       LDA $100,X    Get $CN off stack

Many cards also use "BIT $FF58" as a means for setting the V-bit in the status register.  BE AWARE THAT ProDOS DOES NOT HAVE $60 AT $FF58 in the language card!!!!

The Thunderclock has two entries, at $CN08 and $CN0B, which assume that $CN is already in the X-register.  $CN0B allows setting the clock mode, and $CN08 reads the clock in the current mode.  The ProDOS driver calls on these two entries, as the following listing shows.

ProDOS maintains a full page at $BF00 called the System Global Page.  The definition of this page should not change, ever.  They say.  Locations $BF90-BF93 contain the current date and time in a packed format.  A system call will read the clock, if a driver is installed, and format the year-month-day-hour-minute into these four bytes.

Now here is a listing of the current Thunderclock driver, as labelled and commented by me.
