<article>
-<title>enhanced Apple //e specific information for cc65
-<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
-<date>2003-12-16
+<title>Enhanced Apple //e specific information for cc65
+<author>Oliver Schmidt, <htmlurl url="mailto:ol.sc@web.de" name="ol.sc@web.de">
+<date>2009-10-07
<abstract>
An overview over the enhanced Apple //e runtime system as it is
<sect>Binary format<p>
-The standard binary output format generated by the linker for the
-enhanced Apple //e target is a machine language program with a 4 byte DOS
-3.3 header containing the load address and load size. The standard load address
-is $803.
-
-The DOS 3.3 header is in its own segment named <tt/EXEHDR/. If you don't want
-the header for some reason, you can change
-
-<verb>
- HEADER: start = $0000, size = $0004, file = %O;
-</verb>
-
-to
-
-<verb>
- HEADER: start = $0000, size = $0004, file = "";
-</verb>
-
-in the linker configuration to have the linker remove it.
+The standard binary file format generated by the linker for the
+enhanced Apple //e 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 an option <tt/-cc65/
-that allows to put binary files with the DOS 3.3 header onto disk images
-containing either DOS 3.3 or ProDOS 8.
-
-Please note that there is an <bf/Apple ][ ProDOS 8 system program
-for loading binary programs/ available in the cc65 User Contributions section.
-It adds all benefits of a ProDOS 8 system program to the standard binary
-program generated by the linker for the enhanced Apple //e target.
+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.
+For ProDOS 8 system programs the load address is fixed to $2000 so there
+is no need for a header. Thus the linker configuration
+<htmlurl url="apple2enh-4.html#ss4.3" name="apple2enh-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 </-p/.
<sect>Memory layout<p>
In the standard setup, cc65 generated programs use the memory from
-$803 to $95FF, so 35.5KB of RAM are available. While running
-<tt/main()/ the Language Card bank 2 is enabled for read access. However while
-running module constructors/destructors the Language Card is disabled.
+$803 to $95FF, so 35.5 KB of RAM are available.
Special locations:
<descrip>
+
<tag/Stack/
The C runtime stack is located at HIMEM and grows downwards, regardless of
how your linker config file is setup.
<tag/Heap/
The C heap is located at the end of the program and grows towards the C
runtime stack.
+
</descrip><p>
-Enabling the Language Card allows to use it as additional memory for executable
-code. Actually doing so requires either to compile code with the option
-<tt/--code-name HIGHCODE/ or to use <tt/#pragma codeseg ("HIGHCODE")/.
+While running <tt/main()/ the Language Card bank 2 is enabled for read access.
+However while running module constructors/destructors the Language Card is disabled.
-The amount of memory available in the Language Card for executable code depends
-on the chosen program environment. A plain vanilla ProDOS 8 doesn't actually
-use the Language Card bank 2 memory from $D400 to $DFFF.
-Therefore the builtin linker configuration defines these 3KB as <tt/LC/ memory
-area for executable code.
+Enabling the Language Card allows to use it as additional memory for cc65
+generated code. However code is never automatically placed there. Rather code
+needs to be explicitly placed in the Language Card either per file by compiling
+with <tt/--code-name HIGHCODE/ or per function by enclosing in <tt/#pragma
+codeseg (push, "HIGHCODE")/ and <tt/#pragma codeseg (pop)/. In either case the
+cc65 runtime system takes care of actually moving the code into the Language
+Card.
-A plain vanilla DOS 3.3 doesn't make use of the Language Card at all. So you
-can change
+The amount of memory available in the Language Card for generated code depends
+on the chosen <htmlurl url="apple2enh-4.html" name="linker configuration">.
-<verb>
- LC: start = $D400, size = $0C00, define = yes;
-</verb>
-to
-<verb>
- LC: start = $D000, size = $3000, define = yes;
-</verb>
+<sect>Linker configurations<p>
+
+The ld65 linker comes with a builtin config file for the enhanced Apple //e,
+which is used via <tt/-t apple2enh/ (and displayed via <tt/--dump-config apple2enh/).
+The apple2enh package comes with additional secondary linker config files, which
+are used via <tt/-C <configfile>/.
+
+
+<sect1>builtin config file<p>
+
+Default configuration optimized for a binary program running on ProDOS 8 with
+BASIC.SYSTEM. A plain vanilla ProDOS 8 doesn't actually use the Language Card
+bank 2 memory from $D400 to $DFFF.
+
+<descrip>
+
+ <tag><tt/RAM:/ Main memory area</tag>
+ From $803 to $95FF (35.5 KB)
+
+ <tag><tt/LC:/ Language Card memory area</tag>
+ From $D400 to $DFFF (3 KB)
+
+ <tag><tt/STARTADDRESS:/ Program start address</tag>
+ Variable (default: $803)
+
+ <tag><tt/HEADER:/ Binary file header</tag>
+ DOS 3.3 header (address and length)
+
+</descrip><p>
+
+
+<sect1><tt/apple2enh-dos33.cfg/<p>
+
+Configuration optimized for a binary program running on DOS 3.3. A plain
+vanilla DOS 3.3 doesn't make use of the Language Card at all.
+
+<descrip>
+
+ <tag><tt/RAM:/ Main memory area</tag>
+ From $803 to $95FF (35.5 KB)
+
+ <tag><tt/LC:/ Language Card memory area</tag>
+ From $D000 to $FFFF (12 KB)
+
+ <tag><tt/STARTADDRESS:/ Program start address</tag>
+ Variable (default: $803)
+
+ <tag><tt/HEADER:/ Binary file header</tag>
+ DOS 3.3 header (address and length)
+
+</descrip><p>
+
+
+<sect1><tt/apple2enh-system.cfg/<p>
+
+Configuration for a system program running on ProDOS 8.
+
+<descrip>
+
+ <tag><tt/RAM:/ Main memory area</tag>
+ From $2000 to $BEFF (39.75 KB)
+
+ <tag><tt/LC:/ Language Card memory area</tag>
+ From $D400 to $DFFF (3 KB)
+
+ <tag><tt/STARTADDRESS:/ Program start address</tag>
+ Fixed ($2000)
-in the linker configuration to define the whole 12KB Language Card address
-space as memory area for executable code.
+ <tag><tt/HEADER:/ Binary file header</tag>
+ None
+
+</descrip><p>
+
+
+<sect1><tt/apple2enh-loader.cfg/<p>
+
+Configuration optimized for a binary program running on ProDOS 8 without
+BASIC.SYSTEM. Intended to be used with <bf/LOADER.SYSTEM - an
+Apple ][ ProDOS 8 loader for cc65 programs/, which is available
+in the cc65 User Contributions section.
+
+A program loaded by LOADER.SYSTEM works like a ProDOS 8 system program but
+isn't tied to the start adress $2000. Thus with the default start
+address $800 the main memory area is increased by 6 KB.
+
+<descrip>
+
+ <tag><tt/RAM:/ Main memory area</tag>
+ From $800 to $BEFF (45.75 KB)
+
+ <tag><tt/LC:/ Language Card memory area</tag>
+ From $D400 to $DFFF (3 KB)
+
+ <tag><tt/STARTADDRESS:/ Program start address</tag>
+ Variable (default: $800)
+
+ <tag><tt/HEADER:/ Binary file header</tag>
+ DOS 3.3 header (address and length)
+
+</descrip><p>
+
+
+<sect1><tt/apple2enh-reboot.cfg/<p>
+
+Configuration optimized for a binary program running on ProDOS 8 without
+BASIC.SYSTEM. Intended to be used with <bf/LOADER.SYSTEM - an
+Apple ][ ProDOS 8 loader for cc65 programs/ (see above) together
+with the function <tt/rebootafterexit()/.
+
+If a ProDOS 8 system program doesn't quit to the ProDOS 8 dispatcher but rather
+reboots the machine after exit then a plain vanilla ProDOS 8 doesn't make use of
+the Language Card bank 2 at all.
+
+This setup makes nearly 50 KB available to a cc65 program - on a 64 KB machine!
+
+<descrip>
+
+ <tag><tt/RAM:/ Main memory area</tag>
+ From $800 to $BEFF (45.75 KB)
+
+ <tag><tt/LC:/ Language Card memory area</tag>
+ From $D000 to $DFFF (4 KB)
+
+ <tag><tt/STARTADDRESS:/ Program start address</tag>
+ Variable (default: $800)
+
+ <tag><tt/HEADER:/ Binary file header</tag>
+ DOS 3.3 header (address and length)
+
+</descrip><p>
+
+
+
+<sect>ProDOS 8 system programs<p>
+
+ProDOS 8 system programs are always loaded to the start adress $2000.
+For cc65 programs this means that the 6 KB from $800 to $2000 are
+by default unused. There are however several options to make use of that memory
+range.
+
+
+<sect1>LOADER.SYSTEM<p>
+
+The easiest (and for really large programs in fact the only) way to have a cc65
+program use the memory from $800 to $2000 is to link it as binary
+(as opposed to system) program using the linker configuration
+<htmlurl url="apple2enh-4.html#ss4.4" name="apple2enh-loader.cfg"> with start address
+$800 and load it with <bf/LOADER.SYSTEM - an Apple ][
+ProDOS 8 loader for cc65 programs/. The program then works like a system program
+(i.e. quits to the ProDOS dispatcher).
+
+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/.
+
+
+<sect1>Heap<p>
+
+If the cc65 program can be successully linked as system program using the linker
+configuration <htmlurl url="apple2enh-4.html#ss4.3" name="apple2enh-system.cfg"> but
+uses the heap either explicitly or implicitly (i.e. by loading a driver) then
+the memory from $800 to $2000 can be added to the heap by calling
+<tt/_heapadd ((void *) 0x0800, 0x1800);/ at the beginning of <tt/main()/.
+
+
+<sect1>ProDOS 8 I/O buffers<p>
+
+ProDOS 8 requires for every open file a page-aligned 1 KB I/O buffer. By default
+these buffers are allocated by the cc65 runtime system on the heap using
+<tt/posix_memalign()/. While this is generally the best solution it means quite
+some overhead for (especially rather small) cc65 programs which do open files
+but don't make use of the heap otherwise.
+
+The apple2enh package comes with the alternative ProDOS 8 I/O buffer allocation
+module <tt/apple2enh-iobuf-0800.o/ which uses the memory between $800 and
+the program start address for the 1 KB I/O buffers. For system programs (with
+start address $2000) this results in up to 6 I/O buffers and thus up to 6
+concurrently open files.
+
+While using <tt/_heapadd()/ as described in the section above together with the
+default I/O buffer allocation basically yields the same placement of I/O buffers
+in memory the primary benefit of <tt/apple2enh-iobuf-0800.o/ is a reduction in code
+size - and thus program file size - of more than 1400 bytes.
+
+Using <tt/apple2enh-iobuf-0800.o/ is as simple as placing it on the linker command
+line like this:
+
+<tscreen><verb>
+cl65 -t apple2enh -C apple2enh-system.cfg myprog.c apple2enh-iobuf-0800.o
+</verb></tscreen>
<tt/apple2enh.h/ header file.
-<sect1>
enhanced Apple //e specific functions<p>
+<sect1>
Enhanced Apple //e specific functions<p>
The functions listed below are special for the enhanced Apple //e. See
the <htmlurl url="funcref.html" name="function reference"> for declaration and
<tt/--start-addr $6000/ to reserve both hires pages.
In memory constrained situations the memory from $803 to $1FFF
- can be made available to a program by executing <tt/_heapadd ((void *) 0x0803, 0x17FD);/
+ can be made available to a program by calling <tt/_heapadd ((void *) 0x0803, 0x17FD);/
at the beginning of <tt/main()/. Doing so is beneficial even if the program
doesn't use the the heap explicitly because loading the driver (and in fact
already opening the driver file) uses the heap implicitly.
Although <htmlurl url="dio.html" name="DIO"> generally works with all ProDOS 8
devices, the function <htmlurl url="dio-3.html" name="dio_query_sectcount()">
-simply always return 280 (which is only correct for a 140KB disk).
+simply always return 280 (which is only correct for a 140 KB disk).
<sect1>Direct console I/O<p>
projects / cc65 / commitdiff