prodos-drivers/clocks
Joshua Bell 7bbc96924b Add SETUP.SYSTEM and build .SETUP files
This is an alternate approach proposed by Sean Nolan in 1987 which
allows placing the driver files in a subdirectory of the root volume
to avoid clutter and file ordering issues. Only a SETUP.SYSTEM file is
needed at the top level, and the drivers go into a SETUPS/ directory.

All drivers here (except QUIT.SYSTEM and SETUP.SYSTEM itself) have
alternate forms built into the /DRIVERS/SETUPS/ directory as XYZ.SETUP
instead of XYZ.SYSTEM. If you choose to use SETUP.SYSTEM, place these
.SETUP files in your SETUPS/ directory. The naming doesn't matter -
any SYS or BIN file can be used - but this convention makes
distribution easier. These .SETUP files do **NOT** chain to the next
file - that's handled by SETUP.SYSTEM itself.

Resolves #16
2024-01-30 21:16:32 -08:00
..
cricket Add SETUP.SYSTEM and build .SETUP files 2024-01-30 21:16:32 -08:00
dclock Add SETUP.SYSTEM and build .SETUP files 2024-01-30 21:16:32 -08:00
fujinet Add SETUP.SYSTEM and build .SETUP files 2024-01-30 21:16:32 -08:00
jumbo Add SETUP.SYSTEM and build .SETUP files 2024-01-30 21:16:32 -08:00
ns.clock Add SETUP.SYSTEM and build .SETUP files 2024-01-30 21:16:32 -08:00
romx Add SETUP.SYSTEM and build .SETUP files 2024-01-30 21:16:32 -08:00
Makefile Add build options to suppress success and/or failure logging 2023-05-01 19:47:10 -07:00
README.md Add "jumbo" clock driver, an amalgamation of the others 2022-11-26 20:29:38 -08:00

ProDOS Clock Drivers

Other than the Apple IIgs model, the Apple II did not ship with a real-time system clock. Many third party Apple II system clocks were produced in the 1980s, and many new system clocks are available, either as entirely new designs or recreations.

The ProDOS operating system for the Apple II personal computer line natively supports the Thunderclock real-time clock card, but there is a protocol for custom clock drivers to be installed:

  • Check MACHID bit 0 to see if a clock is already active; abort if so.
  • Optional: Probe hardware to determine if the clock is present; abort if not.
  • Relocate the clock driver to LC bank 1, at the address at DATETIME+1
  • Update DATETIME to be a JMP instruction.
  • Optional: Chain to the next .SYSTEM file.

In addition:

  • The clock driver must fit into 125 bytes.
  • The driver may dirty $200-$207 but other memory must be restored if modified.
  • When invoked, the clock driver should read the clock hardware and encode the date and time into DATELO/DATEHI and TIMELO/TIMEHI.
  • ProDOS calls the clock driver when GET_TIME is called, and on every call (CREATE, RENAME, etc) that might need the date and time.

See https://prodos8.com/docs/techref/adding-routines-to-prodos/ for more information.

Included drivers

This directory includes drivers for the following real-time clocks:

All follow the above protocol: install only if there is not already a clock, probe for the clock before installing, and chain to the next driver.

In addition, the "jumbo" directory combines the other driver installers to create a single unified clock driver installer. See its README for more details.