<!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 a binary program with a 4 byte DOS 3.3 header
-containing the load address and load length. The default load address is
-$803.
-
-<bf/AppleCommander 1.3.5/ or later (available at <url
-url="http://applecommander.sourceforge.net/">) includes the option <tt/-cc65/
-that allows to put binary files with a DOS 3.3 header onto disk images
-containing DOS 3.3 as well as ProDOS 8.
+Apple ][ target is an <url name="AppleSingle"
+url="http://kaiser-edv.de/documents/AppleSingle_AppleDouble.pdf"> file.
+The default load address is $803.
-For ProDOS 8 system programs the load address is fixed to $2000 so there
-is no need for a header. Thus the linker configuration
-<ref id="apple-sys-cfg" name="apple2-system.cfg"> for those programs
-omits the DOS 3.3 header. The right AppleCommander option to put system files
-without a header on a ProDOS 8 disk image is <tt/-p/.
+<bf/AppleCommander 1.4.0/ or later (available at <url
+url="https://applecommander.github.io/">) includes the option <tt/-as/ that
+allows to put AppleSingle files onto disk images containing DOS 3.3 as well
+as ProDOS 8.
<sect>Memory layout<p>
<tag><tt/STARTADDRESS:/ Program start address</tag>
Default: $803. Use <tt/-S <addr>/ to set a different start address.
- <tag><tt/__EXEHDR__:/ Executable file header</tag>
- Default: DOS 3.3 header (address and length). Use <tt/-D __EXEHDR__=0/ to omit
- the header.
+ <tag><tt/__EXEHDR__:/ AppleSingle executable file header</tag>
+ Default: Yes. Use <tt/-D __EXEHDR__=0/ to omit the AppleSingle header.
<tag><tt/__STACKSIZE__:/ C runtime stack size</tag>
Default: $800. Use <tt/-D __STACKSIZE__=<size>/ to set a different
<descrip>
+ <tag><tt/__EXEHDR__:/ AppleSingle executable file header</tag>
+ Default: Yes. Use <tt/-D __EXEHDR__=0/ to omit the AppleSingle header.
+
+ <tag><tt/__STACKSIZE__:/ C runtime stack size</tag>
+ Default: $800. Use <tt/-D __STACKSIZE__=<size>/ to set a different
+ stack size.
+
+ <tag><tt/__LCADDR__:/ Address of code in the Language Card</tag>
+ Default: $D400. Use <tt/-D __LCADDR__=<addr>/ to set a different
+ code address.
+
+ <tag><tt/__LCSIZE__:/ Size of code in the Language Card</tag>
+ Default: $C00. Use <tt/-D __LCSIZE__=<size>/ to set a different
+ code size.
+
+</descrip><p>
+
+
+<sect1><tt/apple2-hgr.cfg/<p>
+
+Configuration for a program including a hires page. See <tt>testcode/lib/apple/hgrtest.c</tt>
+for an example of such a program.
+
+Parameters:
+
+<descrip>
+
+ <tag><tt/STARTADDRESS:/ Program start address</tag>
+ Default: $803. Use <tt/-S <addr>/ to set a different start address.
+
+ <tag><tt/__EXEHDR__:/ AppleSingle executable file header</tag>
+ Default: Yes. Use <tt/-D __EXEHDR__=0/ to omit the AppleSingle header.
+
<tag><tt/__STACKSIZE__:/ C runtime stack size</tag>
Default: $800. Use <tt/-D __STACKSIZE__=<size>/ to set a different
stack size.
+ <tag><tt/__HIMEM__:/ Highest usable memory address presumed at link time</tag>
+ Default: $9600. Use <tt/-D __HIMEM__=<addr>/ to set a different
+ highest usable address.
+
<tag><tt/__LCADDR__:/ Address of code in the Language Card</tag>
Default: $D400. Use <tt/-D __LCADDR__=<addr>/ to set a different
code address.
<sect1><tt/apple2-overlay.cfg/<p>
-Configuration for overlay programs with the up to nine overlays. The overlay files
-don't include the DOS 3.3 header. See <tt>samples/overlaydemo.c</tt> for more
+Configuration for an overlay program with up to nine overlays. The overlay files
+don't include the AppleSingle header. See <tt>samples/overlaydemo.c</tt> for more
information on overlays.
Parameters:
<tag><tt/STARTADDRESS:/ Program start address</tag>
Default: $803. Use <tt/-S <addr>/ to set a different start address.
- <tag><tt/__EXEHDR__:/ Executable file header</tag>
- Default: DOS 3.3 header (address and length). Use <tt/-D __EXEHDR__=0/ to omit
- the header.
+ <tag><tt/__EXEHDR__:/ AppleSingle executable file header</tag>
+ Default: Yes. Use <tt/-D __EXEHDR__=0/ to omit the AppleSingle header.
<tag><tt/__STACKSIZE__:/ C runtime stack size</tag>
Default: $800. Use <tt/-D __STACKSIZE__=<size>/ to set a different
<sect1><tt/apple2-asm.cfg/<p>
-Configuration for a assembler programs which don't need a special setup.
+Configuration for an assembler program that doesn't need a special setup.
Parameters:
<tag><tt/STARTADDRESS:/ Program start address</tag>
Default: $803. Use <tt/-S <addr>/ to set a different start address.
- <tag><tt/__EXEHDR__:/ Executable file header</tag>
- Default: No header. Use <tt/-u __EXEHDR__ apple2.lib/ to add a DOS 3.3 header
- (address and length).
+ <tag><tt/__EXEHDR__:/ AppleSingle executable file header</tag>
+ Default: No. Use <tt/-u __EXEHDR__ apple2.lib/ to add the AppleSingle header.
</descrip><p>
Using LOADER.SYSTEM is as simple as copying it to the ProDOS 8 directory of the
program to load under name <program>.SYSTEM as a system program. For
-example the program <tt/MYPROG/ is loaded by <tt/MYPROG.SYSTEM/.
+example the program <tt/MYPROG/ is loaded by <tt/MYPROG.SYSTEM/. The right
+AppleCommander option to put LOADER.SYSTEM on a ProDOS 8 disk image is <tt/-p/.
<sect1>Heap<p>
<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
<tag/Interrupts/
There's no <tt/interruptor/ support. Any attempt to use it yields the message
'FAILED TO ALLOC INTERRUPT' on program startup. This implicitly means that
- joystick, mouse and RS232 device drivers are not functional as they depend on
- interrupts.
+ mouse and RS232 device drivers are not functional as they depend on interrupts.
</descrip><p>
<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