this file was slightly edited from the original release which is available
here: https://groups.yahoo.com/neo/groups/chameleon_64/conversations/messages/3531

Turbo Chameleon 64 RTC Readme
=============================

Introduction
------------

This text describes the files found on
this disk to read or set the real time
clock built into the Turbo Cameleon 64.

Written by Paul Foerster
(paul.foerster@gmail.com), based on
Yahoo Chameleon 64 group, article #349
by Peter Wendrich (pwsoft@syntiac.com)

The Turbo Chameleon 64 contains a
PFC2123 real time clock chip. This chip
can store date and time information for
year, month, day-of-week, day, hour,
minute and second in this order and in
BCD format. It does not store any
century information, though.

I hope this documentation is useful,
especially for people wanting the time
set at C64 startup time or for example
GEOS boot time.{$a0}It should be rather
simple to turn this routine into a GEOS
driver and put it into its autostart.


Contents
--------

readme.txt
  This file.

rtc-r.prg
  A demo BASIC program containing the
  assembly routine to read the RTC
  inside data statements.

  When run, it loads the assembly
  routine into the C64 memory, reads
  out the Turbo Chameleon's clock chip
  and displays the time read from the
  RTC in a nicely formatted way.

  The location where the assembly
  routine should be stored in memory
  can be set in line 60. You can also
  set the location of the time buffer
  in line 70. When loading the assembly
  routine from the data lines to
  memory, the start of the time buffer
  is patched to the location you
  specified in line 70.

  This program is best run in Turbo
  Chameleon's turbo mode!

rtc-w.prg
  A{$a0}demo BASIC program containing the
  assembly routine to set the RTC
  inside data statements.

  When run, it does essentially the
  same thing as does rtc-r.prg
  internally with the exception that it
  then asks for a valid date and time
  and will set the RTC accordingly. You
  will not be asked to enter the day of
  week. This is calculated from the
  date entered.

  As this is a demo program only,
  please make sure to enter only valid
  date and time information. There is
  no check for validity of the data
  entered.

  It can be configured the same way
  that rtc-r.prg can be configured.

  This program is best run in Turbo
  Chameleon's turbo mode.

rtc-r.asm
rtc-w.asm
  These are the assembly language
  source files for the RTC reading and
  writing routines exported as
  sequential plain text files by the
  the Turbo Macro Pro 7.2 assembler.

rtc-r.prg
rtc-w.prg
  These two contain the assembled code
  from the above mentioned two source
  files. The starting address is set to
  $0900 and the time buffer starts at
  the location *-$08 or $08f8
  respectively. 
  Both routines are freely relocatable
  in memory!


The Time-Buffer
---------------

The time buffer is an 8-byte buffer
used to hold the time which is either
sent to or read from the Chameleon's
RTC. It holds the values in BCD format,
i.e. CC{$a0}YY{$a0}MM{$a0}DY{$a0}DD{$a0}HH{$a0}MM{$a0}SS, which is
century, year, month, day-of-week, day,
hours, minutes and seconds.

The PFC2123 stores the day-of-week as a
number in the range 0 through 6, with 0
representing Sunday through 6 for
Saturday.

Note that the PFC2123 RTC chip does not
store century information, so this
value should always be assumed to be
$20! In fact, the read routine will
always put a $20 there while the write
routine will simply ignore it for the
fact that a century can't be written
to the RTC anyway.

Just make sure you have valid values in
the time buffer before executing the
write routine, unless you want garbage
values appear in your RTC's registers,
that is.


Enjoy! :-)

Paul Foerster
paul.foerster@gmail.com
Sat, 04-Jan-2014, 19:16:47 :-)