From: Oliver Schmidt <ol.sc@web.de>
Date: Tue, 13 Nov 2018 17:31:53 +0000 (+0100)
Subject: Added target docs on the clock_... functions.
X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=4b42d6ad54a9e8d3adc801fca7b19092396a6c42;p=cc65

Added target docs on the clock_... functions.
---

diff --git a/doc/apple2.sgml b/doc/apple2.sgml
index aa3089957..f61a8a68e 100644
--- a/doc/apple2.sgml
+++ b/doc/apple2.sgml
@@ -469,25 +469,47 @@ BASIC.SYSTEM) there are some limitations for DOS 3.3:
 
 <sect1>Direct console I/O<p>
 
-<descrip>
-
-  <tag/Color/
-  The Apple&nbsp;&rsqb;&lsqb; has no color text mode. Therefore the functions textcolor(),
-  bgcolor() and bordercolor() have no effect.
-
-</descrip><p>
+The Apple&nbsp;&rsqb;&lsqb; has no color text mode. Therefore the functions
+<tt/textcolor()/, <tt/bgcolor()/ and <tt/bordercolor()/ have no effect.
 
 
 <sect1>Random number generator<p>
 
-<descrip>
-
-  <tag/Random number seed/
-  The random number seed is generated from the time the program waits for user input.
-  Therefore it is necessary to wait for at least one user keypress either via Standard
-  I/O or via Direct console I/O before initializing the pseudo random number generator.
-
-</descrip><p>
+The random number seed is generated from the time the program waits for user input.
+Therefore it is necessary to wait for at least one user keypress either via Standard
+I/O or via Direct console I/O before initializing the pseudo random number generator.
+
+
+<sect1>Realtime clock<p>
+
+There are several types of realtime clocks. It's not desirable to have specific code
+for all of them. As ProDOS 8 supports file timestamps, realtime clock owners usually
+use ProDOS 8 drivers for their realtime clock. Those drivers read the realtime clock
+and write the result to the date/time location in RAM (&dollar;BF90 to &dollar;BF93).
+ProDOS 8 reads the date/time from that RAM location. If there's no realtime clock the
+RAM location keeps containing zeros. ProDOS 8 uses those zeros as timestamps and the
+files show up in a directory as <tt/&lt;NO DATE&gt;/.
+
+There's no common interface to set realtime clocks so if a realtme clock <bf/IS/
+present there's just nothing to do. However, if there's <bf/NO/ realtime clock present,
+the user might very well be interest to "manually" set the RAM location in order to
+have timestamps. But he surely doesn't want to manually set the RAM location over and
+over again. Rather he wants to set it just once after booting ProDOS 8.
+
+From that perspective it makes most sense to not set both the date and the time but
+rather only set the date and have the time just stay zero. Then files show up in a
+directory as <tt/DD-MON-YY  0:00/.
+
+So <tt/clock_settime()/ checks if the current time equals 0:00. If it does <bf/NOT/
+then a realtime clock is supposed to be active and <tt/clock_settime()/ fails with
+<tt/ERANGE/. Otherwise <tt/clock_settime()/ sets the date - and completely ignores
+the time provided as parameter.
+
+<tt/clock_getres()/ too checks if the current time equals 0:00. If it does <bf/NOT/
+then a realtime clock is supposed to be active and <tt/clock_getres()/ returns a time
+resolution of one minute. Otherwise <tt/clock_getres()/ presumes that the only one
+who sets the RAM location is <tt/clock_settime()/ and therefore returns a time
+resolution of one day.
 
 
 
diff --git a/doc/apple2enh.sgml b/doc/apple2enh.sgml
index fbdba908b..649c6ef9f 100644
--- a/doc/apple2enh.sgml
+++ b/doc/apple2enh.sgml
@@ -470,25 +470,47 @@ BASIC.SYSTEM) there are some limitations for DOS 3.3:
 
 <sect1>Direct console I/O<p>
 
-<descrip>
-
-  <tag/Color/
-  The enhanced&nbsp;Apple&nbsp;//e has no color text mode. Therefore the functions
-  textcolor(), bgcolor() and bordercolor() have no effect.
-
-</descrip><p>
+The enhanced&nbsp;Apple&nbsp;//e has no color text mode. Therefore the functions
+<tt/textcolor()/, <tt/bgcolor()/ and <tt/bordercolor()/ have no effect.
 
 
 <sect1>Random number generator<p>
 
