more information.
+
<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.
+3.3 header. The standard 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;
+ HEADER: start = $0000, size = $0004, file = %O;
</verb>
to
<verb>
- HEADER: start = $0000, size = $4, file = "";
+ HEADER: start = $0000, size = $0004, file = "";
</verb>
in the linker configuration to have the linker remove it.
+Please note that there is an '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.
+
<sect>Memory layout<p>
In the standard setup, cc65 generated programs use the memory from
-$800 to $8E00, so 33.5K of memory (including the stack) is
-available. ROM calls are possible without further precautions.
+$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.
Special locations:
<descrip>
<tag/Stack/
- The C runtime stack is located at $8DFF and growing downwards.
+ 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")/.
+
+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.
+
+A plain vanilla DOS 3.3 doesn't make use of the Language Card at all. So you
+can change
+
+<verb>
+ LC: start = $D400, size = $0C00, define = yes;
+</verb>
+
+to
+
+<verb>
+ LC: start = $D000, size = $3000, define = yes;
+</verb>
+
+in the linker configuration to define the whole 12KB Language Card address
+space as memory area for executable code.
+
<sect>Platform specific header files<p>
usage.
<itemize>
+<item>_dos_type
<item>get_ostype
</itemize>
-
<sect1>Hardware access<p>
There's currently no support for direct hardware access. This does not mean
<sect>Loadable drivers<p>
-<em>Note:</em> Since the Apple ][ doesn't have working disk I/O
-(see <ref id="limitations" name="section "Limitations"">), the
-available drivers cannot be loaded at runtime (so the term "loadable drivers"
-is somewhat misleading). Instead, the drivers have to be converted using the
-<htmlurl url="co65.html" name="co65 utility"> and statically linked. While
-this may seem overhead, it has two advantages:
-
-<enum>
-<item>The interface is identical to the one used for other platforms
- and to the one for the Apple ][ once it has disk I/O.
-<item>Once disk I/O is available, existing code can be changed to load drivers
- at runtime with almost no effort.
-</enum>
-
-
<sect1>Graphics drivers<p>
-<em>Note:</em> Since memory for the high resolution graphics has to be allocated,
-programs using graphics drivers will have to be linked using a special linker
-configuration. See the <tt/apple2-tgi.cfg/ file in the documentation
-directory, and the <htmlurl url="ld65.html" name="linker documentation"> on
-how to use it.
-
<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.
+ 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 executing <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 ][ language card. The driver was contributed by
- Stefan Haubenthal. Note: 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>
-
<sect1>Joystick drivers<p>
<descrip>
</descrip><p>
-
<sect1>Mouse drivers<p>
-Currently no drivers available (in fact, the API for loadable mouse drivers
-does not exist).
+<descrip>
+
+ <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) 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.
+
+</descrip><p>
<sect1>RS232 device drivers<p>
-No serial drivers are currently available for the Apple ][.
+<descrip>
+ <tag><tt/a2.ssc.ser/</tag>
+ Driver for the Apple II Super Serial Card. Supports up to 19200 baud,
+ hardware flow control (RTS/CTS) and interrupt driven receives. Note
+ that because of the peculiarities of the 6551 chip transmits are not
+ interrupt driven, and the transceiver blocks if the receiver asserts
+ 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_ERR_NO_DEVICE/ if there's no SSC firmware found in the selected slot.
-<sect>Limitations<label id="limitations"><p>
+</descrip><p>
-<sect1>Disk I/O<p>
-The existing library for the Apple ][ doesn't implement C file
-I/O. There are two hacks for the <tt/read()/ and <tt/write()/ routines in
-place, which will make functions work that read from or write to <tt/stdout/
-(like <tt/printf()/). However, these functions have some shortcomings which
-won't be fixed, because they're going to be replaced anyway.
-To be more concrete, this limitation means that you cannot use any of the
-following functions (and a few others):
+<sect>Limitations<p>
-<itemize>
-<item>fclose
-<item>fopen
-<item>fread
-<item>fprintf
-<item>fputc
-<item>fscanf
-<item>fwrite
-<item>...
-</itemize>
<sect>Other hints<p>
+
<sect1>Passing arguments to the program<p>
-Command line arguments can be passed to <tt/main()/. Since this is not
-supported by BASIC, the following syntax was choosen:
+Command line arguments can be passed to <tt/main()/ after BLOAD. Since this is not
+supported by BASIC, the following syntax was chosen:
<tscreen><verb>
- CALL2048:REM,ARG1," ARG2", ARG 3,, ARG5, ...
+]CALL2051:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5
</verb></tscreen>
<enum>
-<item>Arguments are separated by commas.
-<item>There must be a comma after the first <tt/REM/.
-<item>Leading spaces are ignored; trailing spaces are included unless the
- argument was quoted.
+<item>Arguments are separated by spaces.
+<item>Arguments may be quoted.
+<item>Leading and trailing spaces around an argument are ignored. Spaces within
+ a quoted argument are allowed.
<item>The first argument passed to <tt/main/ is the program name.
+<item>A maximum number of 10 arguments (including the program name) are
+ supported.
</enum>
-<sect1>Function keys<p>
+<sect1>Interrupts<p>
-These are defined to be OpenApple + number key.
+The runtime for the Apple ][ uses routines marked as <tt/.CONDES/
+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">.
<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,
</enum>
</article>
-
-
-