1 <!doctype linuxdoc system>
5 <title>enhanced Apple //e specific information for cc65
6 <author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
10 An overview over the enhanced Apple //e runtime system as it is
11 implemented for the cc65 C compiler.
14 <!-- Table of contents -->
17 <!-- Begin the document -->
21 This file contains an overview of the enhanced Apple //e runtime system
22 as it comes with the cc65 C compiler. It describes the memory layout,
23 enhanced Apple //e specific header files, available drivers, and any
24 pitfalls specific to that platform.
26 Please note that enhanced Apple //e specific functions are just mentioned
27 here, they are described in detail in the separate <htmlurl url="funcref.html"
28 name="function reference">. Even functions marked as "platform dependent" may
29 be available on more than one platform. Please see the function reference for
34 <sect>Binary format<p>
36 The standard binary output format generated by the linker for the
37 enhanced Apple //e target is a machine language program with a 4 byte DOS
38 3.3 header. The standard load address is $803.
40 The DOS header is in its own segment named <tt/EXEHDR/. If you don't want the
41 header for some reason, you can change
44 HEADER: start = $0000, size = $0004, file = %O;
50 HEADER: start = $0000, size = $0004, file = "";
53 in the linker configuration to have the linker remove it.
55 Please note that there is an 'Apple ][ ProDOS 8 system program
56 for loading binary programs' available in the cc65 User Contributions section.
57 It adds all benefits of a ProDOS 8 system program to the standard binary
58 program generated by the linker for the enhanced Apple //e target.
62 <sect>Memory layout<p>
64 In the standard setup, cc65 generated programs use the memory from
65 $803 to $95FF, so 35.5KB of RAM are available. While running
66 <tt/main()/ the Language Card bank 2 is enabled for read access. However while
67 running module constructors/destructors the Language Card is disabled.
73 The C runtime stack is located at HIMEM and grows downwards, regardless of
74 how your linker config file is setup.
77 The C heap is located at the end of the program and grows towards the C
81 Enabling the Language Card allows to use it as additional memory for executable
82 code. Actually doing so requires either to compile code with the option
83 <tt/--code-name HIGHCODE/ or to use <tt/#pragma codeseg ("HIGHCODE")/.
85 The amount of memory available in the Language Card for executable code depends
86 on the chosen program environment. A plain vanilla ProDOS 8 doesn't actually
87 use the Language Card bank 2 memory from $D400 to $DFFF.
88 Therefore the builtin linker configuration defines these 3KB as <tt/LC/ memory
89 area for executable code.
91 A plain vanilla DOS 3.3 doesn't make use of the Language Card at all. So you
95 LC: start = $D400, size = $0C00, define = yes;
101 LC: start = $D000, size = $3000, define = yes;
104 in the linker configuration to define the whole 12KB Language Card address
105 space as memory area for executable code.
109 <sect>Platform specific header files<p>
111 Programs containing enhanced Apple //e specific code may use the
112 <tt/apple2enh.h/ header file.
115 <sect1>enhanced Apple //e specific functions<p>
117 The functions listed below are special for the enhanced Apple //e. See
118 the <htmlurl url="funcref.html" name="function reference"> for declaration and
129 <sect1>Hardware access<p>
131 There's currently no support for direct hardware access. This does not mean
132 you cannot do it, it just means that there's no help.
136 <sect>Loadable drivers<p>
139 <sect1>Graphics drivers<p>
143 <tag><tt/a2e.lo.tgi/</tag>
144 This driver features a resolution of 40×48 with 16 colors.
146 <tag><tt/a2e.hi.tgi/</tag>
147 This driver features a resolution of 280×192 with 8 colors and two
148 hires pages. Note that programs using this driver will have to be linked
149 with <tt/--start-addr $4000/ to reserve the first hires page or with
150 <tt/--start-addr $6000/ to reserve both hires pages.
152 In memory constrained situations the memory from $803 to $1FFF
153 can be made available to a program by executing <tt/_heapadd ((void *) 0x0803, 0x17FD);/
154 at the beginning of <tt/main()/. Doing so is beneficial even if the program
155 doesn't use the the heap explicitly because loading the driver (and in fact
156 already opening the driver file) uses the heap implicitly.
161 <sect1>Extended memory drivers<p>
165 <tag><tt/a2e.auxmem.emd/</tag>
166 Gives access to 47,5 KB RAM (190 pages of 256 bytes each) on an Extended
169 Note that this driver doesn't check for the actual existence of the memory
170 and that it doesn't check for ProDOS 8 RAM disk content!
175 <sect1>Joystick drivers<p>
179 <tag><tt/a2e.stdjoy.joy/</tag>
180 Supports up to two standard analog joysticks connected to the game port of
181 the enhanced Apple //e.
186 <sect1>Mouse drivers<p>
190 <tag><tt/a2e.stdmou.mou/</tag>
191 Driver for the AppleMouse II Card. Searches all Apple II slots
192 for an AppleMouse II Card compatible firmware. The default bounding
193 box is [0..279,0..191].
195 Note that the enhanced Apple //e default mouse callbacks support
201 <sect1>RS232 device drivers<p>
205 <tag><tt/a2e.ssc.ser/</tag>
206 Driver for the Apple II Super Serial Card. Supports up to 19200 baud,
207 hardware flow control (RTS/CTS) and interrupt driven receives. Note
208 that because of the peculiarities of the 6551 chip transmits are not
209 interrupt driven, and the transceiver blocks if the receiver asserts
210 flow control because of a full buffer.
212 The driver defaults to slot 2. Call <tt/ser_ioctl(0, <slot>)/ prior to
213 <tt/ser_open()/ in order to select a different slot. <tt/ser_ioctl()/
214 succeeds for all Apple II slots, but <tt/ser_open()/ fails with
215 <tt/SER_ERR_NO_DEVICE/ if there's no SSC firmware found in the selected slot.
228 <sect1>Passing arguments to the program<p>
230 Command line arguments can be passed to <tt/main()/ after BLOAD. Since this is not
231 supported by BASIC, the following syntax was chosen:
234 ]CALL2051:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5
238 <item>Arguments are separated by spaces.
239 <item>Arguments may be quoted.
240 <item>Leading and trailing spaces around an argument are ignored. Spaces within
241 a quoted argument are allowed.
242 <item>The first argument passed to <tt/main/ is the program name.
243 <item>A maximum number of 10 arguments (including the program name) are
248 <sect1>Function keys<p>
250 These are defined to be OpenApple + number key.
255 The runtime for the enhanced Apple //e uses routines marked as <tt/.CONDES/
256 type <tt/interruptor/ for ProDOS 8 interrupt handlers. Such routines must be
257 written as simple machine language subroutines and will be called automatically
258 by the interrupt handler code when they are linked into a program. See the
259 discussion of the <tt/.CONDES/ feature in the <htmlurl url="ca65.html"
260 name="assembler manual">.
264 <sect>Bugs/Feedback<p>
266 If you have problems using the library, if you find any bugs, or if you're
267 doing something interesting with it, I would be glad to hear from you. Feel
268 free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
269 name="uz@cc65.org">).
275 This software is provided 'as-is', without any expressed or implied
276 warranty. In no event will the authors be held liable for any damages
277 arising from the use of this software.
279 Permission is granted to anyone to use this software for any purpose,
280 including commercial applications, and to alter it and redistribute it
281 freely, subject to the following restrictions:
284 <item> The origin of this software must not be misrepresented; you must not
285 claim that you wrote the original software. If you use this software
286 in a product, an acknowledgment in the product documentation would be
287 appreciated but is not required.
288 <item> Altered source versions must be plainly marked as such, and must not
289 be misrepresented as being the original software.
290 <item> This notice may not be removed or altered from any source