<article>
<title>Apple ][ specific information for cc65
-<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
-<date>2003-12-16
+<author>Oliver Schmidt, <htmlurl url="mailto:ol.sc@web.de" name="ol.sc@web.de">
+<date>2009-10-07
<abstract>
An overview over the Apple ][ runtime system as it is
<sect>Binary format<p>
-The standard binary output format generated by the linker for the
-Apple ][ target is a machine language program with a 4 byte DOS
-3.3 header. The standard load address is $800.
+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.
-The DOS 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 = $4, file = %O;
-</verb>
-
-to
-
-<verb>
- HEADER: start = $0000, size = $4, file = "";
-</verb>
-
-in the linker configuration to have the linker remove it.
-
-Please note that there is a "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 Apple ][ target.
+<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.
+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="apple2-4.html#ss4.3" 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/.
<sect>Memory layout<p>
In the standard setup, cc65 generated programs use the memory from
-$800 to $95FF, so 35.5K of memory are available. ROM calls are
-possible without further precautions.
+$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>
+
+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.
+
+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
+code-name (push, "HIGHCODE")/ and <tt/#pragma code-name (pop)/. In either case the
+cc65 runtime system takes care of actually moving the code into the Language
+Card.
+
+The amount of memory available in the Language Card for generated code depends
+on the chosen <htmlurl url="apple2-4.html" name="linker configuration">.
+
+
+
+<sect>Linker configurations<p>
+
+The ld65 linker comes with a builtin config file for the Apple ][,
+which is used via <tt/-t apple2/ (and displayed via <tt/--dump-config apple2/).
+The apple2 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/apple2-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/apple2-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)
+
+ <tag><tt/HEADER:/ Binary file header</tag>
+ None
+
+</descrip><p>
+
+
+<sect1><tt/apple2-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/apple2-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="apple2-4.html#ss4.4" name="apple2-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="apple2-4.html#ss4.3" name="apple2-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 apple2 package comes with the alternative ProDOS 8 I/O buffer allocation
+module <tt/apple2-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/apple2-iobuf-0800.o/ is a reduction in code
+size - and thus program file size - of more than 1400 bytes.
+
+Using <tt/apple2-iobuf-0800.o/ is as simple as placing it on the linker command
+line like this:
+
+<tscreen><verb>
+cl65 -t apple2 -C apple2-system.cfg myprog.c apple2-iobuf-0800.o
+</verb></tscreen>
+
+
+
<sect>Platform specific header files<p>
Programs containing Apple ][ specific code may use the
<itemize>
<item>_dos_type
<item>get_ostype
+<item>rebootafterexit
</itemize>
<descrip>
<tag><tt/a2.lo.tgi/</tag>
- This driver was written by Stefan Haubenthal. It features a resolution of
- 40×40 with 16 colors. At the bottom of the screen, 4 additional text
- lines are available.
+ This driver features a resolution of 40×48 with 16 colors.
<tag><tt/a2.hi.tgi/</tag>
- This driver was written by Stefan Haubenthal. It features a resolution of
- 280×192 with 6 colors. Note that programs using this driver will have
- to be linked with <tt/--start-addr $4000/ to reserve the first hires page.
+ This driver features a resolution of 280×192 with 8 colors and two
+ hires pages. Note that programs using this driver will have to be linked
+ with <tt/--start-addr $4000/ to reserve the first hires page or with
+ <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 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.
</descrip><p>
<descrip>
- <tag><tt/a2.lc.emd/</tag>
- Gives access to 12KB RAM (48 pages of 256 bytes each) on the
- Apple II Language Card. The driver was contributed by Stefan Haubenthal.
- Note that this driver is incompatible with any DOS using the Language
- Card memory!
+ <tag><tt/a2.auxmem.emd/</tag>
+ Gives access to 47,5 KB RAM (190 pages of 256 bytes each) on an Extended
+ 80-Column Text Card.
+
+ Note that this driver doesn't check for the actual existence of the memory
+ and that it doesn't check for ProDOS 8 RAM disk content!
</descrip><p>
<tag><tt/a2.stdmou.mou/</tag>
Driver for the AppleMouse II Card. Searches all Apple II slots
for an AppleMouse II Card compatible firmware. The default bounding
- box is [0..279,0..191]. Programs using this driver will have
- to be linked with <tt/--start-addr $4000/ to reserve the first hires page
- if they are intended to run on an Apple ][ (in contrast to
- an Apple //e).
+ box is [0..279,0..191].
+
+ Programs using this driver will have to be linked with <tt/--start-addr $4000/
+ to reserve the first hires page if they are intended to run on an
+ Apple ][ (in contrast to an Apple //e) because the
+ AppleMouse II Card firmware writes to the hires page when initializing
+ on that machine.
Note that the Apple ][ default mouse callbacks support text
mode only.
flow control because of a full buffer.
The driver defaults to slot 2. Call <tt/ser_ioctl(0, <slot>)/ prior to
- <tt/ser_open/ in order to select a different slot. <tt/ser_ioctl/ succeeds
- for all Apple II slots, but <tt/ser_open/ fails with
+ <tt/ser_open()/ in order to select a different slot. <tt/ser_ioctl()/
+ succeeds for all Apple II slots, but <tt/ser_open()/ fails with
<tt/SER_ERR_NO_DEVICE/ if there's no SSC firmware found in the selected slot.
</descrip><p>
<sect>Limitations<p>
+<sect1>DOS 3.3<p>
+
+Although the standard binaries generated by the linker for the Apple ][
+generally run both on DOS 3.3 (with Applesoft BASIC) and on ProDOS 8 (with
+BASIC.SYSTEM) there are some limitations for DOS 3.3:
+
+<descrip>
+
+ <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. However they
+ may be converted to statically linked drivers using the co65 object-file
+ converter.
+
+ <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
+ <tt/a2.stdmou.mou/ and <tt/a2.ssc.ser/ are not functional as they depend on
+ interrupts.
+
+</descrip><p>
+
+
+<sect1>DIO<p>
+
+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 140 KB disk).
+
+
+<sect1>Direct console I/O<p>
+
+<descrip>
+
+ <tag/Color/
+ The Apple ][ has no color text mode. Therefore the functions
+ <htmlurl url="funcref-205.html" name="textcolor()">,
+ <htmlurl url="funcref-68.html" name="bgcolor()"> and
+ <htmlurl url="funcref-69.html" name="bordercolor()"> have no effect.
+
+ <tag/Cursor/
+ The Apple ][ has no hardware cursor. Therefore the function
+ <htmlurl url="funcref-88.html" name="cursor()"> has no effect.
+
+</descrip><p>
+
+
<sect>Other hints<p>
supported by BASIC, the following syntax was chosen:
<tscreen><verb>
-]CALL2048:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5
+]CALL2051:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5
</verb></tscreen>
<enum>
<sect1>Interrupts<p>
The runtime for the Apple ][ uses routines marked as <tt/.CONDES/
-type 2 for ProDOS interrupt handlers. Such routines must be written as simple
-machine language subroutines and will be called automatically by the interrupt
-handler code when they are linked into a program. See the discussion of the
-<tt/.CONDES/ feature in the <htmlurl url="ca65.html" name="assembler manual">.
+type <tt/interruptor/ for ProDOS 8 interrupt handlers. Such routines must be
+written as simple machine language subroutines and will be called automatically
+by the interrupt handler code when they are linked into a program. See the
+discussion of the <tt/.CONDES/ feature in the <htmlurl url="ca65.html"
+name="assembler manual">.
+
+
+<sect1>DIO<p>
+
+The function <htmlurl url="dio-1.html" name="dio_open()"> has the single parameter
+<tt/drive_id/ to identify the drive to be opened. Therefore an Apple II
+slot and drive pair is mapped to that <tt/drive_id/ according to the formula
+
+<verb>
+ drive_id = (slot * 2) + (drive - 1)
+</verb>
+
+so that for example slot 6 drive 1 is mapped to <tt/drive_id/ 12.
+
+The function <htmlurl url="dio-1.html" name="dio_open()"> succeeds only if a
+formatted disk is present in the drive. However intentionally no check is
+performed on the presence of a ProDOS 8 disk. Therefore access to all standard
+16-sector disks (as for instance DOS 3.3) is possible.
<sect>License<p>
This software is provided 'as-is', without any expressed or implied
-warranty. In no event will the authors be held liable for any damages
+warranty. In no event will the authors be held liable for any damages
arising from the use of this software.
Permission is granted to anyone to use this software for any purpose,