<article>
<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
+<author><url url="mailto:ol.sc@web.de" name="Oliver Schmidt">
+<date>2014-04-10
<abstract>
An overview over the enhanced Apple //e runtime system as it is
pitfalls specific to that platform.
Please note that enhanced Apple //e specific functions are just mentioned
-here, they are described in detail in the separate <htmlurl url="funcref.html"
+here, they are described in detail in the separate <url url="funcref.html"
name="function reference">. Even functions marked as "platform dependent" may
be available on more than one platform. Please see the function reference for
more information.
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
+<ref id="apple-sys-cfg" 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 <tt/-p/.
Card.
The amount of memory available in the Language Card for generated code depends
-on the chosen <htmlurl url="apple2enh-4.html" name="linker configuration">.
+on the chosen <ref id="link-configs" name="linker configuration">.
-<sect>Linker configurations<p>
+<sect>Linker configurations<label id="link-configs"><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 ld65 linker comes with a default config file for the enhanced Apple //e,
+which is used via <tt/-t apple2enh/.
The apple2enh package comes with additional secondary linker config files, which
-are used via <tt/-C <configfile>/.
+are used via <tt/-t apple2enh -C <configfile>/.
-<sect1>builtin config file<p>
+<sect1>default config file (<tt/apple2enh.cfg/)<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
</descrip><p>
-<sect1><tt/apple2enh-system.cfg/<p>
+<sect1><tt/apple2enh-system.cfg/<label id="apple-sys-cfg"><p>
Configuration for a system program running on ProDOS 8.
</descrip><p>
-<sect1><tt/apple2enh-loader.cfg/<p>
+<sect1><tt/apple2enh-loader.cfg/<label id="apple-load-cfg"><p>
Configuration optimized for a binary program running on ProDOS 8 without
BASIC.SYSTEM. Intended to be used with <bf/LOADER.SYSTEM - an
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).
+<ref id="apple-load-cfg" name="apple2enh-loader.cfg"> with start address
+$803 and load it with the targetutil LOADER.SYSTEM. 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
<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
+If the cc65 program can be successfully linked as system program using the linker
+configuration <ref id="apple-sys-cfg" 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>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
+the <url url="funcref.html" name="function reference"> for declaration and
usage.
<itemize>
+<item>_auxtype
<item>_dos_type
-<item>drivecount
-<item>drivelist
+<item>_filetype
<item>get_ostype
<item>rebootafterexit
-<item>rootdir
<item>ser_apple2_slot
<item>textframe
<item>textframexy
<sect>Loadable drivers<p>
+The names in the parentheses denote the symbols to be used for static linking of the drivers.
+
<sect1>Graphics drivers<p>
<descrip>
- <tag><tt/a2e.lo.tgi/</tag>
+ <tag><tt/a2e.lo.tgi (a2e_lo_tgi)/</tag>
This driver features a resolution of 40×48 with 16 colors.
The function <tt/tgi_apple2_mix()/ allows to activate 4 lines of text. The
function clears the corresponding area at the bottom of the screen.
- <tag><tt/a2e.hi.tgi/</tag>
+ <tag><tt/a2e.hi.tgi (a2e_hi_tgi)/</tag>
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
<descrip>
- <tag><tt/a2e.auxmem.emd/</tag>
- Gives access to 47,5 KB RAM (190 pages of 256 bytes each) on an Extended
+ <tag><tt/a2e.auxmem.emd (a2e_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
<descrip>
- <tag><tt/a2e.stdjoy.joy/</tag>
+ <tag><tt/a2e.stdjoy.joy (a2e_stdjoy_joy)/</tag>
Supports up to two standard analog joysticks connected to the game port of
the enhanced Apple //e.
<descrip>
- <tag><tt/a2e.stdmou.mou/</tag>
+ <tag><tt/a2e.stdmou.mou (a2e_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].
<descrip>
- <tag><tt/a2e.ssc.ser/</tag>
+ <tag><tt/a2e.ssc.ser (a2e_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
<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.
+ are in general not functional as they depend on disk file I/O. Therefore the statically
+ linked drivers have to be used instead.
<tag/Interrupts/
There's no <tt/interruptor/ support. Any attempt to use it yields the message
<tag/Color/
The enhanced Apple //e 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.
+ textcolor(), bgcolor() and bordercolor() have no effect.
<tag/Cursor/
The enhanced Apple //e has no hardware cursor. Therefore the function
- <htmlurl url="funcref-88.html" name="cursor()"> has no effect.
+ cursor() has no effect.
</descrip><p>
<sect1>Interrupts<p>
-The runtime for the enhanced Apple //e 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">.
+The runtime for the enhanced Apple //e uses routines marked as
+<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 <url
+url="ca65.html" name="assembler manual">.
<sect1>DIO<p>
<descrip>
<tag/Drive ID/
- 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
+ The function <url url="dio.html#s1" name="dio_open()"> has the single
+ parameter <tt/device/ to identify the device 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 * 16 + (drive - 1) * 128
- </verb>
+ <tscreen>
+ device = slot + (drive - 1) * 8
+ </tscreen>
- so that for example slot 6 drive 2 is mapped to <tt/drive_id/ 224.
+ so that for example slot 6 drive 2 is mapped to <tt/device/ 14.
<tag/Sector count/
- The function <htmlurl url="dio-3.html" name="dio_query_sectcount()"> returns
+ The function <url url="dio.html#s3" name="dio_query_sectcount()"> returns
the correct sector count for all ProDOS 8 disks. However for any non-ProDOS 8
disk it simply always returns 280 (which is only correct for a 140 KB disk).
- This condition is indicated by the _oserror value 82.
+ This condition is indicated by the <tt/_oserror/ value 82.
</descrip><p>
-<sect>Bugs/Feedback<p>
-
-If you have problems using the library, if you find any bugs, or if you're
-doing something interesting with it, I would be glad to hear from you. Feel
-free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
-name="uz@cc65.org">).
-
-
-
<sect>License<p>
This software is provided 'as-is', without any expressed or implied