mirror of
https://github.com/cc65/cc65.git
synced 2024-12-27 15:29:46 +00:00
Added quite some info on the stuff in 'cfg' and 'obj'. Apple2enh needs to be adjusted too for sure, but check the result of the nightly build first.
git-svn-id: svn://svn.cc65.org/cc65/trunk@4352 b7a2c559-68d2-44c3-8de9-860c34a00d81
This commit is contained in:
ol.sc
parent
f2d1ea10d9
commit
b7071c05a2
277
doc/apple2.sgml
277
doc/apple2.sgml
@ -3,8 +3,8 @@
|
||||
<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
|
||||
@ -33,48 +33,31 @@ 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 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.
|
||||
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.
|
||||
|
||||
<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 Apple ][ target.
|
||||
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. Therefore the linker configuration
|
||||
<htmlurl url="apple2-4.html#ss4.3" name="apple2-system.cfg"> for those programs
|
||||
omits the DOS 3.3 header.
|
||||
|
||||
|
||||
<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.
|
||||
$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.
|
||||
@ -82,33 +65,215 @@ Special locations:
|
||||
<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")/.
|
||||
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.
|
||||
|
||||
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.
|
||||
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
|
||||
codeseg (push, "HIGHCODE")/ and <tt/#pragma codeseg (pop)/. In either case the
|
||||
cc65 runtime system takes care of actually moving the code into the Language
|
||||
Card.
|
||||
|
||||
A plain vanilla DOS 3.3 doesn't make use of the Language Card at all. So you
|
||||
can change
|
||||
The amount of memory available in the Language Card for generated code depends
|
||||
on the chosen <htmlurl url="apple2-4.html" name="linker configuration">.
|
||||
|
||||
<verb>
|
||||
LC: start = $D400, size = $0C00, define = yes;
|
||||
</verb>
|
||||
|
||||
to
|
||||
|
||||
<verb>
|
||||
LC: start = $D000, size = $3000, define = yes;
|
||||
</verb>
|
||||
<sect>Linker configurations<p>
|
||||
|
||||
in the linker configuration to define the whole 12KB Language Card address
|
||||
space as memory area for executable code.
|
||||
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 in general this is the best solution it means quite
|
||||
some overhead for (especially rather small) cc65 programs which do open files
|
||||
but do not 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
|
||||
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>
|
||||
|
||||
|
||||
|
||||
@ -155,7 +320,7 @@ you cannot do it, it just means that there's no help.
|
||||
<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);/
|
||||
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.
|
||||
@ -247,7 +412,7 @@ BASIC.SYSTEM) there are some limitations for DOS 3.3:
|
||||
may be converted to statically linked drivers using the co65 object-file
|
||||
converter.
|
||||
|
||||
<tag>Interrupts</tag>
|
||||
<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
|
||||
@ -260,20 +425,20 @@ BASIC.SYSTEM) there are some limitations for DOS 3.3:
|
||||
|
||||
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).
|
||||
simply always return 280 (which is only correct for a 140 KB disk).
|
||||
|
||||
|
||||
<sect1>Direct console I/O<p>
|
||||
|
||||
<descrip>
|
||||
|
||||
<tag>Color</tag>
|
||||
<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</tag>
|
||||
<tag/Cursor/
|
||||
The Apple ][ has no hardware cursor. Therefore the function
|
||||
<htmlurl url="funcref-88.html" name="cursor()"> has no effect.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user