<!doctype linuxdoc system>
<article>
-
<title>Apple ][ specific information for cc65
<author><url url="mailto:ol.sc@web.de" name="Oliver Schmidt">
-<date>2014-04-10
<abstract>
An overview over the Apple ][ runtime system as it is
<sect>Binary format<p>
The standard binary file format generated by the linker for the
-Apple ][ target is an <url name="AppleSingle"
+Apple ][ target is an <url name="AppleSingle"
url="http://kaiser-edv.de/documents/AppleSingle_AppleDouble.pdf"> file.
The default load address is $803.
<descrip>
- <tag>Disk File I/O</tag>
+ <tag>Disk file I/O</tag>
There's no disk file I/O support. Any attempt to use it yields an error with
<tt/errno/ set to <tt/ENOSYS/. This implicitly means that loadable drivers
are in general not functional as they depend on disk file I/O. Therefore the statically
<sect1>Direct console I/O<p>
-<descrip>
+The Apple ][ has no color text mode. Therefore the functions
+<tt/textcolor()/, <tt/bgcolor()/ and <tt/bordercolor()/ have no effect.
- <tag/Color/
- The Apple ][ has no color text mode. Therefore the functions textcolor(),
- bgcolor() and bordercolor() have no effect.
-</descrip><p>
+<sect1>Random number generator<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 ($BF90 to $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/<NO DATE>/.
+
+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 interested 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.
ProDOS associates a file type and an auxiliary type with each file.
These type specifications are separate from the file's name, unlike
Windows which uses the file name's suffix (a.k.a.
- extension) to specify the file type. For example, <tt/.exe/,
+ extension) to specify the file type. For example, <tt/.exe/,
<tt/.doc/, or <tt/.bat/.
- The ProDOS low-level
- Machine-Language Interface (MLI) functions for creating and opening
+ The ProDOS low-level
+ Machine-Language Interface (MLI) functions for creating and opening
files require these types to be specified. And if they don't match
with the file being opened, the operation may fail.
In contrast, the ISO C function <tt/fopen()/ and the POSIX function
<tt/open()/ have no parameter to specify either a file type or an
auxiliary type. Therefore, some additional mechanism for specifying
- the file types is needed.
-
+ the file types is needed.
+
<tag>Specifying the File Type and Auxiliary Type</tag>
There are two global variables provided that allow the file type
extern unsigned char _filetype; /* Default: PRODOS_T_BIN */
extern unsigned int _auxtype; /* Default: 0 */
</verb>
- </tscreen>
+ </tscreen>
The header file <tt/apple2_filetype.h/ also defines many values
that can be used to set these variables. It is included in
<tag>Example</tag>
A text file cannot be created with just the
- standard C functions because they default to the binary type
+ standard C functions because they default to the binary type
<tt/PRODOS_T_BIN/. The <tt/_filetype/ variable must be set to
- <tt/PRODOS_T_TXT/ to create a text file.
-
- For a text file,
+ <tt/PRODOS_T_TXT/ to create a text file.
+
+ For a text file,
<tt/_auxtype/ specifies the record length. A zero record
length text file is referred to as a sequential text file.
- This is equivalent to text files on
+ This is equivalent to text files on
other operating systems, except that the line terminator is a
- carriage return instead of a line-feed (Linux/BSD/MacOS) or
+ carriage return instead of a line-feed (Linux/BSD/MacOS) or
carriage return, line-feed pair (Windows).
-
- The "sequential" text file terminology is in contrast to a
+
+ The "sequential" text file terminology is in contrast to a
"random-access" text file which would
- have a fixed-length, non-zero record length, so that the
+ have a fixed-length, non-zero record length, so that the
file position of any individual record can be calculated.
-
+
For this example, the
<tt/_auxtype/ does not need to be set because it defaults to
- the desired value, which is zero. To be more explicit,
+ the desired value, which is zero. To be more explicit,
<tt/_auxtype/ can also be set to <tt/PRODOS_AUX_T_TXT_SEQ/
which is defined as zero.
}
}
</verb>
- </tscreen>
+ </tscreen>
</descrip><p>
freely, subject to the following restrictions:
<enum>
-<item> The origin of this software must not be misrepresented; you must not
- claim that you wrote the original software. If you use this software
- in a product, an acknowledgment in the product documentation would be
- appreciated but is not required.
-<item> Altered source versions must be plainly marked as such, and must not
- be misrepresented as being the original software.
-<item> This notice may not be removed or altered from any source
- distribution.
+<item> The origin of this software must not be misrepresented; you must not
+ claim that you wrote the original software. If you use this software
+ in a product, an acknowledgment in the product documentation would be
+ appreciated but is not required.
+<item> Altered source versions must be plainly marked as such, and must not
+ be misrepresented as being the original software.
+<item> This notice may not be removed or altered from any source
+ distribution.
</enum>
</article>
projects / cc65 / blobdiff