-<descrip>
-
-  <tag/Random number seed/
-  The random number seed is generated from the time the program waits for user input.
-  Therefore it is necessary to wait for at least one user keypress either via Standard
-  I/O or via Direct console I/O before initializing the pseudo random number generator.
-
-</descrip><p>
+The random number seed is generated from the time the program waits for user input.
+Therefore it is necessary to wait for at least one user keypress either via Standard
+I/O or via Direct console I/O before initializing the pseudo random number generator.
+
+
+<sect1>Realtime clock<p>
+
+There are several types of realtime clocks. It's not desirable to have specific code
+for all of them. As ProDOS 8 supports file timestamps, realtime clock owners usually
+use ProDOS 8 drivers for their realtime clock. Those drivers read the realtime clock
+and write the result to the date/time location in RAM (&dollar;BF90 to &dollar;BF93).
+ProDOS 8 reads the date/time from that RAM location. If there's no realtime clock the
+RAM location keeps containing zeros. ProDOS 8 uses those zeros as timestamps and the
+files show up in a directory as <tt/&lt;NO DATE&gt;/.
+
+There's no common interface to set realtime clocks so if a realtme clock <bf/IS/
+present there's just nothing to do. However, if there's <bf/NO/ realtime clock present,
+the user might very well be interest to "manually" set the RAM location in order to
+have timestamps. But he surely doesn't want to manually set the RAM location over and
+over again. Rather he wants to set it just once after booting ProDOS 8.
+
+From that perspective it makes most sense to not set both the date and the time but
+rather only set the date and have the time just stay zero. Then files show up in a
+directory as <tt/DD-MON-YY  0:00/.
+
+So <tt/clock_settime()/ checks if the current time equals 0:00. If it does <bf/NOT/
+then a realtime clock is supposed to be active and <tt/clock_settime()/ fails with
+<tt/ERANGE/. Otherwise <tt/clock_settime()/ sets the date - and completely ignores
+the time provided as parameter.
+
+<tt/clock_getres()/ too checks if the current time equals 0:00. If it does <bf/NOT/
+then a realtime clock is supposed to be active and <tt/clock_getres()/ returns a time
+resolution of one minute. Otherwise <tt/clock_getres()/ presumes that the only one
+who sets the RAM location is <tt/clock_settime()/ and therefore returns a time
+resolution of one day.
 
 
 
diff --git a/doc/c128.sgml b/doc/c128.sgml
index dd9af2d6b..84b601ab7 100644
--- a/doc/c128.sgml
+++ b/doc/c128.sgml
@@ -339,6 +339,13 @@ The default drivers, <tt/mouse_stddrv (mouse_static_stddrv)/, point to <tt/c128-
 <sect>Limitations<p>
 
 
+<sect1>Realtime clock<p>
+
+The realtime clock functions use the CIA1 TOD clock. As that clock only stores
+the time but not the date, the date set by <tt/clock_settime()/ ist simply stored
+inside the C library for retrieval in the same program via <tt/clock_gettime()/.
+
+
 
 <sect>Other hints<p>
 
diff --git a/doc/c64.sgml b/doc/c64.sgml
index 328a77ab6..8c910666c 100644
--- a/doc/c64.sgml
+++ b/doc/c64.sgml
@@ -418,6 +418,13 @@ The default drivers, <tt/mouse_stddrv (mouse_static_stddrv)/, point to <tt/c64-1
 <sect>Limitations<p>
 
 
+<sect1>Realtime clock<p>
+
+The realtime clock functions use the CIA1 TOD clock. As that clock only stores
+the time but not the date, the date set by <tt/clock_settime()/ ist simply stored
+inside the C library for retrieval in the same program via <tt/clock_gettime()/.
+
+
 
 <sect>Other hints<p>
 
diff --git a/doc/cbm510.sgml b/doc/cbm510.sgml
index 5c7c0f767..5df8f06f6 100644
--- a/doc/cbm510.sgml
+++ b/doc/cbm510.sgml
@@ -242,6 +242,13 @@ The default drivers, <tt/mouse_stddrv (mouse_static_stddrv)/, point to <tt/cbm51
 <sect>Limitations<label id="limitations"><p>
 
 
+<sect1>Realtime clock<p>
+
+The realtime clock functions use the CIA1 TOD clock. As that clock only stores
+the time but not the date, the date set by <tt/clock_settime()/ ist simply stored
+inside the C library for retrieval in the same program via <tt/clock_gettime()/.
+
+
 <sect1>Kernal and hardware access<p>
 
 Since the program runs in bank 0, and the kernal and all I/O chips are located
diff --git a/doc/cbm610.sgml b/doc/cbm610.sgml
index c1faefd51..49313c4d2 100644
--- a/doc/cbm610.sgml
+++ b/doc/cbm610.sgml
@@ -224,6 +224,13 @@ No mouse drivers are currently available for the Commodore 610.
 <sect>Limitations<label id="limitations"><p>
 
 
+<sect1>Realtime clock<p>
+
+The realtime clock functions use the CIA1 TOD clock. As that clock only stores
+the time but not the date, the date set by <tt/clock_settime()/ ist simply stored
+inside the C library for retrieval in the same program via <tt/clock_gettime()/.
+
+
 <sect1>Kernal and hardware access<p>
 
 Since the program runs in bank 1, and the kernal and all I/O chips are located