6502/cc65
1
0
Fork 0
mirror of https://github.com/cc65/cc65.git synced 2024-06-08 15:29:37 +00:00
Code Issues Projects Releases Wiki Activity

Added target docs on the clock_... functions.

Browse Source
This commit is contained in:
Oliver Schmidt 2018-11-13 18:31:53 +01:00
parent 83768a1e8a
commit 4b42d6ad54
6 changed files with 98 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
doc/apple2.sgml
View File

@ -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>
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.
<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>
<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.

48
doc/apple2enh.sgml
View File

@ -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>
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.
<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>
<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.

7
doc/c128.sgml
View File

@ -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>

7
doc/c64.sgml
View File

@ -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>

7
doc/cbm510.sgml
View File

@ -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

7
doc/cbm610.sgml
View File

@ -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