mirror of
https://github.com/cc65/cc65.git
synced 2024-11-13 13:11:06 +00:00
367 lines
11 KiB
Plaintext
367 lines
11 KiB
Plaintext
<!doctype linuxdoc system>
|
|
|
|
<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
|
|
|
|
<abstract>
|
|
An overview over the enhanced Apple //e runtime system as it is
|
|
implemented for the cc65 C compiler.
|
|
</abstract>
|
|
|
|
<!-- Table of contents -->
|
|
<toc>
|
|
|
|
<!-- Begin the document -->
|
|
|
|
<sect>Overview<p>
|
|
|
|
This file contains an overview of the enhanced Apple //e runtime system
|
|
as it comes with the cc65 C compiler. It describes the memory layout,
|
|
enhanced Apple //e specific header files, available drivers, and any
|
|
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"
|
|
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.
|
|
|
|
|
|
|
|
<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.
|
|
|
|
<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.
|
|
|
|
|
|
|
|
<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.
|
|
|
|
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")/.
|
|
|
|
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>
|
|
|
|
Programs containing enhanced Apple //e specific code may use the
|
|
<tt/apple2enh.h/ header file.
|
|
|
|
|
|
<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
|
|
usage.
|
|
|
|
<itemize>
|
|
<item>_dos_type
|
|
<item>_textframe
|
|
<item>_textframexy
|
|
<item>get_ostype
|
|
</itemize>
|
|
|
|
|
|
<sect1>Hardware access<p>
|
|
|
|
There's currently no support for direct hardware access. This does not mean
|
|
you cannot do it, it just means that there's no help.
|
|
|
|
|
|
|
|
<sect>Loadable drivers<p>
|
|
|
|
|
|
<sect1>Graphics drivers<p>
|
|
|
|
<descrip>
|
|
|
|
<tag><tt/a2e.lo.tgi/</tag>
|
|
This driver features a resolution of 40×48 with 16 colors.
|
|
|
|
<tag><tt/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
|
|
<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>
|
|
|
|
|
|
<sect1>Extended memory drivers<p>
|
|
|
|
<descrip>
|
|
|
|
<tag><tt/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
|
|
and that it doesn't check for ProDOS 8 RAM disk content!
|
|
|
|
</descrip><p>
|
|
|
|
|
|
<sect1>Joystick drivers<p>
|
|
|
|
<descrip>
|
|
|
|
<tag><tt/a2e.stdjoy.joy/</tag>
|
|
Supports up to two standard analog joysticks connected to the game port of
|
|
the enhanced Apple //e.
|
|
|
|
</descrip><p>
|
|
|
|
|
|
<sect1>Mouse drivers<p>
|
|
|
|
<descrip>
|
|
|
|
<tag><tt/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].
|
|
|
|
Note that the enhanced Apple //e default mouse callbacks support
|
|
text mode only.
|
|
|
|
</descrip><p>
|
|
|
|
|
|
<sect1>RS232 device drivers<p>
|
|
|
|
<descrip>
|
|
|
|
<tag><tt/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
|
|
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.
|
|
|
|
</descrip><p>
|
|
|
|
|
|
|
|
<sect>Limitations<p>
|
|
|
|
|
|
<sect1>DOS 3.3<p>
|
|
|
|
Although the standard binaries generated by the linker for the enhanced Apple //e
|
|
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</tag>
|
|
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/a2e.stdmou.mou/ and <tt/a2e.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 140KB disk).
|
|
|
|
|
|
<sect1>Direct console I/O<p>
|
|
|
|
<descrip>
|
|
|
|
<tag>Color</tag>
|
|
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.
|
|
|
|
<tag>Cursor</tag>
|
|
The enhanced Apple //e has no hardware cursor. Therefore the function
|
|
<htmlurl url="funcref-88.html" name="cursor()"> has no effect.
|
|
|
|
</descrip><p>
|
|
|
|
|
|
|
|
<sect>Other hints<p>
|
|
|
|
|
|
<sect1>Passing arguments to the program<p>
|
|
|
|
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>
|
|
]CALL2051:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5
|
|
</verb></tscreen>
|
|
|
|
<enum>
|
|
<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>
|
|
|
|
These are defined to be OpenApple + number key.
|
|
|
|
|
|
<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">.
|
|
|
|
|
|
<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>
|
|
<tt/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>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
|
|
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,
|
|
including commercial applications, and to alter it and redistribute it
|
|
freely, subject to the following restrictions:
|
|
|
|
<enum>
|
|
<item> The origin of this software must not be misrepresented; you must not
|
|
claim that you wrote the original software. If you use this software
|
|
in a product, an acknowledgment in the product documentation would be
|
|
appreciated but is not required.
|
|
<item> Altered source versions must be plainly marked as such, and must not
|
|
be misrepresented as being the original software.
|
|
<item> This notice may not be removed or altered from any source
|
|
distribution.
|
|
</enum>
|
|
|
|
</article>
|