retro/cc65
1
0
Fork 0
mirror of https://github.com/cc65/cc65.git synced 2024-09-21 10:37:28 +00:00
Code Issues Packages Projects Releases Wiki Activity

Revert "No linuxdoc here. Documenation is to be maintained as HTML in branch 'gh-pages'."

Browse Source 
This reverts commit fcea8951f1.

Conflicts:
	doc/Makefile
This commit is contained in:
Oliver Schmidt 2014-02-04 22:18:58 +01:00
parent b8eb1c7794
commit aa7561ec45
38 changed files with 27593 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

544
doc/apple2.sgml Normal file
View File

@ -0,0 +1,544 @@
<!doctype linuxdoc system>
<article>
<title>Apple&nbsp;&rsqb;&lsqb; specific information for cc65
<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&nbsp;&rsqb;&lsqb; 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 Apple&nbsp;&rsqb;&lsqb; runtime system
as it comes with the cc65 C compiler. It describes the memory layout,
Apple&nbsp;&rsqb;&lsqb; specific header files, available drivers, and any
pitfalls specific to that platform.
Please note that Apple&nbsp;&rsqb;&lsqb; 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 file format generated by the linker for the
Apple&nbsp;&rsqb;&lsqb; 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
&dollar;803.
<bf/AppleCommander 1.3.5/ or later (available at <url
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 &dollar;2000 so there
is no need for a header. Thus the linker configuration
<htmlurl url="apple2-4.html#ss4.3" name="apple2-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/.
<sect>Memory layout<p>
In the standard setup, cc65 generated programs use the memory from
&dollar;803 to &dollar;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.
<tag/Heap/
The C heap is located at the end of the program and grows towards the C
runtime stack.
</descrip><p>
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.
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
code-name (push, "HIGHCODE")/ and <tt/#pragma code-name (pop)/. In either case the
cc65 runtime system takes care of actually moving the code into the Language
Card.
The amount of memory available in the Language Card for generated code depends
on the chosen <htmlurl url="apple2-4.html" name="linker configuration">.
<sect>Linker configurations<p>
The ld65 linker comes with a builtin config file for the Apple&nbsp;&rsqb;&lsqb;,
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 &lt;configfile&gt;/.
<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 &dollar;D400 to &dollar;DFFF.
<descrip>
<tag><tt/RAM:/ Main memory area</tag>
From &dollar;803 to &dollar;95FF (35.5 KB)
<tag><tt/LC:/ Language Card memory area</tag>
From &dollar;D400 to &dollar;DFFF (3 KB)
<tag><tt/STARTADDRESS:/ Program start address</tag>
Variable (default: &dollar;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 &dollar;803 to &dollar;95FF (35.5 KB)
<tag><tt/LC:/ Language Card memory area</tag>
From &dollar;D000 to &dollar;FFFF (12 KB)
<tag><tt/STARTADDRESS:/ Program start address</tag>
Variable (default: &dollar;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 &dollar;2000 to &dollar;BEFF (39.75 KB)
<tag><tt/LC:/ Language Card memory area</tag>
From &dollar;D400 to &dollar;DFFF (3 KB)
<tag><tt/STARTADDRESS:/ Program start address</tag>
Fixed (&dollar;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&nbsp;&rsqb;&lsqb; 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 address &dollar;2000. Thus with the default start
address &dollar;800 the main memory area is increased by 6 KB.
<descrip>
<tag><tt/RAM:/ Main memory area</tag>
From &dollar;800 to &dollar;BEFF (45.75 KB)
<tag><tt/LC:/ Language Card memory area</tag>
From &dollar;D400 to &dollar;DFFF (3 KB)
<tag><tt/STARTADDRESS:/ Program start address</tag>
Variable (default: &dollar;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&nbsp;&rsqb;&lsqb; 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 &dollar;800 to &dollar;BEFF (45.75 KB)
<tag><tt/LC:/ Language Card memory area</tag>
From &dollar;D000 to &dollar;DFFF (4 KB)
<tag><tt/STARTADDRESS:/ Program start address</tag>
Variable (default: &dollar;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 address &dollar;2000.
For cc65 programs this means that the 6 KB from &dollar;800 to &dollar;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 &dollar;800 to &dollar;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
&dollar;800 and load it with <bf/LOADER.SYSTEM - an Apple&nbsp;&rsqb;&lsqb;
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 &lt;program&gt;.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 successfully 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 &dollar;800 to &dollar;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 this is generally the best solution it means quite
some overhead for (especially rather small) cc65 programs which do open files
but don't 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 &dollar;800 and
the program start address for the 1 KB I/O buffers. For system programs (with
start address &dollar;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
in memory 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>
<sect>Platform specific header files<p>
Programs containing Apple&nbsp;&rsqb;&lsqb; specific code may use the
<tt/apple2.h/ header file.
<sect1>Apple&nbsp;&rsqb;&lsqb; specific functions<p>
The functions listed below are special for the Apple&nbsp;&rsqb;&lsqb;. See
the <htmlurl url="funcref.html" name="function reference"> for declaration and
usage.
<itemize>
<item>_auxtype
<item>_dos_type
<item>_filetype
<item>get_ostype
<item>rebootafterexit
<item>ser_apple2_slot
<item>tgi_apple2_mix
</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>
The names in the parentheses denote the symbols to be used for static linking of the drivers.
<sect1>Graphics drivers<p>
<descrip>
<tag><tt/a2.lo.tgi (apple2_40_48_16)/</tag>
This driver features a resolution of 40&times;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/a2.hi.tgi (apple2_280_192_8)/</tag>
This driver features a resolution of 280&times;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.
The function <tt/tgi_apple2_mix()/ allows to activate 4 lines of text. The
function doesn't clear the corresponding area at the bottom of the screen.
In memory constrained situations the memory from &dollar;803 to &dollar;1FFF
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.
</descrip><p>
<sect1>Extended memory drivers<p>
<descrip>
<tag><tt/a2.auxmem.emd (apple2_auxmem)/</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/a2.stdjoy.joy (apple2_stdjoy)/</tag>
Supports up to two standard analog joysticks connected to the game port of
the Apple&nbsp;&rsqb;&lsqb;.
</descrip><p>
<sect1>Mouse drivers<p>
<descrip>
<tag><tt/a2.stdmou.mou (apple2_stdmou)/</tag>
Driver for the AppleMouse&nbsp;II Card. Searches all Apple&nbsp;II slots
for an AppleMouse&nbsp;II Card compatible firmware. The default bounding
box is &lsqb;0..279,0..191&rsqb;.
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&nbsp;&rsqb;&lsqb; (in contrast to an Apple&nbsp;//e) because the
AppleMouse&nbsp;II Card firmware writes to the hires page when initializing
on that machine.
Note that the Apple&nbsp;&rsqb;&lsqb; default mouse callbacks support text
mode only.
</descrip><p>
<sect1>RS232 device drivers<p>
<descrip>
<tag><tt/a2.ssc.ser (apple2_ssc)/</tag>
Driver for the Apple&nbsp;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_apple2_slot()/ prior to
<tt/ser_open()/ in order to select a different slot. <tt/ser_apple2_slot()/
succeeds for all Apple&nbsp;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 Apple&nbsp;&rsqb;&lsqb;
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/
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
interrupts.
</descrip><p>
<sect1>Direct console I/O<p>
<descrip>
<tag/Color/
The Apple&nbsp;&rsqb;&lsqb; 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/
The Apple&nbsp;&rsqb;&lsqb; 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>Interrupts<p>
The runtime for the Apple&nbsp;&rsqb;&lsqb; 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 <htmlurl
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/device/ to identify the device to be opened. Therefore an
Apple&nbsp;II slot and drive pair is mapped to that <tt/device/ according
to the formula
<tscreen>
device = slot + (drive - 1) * 8
</tscreen>
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 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 <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
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>

550
doc/apple2enh.sgml Normal file
View File

@ -0,0 +1,550 @@
<!doctype linuxdoc system>
<article>
<title>Enhanced&nbsp;Apple&nbsp;//e specific information for cc65
<author>Oliver Schmidt, <htmlurl url="mailto:ol.sc@web.de" name="ol.sc@web.de">
<date>2009-10-07
<abstract>
An overview over the enhanced&nbsp;Apple&nbsp;//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&nbsp;Apple&nbsp;//e runtime system
as it comes with the cc65 C compiler. It describes the memory layout,
enhanced&nbsp;Apple&nbsp;//e specific header files, available drivers, and any
pitfalls specific to that platform.
Please note that enhanced&nbsp;Apple&nbsp;//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 file format generated by the linker for the
enhanced&nbsp;Apple&nbsp;//e 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
&dollar;803.
<bf/AppleCommander 1.3.5/ or later (available at <url
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 &dollar;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
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/.
<sect>Memory layout<p>
In the standard setup, cc65 generated programs use the memory from
&dollar;803 to &dollar;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.
<tag/Heap/
The C heap is located at the end of the program and grows towards the C
runtime stack.
</descrip><p>
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.
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
code-name (push, "HIGHCODE")/ and <tt/#pragma code-name (pop)/. In either case the
cc65 runtime system takes care of actually moving the code into the Language
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">.
<sect>Linker configurations<p>
The ld65 linker comes with a builtin config file for the enhanced&nbsp;Apple&nbsp;//e,
which is used via <tt/-t apple2enh/ (and displayed via <tt/--dump-config apple2enh/).
The apple2enh package comes with additional secondary linker config files, which
are used via <tt/-C &lt;configfile&gt;/.
<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 &dollar;D400 to &dollar;DFFF.
<descrip>
<tag><tt/RAM:/ Main memory area</tag>
From &dollar;803 to &dollar;95FF (35.5 KB)
<tag><tt/LC:/ Language Card memory area</tag>
From &dollar;D400 to &dollar;DFFF (3 KB)
<tag><tt/STARTADDRESS:/ Program start address</tag>
Variable (default: &dollar;803)
<tag><tt/HEADER:/ Binary file header</tag>
DOS 3.3 header (address and length)
</descrip><p>
<sect1><tt/apple2enh-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 &dollar;803 to &dollar;95FF (35.5 KB)
<tag><tt/LC:/ Language Card memory area</tag>
From &dollar;D000 to &dollar;FFFF (12 KB)
<tag><tt/STARTADDRESS:/ Program start address</tag>
Variable (default: &dollar;803)
<tag><tt/HEADER:/ Binary file header</tag>
DOS 3.3 header (address and length)
</descrip><p>
<sect1><tt/apple2enh-system.cfg/<p>
Configuration for a system program running on ProDOS 8.
<descrip>
<tag><tt/RAM:/ Main memory area</tag>
From &dollar;2000 to &dollar;BEFF (39.75 KB)
<tag><tt/LC:/ Language Card memory area</tag>
From &dollar;D400 to &dollar;DFFF (3 KB)
<tag><tt/STARTADDRESS:/ Program start address</tag>
Fixed (&dollar;2000)
<tag><tt/HEADER:/ Binary file header</tag>
None
</descrip><p>
<sect1><tt/apple2enh-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&nbsp;&rsqb;&lsqb; 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 address &dollar;2000. Thus with the default start
address &dollar;800 the main memory area is increased by 6 KB.
<descrip>
<tag><tt/RAM:/ Main memory area</tag>
From &dollar;800 to &dollar;BEFF (45.75 KB)
<tag><tt/LC:/ Language Card memory area</tag>
From &dollar;D400 to &dollar;DFFF (3 KB)
<tag><tt/STARTADDRESS:/ Program start address</tag>
Variable (default: &dollar;800)
<tag><tt/HEADER:/ Binary file header</tag>
DOS 3.3 header (address and length)
</descrip><p>
<sect1><tt/apple2enh-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&nbsp;&rsqb;&lsqb; 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 &dollar;800 to &dollar;BEFF (45.75 KB)
<tag><tt/LC:/ Language Card memory area</tag>
From &dollar;D000 to &dollar;DFFF (4 KB)
<tag><tt/STARTADDRESS:/ Program start address</tag>
Variable (default: &dollar;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 address &dollar;2000.
For cc65 programs this means that the 6 KB from &dollar;800 to &dollar;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 &dollar;800 to &dollar;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
&dollar;800 and load it with <bf/LOADER.SYSTEM - an Apple&nbsp;&rsqb;&lsqb;
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 &lt;program&gt;.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 successfully linked as system program using the linker
configuration <htmlurl url="apple2enh-4.html#ss4.3" name="apple2enh-system.cfg"> but
uses the heap either explicitly or implicitly (i.e. by loading a driver) then
the memory from &dollar;800 to &dollar;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 this is generally the best solution it means quite
some overhead for (especially rather small) cc65 programs which do open files
but don't make use of the heap otherwise.
The apple2enh package comes with the alternative ProDOS 8 I/O buffer allocation
module <tt/apple2enh-iobuf-0800.o/ which uses the memory between &dollar;800 and
the program start address for the 1 KB I/O buffers. For system programs (with
start address &dollar;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
in memory the primary benefit of <tt/apple2enh-iobuf-0800.o/ is a reduction in code
size - and thus program file size - of more than 1400 bytes.
Using <tt/apple2enh-iobuf-0800.o/ is as simple as placing it on the linker command
line like this:
<tscreen><verb>
cl65 -t apple2enh -C apple2enh-system.cfg myprog.c apple2enh-iobuf-0800.o
</verb></tscreen>
<sect>Platform specific header files<p>
Programs containing enhanced&nbsp;Apple&nbsp;//e specific code may use the
<tt/apple2enh.h/ header file.
<sect1>Enhanced&nbsp;Apple&nbsp;//e specific functions<p>
The functions listed below are special for the enhanced&nbsp;Apple&nbsp;//e. See
the <htmlurl url="funcref.html" name="function reference"> for declaration and
usage.
<itemize>
<item>_auxtype
<item>_dos_type
<item>_filetype
<item>get_ostype
<item>rebootafterexit
<item>ser_apple2_slot
<item>textframe
<item>textframexy
<item>tgi_apple2_mix
<item>videomode
</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>
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 (apple2_40_48_16)/</tag>
This driver features a resolution of 40&times;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 (apple2_280_192_8)/</tag>
This driver features a resolution of 280&times;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.
Note that the second hires page is only available if the text display is not in
80 column mode. This can be asserted by calling <tt/videomode (VIDEOMODE_40COL);/
before installing the driver.
The function <tt/tgi_apple2_mix()/ allows to activate 4 lines of text. The
function doesn't clear the corresponding area at the bottom of the screen.
In memory constrained situations the memory from &dollar;803 to &dollar;1FFF
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.
</descrip><p>
<sect1>Extended memory drivers<p>
<descrip>
<tag><tt/a2e.auxmem.emd (apple2_auxmem)/</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 (apple2_stdjoy)/</tag>
Supports up to two standard analog joysticks connected to the game port of
the enhanced&nbsp;Apple&nbsp;//e.
</descrip><p>
<sect1>Mouse drivers<p>
<descrip>
<tag><tt/a2e.stdmou.mou (apple2_stdmou)/</tag>
Driver for the AppleMouse&nbsp;II Card. Searches all Apple&nbsp;II slots
for an AppleMouse&nbsp;II Card compatible firmware. The default bounding
box is &lsqb;0..279,0..191&rsqb;.
Note that the enhanced&nbsp;Apple&nbsp;//e default mouse callbacks support
text mode only.
</descrip><p>
<sect1>RS232 device drivers<p>
<descrip>
<tag><tt/a2e.ssc.ser (apple2_ssc)/</tag>
Driver for the Apple&nbsp;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_apple2_slot()/ prior to
<tt/ser_open()/ in order to select a different slot. <tt/ser_apple2_slot()/
succeeds for all Apple&nbsp;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&nbsp;Apple&nbsp;//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/
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>Direct console I/O<p>
<descrip>
<tag/Color/
The enhanced&nbsp;Apple&nbsp;//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/
The enhanced&nbsp;Apple&nbsp;//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&nbsp;Apple&nbsp;//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 <htmlurl
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/device/ to identify the device to be opened. Therefore an
Apple&nbsp;II slot and drive pair is mapped to that <tt/drive_id/ according
to the formula
<tscreen>
device = slot + (drive - 1) * 8
</tscreen>
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 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 <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
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>

156
doc/ar65.sgml Normal file
View File

@ -0,0 +1,156 @@
<!doctype linuxdoc system>
<article>
<title>ar65 Users Guide
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
<date>19.07.2000
<abstract>
ar65 is an archiver for object files generated by ca65. It allows to create
archives, add or remove modules from archives, and to extract modules from
existing archives.
</abstract>
<!-- Table of contents -->
<toc>
<!-- Begin the document -->
<sect>Overview<p>
ar65 is a replacement for the libr65 archiver that was part of the cc65 C
compiler suite developed by John R. Dunning. libr65 had some problems and
the copyright does not permit some things which I wanted to be possible,
so I decided to write a completely new assembler/linker/archiver suite
for the cc65 compiler. ar65 is part of this suite.
<sect>Usage<p>
The archiver is called as follows:
<tscreen><verb>
Usage: ar65 <operation> lib file|module ...
Operation is one of:
a Add modules
d Delete modules
l List library contents
x Extract modules
V Print the archiver version
</verb></tscreen>
You may add modules to a library using the `a' command. If the library
does not exist, it is created (and a warning message is printed which you
may ignore if creation of the library was your intention). You may
specify any number of modules on the command line following the library.
If a module with the same name exists in the library, it is replaced by
the new one. The archiver prints a warning, if the module in the library
has a newer timestamp than the one to add.
Here's an example:
<tscreen><verb>
ar65 a mysubs.lib sub1.o sub2.o
</verb></tscreen>
This will add two modules to the library `mysubs.lib' creating the
library if necessary. If the library contains modules named sub1.o or
sub2.o, they are replaced by the new ones.
Modules names in the library are stored without the path, so, using
<tscreen><verb>
ar65 a mysubs.lib ofiles/sub1.o ofiles/sub2.o
</verb></tscreen>
will add two modules named `sub1.o' and `sub2.o' to the library.
Deleting modules from a library is done with the `d' command. You may not
give a path when naming the modules.
Example:
<tscreen><verb>
ar65 d mysubs.lib sub1.o
</verb></tscreen>
This will delete the module named `sub1.o' from the library, printing an
error if the library does not contain that module.
The `l' command prints a list of all modules in the library. Any module
names on the command line are ignored.
Example:
<tscreen><verb>
ar65 l mysubs.lib
</verb></tscreen>
Using the `x' command, you may extract modules from the library. The
modules named on the command line are extracted from the library and put
into the current directory.
Note: Because of the indexing done by the archiver, the modules may have
a changed binary layout, that is, a binary compare with the old module
(before importing it into the library) may yield differences. The
extracted modules are accepted by the linker and archiver, however, so
this is not a problem.
Example for extracting a module from the library:
<tscreen><verb>
ar65 x mysubs.lib sub1.o
</verb></tscreen>
The `V' command prints the version number of the assembler. If you send
any suggestions or bugfixes, please include your version number.
In addition to these operations, the archiver will check for, and warn
about duplicate external symbols in the library, every time when an
operation does update the library. This is only a warning, the linker
will ignore one of the duplicate symbols (which one is unspecified).
<sect>Bugs/Feedback<p>
If you have problems using the archiver, 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>Copyright<p>
ar65 (and all cc65 binutils) are (C) Copyright 1998-2000 Ullrich von
Bassewitz. For usage of the binaries and/or sources the following conditions
do apply:
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>

590
doc/atari.sgml Normal file
View File

@ -0,0 +1,590 @@
<!doctype linuxdoc system>
<article>
<title>Atari specific information for cc65
<author>Shawn Jefferson, <htmlurl
url="mailto:shawnjefferson@24fightingchickens.com"
name="shawnjefferson@24fightingchickens.com"> and
Christian Groessler, <htmlurl url="mailto:chris@groessler.org" name="chris@groessler.org">
<date>03-Jan-2006
<abstract>
An overview over the Atari 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 Atari runtime system as it comes
with the cc65 C compiler. It describes the memory layout, Atari specific
header files, available drivers, and any pitfalls specific to that
platform.
Please note that Atari 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
Atari target is a machine language program with a standard executable
header (FF FF &lt;2 byte start address&gt; &lt;2 bytes end address&gt;
&lsqb;program bytes&rsqb;). These values are calculated in the crt0.s
file from the __STARTUP_LOAD__ and __ZPSAVE_LOAD__ values, so keep
this in mind if you create a custom linker config file and start
moving segments around (see section
<ref name="Reserving a memory area inside the program" id="memhole">).
You can override this behaviour by creating your own crt0.s file and
linking it into your program. A run vector is added to the end of the
file (&dollar;02E0 &lt;run vector&gt;) and is calculated using
__STARTUP_LOAD__ in crt0.s.
<sect>Memory layout<p>
The default linker script assumes that the BASIC ROM is disabled (or
the BASIC cartridge unplugged). This gives a usable memory range from
&dollar;2E00 - &dollar;BC1F. The library startup code examines the
current memory configuration, which depends on the size of the
installed memory and cartridges present, by inspecting the value in
the MEMTOP (&dollar;2E5) variable. Then the initial stack pointer,
which indicates the upper bound of memory used, is adjusted. The
default load address of &dollar;2E00 was chosen to accommodate having
a DOS loaded and a driver that resides in low memory such as the 850
R: handler. You can override this behaviour by creating a custom
linker config file or by using the "--start-addr" cl65 command line
argument or the "--start-addr" or "-S" ld65 command line arguments.
Special locations:
<descrip>
<tag/Text screen/
The text screen depends on the installed memory size and cartridges
and can be obtained from the SAVMSC variable (&dollar;58).
<tag/Stack/
The C runtime stack is located at MEMTOP and grows downwards,
regardless of how your linker config file is setup. This
accommodates the different memory configurations of the Atari
machines, as well as having a cartridge installed. You can override
this behaviour by writing your own crt0.s file and linking it to
your program (see also <ref name="Final note"
id="memhole_final_note">).
<tag/Heap/
The C heap is located at the end of the program and grows towards the C
runtime stack.
</descrip><p>
<sect>Platform specific header files<p>
Programs containing Atari specific code may use the <tt/atari.h/
header file.
<sect1>Atari specific functions<p>
The functions and global variable listed below are special for the Atari.
See the <htmlurl url="funcref.html" name="function reference"> for declaration and usage.
<itemize>
<item>get_ostype
<item>get_tv
<item>_dos_type
<item>_gtia_mkcolor
<item>_getcolor
<item>_getdefdev
<item>_graphics
<item>_rest_vecs
<item>_save_vecs
<item>_scroll
<item>_setcolor
<item>_setcolor_low
</itemize>
<sect1>Hardware access<p>
The following pseudo variables declared in the <tt/atari.h/ header
file do allow access to hardware located in the address space. Some
variables are structures, accessing the struct fields will access the
chip registers.
<descrip>
<tag><tt/GTIA_READ/ and <tt/GTIA_WRITE/</tag>
The <tt/GTIA_READ/ structure allows read access to the GTIA. The
<tt/GTIA_WRITE/ structure allows write access to the GTIA.
See the <tt/_gtia.h/ header file located in the include directory
for the declaration of the structure.
<tag><tt/POKEY_READ/ and <tt/POKEY_WRITE/</tag>
The <tt/POKEY_READ/ structure allows read access to the POKEY. The
<tt/POKEY_WRITE/ structure allows write access to the POKEY.
See the <tt/_pokey.h/ header file located in the include directory
for the declaration of the structure.
<tag><tt/ANTIC/</tag>
The <tt/ANTIC/ structure allows read access to the ANTIC.
See the <tt/_antic.h/ header file located in the include directory
for the declaration of the structure.
<tag><tt/PIA/</tag>
The <tt/PIA/ structure allows read access to the PIA 6520.
See the <tt/_pia.h/ header file located in the include directory
for the declaration of the structure.
</descrip><p>
<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/atari10.tgi (atari_10)/</tag>
<tag><tt/atr10p2.tgi (atari_10p2)/</tag>
<tag><tt/atari11.tgi (atari_11)/</tag>
<tag><tt/atari14.tgi (atari_14)/</tag>
<tag><tt/atari15.tgi (atari_15)/</tag>
<tag><tt/atr15p2.tgi (atari_15p2)/</tag>
<tag><tt/atari3.tgi (atari_3)/</tag>
<tag><tt/atari4.tgi (atari_4)/</tag>
<tag><tt/atari5.tgi (atari_5)/</tag>
<tag><tt/atari6.tgi (atari_6)/</tag>
<tag><tt/atari7.tgi (atari_7)/</tag>
<tag><tt/atari8.tgi (atari_8)/</tag>
<tag><tt/atr8p2.tgi (atari_8p2)/</tag>
<tag><tt/atari9.tgi (atari_9)/</tag>
<tag><tt/atr9p2.tgi (atari_9p2)/</tag>
</descrip><p>
Many graphics modes require more memory than the text screen which is
in effect when the program starts up. Therefore the programmer has to
tell the program beforehand the memory requirements of the graphics
modes the program intends to use.
This can be done by using the __RESERVED_MEMORY__ linker config
variable. The number specified there describes the number of bytes to
subtract from the top of available memory as seen from the runtime
library. This memory is then used by the screen buffer.
The numbers for the different graphics modes presented below should
only be seen as a rule of thumb. Since the screen buffer memory needs
to start at specific boundaries, the numbers depend on the current top
of available memory.
The following numbers were determined by a BASIC program.
<table>
<tabular ca="rr">
graphics mode|reserved memory@<hline>
0|1@
1|1@
2|1@
3|1@
4|1@
5|182@
6|1182@
7|3198@
8|7120@
9|7146@
10|7146@
11|7146@
12|162@
13|1@
14|3278@
15|7120@
16|1@
17|1@
18|1@
19|1@
20|1@
21|184@
22|1192@
23|3208@
24|7146@
25|7146@
26|7146@
27|7146@
28|162@
29|1@
30|3304@
31|7146
</tabular>
<caption>reserved memory required for different graphics modes
</table>
The values of "1" are needed because the graphics command crashes if
it doesn't have at least one byte available. This seems to be a bug of
the Atari ROM code.
<sect1>Extended memory drivers<p>
<descrip>
<tag><tt/atr130xe.emd (atari_130xe)/</tag>
</descrip><p>
<sect1>Joystick drivers<p>
<descrip>
<tag><tt/ataristd.joy (atari_stdjoy)/</tag>
Supports up to four standard joysticks connected to the joystick ports of
the Atari.
<tag><tt/atarim8.joy (atari_multijoy)/</tag>
Supports up to eight standard joysticks connected to a MultiJoy adapter.
</descrip><p>
<sect1>Mouse drivers<p>
Currently no drivers available (in fact, the API for loadable mouse drivers
does not exist). There is a static driver you can use.
<sect1>RS232 device drivers<p>
Currently there are no RS232 loadable drivers available for the Atari
platform. There is a static driver you can use.
<sect>Limitations<p>
<sect>DIO implementation<label id="dio"><p>
The Atari supports disk drives with either 128 or 256 byte sectors.
The first three sectors of any disk are always 128 bytes long though. This is
because the system can only boot from 128 bytes sectors.
Therefore the DIO read and write functions transfer only 128 bytes
for sectors 1 to 3, regardless of the type of diskette.
<sect>CONIO implementation<label id="conio"><p>
The console I/O is speed optimized therefore support for XEP80 hardware
or f80.com software is missing. Of course you may use stdio.h functions.
<sect>Other hints<p>
<sect1>Function keys<p>
Function keys are mapped to Atari + number key.
<sect1>Passing arguments to the program<p>
Command line arguments can be passed to <tt/main()/ when DOS supports it.
<enum>
<item>Arguments are separated by spaces.
<item>Leading and trailing spaces around an argument are ignored.
<item>The first argument passed to <tt/main/ is the program name.
<item>A maximum number of 16 arguments (including the program name) are
supported.
</enum>
<sect1>Interrupts<p>
The runtime for the Atari uses routines marked as <tt/.INTERRUPTOR/ for
interrupt handlers. Such routines must be written as simple machine language
subroutines and will be called automatically by the VBI 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>Reserving a memory area inside a program<label id="memhole"><p>
The Atari 130XE maps its additional memory into CPU memory in 16K
chunks at address &dollar;4000 to &dollar;7FFF. One might want to
prevent this memory area from being used by cc65. Other reasons to
prevent the use of some memory area could be to reserve space for the
buffers for display lists and screen memory.
<p>
The Atari executable format allows holes inside a program, e.g. one
part loads into &dollar;2E00 to &dollar;3FFF, going below the reserved
memory area (assuming a reserved area from &dollar;4000 to
&dollar;7FFF), and another part loads into &dollar;8000 to
&dollar;BC1F.
<p>
Each load chunk of the executable starts with a 4 byte header which
defines its load address and size. In the following linker scripts
these headers are named HEADER and SECHDR (for the MEMORY layout), and
accordingly NEXEHDR and CHKHDR (for the SEGMENTS layout).
<p>
<sect2>Low code and high data example<p>
Goal: Create an executable with 2 load chunks which doesn't use the
memory area from &dollar;4000 to &dollar;7FFF. The CODE segment of
the program should go below &dollar;4000 and the DATA and RODATA
segments should go above &dollar;7FFF.
<p>
The main problem is that the EXE header generated by the cc65 runtime
lib is wrong. It defines a single load chunk with the sizes/addresses
of the STARTUP, LOWCODE, INIT, CODE, RODATA, and DATA segments (the whole user
program).
<p>
The contents of the EXE header come from the EXEHDR segment, which is
defined in crt0.s. This cannot be changed without modifying and
recompiling the cc65 atari runtime lib. Therefore the original EXE
header must be discarded. It will be replaced by a user created
one. The discarding is done by assigning the EXEHDR segment to the
BANK memory area. The BANK memory area is discarded in the new linker
script (written to file "").
<p>
The user needs to create a customized linker config file which adds
new memory areas and segments to hold the new EXE header and the
header data for the second load chunk. Also an assembly source file
needs to be created which defines the contents of the new EXE header
and the second load chunk header.
<p>
<p>
This is an example of a modified cc65 Atari linker configuration file
(split.cfg):
<tscreen><verb>
SYMBOLS {
__STACKSIZE__ = $800; # 2K stack
__RESERVED_MEMORY__: value = $0000, weak = yes;
}
FEATURES {
STARTADDRESS: default = $2E00;
}
MEMORY {
ZP: start = $82, size = $7E, type = rw, define = yes;
HEADER: start = $0000, size = $6, file = %O; # first load chunk
RAMLO: start = %S, size = $4000 - %S, file = %O;
BANK: start = $4000, size = $4000, file = "";
SECHDR: start = $0000, size = $4, file = %O; # second load chunk
RAM: start = $8000, size = $3C20, file = %O; # $3C20: matches upper bound $BC1F
}
SEGMENTS {
EXEHDR: load = BANK, type = ro;
NEXEHDR: load = HEADER, type = ro; # first load chunk
STARTUP: load = RAMLO, type = ro, define = yes;
LOWCODE: load = RAMLO, type = ro, define = yes, optional = yes;
INIT: load = RAMLO, type = ro, optional = yes;
CODE: load = RAMLO, type = ro, define = yes;
CHKHDR: load = SECHDR, type = ro; # second load chunk
RODATA: load = RAM, type = ro, define = yes;
DATA: load = RAM, type = rw, define = yes;
BSS: load = RAM, type = bss, define = yes;
ZPSAVE: load = RAM, type = bss, define = yes;
ZEROPAGE: load = ZP, type = zp;
AUTOSTRT: load = RAM, type = ro; # defines program entry point
}
FEATURES {
CONDES: segment = RODATA,
type = constructor,
label = __CONSTRUCTOR_TABLE__,
count = __CONSTRUCTOR_COUNT__;
CONDES: segment = RODATA,
type = destructor,
label = __DESTRUCTOR_TABLE__,
count = __DESTRUCTOR_COUNT__;
}
</verb></tscreen>
<p>
A new memory area BANK was added which describes the reserved area.
It gets loaded with the contents of the old EXEHDR segment. But the
memory area isn't written to the output file. This way the contents of
the EXEHDR segment get discarded.
<p>
The newly added NEXEHDR segment defines the correct EXE header. It
puts the STARTUP, LOWCODE, INIT, and CODE segments, which are the
segments containing only code, into load chunk #1 (RAMLO memory area).
<p>
The header for the second load chunk comes from the new CHKHDR
segment. It puts the RODATA, DATA, BSS, and ZPSAVE segments into load
chunk #2 (RAM memory area).
<p>
<p>
The contents of the new NEXEHDR and CHKHDR segments come from this
file (split.s):
<tscreen><verb>
.import __CODE_LOAD__, __BSS_LOAD__, __CODE_SIZE__
.import __DATA_LOAD__, __RODATA_LOAD__, __STARTUP_LOAD__
.segment "NEXEHDR"
.word $FFFF
.word __STARTUP_LOAD__
.word __CODE_LOAD__ + __CODE_SIZE__ - 1
.segment "CHKHDR"
.word __RODATA_LOAD__
.word __BSS_LOAD__ - 1
</verb></tscreen>
<p>
Compile with
<tscreen><verb>
cl65 -t atari -C split.cfg -o prog.com prog.c split.s
</verb></tscreen>
<sect2>Low data and high code example<p>
Goal: Put RODATA and DATA into low memory and STARTUP, LOWCODE, INIT,
CODE, BSS, ZPSAVE into high memory (split2.cfg):
<tscreen><verb>
SYMBOLS {
__STACKSIZE__ = $800; # 2K stack
__RESERVED_MEMORY__: value = $0000, weak = yes;
}
FEATURES {
STARTADDRESS: default = $2E00;
}
MEMORY {
ZP: start = $82, size = $7E, type = rw, define = yes;
HEADER: start = $0000, size = $6, file = %O; # first load chunk
RAMLO: start = %S, size = $4000 - %S, file = %O;
BANK: start = $4000, size = $4000, file = "";
SECHDR: start = $0000, size = $4, file = %O; # second load chunk
RAM: start = $8000, size = $3C20, file = %O; # $3C20: matches upper bound $BC1F
}
SEGMENTS {
EXEHDR: load = BANK, type = ro; # discarded old EXE header
NEXEHDR: load = HEADER, type = ro; # first load chunk
RODATA: load = RAMLO, type = ro, define = yes;
DATA: load = RAMLO, type = rw, define = yes;
CHKHDR: load = SECHDR, type = ro; # second load chunk
STARTUP: load = RAM, type = ro, define = yes;
INIT: load = RAM, type = ro, optional = yes;
CODE: load = RAM, type = ro, define = yes;
ZPSAVE: load = RAM, type = bss, define = yes;
BSS: load = RAM, type = bss, define = yes;
ZEROPAGE: load = ZP, type = zp;
AUTOSTRT: load = RAM, type = ro; # defines program entry point
}
FEATURES {
CONDES: segment = RODATA,
type = constructor,
label = __CONSTRUCTOR_TABLE__,
count = __CONSTRUCTOR_COUNT__;
CONDES: segment = RODATA,
type = destructor,
label = __DESTRUCTOR_TABLE__,
count = __DESTRUCTOR_COUNT__;
}
</verb></tscreen>
New contents for NEXEHDR and CHKHDR are needed (split2.s):
<tscreen><verb>
.import __STARTUP_LOAD__, __ZPSAVE_LOAD__, __DATA_SIZE__
.import __DATA_LOAD__, __RODATA_LOAD__
.segment "NEXEHDR"
.word $FFFF
.word __RODATA_LOAD__
.word __DATA_LOAD__ + __DATA_SIZE__ - 1
.segment "CHKHDR"
.word __STARTUP_LOAD__
.word __ZPSAVE_LOAD__ - 1
</verb></tscreen>
Compile with
<tscreen><verb>
cl65 -t atari -C split2.cfg -o prog.com prog.c split2.s
</verb></tscreen>
<sect2>Final note<label id="memhole_final_note"><p>
There are two other memory areas which don't appear directly in the
linker script. They are the stack and the heap.
The cc65 runtime lib places the stack location at the end of available
memory. This is dynamically set from the MEMTOP system variable at
startup. The heap is located in the area between the end of the BSS
segment and the top of the stack as defined by __STACKSIZE__.
If BSS and/or the stack shouldn't stay at the end of the program,
some parts of the cc65 runtime lib need to be replaced/modified.
common/_heap.s defines the location of the heap and atari/crt0.s
defines the location of the stack by initializing sp.
<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"> or <htmlurl url="mailto:chris@groessler.org"
name="chris@groessler.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>

260
doc/atmos.sgml Normal file
View File

@ -0,0 +1,260 @@
<!doctype linuxdoc system>
<article>
<title>Oric Atmos specific information for cc65
<author>Ullrich von Bassewitz <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"><newline>
Stefan A. Haubenthal <htmlurl url="mailto:polluks@sdf.lonestar.org" name="polluks@sdf.lonestar.org"><newline>
<url url="mailto:greg.king5@verizon.net" name="Greg King">
<date>2013-01-08
<abstract>
An overview over the Atmos 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 Atmos runtime system as it comes with the
cc65 C compiler. It describes the memory layout, Atmos specific header files,
available drivers, and any pitfalls specific to that platform.
Please note that Atmos 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 Atmos target
is a machine language program with a 17 byte tape header including a cc65 tag.
The standard load and autostart address is &dollar;500.
<sect>Memory layout<p>
In the standard setup, cc65 generated programs use the memory from
&dollar;500 to &dollar;9800, so nearly 37K of memory (including the stack) is
available. ROM calls are possible without further precautions.
Special locations:
<descrip>
<tag/Stack/
The C runtime stack is located at &dollar;97FF and growing downwards.
<tag/Heap/
The C heap is located at the end of the program and grows towards the C
runtime stack.
</descrip><p>
<sect>Platform specific header files<p>
Programs containing Atmos specific code may use the <tt/atmos.h/ header file.
<sect1>Atmos specific functions<p>
The functions listed below are special for the Atmos. See the <htmlurl
url="funcref.html" name="function reference"> for declaration and usage.
<itemize>
<item>atmos_load
<item>atmos_save
</itemize>
<sect1>Hardware access<p>
The following pseudo variables declared in the <tt/atmos.h/ header file do allow
access to hardware located in the address space. Some variables are
structures, accessing the struct fields will access the chip registers.
<descrip>
<tag><tt/VIA/</tag>
Access to the VIA (versatile interface adapter) chip is available via the
<tt/VIA/ variable. The structure behind this variable is explained in <tt/_6522.h/.
</descrip><p>
<sect>Loadable drivers<p>
<em>Note:</em> Since the Atmos doesn't have working disk I/O
(see <ref id="limitations" name="section &quot;Limitations&quot;">), the
available drivers cannot be loaded at runtime (so the term "loadable drivers"
is somewhat misleading). Instead, the drivers have to be 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 Atmos 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>
The names in the parentheses denote the symbols to be used for static linking of the drivers.
<sect1>Graphics drivers<p>
<descrip>
<tag><tt/atmos-228-200-3.tgi (atmos_228_200_3)/</tag>
This driver was written by Greg King and Stefan Haubenthal.
It features a resolution of 228&times;200 with a palette of two colors that
can be chosen from the Atmos's eight colors. The driver supports a third
palette-"color" that actually "flips" the pixel (it becomes the other color)
that is on the screen under the graphics cursor.
<tag><tt/atmos-240-200-2.tgi (atmos_240_200_2)/</tag>
This driver was written by Stefan Haubenthal and Greg King.
It features a resolution of 240&times;200 with black and white colors.
It is the default graphics driver for the Atmos.
</descrip><p>
<sect1>Extended memory drivers<p>
No extended memory drivers are currently available for the Atmos.
<sect1>Joystick drivers<p>
<descrip>
<tag><tt/atmos-pase.joy (atmos_pase)/</tag>
Supports two standard joysticks connected to the P.A.S.E. interface of the Atmos.
</descrip><p>
<sect1>Mouse drivers<p>
No mouse drivers are currently available for the Atmos.
<sect1>RS232 device drivers<p>
<descrip>
<tag><tt/atmos-acia.ser (atmos_acia)/</tag>
Driver for the Telestrat integrated serial controller and the Atmos with a
serial add-on.
Note that because of the peculiarities of the 6551 chip together with the
use of the NMI, transmits are not interrupt driven, and the transceiver
blocks if the receiver asserts flow control because of a full buffer.
</descrip><p>
<sect>Limitations<label id="limitations"><p>
<sect1>Disk I/O<p>
The existing library for the Atmos doesn't implement C file
I/O. There is one hack for the <tt/write()/ routine in
place, which will make functions work that write to <tt/stdout/
(like <tt/printf()/). However, this function has some shortcomings which
won't be fixed, because it's 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):
<itemize>
<item>fclose
<item>fopen
<item>fread
<item>fprintf
<item>fputc
<item>fscanf
<item>fwrite
<item>...
</itemize>
<sect>Other hints<p>
<sect1>Function keys<p>
These are defined to be FUNCT + number key.
<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 chosen:
<tscreen><verb>
CALL#500: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>Interrupts<p>
The runtime for the Atmos uses routines marked as <tt/.INTERRUPTOR/ for
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>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>

356
doc/c128.sgml Normal file
View File

@ -0,0 +1,356 @@
<!doctype linuxdoc system>
<article>
<title>Commodore 128 specific information for cc65
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
<date>2003-12-14
<abstract>
An overview over the C128 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 C128 runtime system as it comes with the
cc65 C compiler. It describes the memory layout, C128 specific header files,
available drivers, and any pitfalls specific to that platform.
Please note that C128 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 C128 target
is a machine language program with a one line BASIC stub, which calls the
machine language part via SYS. This means that a program can be loaded as
BASIC program and started with RUN. It is of course possible to change this
behaviour by using a modified startup file and linker config.
<sect>Memory layout<p>
cc65 generated programs with the default setup run with the I/O area and the
kernal ROM enabled. Note that this is a non standard memory layout, and that
there is no "memory configuration index" for this layout. This means that
special care has to be taken when changing the configuration, or calling any
code that does this. The memory configuration register at &dollar;FF00 should
be saved and restored instead of relying on the memory configuration index
stored in the zero page.
The setup gives a usable memory range of &dollar;1C00 - &dollar;BFFF. Having
just the kernal ROM mapped in means, that kernal entry points may be called
directly, but using the BASIC ROM is not possible without additional code.
Special locations:
<descrip>
<tag/Text screen/
The text screen is located at &dollar;400 (as in the standard setup).
<tag/Stack/
The C runtime stack is located at &dollar;BFFF and growing downwards.
<tag/Heap/
The C heap is located at the end of the program and grows towards the C
runtime stack.
</descrip><p>
<sect>Platform specific header files<p>
Programs containing C128 specific code may use the <tt/c128.h/ or <tt/cbm.h/
header files. Using the later may be an option when writing code for more than
one CBM platform, since it includes <tt/c128.h/ and declares several functions
common to all CBM platforms.
<sect1>C128 specific functions<p>
The functions listed below are special for the C128. See the <htmlurl
url="funcref.html" name="function reference"> for declaration and usage.
<itemize>
<item>videomode
<item>c64mode
<item>fast
<item>slow
</itemize>
<sect1>CBM specific functions<p>
Some functions are available for all (or at least most) of the Commodore
machines. See the <htmlurl url="funcref.html" name="function reference"> for
declaration and usage.
<itemize>
<item>cbm_close
<item>cbm_closedir
<item>cbm_k_setlfs
<item>cbm_k_setnam
<item>cbm_k_load
<item>cbm_k_save
<item>cbm_k_open
<item>cbm_k_close
<item>cbm_k_readst
<item>cbm_k_chkin
<item>cbm_k_ckout
<item>cbm_k_basin
<item>cbm_k_bsout
<item>cbm_k_clrch
<item>cbm_load
<item>cbm_open
<item>cbm_opendir
<item>cbm_read
<item>cbm_readdir
<item>cbm_save
<item>cbm_write
<item>get_tv
</itemize>
<sect1>Hardware access<p>
The following pseudo variables declared in the <tt/c128.h/ header file do
allow access to hardware located in the address space. Some variables are
structures, accessing the struct fields will access the chip registers.
<descrip>
<tag><tt/VIC/</tag>
The <tt/VIC/ structure allows access to the VIC II (the graphics
controller). See the <tt/_vic2.h/ header file located in the include
directory for the declaration of the structure.
<tag><tt/SID/</tag>
The <tt/SID/ structure allows access to the SID (the sound interface
device). See the <tt/_sid.h/ header file located in the include directory
for the declaration of the structure.
<tag><tt/VDC/</tag>
The <tt/VDC/ structure allows access to the VDC (the video display
controller). See the <tt/_vdc.h/ header file located in the include
directory for the declaration of the structure.
<tag><tt/CIA1, CIA2/</tag>
Access to the two CIA (complex interface adapter) chips is available via
the <tt/CIA1/ and <tt/CIA2/ variables. The structure behind these variables
is explained in <tt/_6526.h/.
<tag><tt/COLOR_RAM/</tag>
A character array that mirrors the color RAM of the C128 at &dollar;D800.
</descrip><p>
<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>
Note: The graphics drivers for the VDC are incompatible with the extended
memory drivers using the VDC memory!
<descrip>
<tag><tt/c128-vdc.tgi (c128_640_200_2)/</tag>
This driver was written by Maciej Witkowiak. It uses the 80 column display
and features a resolution of 640*200 with two colors and an adjustable
palette (that means that the two colors can be chosen out of the 16 VDC
colors).
<tag><tt/c128-vdc2.tgi (c128_640_480_2)/</tag>
This driver was written by Maciej Witkowiak. This driver uses the 80 column
display and features a resolution of 640*480 with two colors and an
adjustable palette (that means that the two colors can be chosen out of the
16 VDC colors). The driver requires 64KB VDC RAM.
</descrip><p>
Note: The colors are translated from definitions in headers to correct VDC values
so please use definitions or VIC color numbers only. Colors <tt/GRAY3/ and <tt/BROWN/ are
missing on VDC and are translated to the two colors missing from VIC palette.
<sect1>Extended memory drivers<p>
<descrip>
<tag><tt/c128-georam.emd (c128_georam)/</tag>
A driver for the GeoRam cartridge. The driver will always assume 2048 pages
of 256 bytes each. There are no checks, so if your program knows better,
just go ahead.
<tag><tt/c128-ram.emd (c128_ram)/</tag>
An extended memory driver for the RAM in page 1. The common memory area is
excluded, so this driver supports 251 pages of 256 bytes each.
<tag><tt/c128-ram2.emd (c128_ram2)/</tag>
An extended memory driver for the RAM in pages 1-3. The common memory area
is excluded, so this driver supports up to 731 pages of 256 bytes each. The
driver can be used as a full replacement for <tt/c128-ram.emd/, because RAM
in pages 2+3 is autodetected, but it's larger and there are not many
machines with RAM in banks 2+3, so it has been made a separate driver. The
additional code was contributed by Marco van den Heuvel.
<tag><tt/c128-ramcart.emd (c128_ramcart)/</tag>
A driver for the RamCart 64/128 written and contributed by Maciej Witkowiak.
Will test the hardware for the available RAM.
<tag><tt/c128-reu.emd (c128_reu)/</tag>
A driver for the CBM REUs. The driver will determine from the connected REU
if it supports 128KB of RAM or more. In the latter case, 256KB are assumed,
but since there are no range checks, the application can use more memory if
it has better knowledge about the hardware than the driver.
<tag><tt/c128-vdc.emd (c128_vdc)/</tag>
A driver for the VDC memory of the C128 written and contributed by Maciej
Witkowiak. Autodetects the amount of memory available (16 or 64K) and offers
64 or 256 pages of 256 bytes each. Note: This driver is incompatible with
any of the graphics drivers using the VDC!
</descrip><p>
<sect1>Joystick drivers<p>
<descrip>
<tag><tt/c128-ptvjoy.joy (c128_ptvjoy)/</tag>
Driver for the Protovision 4-player adapter originally written by Groepaz
for the C64 and converted for the C128 by me. See <htmlurl
url="http://www.protovision-online.de/hardw/hardwstart.htm"
name="http://www.protovision-online.de/hardw/hardwstart.htm"> for prices and
building instructions. Up to four joysticks are supported.
<tag><tt/c128-stdjoy.joy (c128_stdjoy)/</tag>
Supports up to two joysticks connected to the standard joysticks port of
the C128.
</descrip><p>
<sect1>Mouse drivers<p>
<descrip>
<tag><tt/c128-1351.mou (c128_1351)/</tag>
Supports a standard mouse connected to port #0 of the C128.
<tag><tt/c128-joy.mou (c128_joymouse)/</tag>
Supports a mouse emulated by a standard joystick e.g. 1350 mouse in port
#1 of the C128.
<tag><tt/c128-pot.mou (c128_potmouse)/</tag>
Supports a potentiometer device e.g. Koala Pad connected to port #1 of
the C128.
</descrip><p>
<sect1>RS232 device drivers<p>
<descrip>
<tag><tt/c128-swlink.ser (c128_swlink)/</tag>
Driver for the SwiftLink cartridge. Supports up to 38400 baud, hardware flow
control (RTS/CTS) and interrupt driven receives. Note that because of the
peculiarities of the 6551 chip together with the use of the NMI, transmits
are not interrupt driven, and the transceiver blocks if the receiver asserts
flow control because of a full buffer.
The driver uses the RS232 variables and buffers of the kernal (buffers at
&dollar;C00 and &dollar;D00).
</descrip><p>
<sect>Limitations<p>
<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 chosen:
<tscreen><verb>
RUN: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>Program return code<p>
The program return code (low byte) is passed back to BASIC by use of the
<tt/ST/ variable.
<sect1>Interrupts<p>
The runtime for the C128 uses routines marked as <tt/.INTERRUPTOR/ for
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>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>

274
doc/c16.sgml Normal file
View File

@ -0,0 +1,274 @@
<!doctype linuxdoc system>
<article>
<title>Commodore 16/116 specific information for cc65
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
<date>2003-12-15
<abstract>
An overview over the C16 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 C16 runtime system as it comes with the
cc65 C compiler. It describes the memory layout, C16/116 specific header
files, available drivers, and any pitfalls specific to that platform.
Please note that C16 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.
Since the C16/C116 and the Commodore Plus/4 are almost identical (the former
don't have the 6551 ACIA and only 16KB of memory), the <htmlurl
url="plus4.html" name="Plus/4 documentation"> is also worth a look. The
difference between both cc65 targets is that the Plus/4 runtime uses banking
to support full 64K RAM, while the C16 does not use banking and supports up to
32K RAM. Because banking is not needed, most C16 programs will be somewhat
smaller than the same program compiled for the Plus/4. However, programs C16
will always run on the Plus/4, while the reverse is not necessarily true.
<sect>Binary format<p>
The standard binary output format generated by the linker for the C16/116
target is a machine language program with a one line BASIC stub which, calls
the machine language part via SYS. This means that a program can be loaded as
BASIC program and started with RUN. It is of course possible to change this
behaviour by using a modified startup file and linker config.
<sect>Memory layout<p>
cc65 generated programs with the default setup run with the kernal and basic
banked in. This gives a usable memory range of &dollar;1000 - &dollar;4000
(or &dollar;8000 if the machine is equipped with 32K RAM or more). Having the
kernal and basic ROMs banked in means, that ROM entry points may be called
directly from user code.
Special locations:
<descrip>
<tag/Text screen/
The text screen is located at &dollar;C00 (as in the standard setup).
<tag/Color RAM/
The color RAM is located at &dollar;800 (standard location).
<tag/Stack/
The C runtime stack is located at &dollar;3FFF (&dollar;7FFF in case of a
machine with 32K of memory or more) and growing downwards.
<tag/Heap/
The C heap is located at the end of the program and grows towards the C
runtime stack.
</descrip><p>
<sect>Platform specific header files<p>
Programs containing C16 specific code may use the <tt/c16.h/ or <tt/cbm.h/
header files. Using the later may be an option when writing code for more than
one CBM platform, since it includes <tt/c16.h/ and declares several functions
common to all CBM platforms.
Please note that most of the header file declarations from the <tt/c16.h/
header file are shared between the C16 and Plus/4 configurations. For this
reason, most of it is located in a common header file named <tt/cbm264.h/.
<sect1>C16/C116 specific functions<p>
There are currently no special C16/C116 functions.
<sect1>CBM specific functions<p>
Some functions are available for all (or at least most) of the Commodore
machines. See the <htmlurl url="funcref.html" name="function reference"> for
declaration and usage.
<itemize>
<item>cbm_close
<item>cbm_closedir
<item>cbm_k_setlfs
<item>cbm_k_setnam
<item>cbm_k_load
<item>cbm_k_save
<item>cbm_k_open
<item>cbm_k_close
<item>cbm_k_readst
<item>cbm_k_chkin
<item>cbm_k_ckout
<item>cbm_k_basin
<item>cbm_k_bsout
<item>cbm_k_clrch
<item>cbm_load
<item>cbm_open
<item>cbm_opendir
<item>cbm_read
<item>cbm_readdir
<item>cbm_save
<item>cbm_write
<item>get_tv
</itemize>
<sect1>Hardware access<p>
The following pseudo variables declared in the <tt/c16.h/ header file do
allow access to hardware located in the address space. Some variables are
structures, accessing the struct fields will access the chip registers.
<descrip>
<tag><tt/TED/</tag>
The <tt/TED/ structure allows access to the TED chip. See the
<tt/_ted.h/ header file located in the include directory for the
declaration of the structure.
<tag><tt/COLOR_RAM/</tag>
A character array that mirrors the color RAM of the C16 at &dollar;0800.
</descrip><p>
<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>
No graphics drivers are currently available for the C16/C116.
<sect1>Extended memory drivers<p>
<descrip>
<tag><tt/c16-ram.emd (c16_ram)/</tag>
A driver for the hidden RAM below the BASIC and KERNAL ROMs. Supports 125
pages with 256 bytes each if the machine is equipped with 64K of memory
(a Plus/4 or a memory extended C16/116).
</descrip><p>
<sect1>Joystick drivers<p>
<descrip>
<tag><tt/c16-stdjoy.joy (c16_stdjoy)/</tag>
Supports up to two joysticks connected to the standard joysticks port of
the Commodore 16/116.
</descrip><p>
<sect1>Mouse drivers<p>
Currently no drivers available (in fact, the API for loadable mouse drivers
does not exist).
<sect1>RS232 device drivers<p>
The Commodore 16 does not have a builtin ACIA and no RS232 extensions are
known. For this reason, there are no RS232 drivers available. Please note that
the standard Plus/4 driver will <em>not</em> run together with the C16
library, because the latter does not support interrupts needed by the driver.
<sect>Limitations<p>
<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 chosen:
<tscreen><verb>
RUN: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>Program return code<p>
The program return code (low byte) is passed back to BASIC by use of the
<tt/ST/ variable.
<sect1>Interrupts<p>
The runtime for the C16 uses routines marked as <tt/.INTERRUPTOR/ for
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>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>

405
doc/c64.sgml Normal file
View File

@ -0,0 +1,405 @@
<!doctype linuxdoc system>
<article>
<title>Commodore 64 specific information for cc65
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
<date>2003-09-23
<abstract>
An overview over the C64 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 C64 runtime system as it comes with the
cc65 C compiler. It describes the memory layout, C64 specific header files,
available drivers, and any pitfalls specific to that platform.
Please note that C64 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 C64 target
is a machine language program with a one line BASIC stub, which calls the
machine language part via SYS. This means that a program can be loaded as
BASIC program and started with RUN. It is of course possible to change this
behaviour by using a modified startup file and linker config.
<sect>Memory layout<p>
cc65 generated programs with the default setup run with the I/O area and the
kernal ROM enabled (memory under the kernal may be used for graphics or as
extended memory - see the sections about graphics and extended memory
drivers). The BASIC ROM is disabled, which gives a usable memory range of
&dollar;0800 - &dollar;CFFF. This means that kernal entry points may be called
directly, but using the BASIC ROM is not possible without additional code.
Special locations:
<descrip>
<tag/Text screen/
The text screen is located at &dollar;400 (as in the standard setup).
<tag/Stack/
The C runtime stack is located at &dollar;CFFF and growing downwards.
<tag/Heap/
The C heap is located at the end of the program and grows towards the C
runtime stack.
</descrip><p>
<sect>Linker configurations<p>
The ld65 linker comes with a builtin config file for the Commodore&nbsp;64,
which is used via <tt/-t c64/ (and displayed via <tt/--dump-config c64/). The
c64 package comes with additional secondary linker config files, which are
used via <tt/-C &lt;configfile&gt;/.
<sect1>builtin config file<p>
The builtin configuration is tailored to C programs. It supplies the load
address and a small BASIC stub that starts the compiled program using a SYS
command.
<sect1><tt/c64-asm.cfg/<p>
This configuration is made for assembler programmers who don't need a special
setup. The default start address is &dollar;801. It can be changed with the
linker command line option <tt/--start-addr/. All standard segments with the
exception of <tt/zeropage/ are written to the output file and a two byte load
address is prepended.
To use this config file, assemble with <tt/-t c64/ and link with <tt/-C
c64-asm.cfg/. The former will make sure that correct character translation is
in effect, while the latter supplies the actual config. When using <tt/cl65/,
use both command line options.
Sample command line for <tt/cl65/:
<tscreen><verb>
cl65 -o file.prg -t c64 -C c64-asm.cfg source.s
</verb></tscreen>
To generate code that loads to &dollar;C000:
<tscreen><verb>
cl65 -o file.prg --start-addr $C000 -t c64 -C c64-asm.cfg source.s
</verb></tscreen>
It is also possible to add a small BASIC header to the program, that uses SYS
to jump to the program entry point (which is the start of the code segment).
The advantage is that the program can be started using RUN.
To generate a program with a BASIC SYS header, use
<tscreen><verb>
cl65 -o file.prg -u __EXEHDR__ -t c64 -C c64-asm.cfg source.s
</verb></tscreen>
Please note that in this case a changed start address doesn't make sense,
since the program must be loaded to the BASIC start address.
<sect>Platform specific header files<p>
Programs containing C64 specific code may use the <tt/c64.h/ or <tt/cbm.h/
header files. Using the later may be an option when writing code for more than
one CBM platform, since it includes <tt/c64.h/ and declares several functions
common to all CBM platforms.
<sect1>C64 specific functions<p>
The functions listed below are special for the C64. See the <htmlurl
url="funcref.html" name="function reference"> for declaration and usage.
<itemize>
<item>get_ostype
</itemize>
<sect1>CBM specific functions<p>
Some functions are available for all (or at least most) of the Commodore
machines. See the <htmlurl url="funcref.html" name="function reference"> for
declaration and usage.
<itemize>
<item>cbm_close
<item>cbm_closedir
<item>cbm_k_setlfs
<item>cbm_k_setnam
<item>cbm_k_load
<item>cbm_k_save
<item>cbm_k_open
<item>cbm_k_close
<item>cbm_k_readst
<item>cbm_k_chkin
<item>cbm_k_ckout
<item>cbm_k_basin
<item>cbm_k_bsout
<item>cbm_k_clrch
<item>cbm_load
<item>cbm_open
<item>cbm_opendir
<item>cbm_read
<item>cbm_readdir
<item>cbm_save
<item>cbm_write
<item>get_tv
</itemize>
<sect1>Hardware access<p>
The following pseudo variables declared in the <tt/c64.h/ header file do allow
access to hardware located in the address space. Some variables are
structures, accessing the struct fields will access the chip registers.
<descrip>
<tag><tt/VIC/</tag>
The <tt/VIC/ structure allows access to the VIC II (the graphics
controller). See the <tt/_vic2.h/ header file located in the include
directory for the declaration of the structure.
<tag><tt/SID/</tag>
The <tt/SID/ structure allows access to the SID (the sound interface
device). See the <tt/_sid.h/ header file located in the include directory
for the declaration of the structure.
<tag><tt/CIA1, CIA2/</tag>
Access to the two CIA (complex interface adapter) chips is available via
the <tt/CIA1/ and <tt/CIA2/ variables. The structure behind these variables
is explained in <tt/_6526.h/.
<tag><tt/COLOR_RAM/</tag>
A character array that mirrors the color RAM of the C64 at &dollar;D800.
</descrip><p>
<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>
<em>Note:</em> All available graphics drivers for the TGI interface will use
the space below the I/O area and kernal ROM, so you can have hires graphics in
the standard setup without any memory loss or need for a changed
configuration.
<descrip>
<tag><tt/c64-hi.tgi (c64_320_200_2)/</tag>
This driver features a resolution of 320*200 with two colors and an
adjustable palette (that means that the two colors can be chosen out of a
palette of the 16 C64 colors).
</descrip><p>
<sect1>Extended memory drivers<p>
<descrip>
<tag><tt/c64-c256k.emd (c64_c256k)/</tag>
A driver for the C64 256K memory expansion. This driver offers 768 pages of
256 bytes each. Written and contributed by Marco van den Heuvel.
<tag><tt/c64-dqbb.emd (c64_dqbb)/</tag>
A driver for the Double Quick Brown Box cartridge. This driver offers
64 pages of 256 bytes each. Written and contributed by Marco van den Heuvel.
<tag><tt/c64-georam.emd (c64_georam)/</tag>
A driver for the Berkeley Softworks GeoRam cartridge. The driver will
determine the available RAM from the connected cartridge. It supports 64KB
up to 2048KB of RAM.
<tag><tt/c64-isepic.emd (c64_isepic)/</tag>
A driver for the ISEPIC cartridge. This driver offers just 8 pages of 256
bytes each. Written and contributed by Marco van den Heuvel.
<tag><tt/c64-ram.emd (c64_ram)/</tag>
A driver for the hidden RAM below the I/O area and kernal ROM. Supports 48
256 byte pages. Please note that this driver is incompatible with any of the
graphics drivers!
<tag><tt/c64-ramcart.emd (c64_ramcart)/</tag>
A driver for the RamCart 64/128 written and contributed by Maciej Witkowiak.
Will test the hardware for the available RAM.
<tag><tt/c64-reu.emd (c64_reu)/</tag>
A driver for the CBM REUs. The driver will determine from the connected REU
if it supports 128KB of RAM or more. In the latter case, 256KB are assumed,
but since there are no range checks, the application can use more memory if
it has better knowledge about the hardware than the driver.
<tag><tt/c64-vdc.emd (c64_vdc)/</tag>
A driver for the VDC memory of the C128. Written and contributed by Maciej
Witkowiak. Can be used if the program is running in C64 mode of the C128.
Autodetects the amount of memory available (16 or 64K) and offers 64 or 256
pages of 256 bytes each.
<tag><tt/dtv-himem.emd (dtv_himem)/</tag>
A driver for the C64 D2TV (the second or PAL version). This driver offers
indeed 7680 pages of 256 bytes each.
</descrip><p>
<sect1>Joystick drivers<p>
<descrip>
<tag><tt/c64-hitjoy.joy (c64_hitjoy)/</tag>
Driver for the Digital Excess & Hitmen adapter contributed by Groepaz. See
<htmlurl url="http://www.digitalexcess.de/downloads/productions.php"
name="http://www.digitalexcess.de/downloads/productions.php"> on
instructions how to build one. Up to four joysticks are supported.
<tag><tt/c64-ptvjoy.joy (c64_ptvjoy)/</tag>
Driver for the Protovision 4-player adapter contributed by Groepaz. See
<htmlurl url="http://www.protovision-online.de/hardw/hardwstart.htm"
name="http://www.protovision-online.de/hardw/hardwstart.htm"> for prices and
building instructions. Up to four joysticks are supported.
<tag><tt/c64-stdjoy.joy (c64_stdjoy)/</tag>
Supports up to two standard joysticks connected to the joysticks port of
the C64.
<tag><tt/c64-numpad.joy (c64_numpad)/</tag>
Supports one joystick emulated by the numberpad of the C128 in C64 mode,
the firebutton is labeled &dquot;5&dquot; and ENTER.
</descrip><p>
<sect1>Mouse drivers<p>
<descrip>
<tag><tt/c64-1351.mou (c64_1351)/</tag>
Supports a standard mouse connected to port #0 of the C64.
<tag><tt/c64-joy.mou (c64_joymouse)/</tag>
Supports a mouse emulated by a standard joystick e.g. 1350 mouse in port
#1 of the C64.
<tag><tt/c64-pot.mou (c64_potmouse)/</tag>
Supports a potentiometer device e.g. Koala Pad connected to port #1 of
the C64.
</descrip><p>
<sect1>RS232 device drivers<p>
<descrip>
<tag><tt/c64-swlink.ser (c64_swlink)/</tag>
Driver for the SwiftLink cartridge. Supports up to 38400 baud, hardware flow
control (RTS/CTS) and interrupt driven receives. Note that because of the
peculiarities of the 6551 chip together with the use of the NMI, transmits
are not interrupt driven, and the transceiver blocks if the receiver asserts
flow control because of a full buffer.
</descrip><p>
<sect>Limitations<p>
<sect>Other hints<p>
<sect1>Escape code<p>
For an Esc press CTRL and [ key.
<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 chosen:
<tscreen><verb>
RUN: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>Program return code<p>
The program return code (low byte) is passed back to BASIC by use of the
<tt/ST/ variable.
<sect1>Interrupts<p>
The runtime for the C64 uses routines marked as <tt/.INTERRUPTOR/ for
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>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>

4786
doc/ca65.sgml Normal file
View File

File diff suppressed because it is too large Load Diff

289
doc/ca65html.sgml Normal file
View File

@ -0,0 +1,289 @@
<!doctype linuxdoc system>
<article>
<title>ca65html Users Guide
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
<date>2007-10-2
<abstract>
ca65html is an assembly-source-to-HTML converter. It is very useful if you
want to publish your assembler sources in the web.
</abstract>
<!-- Table of contents -->
<toc>
<!-- Begin the document -->
<sect>Overview<p>
ca65html converts assembly source files written for use with the <tt/<url
url="ca65.html" name="ca65">/ crossassembler into HTML. It is a standalone
tool written in PERL; and as such, it does not understand the structure of
assembler sources in the same depth as ca65 does, so it may fail in very rare
cases. In all other cases, it generates very nice output.
<sect>Usage<p>
<sect1>Command line option overview<p>
The HTML converter accepts the following options:
<tscreen><verb>
---------------------------------------------------------------------------
Usage: ca65html [options] file ...
Options:
--bgcolor c Use background color c instead of #FFFFFF
--colorize Add color highlights to the output
--commentcolor c Use color c for comments instead of #B22222
--crefs Generate references to the C source file(s)
--ctrlcolor c Use color c for directives instead of #228B22
--cvttabs Convert tabs to spaces in the output
--help This text
--htmldir dir Specify directory for HTML files
--indexcols n Use n columns on index page (default 6)
--indexname file Use file for the index file instead of index.html
--indexpage Create an index page
--indextitle title Use title as the index title instead of Index
--keywordcolor c Use color c for keywords instead of #A020F0
--linelabels Generate a linexxx HTML label for each line
--linenumbers Add line numbers to the output
--linkstyle style Use the given link style
--replaceext Replace source extension instead of appending .html
--textcolor c Use text color c instead of #000000
--verbose Be more verbose
---------------------------------------------------------------------------
</verb></tscreen>
<sect1>Command line options in detail<p>
Here is a description of all the command line options:
<descrip>
<tag><tt>--bgcolor c</tt></tag>
Set the background color. The argument c must be a valid HTML color, usually
given as RGB triplet in the form <tt/#rrggbb/, where r, g, and b are the
respective red, green, and blue parts as two-digit hex values. The default is
<tt/#FFFFFF/ (white). That color is used in the <tt/&lt;body&gt;/ of the
generated HTML output.
<tag><tt>--colorize</tt></tag>
Colorize the output. The converter outputs processor instructions, assembler
control commands, and comments in different colors.
<tag><tt>--commentcolor c</tt></tag>
Set the color used for comments. The argument c must be a valid HTML color,
usually given as RGB triplet in the form <tt/#rrggbb/, where r, g, and b are
the respective red, green, and blue parts as two-digit hex values. The
default is <tt/#B22222/ (red).
Note that this option has no effect if <tt/--colorize/ is not also given.
<tag><tt>--crefs</tt></tag>
Generate references to the C file, when a <tt/.dbg/ command is found with a
file name. The converter assumes that the C source was also converted into
HTML (for example by use of <tt/c2html/), has the name <tt/file.c.html/, and
lives in the same directory as the assembler file. If the <tt/.dbg/
directive specifies a line, a link to the correct line in the C file is
generated, using a label in the form <tt/linexxx/, as it is created by
<tt/c2html/ by use of the <tt/-n/ option.
<tag><tt>--commentcolor c</tt></tag>
Set the color used for assembler control commands. The argument c must be a
valid HTML color, usually given as RGB triplet in the form <tt/#rrggbb/,
where r, g, and b are the respective red, green, and blue parts as two-digit
hex values. The default is <tt/#228B22/ (green).
Note that this option has no effect if <tt/--colorize/ is not also given.
<tag><tt>--cvttabs</tt></tag>
Convert tabs in the input into spaces in the output, assuming the standard
tab width of 8. This is useful if the <tt/--linenumbers/ option is used to
retain the indentation.
<tag><tt>--help</tt></tag>
Print the command line option summary shown above.
<tag><tt>--htmldir dir</tt></tag>
Specify an output directory for the generated HTML files.
<tag><tt>--indexcols n</tt></tag>
Use n columns on the index page. This option has no effect if used without
<tt/--indexpage/.
<tag><tt>--indexname name</tt></tag>
Use another index file name instead of <tt/index.html/. This option has no
effect if used without <tt/--indexpage/.
<tag><tt>--indexpage</tt></tag>
Causes the converter to generate an index page listing file names, and all
exports found in the converted files.
<tag><tt>--indextitle title</tt></tag>
Use "title" as the title of the index page. This option has no effect if
used without <tt/--indexpage/.
<tag><tt>--keywordcolor c</tt></tag>
Set the color used for processor instructions. The argument c must be a
valid HTML color, usually given as RGB triplet in the form <tt/#rrggbb/,
where r, g, and b are the respective red, green, and blue parts as two-digit
hex values. The default is <tt/#A020F0/ (purple).
Note that this option has no effect if <tt/--colorize/ is not also given.
<tag><tt>--linelabels</tt></tag>
Generate a label for each line using the name <tt/linexxx/ where xxx is the
number of the line.
Note: The converter will not make use of this label. Use this option if you
have other HTML pages referencing the converted assembler file.
<tag><tt>--linenumbers</tt></tag>
Generate line numbers on the left side of the output.
<tag><tt>--linkstyle n</tt></tag>
Influences the style used when generating links for imports. If n is zero
(the default), the converter creates a link to the actual symbol if it is
defined somewhere in the input files. If not, it creates a link to the
<tt/.import/ statement. If n is one, the converter will always generate a
HTML link to the <tt/.import/ statement.
<tag><tt>--replaceext</tt></tag>
Replace the file extension of the input file instead of appending <tt/.html/
when generating the output file name.
<tag><tt>--textcolor c</tt></tag>
Set the color for normal text. The argument c must be a valid HTML color,
usually given as RGB triplet in the form <tt/#rrggbb/, where r, g, and b are
the respective red, green, and blue parts as two-digit hex values. The
default is <tt/#000000/ (black). This color is used in the <tt/&lt;body&gt;/
of the generated HTML output.
<tag><tt>--verbose</tt></tag>
Increase the converter verbosity. Without this option, ca65html is quiet
when working. If you have a slow machine and lots of files to convert, you
might like a little bit more progress information.
</descrip>
<p>
<sect>Peculiarities<p>
<sect1>Cross links<p>
Since ca65html is able to generate links between modules, the best way to use
it is to supply all modules to it in one run, instead of running each file
separately through it.
<sect1>Include files<p>
For now, ca65html will not read files included with <tt/.include/. Specifying
the include files as normal input files on the command line works in many
cases.
<sect1>Conversion errors<p>
Since ca65html does not really parse the input, but does most of its work
applying text patterns, it doesn't know anything about scoping and advanced
features of the assembler. This means that it might miss a label. And, it
might choose the wrong color for an item, in rare cases. Because it's just a
tool for displaying sources in a nice form, I think that's OK. Anyway, if you
find a conversion problem, you can send me a short piece of example input code.
If possible, I will fix it.
<sect1>Colorization<p>
While having colors in the output looks really nice, it has one drawback:
<enum>
<item>Because lots of <tt/&lt;span&gt;/ tags are created in the output,
the size of the output file literally will explode. It seems to be the price
that you have to pay for color.
</enum>
<sect>Bugs/Feedback<p>
If you have problems using the converter, if you find any bugs, or if you're
doing something interesting with the assembler, 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>Copyright<p>
ca65html is (c) Copyright 2000-2007 Ullrich von Bassewitz. For its use, the
following conditions apply:
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>

301
doc/cbm510.sgml Normal file
View File

@ -0,0 +1,301 @@
<!doctype linuxdoc system>
<article>
<title>Commodore 510 (aka P500) specific information for cc65
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
Stefan A. Haubenthal, <htmlurl url="mailto:polluks@sdf.lonestar.org" name="polluks@sdf.lonestar.org">
<date>2006-05-22
<abstract>
An overview over the Commodore 510 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 CBM 510 runtime system as it comes with
the cc65 C compiler. It describes the memory layout, CBM 510 specific header
files, available drivers, and any pitfalls specific to that platform.
Please note that CBM 510 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.
In addition to the Commodore 510 (named P128 in the U.S.), no other
machines are supported by this cc65 target.
<sect>Binary format<p>
The standard binary output format generated by the linker for the Commodore
510 target is a machine language program with a one line BASIC stub, which
transfers control to the machine language running in bank 0. This means that a
program can be loaded as BASIC program and started with RUN. It is of course
possible to change this behaviour by using a modified startup file and linker
config.
<sect>Memory layout<p>
cc65 generated programs for the Commodore 510 run in bank 0, the memory bank
reserved for BASIC programs. Since there are no ROMs in this memory bank,
kernal subroutines are either emulated or called by bank switching, which has
the disadvantage of being slow compared to a direct call.
The default memory configuration for the CBM 510 allocates all memory between
&dollar;0002 and &dollar;FFF0 in bank 0 for the compiled program. Some space
in low memory is lost, because a separate hardware stack is set up in page 1,
and the kernal replacement functions need some more memory locations. A few
more pages are lost in high memory, because the runtime sets up a copy of the
character ROM, a text screen and a CBM compatible jump table at &dollar;FF81.
The main startup code is located at &dollar;0400, so about 54K of the complete
bank are actually usable for applications.
Special locations:
<descrip>
<tag/Stack/
The C runtime stack is located at &dollar;FF81 and growing downwards.
<tag/Heap/
The C heap is located at the end of the program and grows towards the C
runtime stack.
</descrip><p>
<sect>Platform specific header files<p>
Programs containing CBM 510 specific code may use the <tt/cbm510.h/ or
<tt/cbm.h/ header files. Using the later may be an option when writing code
for more than one CBM platform, since it includes <tt/cbm510.h/ and declares
several functions common to all CBM platforms.
<sect1>CBM 510 specific functions<p>
The functions listed below are special for the CBM 510. See the <htmlurl
url="funcref.html" name="function reference"> for declaration and usage.
<itemize>
<item>peekbsys
<item>peekwsys
<item>pokebsys
<item>pokewsys
</itemize>
<sect1>CBM specific functions<p>
Some functions are available for all (or at least most) of the Commodore
machines. See the <htmlurl url="funcref.html" name="function reference"> for
declaration and usage.
<itemize>
<item>cbm_close
<item>cbm_closedir
<item>cbm_k_setlfs
<item>cbm_k_setnam
<item>cbm_k_load
<item>cbm_k_save
<item>cbm_k_open
<item>cbm_k_close
<item>cbm_k_readst
<item>cbm_k_chkin
<item>cbm_k_ckout
<item>cbm_k_basin
<item>cbm_k_bsout
<item>cbm_k_clrch
<item>cbm_load
<item>cbm_open
<item>cbm_opendir
<item>cbm_read
<item>cbm_readdir
<item>cbm_save
<item>cbm_write
<item>get_tv
</itemize>
<sect1>Hardware access<p>
The following pseudo variables declared in the <tt/cbm510.h/ header file do
allow access to hardware located in the address space. Some variables are
structures, accessing the struct fields will access the chip registers.
<bf>Note:</bf> All I/O chips are located in the system bank (bank 15) and can
therefore not be accessed like on other platforms. Please use one of the
<tt/peekbsys/, <tt/peekwsys/, <tt/pokebsys/ and <tt/pokewsys/ functions to
access the I/O chips. Direct reads and writes to the structures named below
will <em>not</em> work!
<descrip>
<tag><tt/VIC/</tag>
The <tt/VIC/ structure allows access to the VIC II (the graphics
controller). See the <tt/_vic2.h/ header file located in the include
directory for the declaration of the structure.
<tag><tt/SID/</tag>
The <tt/SID/ structure allows access to the SID (the sound interface
device). See the <tt/_sid.h/ header file located in the include directory
for the declaration of the structure.
<tag><tt/ACIA/</tag>
Access to the ACIA (the RS232 chip) is available via the <tt/ACIA/ variable.
See the <tt/_6551.h/ header file located in the include directory for the
declaration of the structure.
<tag><tt/CIA/</tag>
Access to the CIA chip is available via the <tt/CIA/ variable. See the
<tt/_6526.h/ header file located in the include directory for the
declaration of the structure.
<tag><tt/TPI1, TPI2/</tag>
The two 6525 triport chips may be accessed by using this variable. See the
<tt/_6525.h/ header file located in the include directory for the
declaration of the structure.
</descrip><p>
<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>
No graphics drivers are currently available for the Commodore 510.
<sect1>Extended memory drivers<p>
<descrip>
<tag><tt/cbm510-ram.emd (cbm510_ram)/</tag>
A driver for the RAM in bank 1. Supports up to 255 pages with 256 bytes
each.
</descrip><p>
<sect1>Joystick drivers<p>
<descrip>
<tag><tt/cbm510-std.joy (cbm510_stdjoy)/</tag>
Supports up to two standard joysticks connected to the joysticks port of
the Commodore 510.
</descrip><p>
<sect1>Mouse drivers<p>
No mouse drivers are currently available for the Commodore 510.
<sect1>RS232 device drivers<p>
<descrip>
<tag><tt/cbm510-std.ser (cbm510_stdser)/</tag>
Driver for the 6551 ACIA chip built into the Commodore 510. 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.
</descrip><p>
<sect>Limitations<label id="limitations"><p>
<sect1>Kernal and hardware access<p>
Since the program runs in bank 0, and the kernal and all I/O chips are located
in bank 15, calling ROM routines or accessing hardware needs special code. The
cc65 runtime implements wrappers for all functions in the kernal jump table.
While this simplifies things, it should be noted that the wrappers do have
quite an impact on performance: A cross bank call has an extra 300&micro;s
penalty added by the wrapper.
<sect1>Interrupts<p>
Compiled programs contain an interrupt handler that runs in the program bank.
This has several advantages, one of them being performance (see cross bank
call overhead mentioned above). However, this introduces one problem:
Interrupts are lost while the CPU executes code in the kernal bank. As a
result, the clock may go wrong and (worse) serial interrupts may get lost.
Since the cc65 runtime does only call the kernal for disk I/O, this means that
a program should not do file I/O while it depends on interrupts.
<sect>Other hints<p>
<sect1>Passing arguments to the program<p>
Command line argument passing is currently not supported for the Commodore
510.
<sect1>Program return code<p>
The program return code (signed char) is passed back to BASIC by use of the
<tt/ST/ variable.
<sect1>Interrupt handlers<p>
The runtime for the Commodore 510 uses routines marked as <tt/.INTERRUPTOR/
for 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>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>

300
doc/cbm610.sgml Normal file
View File

@ -0,0 +1,300 @@
<!doctype linuxdoc system>
<article>
<title>Commodore 610 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 Commodore 610 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 CBM 610 runtime system as it comes with
the cc65 C compiler. It describes the memory layout, CBM 610 specific header
files, available drivers, and any pitfalls specific to that platform.
Please note that CBM 610 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.
In addition to the Commodore 610 (named B40 in the U.S.), several other
machines are supported by this cc65 target, since they have identical
hardware: The Commodore 620 and 630 (more memory, additional coprocessor
card), and the Commodore 710, 720 and 730 (same hardware in another case with
a builtin monitor).
<sect>Binary format<p>
The standard binary output format generated by the linker for the Commodore
610 target is a machine language program with a one line BASIC stub, which
transfers control to the machine language running in bank 1. This means that a
program can be loaded as BASIC program and started with RUN. It is of course
possible to change this behaviour by using a modified startup file and linker
config.
<sect>Memory layout<p>
cc65 generated programs for the Commodore 610 run in bank 1, the memory bank
reserved for BASIC programs. Since there are no ROMs in this memory bank,
kernal subroutines are either emulated or called by bank switching, which has
the disadvantage of being slow compared to a direct call.
The default memory configuration for the CBM 610 allocates all memory between
&dollar;0002 and &dollar;FFF0 in bank 1 for the compiled program. Some space
in low memory is lost, because a separate hardware stack is set up in page 1,
and the kernal replacement functions need some more memory locations. A few
more bytes are lost in high memory, because the runtime sets up a CBM
compatible jump table at &dollar;FF81. The main startup code is located at
&dollar;0400, so about 63K of the complete bank are actually usable for
applications.
Special locations:
<descrip>
<tag/Stack/
The C runtime stack is located at &dollar;FF81 and growing downwards.
<tag/Heap/
The C heap is located at the end of the program and grows towards the C
runtime stack.
</descrip><p>
<sect>Platform specific header files<p>
Programs containing CBM 610 specific code may use the <tt/cbm610.h/ or
<tt/cbm.h/ header files. Using the later may be an option when writing code
for more than one CBM platform, since it includes <tt/cbm610.h/ and declares
several functions common to all CBM platforms.
<sect1>CBM 610 specific functions<p>
The functions listed below are special for the CBM 610. See the <htmlurl
url="funcref.html" name="function reference"> for declaration and usage.
<itemize>
<item>peekbsys
<item>peekwsys
<item>pokebsys
<item>pokewsys
</itemize>
<sect1>CBM specific functions<p>
Some functions are available for all (or at least most) of the Commodore
machines. See the <htmlurl url="funcref.html" name="function reference"> for
declaration and usage.
<itemize>
<item>cbm_close
<item>cbm_closedir
<item>cbm_k_setlfs
<item>cbm_k_setnam
<item>cbm_k_load
<item>cbm_k_save
<item>cbm_k_open
<item>cbm_k_close
<item>cbm_k_readst
<item>cbm_k_chkin
<item>cbm_k_ckout
<item>cbm_k_basin
<item>cbm_k_bsout
<item>cbm_k_clrch
<item>cbm_load
<item>cbm_open
<item>cbm_opendir
<item>cbm_read
<item>cbm_readdir
<item>cbm_save
<item>cbm_write
<item>get_tv
</itemize>
<sect1>Hardware access<p>
The following pseudo variables declared in the <tt/cbm610.h/ header file do
allow access to hardware located in the address space. Some variables are
structures, accessing the struct fields will access the chip registers.
<bf>Note:</bf> All I/O chips are located in the system bank (bank 15) and can
therefore not be accessed like on other platforms. Please use one of the
<tt/peekbsys/, <tt/peekwsys/, <tt/pokebsys/ and <tt/pokewsys/ functions to
access the I/O chips. Direct reads and writes to the structures named below
will <em>not</em> work!
<descrip>
<tag><tt/CRTC/</tag>
The <tt/CRTC/ structure allows access to the CRTC (the video controller).
See the <tt/_6545.h/ header file located in the include directory for the
declaration of the structure.
<tag><tt/SID/</tag> The <tt/SID/ structure allows access to the SID (the
sound interface device). See the <tt/_sid.h/ header file located in the
include directory for the declaration of the structure.
<tag><tt/ACIA/</tag>
Access to the ACIA (the RS232 chip) is available via the <tt/ACIA/ variable.
See the <tt/_6551.h/ header file located in the include directory for the
declaration of the structure.
<tag><tt/CIA/</tag>
Access to the CIA chip is available via the <tt/CIA/ variable. See the
<tt/_6526.h/ header file located in the include directory for the
declaration of the structure.
<tag><tt/TPI1, TPI2/</tag>
The two 6525 triport chips may be accessed by using this variable. See the
<tt/_6525.h/ header file located in the include directory for the
declaration of the structure.
</descrip><p>
<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>
No graphics drivers are currently available for the Commodore 610 (and since
the machine has no graphics capabilities, chances for a graphics driver aren't
really good:-).
<sect1>Extended memory drivers<p>
<descrip>
<tag><tt/cbm610-ram.emd (cbm610_ram)/</tag>
A driver for the RAM in bank 2. Supports up to 255 pages with 256 bytes
each.
</descrip><p>
<sect1>Joystick drivers<p>
The Commodore 610 is a business machine and doesn't have joystick ports. There
are no drivers for the non existing ports available.
<sect1>Mouse drivers<p>
Currently no drivers available (in fact, the API for loadable mouse drivers
does not exist).
<sect1>RS232 device drivers<p>
<descrip>
<tag><tt/cbm610-std.ser (cbm610_stdser)/</tag>
Driver for the 6551 ACIA chip built into the Commodore 610. 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.
</descrip><p>
<sect>Limitations<label id="limitations"><p>
<sect1>Kernal and hardware access<p>
Since the program runs in bank 1, and the kernal and all I/O chips are located
in bank 15, calling ROM routines or accessing hardware needs special code. The
cc65 runtime implements wrappers for all functions in the kernal jump table.
While this simplifies things, it should be noted that the wrappers do have
quite an impact on performance: A cross bank call has an extra 300&micro;s
penalty added by the wrapper.
<sect1>Interrupts<p>
Compiled programs contain an interrupt handler that runs in the program bank.
This has several advantages, one of them being performance (see cross bank
call overhead mentioned above). However, this introduces one problem:
Interrupts are lost while the CPU executes code in the kernal bank. As a
result, the clock may go wrong and (worse) serial interrupts may get lost.
Since the cc65 runtime does only call the kernal for disk I/O, this means that
a program should not do file I/O while it depends on interrupts.
<sect>Other hints<p>
<sect1>Passing arguments to the program<p>
Command line argument passing is currently not supported for the Commodore
610.
<sect1>Program return code<p>
The program return code (low byte) is passed back to BASIC by use of the
<tt/ST/ variable.
<sect1>Interrupt handlers<p>
The runtime for the Commodore 610 uses routines marked as <tt/.INTERRUPTOR/
for 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>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>

1386
doc/cc65.sgml Normal file
View File

File diff suppressed because it is too large Load Diff

316
doc/cl65.sgml Normal file
View File

@ -0,0 +1,316 @@
<!doctype linuxdoc system>
<article>
<title>cl65 Users Guide
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
<date>01.08.2000, 27.11.2000, 02.10.2001
<abstract>
cl65 is the compile &amp; link utility for cc65, the 6502 C compiler. It was
designed as a smart frontend for the C compiler (cc65), the assembler (ca65),
the object file converter (co65), and the linker (ld65).
</abstract>
<!-- Table of contents -->
<toc>
<!-- Begin the document -->
<sect>Overview<p>
cl65 is a frontend for cc65, ca65, co65 and ld65. While you may not use the
full power of the tools when calling them through cl65, most features are
available, and the use of cl65 is much simpler.
<sect>Basic Usage<p>
The cl65 compile and link utility may be used to convert, compile, assemble
and link files. While the separate tools do just one step, cl65 knows how to
build object files from C files (by calling the compiler, then the assembler)
and other things.
<tscreen><verb>
---------------------------------------------------------------------------
Usage: cl65 [options] file [...]
Short options:
-c Compile and assemble but don't link
-d Debug mode
-g Add debug info
-h Help (this text)
-l name Create an assembler listing file
-m name Create a map file
-mm model Set the memory model
-o name Name the output file
-r Enable register variables
-t sys Set the target system
-u sym Force an import of symbol `sym'
-v Verbose mode
-vm Verbose map file
-C name Use linker config file
-Cl Make local variables static
-D sym[=defn] Define a preprocessor symbol
-I dir Set a compiler include directory path
-L path Specify a library search path
-Ln name Create a VICE label file
-O Optimize code
-Oi Optimize code, inline functions
-Or Optimize code, honour the register keyword
-Os Optimize code, inline known C funtions
-S Compile but don't assemble and link
-T Include source as comment
-V Print the version number
-W name[,...] Supress compiler warnings
-Wa options Pass options to the assembler
-Wl options Pass options to the linker
Long options:
--add-source Include source as comment
--asm-args options Pass options to the assembler
--asm-define sym[=v] Define an assembler symbol
--asm-include-dir dir Set an assembler include directory
--bin-include-dir dir Set an assembler binary include directory
--bss-label name Define and export a BSS segment label
--bss-name seg Set the name of the BSS segment
--cc-args options Pass options to the compiler
--cfg-path path Specify a config file search path
--check-stack Generate stack overflow checks
--code-label name Define and export a CODE segment label
--code-name seg Set the name of the CODE segment
--codesize x Accept larger code by factor x
--config name Use linker config file
--cpu type Set cpu type
--create-dep name Create a make dependency file
--create-full-dep name Create a full make dependency file
--data-label name Define and export a DATA segment label
--data-name seg Set the name of the DATA segment
--debug Debug mode
--debug-info Add debug info
--feature name Set an emulation feature
--force-import sym Force an import of symbol `sym'
--forget-inc-paths Forget include search paths (compiler)
--help Help (this text)
--include-dir dir Set a compiler include directory path
--ld-args options Pass options to the linker
--lib file Link this library
--lib-path path Specify a library search path
--list-targets List all available targets
--listing name Create an assembler listing file
--list-bytes n Number of bytes per assembler listing line
--mapfile name Create a map file
--memory-model model Set the memory model
--module Link as a module
--module-id id Specify a module id for the linker
--o65-model model Override the o65 model
--obj file Link this object file
--obj-path path Specify an object file search path
--register-space b Set space available for register variables
--register-vars Enable register variables
--rodata-name seg Set the name of the RODATA segment
--signed-chars Default characters are signed
--standard std Language standard (c89, c99, cc65)
--start-addr addr Set the default start address
--static-locals Make local variables static
--target sys Set the target system
--version Print the version number
--verbose Verbose mode
--zeropage-label name Define and export a ZEROPAGE segment label
--zeropage-name seg Set the name of the ZEROPAGE segment
---------------------------------------------------------------------------
</verb></tscreen>
Most of the options have the same meaning than the corresponding compiler,
assembler or linker option. See the documentation for these tools for an
explanation. If an option is available for more than one of the tools, it
is set for all tools, where it is available. One example for this is <tt/-v/:
The compiler, the assembler and the linker are all called with the <tt/-v/
switch.
There are a few remaining options that control the behaviour of cl65:
<descrip>
<tag><tt>-S</tt></tag>
This option forces cl65 to stop after the assembly step. This means that
C files are translated into assembler files, but nothing more is done.
Assembler files, object files and libraries given on the command line
are ignored.
<tag><tt>-c</tt></tag>
This options forces cl65 to stop after the assembly step. This means
that C and assembler files given on the command line are translated into
object files, but there is no link step, and object files and libraries
given on the command line are ignored.
<tag><tt>-o name</tt></tag>
The -o option is used for the target name in the final step. This causes
problems, if the linker will not be called, and there are several input
files on the command line. In this case, the name given with -o will be
used for all of them, which makes the option pretty useless. You
shouldn't use -o when more than one output file is created.
<tag><tt>-t sys, --target sys</tt></tag>
The default for this option is different from the compiler and linker in the
case that the option is missing: While the other tools (compiler, assembler
and linker) will use the "none" system settings by default, cl65 will use
the C64 as a target system by default. This was chosen since most people
seem to use cc65 to develop for the C64.
<tag><tt>-Wa options, --asm-args options</tt></tag>
Pass options directly to the assembler. This may be used to pass options
that aren't directly supported by cl65. Several options may be separated by
commas, the commas are replaced by spaces when passing them to the
assembler. Beware: Passing arguments directly to the assembler may interfere
with some of the defaults, because cl65 doesn't parse the options passed. So
if cl65 supports an option by itself, do not pass this option to the
assembler by means of the <tt/-Wa/ switch.
<tag><tt>-Wc options, --cc-args options</tt></tag>
Pass options directly to the compiler. This may be used to pass options
that aren't directly supported by cl65. Several options may be separated by
commas, the commas are replaced by spaces when passing them to the
compiler. Beware: Passing arguments directly to the compiler may interfere
with some of the defaults, because cl65 doesn't parse the options passed. So
if cl65 supports an option by itself, do not pass this option to the
compiler by means of the <tt/-Wc/ switch.
<tag><tt>-Wl options, --ld-args options</tt></tag>
Pass options directly to the linker. This may be used to pass options that
aren't directly supported by cl65. Several options may be separated by
commas, the commas are replaced by spaces when passing them to the linker.
Beware: Passing arguments directly to the linker may interfere with some of
the defaults, because cl65 doesn't parse the options passed. So if cl65
supports an option by itself, do not pass this option to the linker by means
of the <tt/-Wl/ switch.
</descrip>
<sect>More usage<p>
Since cl65 was created to simplify the use of the cc65 development
package, it tries to be smart about several things.
<itemize>
<item> If you don't give a target system on the command line, cl65
defaults to the C64.
<item> When linking, cl65 will supply the names of the startup file and
library for the target system to the linker, so you don't have to do
that.
<item> If the final step is the linker, and the name of the output file was
not explicitly given, cl65 will use the name of the first input file
without the extension, provided that the name of this file has an
extension. So you don't need to name the executable name in most
cases, just give the name of your "main" file as first input file.
</itemize>
The command line is parsed from left to right, and the actual processing tool
(compiler, assembler, ...) is invoked whenever a file name is encountered.
This means that only the options to the left of a file name are in effect when
this file is processed. It does also mean that you're able to specify
different options for different files on the command line. As an example.
<tscreen><verb>
cl65 -Oirs main.c -O -g module.c
</verb></tscreen>
translates main.c with full optimization and module.c with less optimization
and debug info enabled.
The type of an input file is derived from its extension:
<itemize>
<item>C files: <tt/.c/
<item>Assembler files: <tt/.s/, <tt/.asm/, <tt/.a65/
<item>Object files: <tt/.o/ <tt/.obj/
<item>Libraries: <tt/.a/, <tt/.lib/
<item>GEOS resource files: <tt/.grc/
<item>o65 files: <tt/.o65/, <tt/.emd/, <tt/.joy/, <tt/.tgi/
</itemize>
Please note that the program cannot handle input files with unknown file
extensions.
<sect>Examples<p>
The morse trainer software, which consists of one C file (morse.c) and one
assembler file (irq.s) will need the following separate steps to compile
into an executable named morse:
<tscreen><verb>
cc65 -g -Oi -t c64 morse.c
ca65 -g morse.s
ca65 -g irq.s
ld65 -o morse -t c64 c64.o morse.o irq.o c64.lib
</verb></tscreen>
When using cl65, this is simplified to
<tscreen><verb>
cl65 -g -Oi morse.c irq.s
</verb></tscreen>
As a general rule, you may use cl65 instead of cc65 at most times,
especially in makefiles to build object files directly from C files. Use
<tscreen><verb>
.c.o:
cl65 -g -Oi $<
</verb></tscreen>
to do this.
<sect>Bugs/Feedback<p>
If you have problems using the utility, 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>Copyright<p>
cl65 (and all cc65 binutils) are (C) Copyright 1998-2004 Ullrich von
Bassewitz. For usage of the binaries and/or sources the following
conditions do apply:
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>

353
doc/co65.sgml Normal file
View File

@ -0,0 +1,353 @@
<!doctype linuxdoc system>
<article>
<title>co65 Users Guide
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
<date>12.02.2003
<abstract>
co65 is an object file conversion utility. It converts o65 object files into
the native object file format used by the cc65 tool chain. Since o65 is the
file format used by cc65 for loadable drivers, the co65 utility allows (among
other things) to link drivers statically to the generated executables instead
of loading them from disk.
</abstract>
<!-- Table of contents -->
<toc>
<!-- Begin the document -->
<sect>Overview<p>
co65 is an object file conversion utility. It converts o65 object files into
assembler files, which may be translated by ca65 to generate object files in
the native object file format used by the cc65 tool chain.
Since loadable drivers used by the library that comes with cc65 use the o65
relocatable object code format, using the co65 utility allows to link these
drivers statically. This enables the use of these drivers without loading
additional files from a disk or other secondary storage.
Another use would be to link object files generated by other development tools
to projects using the cc65 tool chain, but this has not been tested until now,
since such tools are currently rare.
<sect>Usage<p>
The co65 utility converts one o65 file per run into one assembler files in
ca65 format. The utility tries to autodetect the type of the o65 input file
using the operating system identifier contained in the o65 option list.
<sect1>Command line option overview<p>
The converter may be called as follows:
<tscreen><verb>
---------------------------------------------------------------------------
Usage: co65 [options] file
Short options:
-V Print the version number
-g Add debug info to object file
-h Help (this text)
-m model Override the o65 model
-n Don't generate an output file
-o name Name the output file
-v Increase verbosity
Long options:
--bss-label name Define and export a BSS segment label
--bss-name seg Set the name of the BSS segment
--code-label name Define and export a CODE segment label
--code-name seg Set the name of the CODE segment
--data-label name Define and export a DATA segment label
--data-name seg Set the name of the DATA segment
--debug-info Add debug info to object file
--help Help (this text)
--no-output Don't generate an output file
--o65-model model Override the o65 model
--verbose Increase verbosity
--version Print the version number
--zeropage-label name Define and export a ZEROPAGE segment label
--zeropage-name seg Set the name of the ZEROPAGE segment
---------------------------------------------------------------------------
</verb></tscreen>
<sect1>Command line options in detail<p>
Here is a description of all the command line options:
<descrip>
<tag><tt>--bss-label name</tt></tag>
Set the label used to mark the start of the bss segment. When this option is
given, the label is also exported and may be accessed from other code. When
accessing such a label from C code, be sure to include the leading
underscore. If you don't need to access the bss segment, there's no need to
use this option.
<tag><tt>--bss-name seg</tt></tag>
Set the name of the bss segment. The default name is "BSS" which is
compatible with the standard ld65 linker configurations.
<tag><tt>--code-label name</tt></tag>
Set the label used to mark the start of the code segment. When this option
is given, the label is also exported and may be accessed from other code.
When accessing such a label from C code, be sure to include the leading
underscore. If you don't need to access the code segment, there's no need to
use this option.
<tag><tt>--code-name seg</tt></tag>
Set the name of the code segment. The default name is "CODE" which is
compatible with the standard ld65 linker configurations.
<tag><tt>--data-label name</tt></tag>
Set the label used to mark the start of the data segment. When this option
is given, the label is also exported and may be accessed from other code.
When accessing such a label from C code, be sure to include the leading
underscore. If you don't need to access the data segment, there's no need to
use this option.
<tag><tt>--data-name seg</tt></tag>
Set the name of the data segment. The default name is "DATA" which is
compatible with the standard ld65 linker configurations.
<tag><tt>-d, --debug</tt></tag>
Enables debug mode, something that should not be needed for mere mortals.
Currently the converter does only accept cc65 loadable modules generated by
ld65 when not in debug mode. Please note that correct conversion has never
been tested for o65 files from other sources, so be careful when using
<tt/-d/.
<tag><tt>-g, --debug-info</tt></tag>
This will cause the converter to insert a <tt/.DEBUGINFO/ command into the
generated assembler code. This will cause the assembler to include all
symbols in a special section in the object file.
<tag><tt>-h, --help</tt></tag>
Print the short option summary shown above.
<tag><tt>-m model, --o65-model model</tt></tag>
Set an o65 model. This option changes the way, output is generated for the
given o65 file. For example, cc65 loadable drivers have a zero page segment,
but this segment must not be defined in the file itself, because the
standard module loader will overlay it with the zeropage space used by the
application that loads this module. So instead of allocating space in the
zero page segment, the converter will reference the start of the zero page
area used by the application.
Currently, the following models are defined:
<itemize>
<item>lunix
<item>os/a65
<item>cc65-module
</itemize>
The default is to autodetect the model to use from the input file, so
there's rarely a need to use this option.
<tag><tt>-n, --no-output</tt></tag>
Don't do the actual conversion, just read in the o65 file checking for
problems. This option may be used in conjunction with <tt/--verbose/ to
view some information about the input file.
<tag><tt>-o name</tt></tag>
Specify the name of the output file. If you don't specify a name, the
name of the o65 input file is used, with the extension replaced by ".s".
<tag><tt>-v, --verbose</tt></tag>
Using this option, the converter will be somewhat more verbose and print
some information about the o65 input file (among other things). You may use
this option together with <tt/--no-output/ to just get the o65 info.
<tag><tt>-V, --version</tt></tag>
Print the version number of the compiler. When submitting a bug report,
please include the operating system you're using, and the compiler
version.
<tag><tt>--zeropage-label name</tt></tag>
Set the label used to mark the start of the zeropage segment. When this
option is given, the label is also exported and may be accessed from other
code. When accessing such a label from C code, be sure to include the
leading underscore. If you don't need to access the zeropage segment,
there's no need to use this option.
<tag><tt>--zeropage-name seg</tt></tag>
Set the name of the zeropage segment. The default name is "ZEROPAGE" which is
compatible with the standard ld65 linker configurations.
</descrip>
<sect>Input and output<p>
The converter will accept one o65 file per invocation and create a file with
the same base name, but with the extension replaced by ".s". The output
file contains assembler code suitable for the use with the ca65 macro
assembler.
<sect>Converting loadable drivers<p>
<sect1>Differences between static linking and runtime loading<p>
One main use of the utility is conversion of loadable drivers, so they may be
linked statically to an application. Statically linking will cause a few
things to be different from runtime loading:
<itemize>
<item> Without changing the segment names, all segments take the default
names used by the standard linker configurations. This means that the
driver code is no longer contingous in memory, instead the code
segment is placed somewhere in between all other code segments, the
data segment is placed with all other data segments and so on. If the
driver doesn't do strange things this shouldn't be a problem.
<item> With statically linked code, data and bss segments will get intialized
once (when the application is loaded), while a loadable driver will
get its initialization each time the driver is loaded into memory
(which may be more than once in the lifetime of a program). It depends
on the driver if this is a problem. Currently, most drivers supplied
with cc65 behave correctly when linked statically.
</itemize>
<sect1>Additional requirements<p>
All loadable drivers used by cc65 have a header and a jump table at the start
of the code segment. The header is needed to detect the driver (it may also
contain some data that is necessary to access the driver). The jump table is
used to access the functions in the driver code.
When loading a driver at runtime, the load address of the driver is also the
address of the code segment, so the locations of the header and jump table are
known. However, when linking the driver statically, it is up to the programmer
to provide this information to the driver API.
For this purpose, it is necessary to define a code segment label that can be
accessed from the outside later. Please note that the converter does currently
<em/not/ create such a label without being ordered to do so, even if the input
file is a cc65 module.
To create such a label, use the <tt/--code-label/ option when calling the
converter. Be sure to begin the label with a leading underscore when accessing
it from C code. In your code, define an arbitrary variable with this name. Use
the address of this variable as the address of the code segment of the driver.
Be sure to never modify the variable which is in reality the start of your
driver!
<sect1>Example - Convert and link a graphics driver<p>
As an example, here are some instructions to convert and use the c64-hi.tgi
graphics driver:
First, convert the driver, generating a label named "_c64_hi" for the code
segment. Use the assembler to generate an object file from the assembler
output.
<tscreen><verb>
co65 --code-label _c64_hi c64-hi.tgi
ca65 c64-hi.s
</verb></tscreen>
Next, change your C code to declare a variable that is actually the address
of the driver:
<tscreen><verb>
extern void c64_hi[];
</verb></tscreen>
Instead of loading and unloading the driver, change the code to install and
uninstall the driver, which will be already in memory after linking:
<tscreen><verb>
/* Install the driver */
tgi_install (c64_hi);
...
/* Uninstall the driver */
tgi_uninstall ();
</verb></tscreen>
Don't forget to link the driver object file to your application, otherwise you
will get an "undefined external" error for the _c64_hi symbol.
<sect>Bugs/Feedback<p>
If you have problems using the converter, if you find any bugs, or if you're
doing something interesting with the code, 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>Copyright<p>
co65 is (C) Copyright 2003 Ullrich von Bassewitz. For usage of the binaries
and/or sources the following conditions apply:
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>

308
doc/coding.sgml Normal file
View File

@ -0,0 +1,308 @@
<!doctype linuxdoc system>
<article>
<title>cc65 coding hints
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
<date>2000-12-03, 2009-09-01
<abstract>
How to generate the most effective code with cc65.
</abstract>
<sect>Use prototypes<p>
This will not only help to find errors between separate modules, it will also
generate better code, since the compiler must not assume that a variable sized
parameter list is in place and must not pass the argument count to the called
function. This will lead to shorter and faster code.
<sect>Don't declare auto variables in nested function blocks<p>
Variable declarations in nested blocks are usually a good thing. But with
cc65, there is a drawback: Since the compiler generates code in one pass, it
must create the variables on the stack each time the block is entered and
destroy them when the block is left. This causes a speed penalty and larger
code.
<sect>Remember that the compiler does no high level optimizations<p>
The compiler needs hints from you about the code to generate. It will try to
optimize the generated code, but follow the outline you gave in your C
program. So for example, when accessing indexed data structures, get a pointer
to the element and use this pointer instead of calculating the index again and
again. If you want to have your loops unrolled, or loop invariant code moved
outside the loop, you have to do that yourself.
<sect>Longs are slow!<p>
While long support is necessary for some things, it's really, really slow on
the 6502. Remember that any long variable will use 4 bytes of memory, and any
operation works on double the data compared to an int.
<sect>Use unsigned types wherever possible<p>
The 6502 CPU has no opcodes to handle signed values greater than 8 bit. So
sign extension, test of signedness etc. has to be done with extra code. As a
consequence, the code to handle signed operations is usually a bit larger and
slower than the same code for unsigned types.
<sect>Use chars instead of ints if possible<p>
While in arithmetic operations, chars are immidiately promoted to ints, they
are passed as chars in parameter lists and are accessed as chars in variables.
The code generated is usually not much smaller, but it is faster, since
accessing chars is faster. For several operations, the generated code may be
better if intermediate results that are known not to be larger than 8 bit are
casted to chars.
You should especially use unsigned chars for loop control variables if the
loop is known not to execute more than 255 times.
<sect>Make the size of your array elements one of 1, 2, 4, 8<p>
When indexing into an array, the compiler has to calculate the byte offset
into the array, which is the index multiplied by the size of one element. When
doing the multiplication, the compiler will do a strength reduction, that is,
replace the multiplication by a shift if possible. For the values 2, 4 and 8,
there are even more specialized subroutines available. So, array access is
fastest when using one of these sizes.
<sect>Expressions are evaluated from left to right<p>
Since cc65 is not building an explicit expression tree when parsing an
expression, constant subexpressions may not be detected and optimized properly
if you don't help. Look at this example:
<tscreen><verb>
#define OFFS 4
int i;
i = i + OFFS + 3;
</verb></tscreen>
The expression is parsed from left to right, that means, the compiler sees 'i',
and puts it contents into the secondary register. Next is OFFS, which is
constant. The compiler emits code to add a constant to the secondary register.
Same thing again for the constant 3. So the code produced contains a fetch
of 'i', two additions of constants, and a store (into 'i'). Unfortunately, the
compiler does not see, that "OFFS + 3" is a constant for itself, since it does
its evaluation from left to right. There are some ways to help the compiler
to recognize expression like this:
<enum>
<item>Write "i = OFFS + 3 + i;". Since the first and second operand are
constant, the compiler will evaluate them at compile time reducing the code to
a fetch, one addition (secondary + constant) and one store.
<item>Write "i = i + (OFFS + 3)". When seeing the opening parenthesis, the
compiler will start a new expression evaluation for the stuff in the braces,
and since all operands in the subexpression are constant, it will detect this
and reduce the code to one fetch, one addition and one store.
</enum>
<sect>Use the preincrement and predecrement operators<p>
The compiler is not always smart enough to figure out, if the rvalue of an
increment is used or not. So it has to save and restore that value when
producing code for the postincrement and postdecrement operators, even if this
value is never used. To avoid the additional overhead, use the preincrement
and predecrement operators if you don't need the resulting value. That means,
use
<tscreen><verb>
...
++i;
...
</verb></tscreen>
instead of
<tscreen><verb>
...
i++;
...
</verb></tscreen>
<sect>Use constants to access absolute memory locations<p>
The compiler produces optimized code, if the value of a pointer is a constant.
So, to access direct memory locations, use
<tscreen><verb>
#define VDC_STATUS 0xD601
*(char*)VDC_STATUS = 0x01;
</verb></tscreen>
That will be translated to
<tscreen><verb>
lda #$01
sta $D601
</verb></tscreen>
The constant value detection works also for struct pointers and arrays, if the
subscript is a constant. So
<tscreen><verb>
#define VDC ((unsigned char*)0xD600)
#define STATUS 0x01
VDC[STATUS] = 0x01;
</verb></tscreen>
will also work.
If you first load the constant into a variable and use that variable to access
an absolute memory location, the generated code will be much slower, since the
compiler does not know anything about the contents of the variable.
<sect>Use initialized local variables<p>
Initialization of local variables when declaring them gives shorter and faster
code. So, use
<tscreen><verb>
int i = 1;
</verb></tscreen>
instead of
<tscreen><verb>
int i;
i = 1;
</verb></tscreen>
But beware: To maximize your savings, don't mix uninitialized and initialized
variables. Create one block of initialized variables and one of uniniitalized
ones. The reason for this is, that the compiler will sum up the space needed
for uninitialized variables as long as possible, and then allocate the space
once for all these variables. If you mix uninitialized and initialized
variables, you force the compiler to allocate space for the uninitialized
variables each time, it parses an initialized one. So do this:
<tscreen><verb>
int i, j;
int a = 3;
int b = 0;
</verb></tscreen>
instead of
<tscreen><verb>
int i;
int a = 3;
int j;
int b = 0;
</verb></tscreen>
The latter will work, but will create larger and slower code.
<sect>Use the array operator &lsqb;&rsqb; even for pointers<p>
When addressing an array via a pointer, don't use the plus and dereference
operators, but the array operator. This will generate better code in some
common cases.
Don't use
<tscreen><verb>
char* a;
char b, c;
char b = *(a + c);
</verb></tscreen>
Use
<tscreen><verb>
char* a;
char b, c;
char b = a[c];
</verb></tscreen>
instead.
<sect>Use register variables with care<p>
Register variables may give faster and shorter code, but they do also have an
overhead. Register variables are actually zero page locations, so using them
saves roughly one cycle per access. The calling routine may also use register
variables, so the old values have to be saved on function entry and restored
on exit. Saving an d restoring has an overhead of about 70 cycles per 2 byte
variable. It is easy to see, that - apart from the additional code that is
needed to save and restore the values - you need to make heavy use of a
variable to justify the overhead.
As a general rule: Use register variables only for pointers that are
dereferenced several times in your function, or for heavily used induction
variables in a loop (with several 100 accesses).
When declaring register variables, try to keep them together, because this
will allow the compiler to save and restore the old values in one chunk, and
not in several.
And remember: Register variables must be enabled with <tt/-r/ or <tt/-Or/.
<sect>Decimal constants greater than 0x7FFF are actually long ints<p>
The language rules for constant numeric values specify that decimal constants
without a type suffix that are not in integer range must be of type long int
or unsigned long int. So a simple constant like 40000 is of type long int!
This is often unexpected and may cause an expression to be evaluated with 32
bits. While in many cases the compiler takes care about it, in some places it
can't. So be careful when you get a warning like
<tscreen><verb>
test.c(7): Warning: Constant is long
</verb></tscreen>
Use the <tt/U/, <tt/L/ or <tt/UL/ suffixes to tell the compiler the desired
type of a numeric constant.
<sect>Access to parameters in variadic functions is expensive<p>
Since cc65 has the "wrong" calling order, the location of the fixed parameters
in a variadic function (a function with a variable parameter list) depends on
the number and size of variable arguments passed. Since this number and size
is unknown at compile time, the compiler will generate code to calculate the
location on the stack when needed.
Because of this additional code, accessing the fixed parameters in a variadic
function is much more expensive than access to parameters in a "normal"
function. Unfortunately, this additional code is also invisible to the
programmer, so it is easy to forget.
As a rule of thumb, if you access such a parameter more than once, you should
think about copying it into a normal variable and using this variable instead.
</article>

730
doc/customizing.sgml Normal file
View File

@ -0,0 +1,730 @@
<!doctype linuxdoc system>
<article>
<title>Defining a Custom cc65 Target
<author>Bruce Reidenbach
<date>2010-02-22
<abstract>
This section provides step-by-step instructions on how to use the cc65
toolset for a custom hardware platform (a target system not currently
supported by the cc65 library set).
</abstract>
<!-- Table of contents -->
<toc>
<!-- Begin the document -->
<sect>Overview<p>
The cc65 toolset provides a set of pre-defined libraries that allow the
user to target the executable image to a variety of hardware platforms.
In addition, the user can create a customized environment so that the
executable can be targeted to a custom platform. The following
instructions provide step-by-step instructions on how to customize the
toolset for a target that is not supported by the standard cc65
installation.
The platform used in this example is a Xilinx Field Programmable Gate
Array (FPGA) with an embedded 65C02 core. The processor core supports
the additional opcodes/addressing modes of the 65SC02, along with the
STP and WAI instructions. These instructions will create a set of files
to create a custom target, named SBC, for <bf>S</bf>ingle <bf>B</bf>oard
<bf>C</bf>omputer.
<sect>System Memory Map Definition<p>
The targeted system uses block RAM contained on the XILINX FPGA for the
system memory (both RAM and ROM). The block RAMs are available in
various aspect ratios, and they will be used in this system as 2K*8
devices. There will be two RAMs used for data storage, starting at
location $0000 and growing upwards. There will be one ROM (realized as
initialized RAM) used code storage, starting at location $FFFF and
growing downwards.
The cc65 toolset requires a memory configuration file to define the
memory that is available to the cc65 run-time environment, which is
defined as follows:
<tscreen><code>
MEMORY {
ZP: start = $0, size = $100, type = rw, define = yes;
RAM: start = $200, size = $0E00, define = yes;
ROM: start = $F800, size = $0800, file = %O;
}
</code></tscreen>
ZP defines the available zero page locations, which in this case starts
at $0 and has a length of $100. Keep in mind that certain systems may
require access to some zero page locations, so the starting address may
need to be adjusted accordingly to prevent cc65 from attempting to reuse
those locations. Also, at a minimum, the cc65 run-time environment uses
26 zero page locations, so the smallest zero page size that can be
specified is $1A. The usable RAM memory area begins after the 6502
stack storage in page 1, so it is defined as starting at location $200
and filling the remaining 4K of space (4096 - 2 *
256&nbsp;=&nbsp;3584&nbsp;=&nbsp;$0E00). The 2K of ROM space begins at
address $F800 and goes to $FFFF (size&nbsp;=&nbsp;$0800).
Next, the memory segments within the memory devices need to be defined.
A standard segment definition is used, with one notable exception. The
interrupt and reset vector locations need to be defined at locations
$FFFA through $FFFF. A special segment named VECTORS is defined that
resides at these locations. Later, the interrupt vector map will be
created and placed in the VECTORS segment, and the linker will put these
vectors at the proper memory locations. The segment definition is:
<tscreen><code>
SEGMENTS {
ZEROPAGE: load = ZP, type = zp, define = yes;
DATA: load = ROM, type = rw, define = yes, run = RAM;
BSS: load = RAM, type = bss, define = yes;
HEAP: load = RAM, type = bss, optional = yes;
STARTUP: load = ROM, type = ro;
INIT: load = ROM, type = ro, optional = yes;
CODE: load = ROM, type = ro;
RODATA: load = ROM, type = ro;
VECTORS: load = ROM, type = ro, start = $FFFA;
}
</code></tscreen>
The meaning of each of these segments is as follows.
<p><tt> ZEROPAGE: </tt>Data in page 0, defined by ZP as starting at $0 with length $100
<p><tt> DATA: </tt>Initialized data that can be modified by the program, stored in RAM
<p><tt> BSS: </tt>Uninitialized data stored in RAM (used for variable storage)
<p><tt> HEAP: </tt>Uninitialized C-level heap storage in RAM, optional
<p><tt> STARTUP: </tt>The program initialization code, stored in ROM
<p><tt> INIT: </tt>The code needed to initialize the system, stored in ROM
<p><tt> CODE: </tt>The program code, stored in ROM
<p><tt> RODATA: </tt>Initialized data that cannot be modified by the program, stored in ROM
<p><tt> VECTORS: </tt>The interrupt vector table, stored in ROM at location $FFFA
A note about initialized data: any variables that require an initial
value, such as external (global) variables, require that the initial
values be stored in the ROM code image. However, variables stored in
ROM cannot change; therefore the data must be moved into variables that
are located in RAM. Specifying <tt>run&nbsp;=&nbsp;RAM</tt> as part of
the DATA segment definition will indicate that those variables will
require their initialization value to be copied via a call to the
<tt>copydata</tt> routine in the startup assembly code. In addition,
there are system level variables that will need to be initialized as
well, especially if the heap segment is used via a C-level call to
<tt>malloc&nbsp;()</tt>.
The final section of the definition file contains the data constructors
and destructors used for system startup. In addition, if the heap is
used, the maximum C-level stack size needs to be defined in order for
the system to be able to reliably allocate blocks of memory. The stack
size selection must be greater than the maximum amount of storage
required to run the program, keeping in mind that the C-level subroutine
call stack and all local variables are stored in this stack. The
<tt>FEATURES</tt> section defines the required constructor/destructor
attributes and the <tt>SYMBOLS</tt> section defines the stack size. The
constructors will be run via a call to <tt>initlib</tt> in the startup
assembly code and the destructors will be run via an assembly language
call to <tt>donelib</tt> during program termination.
<tscreen><code>
FEATURES {
CONDES: segment = STARTUP,
type = constructor,
label = __CONSTRUCTOR_TABLE__,
count = __CONSTRUCTOR_COUNT__;
CONDES: segment = STARTUP,
type = destructor,
label = __DESTRUCTOR_TABLE__,
count = __DESTRUCTOR_COUNT__;
}
SYMBOLS {
# Define the stack size for the application
__STACKSIZE__: value = $0200, weak = yes;
}
</code></tscreen>
These definitions are placed in a file named &quot;sbc.cfg&quot;
and are referred to during the ld65 linker stage.
<sect>Startup Code Definition<p>
In the cc65 toolset, a startup routine must be defined that is executed
when the CPU is reset. This startup code is marked with the STARTUP
segment name, which was defined in the system configuration file as
being in read only memory. The standard convention used in the
predefined libraries is that this code is resident in the crt0 module.
For this custom system, all that needs to be done is to perform a little
bit of 6502 housekeeping, set up the C-level stack pointer, initialize
the memory storage, and call the C-level routine <tt>main&nbsp;()</tt>.
The following code was used for the crt0 module, defined in the file
&quot;crt0.s&quot;:
<tscreen><code>
; ---------------------------------------------------------------------------
; crt0.s
; ---------------------------------------------------------------------------
;
; Startup code for cc65 (Single Board Computer version)
.export _init, _exit
.import _main
.export __STARTUP__ : absolute = 1 ; Mark as startup
.import __RAM_START__, __RAM_SIZE__ ; Linker generated
.import copydata, zerobss, initlib, donelib
.include &quot;zeropage.inc&quot;
; ---------------------------------------------------------------------------
; Place the startup code in a special segment
.segment &quot;STARTUP&quot;
; ---------------------------------------------------------------------------
; A little light 6502 housekeeping
_init: LDX #$FF ; Initialize stack pointer to $01FF
TXS
CLD ; Clear decimal mode
; ---------------------------------------------------------------------------
; Set cc65 argument stack pointer
LDA #&lt;(__RAM_START__ + __RAM_SIZE__)
STA sp
LDA #&gt;(__RAM_START__ + __RAM_SIZE__)
STA sp+1
; ---------------------------------------------------------------------------
; Initialize memory storage
JSR zerobss ; Clear BSS segment
JSR copydata ; Initialize DATA segment
JSR initlib ; Run constructors
; ---------------------------------------------------------------------------
; Call main()
JSR _main
; ---------------------------------------------------------------------------
; Back from main (this is also the _exit entry): force a software break
_exit: JSR donelib ; Run destructors
BRK
</code></tscreen>
The following discussion explains the purpose of several important
assembler level directives in this file.
<tscreen><verb>
.export _init, _exit
</verb></tscreen>
This line instructs the assembler that the symbols <tt>_init</tt> and
<tt>_exit</tt> are to be accessible from other modules. In this
example, <tt>_init</tt> is the location that the CPU should jump to when
reset, and <tt>_exit</tt> is the location that will be called when the
program is finished.
<tscreen><verb>
.import _main
</verb></tscreen>
This line instructs the assembler to import the symbol <tt>_main</tt>
from another module. cc65 names all C-level routines as
{underscore}{name} in assembler, thus the <tt>main&nbsp;()</tt> routine
in C is named <tt>_main</tt> in the assembler. This is how the startup
code will link to the C-level code.
<tscreen><verb>
.export __STARTUP__ : absolute = 1 ; Mark as startup
</verb></tscreen>
This line marks this code as startup code (code that is executed when
the processor is reset), which will then be automatically linked into
the executable code.
<tscreen><verb>
.import __RAM_START__, __RAM_SIZE__ ; Linker generated
</verb></tscreen>
This line imports the RAM starting address and RAM size constants, which
are used to initialize the cc65 C-level argument stack pointer.
<tscreen><verb>
.segment &quot;STARTUP&quot;
</verb></tscreen>
This line instructs the assembler that the code is to be placed in the
STARTUP segment of memory.
<tscreen><verb>
JSR zerobss ; Clear BSS segment
JSR copydata ; Initialize DATA segment
JSR initlib ; Run constructors
</verb></tscreen>
These three lines initialize the external (global) and system
variables. The first line sets the BSS segment -- the memory locations
used for external variables -- to 0. The second line copies the
initialization value stored in ROM to the RAM locations used for
initialized external variables. The last line runs the constructors
that are used to initialize the system run-time variables.
<tscreen><verb>
JSR _main
</verb></tscreen>
This is the actual call to the C-level <tt>main&nbsp;()</tt> routine,
which is called after the startup code completes.
<tscreen><verb>
_exit: JSR donelib ; Run destructors
BRK
</verb></tscreen>
This is the code that will be executed when <tt>main ()</tt>
terminates. The first thing that must be done is run the destructors
via a call to <tt>donelib</tt>. Then the program can terminate. In
this example, the program is expected to run forever. Therefore, there
needs to be a way of indicating when something has gone wrong and the
system needs to be shut down, requiring a restart only by a hard reset.
The BRK instruction will be used to indicate a software fault. This is
advantageous because cc65 uses the BRK instruction as the fill byte in
the final binary code. In addition, the hardware has been designed to
force the data lines to $00 for all illegal memory accesses, thereby
also forcing a BRK instruction into the CPU.
<sect>Custom Run-Time Library Creation<p>
The next step in customizing the cc65 toolset is creating a run-time
library for the targeted hardware. The easiest way to do this is to
modify a standard library from the cc65 distribution. In this example,
there is no console I/O, mouse, joystick, etc. in the system, so it is
most appropriate to use the simplest library as the base, which is for
the Watara Supervision and is named &quot;supervision.lib&quot; in the
lib directory of the distribution.
The only modification required is to replace the <tt>crt0</tt> module in
the supervision.lib library with custom startup code. This is simply
done by first copying the library and giving it a new name, compiling
the startup code with ca65, and finally using the ar65 archiver to
replace the module in the new library. The steps are shown below:
<tscreen><verb>
$ copy &quot;C:\Program Files\cc65\lib\supervision.lib&quot; sbc.lib
$ ca65 crt0.s
$ ar65 a sbc.lib crt0.o
</verb></tscreen>
<sect>Interrupt Service Routine Definition<p>
For this system, the CPU is put into a wait condition prior to allowing
interrupt processing. Therefore, the interrupt service routine is very
simple: return from all valid interrupts. However, as mentioned
before, the BRK instruction is used to indicate a software fault, which
will call the same interrupt service routine as the maskable interrupt
signal IRQ. The interrupt service routine must be able to tell the
difference between the two, and act appropriately.
The interrupt service routine shown below includes code to detect when a
BRK instruction has occurred and stops the CPU from further processing.
The interrupt service routine is in a file named
&quot;interrupt.s&quot;.
<tscreen><code>
; ---------------------------------------------------------------------------
; interrupt.s
; ---------------------------------------------------------------------------
;
; Interrupt handler.
;
; Checks for a BRK instruction and returns from all valid interrupts.
.import _stop
.export _irq_int, _nmi_int
.segment &quot;CODE&quot;
.PC02 ; Force 65C02 assembly mode
; ---------------------------------------------------------------------------
; Non-maskable interrupt (NMI) service routine
_nmi_int: RTI ; Return from all NMI interrupts
; ---------------------------------------------------------------------------
; Maskable interrupt (IRQ) service routine
_irq_int: PHX ; Save X register contents to stack
TSX ; Transfer stack pointer to X
PHA ; Save accumulator contents to stack
INX ; Increment X so it points to the status
INX ; register value saved on the stack
LDA $100,X ; Load status register contents
AND #$10 ; Isolate B status bit
BNE break ; If B = 1, BRK detected
; ---------------------------------------------------------------------------
; IRQ detected, return
irq: PLA ; Restore accumulator contents
PLX ; Restore X register contents
RTI ; Return from all IRQ interrupts
; ---------------------------------------------------------------------------
; BRK detected, stop
break: JMP _stop ; If BRK is detected, something very bad
; has happened, so stop running
</code></tscreen>
The following discussion explains the purpose of several important
assembler level directives in this file.
<tscreen><verb>
.import _stop
</verb></tscreen>
This line instructs the assembler to import the symbol <tt>_stop</tt>
from another module. This routine will be called if a BRK instruction
is encountered, signaling a software fault.
<tscreen><verb>
.export _irq_int, _nmi_int
</verb></tscreen>
This line instructs the assembler that the symbols <tt>_irq_int</tt> and
<tt>_nmi_int</tt> are to be accessible from other modules. In this
example, the address of these symbols will be placed in the interrupt
vector table.
<tscreen><verb>
.segment &quot;CODE&quot;
</verb></tscreen>
This line instructs the assembler that the code is to be placed in the
CODE segment of memory. Note that because there are 65C02 mnemonics in
the assembly code, the assembler is forced to use the 65C02 instruction
set with the <tt>.PC02</tt> directive.
The final step is to define the interrupt vector memory locations.
Recall that a segment named VECTORS was defined in the memory
configuration file, which started at location $FFFA. The addresses of
the interrupt service routines from &quot;interrupt.s&quot; along with
the address for the initialization code in crt0 are defined in a file
named &quot;vectors.s&quot;. Note that these vectors will be placed in
memory in their proper little-endian format as:
<p><tt> $FFFA&nbsp;-&nbsp;$FFFB:</tt> NMI interrupt vector (low byte, high byte)
<p><tt> $FFFC&nbsp;-&nbsp;$FFFD:</tt> Reset vector (low byte, high byte)
<p><tt> $FFFE&nbsp;-&nbsp;$FFFF:</tt> IRQ/BRK interrupt vector (low byte, high byte)
using the <tt>.addr</tt> assembler directive. The contents of the file are:
<tscreen><code>
; ---------------------------------------------------------------------------
; vectors.s
; ---------------------------------------------------------------------------
;
; Defines the interrupt vector table.
.import _init
.import _nmi_int, _irq_int
.segment &quot;VECTORS&quot;
.addr _nmi_int ; NMI vector
.addr _init ; Reset vector
.addr _irq_int ; IRQ/BRK vector
</code></tscreen>
The cc65 toolset will replace the address symbols defined here with the
actual addresses of the routines during the link process.
<sect>Adding Custom Instructions<p>
The cc65 instruction set only supports the WAI (Wait for Interrupt) and
STP (Stop) instructions when used with the 65816 CPU (accessed via the
--cpu command line option of the ca65 macro assembler). The 65C02 core
used in this example supports these two instructions, and in fact the
system benefits from the use of both the WAI and STP instructions.
In order to use the WAI instruction in this case, a C routine named
&quot;wait&quot; was created that consists of the WAI opcode followed by
a subroutine return. It was convenient in this example to put the IRQ
interrupt enable in this subroutine as well, since interrupts should
only be enabled when the code is in this wait condition.
For both the WAI and STP instructions, the assembler is
&quot;fooled&quot; into placing those opcodes into memory by inserting a
single byte of data that just happens to be the opcode for those
instructions. The assembly code routines are placed in a file, named
&quot;wait.s&quot;, which is shown below:
<tscreen><code>
; ---------------------------------------------------------------------------
; wait.s
; ---------------------------------------------------------------------------
;
; Wait for interrupt and return
.export _wait, _stop
; ---------------------------------------------------------------------------
; Wait for interrupt: Forces the assembler to emit a WAI opcode ($CB)
; ---------------------------------------------------------------------------
.segment &quot;CODE&quot;
.proc _wait: near
CLI ; Enable interrupts
.byte $CB ; Inserts a WAI opcode
RTS ; Return to caller
.endproc
; ---------------------------------------------------------------------------
; Stop: Forces the assembler to emit a STP opcode ($DB)
; ---------------------------------------------------------------------------
.proc _stop: near
.byte $DB ; Inserts a STP opcode
.endproc
</code></tscreen>
The label <tt>_wait</tt>, when exported, can be called by using the
<tt>wait&nbsp;()</tt> subroutine call in C. The section is marked as
code so that it will be stored in read-only memory, and the procedure is
tagged for 16-bit absolute addressing via the &quot;near&quot;
modifier. Similarly, the <tt>_stop</tt> routine can be called from
within the C-level code via a call to <tt>stop&nbsp;()</tt>. In
addition, the routine can be called from assembly code by calling
<tt>_stop</tt> (as was done in the interrupt service routine).
<sect>Hardware Drivers<p>
Oftentimes, it can be advantageous to create small application helpers
in assembly language to decrease codespace and increase execution speed
of the overall program. An example of this would be the transfer of
characters to a FIFO (<bf>F</bf>irst-<bf>I</bf>n,
<bf>F</bf>irst-<bf>O</bf>ut) storage buffer for transmission over a
serial port. This simple action could be performed by an assembly
language driver which would execute much quicker than coding it in C.
The following discussion outlines a method of interfacing a C program
with an assembly language subroutine.
The first step in creating the assembly language code for the driver is
to determine how to pass the C arguments to the assembly language
routine. The cc65 toolset allows the user to specify whether the data
is passed to a subroutine via the stack or by the processor registers by
using the <tt>__fastcall__</tt> function declaration (note that there
are two underscore characters in front of and two behind the
<tt>fastcall</tt> declaration). When <tt>__fastcall__</tt> is
specified, the rightmost argument in the function call is passed to the
subroutine using the 6502 registers instead of the stack. Note that if
there is only one argument in the function call, the execution overhead
required by the stack interface routines is completely avoided.
Without <tt>__fastcall__</tt>, the argument is loaded in the A and X
registers and then pushed onto the stack via a call to <tt>pushax</tt>.
The first thing the subroutine does is retrieve the argument from the
stack via a call to <tt>ldax0sp</tt>, which copies the values into the A
and X. When the subroutine is finished, the values on the stack must be
popped off and discarded via a jump to <tt>incsp2</tt>, which includes
the RTS subroutine return command. This is shown in the following code
sample.
Calling sequence:
<tscreen><verb>
lda #&lt;(L0001) ; Load A with the high order byte
ldx #&gt;(L0001) ; Load X with the low order byte
jsr pushax ; Push A and X onto the stack
jsr _foo ; Call foo, i.e., foo (arg)
</verb></tscreen>
Subroutine code:
<tscreen><verb>
_foo: jsr ldax0sp ; Retrieve A and X from the stack
sta ptr ; Store A in ptr
stx ptr+1 ; Store X in ptr+1
... ; (more subroutine code goes here)
jmp incsp2 ; Pop A and X from the stack (includes return)
</verb></tscreen>
If <tt>__fastcall__</tt> is specified, the argument is loaded into the A
and X registers as before, but the subroutine is then called
immediately. The subroutine does not need to retrieve the argument
since the value is already available in the A and X registers.
Furthermore, the subroutine can be terminated with an RTS statement
since there is no stack cleanup which needs to be performed. This is
shown in the following code sample.
Calling sequence:
<tscreen><verb>
lda #&lt;(L0001) ; Load A with the high order byte
ldx #&gt;(L0001) ; Load X with the low order byte
jsr _foo ; Call foo, i.e., foo (arg)
</verb></tscreen>
Subroutine code:
<tscreen><verb>
_foo: sta ptr ; Store A in ptr
stx ptr+1 ; Store X in ptr+1
... ; (more subroutine code goes here)
rts ; Return from subroutine
</verb></tscreen>
The hardware driver in this example writes a string of character data to
a hardware FIFO located at memory location $1000. Each character is
read and is compared to the C string termination value ($00), which will
terminate the loop. All other character data is written to the FIFO.
For convenience, a carriage return/line feed sequence is automatically
appended to the serial stream. The driver defines a local pointer
variable which is stored in the zero page memory space in order to allow
for retrieval of each character in the string via the indirect indexed
addressing mode.
The assembly language routine is stored in a file names
&quot;rs232_tx.s&quot; and is shown below:
<tscreen><code>
; ---------------------------------------------------------------------------
; rs232_tx.s
; ---------------------------------------------------------------------------
;
; Write a string to the transmit UART FIFO
.export _rs232_tx
.exportzp _rs232_data: near
.define TX_FIFO $1000 ; Transmit FIFO memory location
.zeropage
_rs232_data: .res 2, $00 ; Reserve a local zero page pointer
.segment &quot;CODE&quot;
.proc _rs232_tx: near
; ---------------------------------------------------------------------------
; Store pointer to zero page memory and load first character
sta _rs232_data ; Set zero page pointer to string address
stx _rs232_data+1 ; (pointer passed in via the A/X registers)
ldy #00 ; Initialize Y to 0
lda (_rs232_data) ; Load first character
; ---------------------------------------------------------------------------
; Main loop: read data and store to FIFO until \0 is encountered
loop: sta TX_FIFO ; Loop: Store character in FIFO
iny ; Increment Y index
lda (_rs232_data),y ; Get next character
bne loop ; If character == 0, exit loop
; ---------------------------------------------------------------------------
; Append CR/LF to output stream and return
lda #$0D ; Store CR
sta TX_FIFO
lda #$0A ; Store LF
sta TX_FIFO
rts ; Return
.endproc
</code></tscreen>
<sect>Hello World! Example<p>
The following short example demonstrates programming in C using the cc65
toolset with a custom run-time environment. In this example, a Xilinx
FPGA contains a UART which is connected to a 65c02 processor with FIFO
(<bf>F</bf>irst-<bf>I</bf>n, <bf>F</bf>irst-<bf>O</bf>ut) storage to
buffer the data. The C program will wait for an interrupt generated by
the receive UART and then respond by transmitting the string &quot;Hello
World! &quot; every time a question mark character is received via a
call to the hardware driver <tt>rs232_tx&nbsp;()</tt>. The driver
prototype uses the <tt>__fastcall__</tt> extension to indicate that the
driver does not use the stack. The FIFO data interface is at address
$1000 and is defined as the symbolic constant <tt>FIFO_DATA</tt>.
Writing to <tt>FIFO_DATA</tt> transfers a byte of data into the transmit
FIFO for subsequent transmission over the serial interface. Reading
from <tt>FIFO_DATA</tt> transfers a byte of previously received data out
of the receive FIFO. The FIFO status data is at address $1001 and is
defined as the symbolic constant <tt>FIFO_STATUS</tt>. For convenience,
the symbolic constants <tt>TX_FIFO_FULL</tt> (which isolates bit 0 of
the register) and <tt>RX_FIFO_EMPTY</tt> (which isolates bit 1 of the
register) have been defined to read the FIFO status.
The following C code is saved in the file &quot;main.c&quot;. As this
example demonstrates, the run-time environment has been set up such that
all of the behind-the-scene work is transparent to the user.
<tscreen><code>
#define FIFO_DATA (*(unsigned char *) 0x1000)
#define FIFO_STATUS (*(unsigned char *) 0x1001)
#define TX_FIFO_FULL (FIFO_STATUS &amp; 0x01)
#define RX_FIFO_EMPTY (FIFO_STATUS &amp; 0x02)
extern void wait ();
extern void __fastcall__ rs232_tx (char *str);
int main () {
while (1) { // Run forever
wait (); // Wait for an RX FIFO interrupt
while (RX_FIFO_EMPTY == 0) { // While the RX FIFO is not empty
if (FIFO_DATA == '?') { // Does the RX character = '?'
rs232_tx (&quot;Hello World!&quot;); // Transmit &quot;Hello World!&quot;
} // Discard any other RX characters
}
}
return (0); // We should never get here!
}
</code></tscreen>
<sect>Putting It All Together<p>
The following commands will create a ROM image named &quot;a.out&quot;
that can be used as the initialization data for the Xilinx Block RAM
used for code storage:
<tscreen><verb>
$ cc65 -t none -O --cpu 65sc02 main.c
$ ca65 --cpu 65sc02 main.s
$ ca65 --cpu 65sc02 rs232_tx.s
$ ca65 --cpu 65sc02 interrupt.s
$ ca65 --cpu 65sc02 vectors.s
$ ca65 --cpu 65sc02 wait.s
$ ld65 -C sbc.cfg -m main.map interrupt.o vectors.o wait.o rs232_tx.o
main.o sbc.lib
</verb></tscreen>
During the C-level code compilation phase (<tt>cc65</tt>), assumptions
about the target system are disabled via the <tt>-t none</tt> command
line option. During the object module linker phase (<tt>ld65</tt>), the
target customization is enabled via inclusion of the <tt>sbc.lib</tt>
file and the selection of the configuration file via the <tt>-C
sbc.cfg</tt> command line option.
The 65C02 core used most closely matches the cc65 toolset processor
named 65SC02 (the 65C02 extensions without the bit manipulation
instructions), so all the commands specify the use of that processor via
the <tt>--cpu 65sc02</tt> option.
</article>

694
doc/da65.sgml Normal file
View File

@ -0,0 +1,694 @@
<!doctype linuxdoc system>
<article>
<title>da65 Users Guide
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
<date>2003-08-08
<abstract>
da65 is a 6502/65C02 disassembler that is able to read user supplied
information about its input data for better results. The output is ready for
feeding into ca65, the macro assembler supplied with the cc65 C compiler.
</abstract>
<!-- Table of contents -->
<toc>
<!-- Begin the document -->
<sect>Overview<p>
da65 is a disassembler for 6502/65C02 code. It is supplied as a utility with
the cc65 C compiler and generates output that is suitable for the ca65
macro assembler.
Besides generating output for ca65, one of the design goals was that the user
is able to feed additional information about the code into the disassembler
for improved results. This information may include the location and size of
tables, and their format.
One nice advantage of this concept is that disassembly of copyrighted binaries
may be handled without problems: One can just pass the information file for
disassembling the binary, so everyone with a legal copy of the binary can
generate a nicely formatted disassembly with readable labels and other
information.
<sect>Usage<p>
<sect1>Command line option overview<p>
The assembler accepts the following options:
<tscreen><verb>
---------------------------------------------------------------------------
Usage: da65 [options] [inputfile]
Short options:
-g Add debug info to object file
-h Help (this text)
-i name Specify an info file
-o name Name the output file
-v Increase verbosity
-F Add formfeeds to the output
-S addr Set the start/load address
-V Print the disassembler version
Long options:
--argument-column n Specify argument start column
--comment-column n Specify comment start column
--comments n Set the comment level for the output
--cpu type Set cpu type
--debug-info Add debug info to object file
--formfeeds Add formfeeds to the output
--help Help (this text)
--hexoffs Use hexadecimal label offsets
--info name Specify an info file
--label-break n Add newline if label exceeds length n
--mnemonic-column n Specify mnemonic start column
--pagelength n Set the page length for the listing
--start-addr addr Set the start/load address
--text-column n Specify text start column
--verbose Increase verbosity
--version Print the disassembler version
---------------------------------------------------------------------------
</verb></tscreen>
<sect1>Command line options in detail<p>
Here is a description of all the command line options:
<descrip>
<label id="option--argument-column">
<tag><tt>--argument-column n</tt></tag>
Specifies the column where the argument for a mnemonic or pseudo instruction
starts.
<label id="option--comment-column">
<tag><tt>--comment-column n</tt></tag>
Specifies the column where the comment for an instruction starts.
<label id="option--comments">
<tag><tt>--comments n</tt></tag>
Set the comment level for the output. Valid arguments are 0..4. Greater
values will increase the level of additional information written to the
output file in form of comments.
<label id="option--cpu">
<tag><tt>--cpu type</tt></tag>
Set the CPU type. The option takes a parameter, which may be one of
6502, 6502x, 65sc02, 65c02, huc6280
6502x is the NMOS 6502 with illegal opcodes. huc6280 is the CPU of the PC
engine. Support for the 65816 is currently not available.
<label id="option--formfeeds">
<tag><tt>-F, --formfeeds</tt></tag>
Add formfeeds to the generated output. This feature is useful together
with the <tt><ref id="option--pagelength" name="--pagelength"></tt> option.
If <tt/--formfeeds/ is given, a formfeed is added to the output after each
page.
<tag><tt>-g, --debug-info</tt></tag>
This option adds the <tt/.DEBUGINFO/ command to the output file, so the
assembler will generate debug information when reassembling the generated
output.
<tag><tt>-h, --help</tt></tag>
Print the short option summary shown above.
<label id="option--hexoffs">
<tag><tt>--hexoffs</tt></tag>
Output label offsets in hexadecimal instead of decimal notation.
<label id="option--info">
<tag><tt>-i name, --info name</tt></tag>
Specify an info file. The info file contains global options that may
override or replace command line options plus informations about the code
that has to be disassembled. See the separate section <ref id="infofile"
name="Info File Format">.
<label id="option-o">
<tag><tt>-o name</tt></tag>
Specify a name for an output file. The default is to use <tt/stdout/, so
without this switch or the corresponding <ref id="global-options"
name="global option"> <tt><ref id="OUTPUTNAME" name="OUTPUTNAME"></tt>,
the output will go to the terminal.
<label id="option--label-break">
<tag><tt>--label-break n</tt></tag>
Adds a newline if the length of a label exceeds the given length.
Note: If the label would run into the code in the mid column, a
linefeed is always inserted regardless of this setting.
This option overrides the <ref id="global-options" name="global option">
<tt><ref id="LABELBREAK" name="LABELBREAK"></tt>.
<label id="option--mnemonic-column">
<tag><tt>--mnemonic-column n</tt></tag>
Specifies the column where a mnemonic or pseudo instrcuction is output.
<label id="option--pagelength">
<tag><tt>--pagelength n</tt></tag>
Sets the length of a listing page in lines. After this number of lines, a
new page header is generated. If the <tt><ref id="option--formfeeds"
name="--formfeeds"></tt> is also given, a formfeed is inserted before
generating the page header.
A value of zero for the page length will disable paging of the output.
<label id="option--start-addr">
<tag><tt>-S addr, --start-addr addr</tt></tag>
Specify the start/load address of the binary code that is going to be
disassembled. The given address is interpreted as an octal value if
preceded with a '0' digit, as a hexadecimal value if preceded
with '0x', '0X', or '$', and as a decimal value in all other cases. If no
start address is specified, $10000 minus the size of the input file is used.
<label id="option--text-column">
<tag><tt>--text-column n</tt></tag>
Specifies the column where additional text is output. This additional text
consists of the bytes encoded in this line in text representation.
<tag><tt>-v, --verbose</tt></tag>
Increase the disassembler verbosity. Usually only needed for debugging
purposes. You may use this option more than one time for even more
verbose output.
<tag><tt>-V, --version</tt></tag>
Print the version number of the assembler. If you send any suggestions
or bugfixes, please include the version number.
</descrip>
<p>
<sect>Detailed workings<p>
<sect1>Supported CPUs<p>
The default (no CPU given on the command line or in the <tt/GLOBAL/ section of
the info file) is the 6502 CPU. The disassembler knows all "official" opcodes
for this CPU. Invalid opcodes are translated into <tt/.byte/ commands.
With the command line option <tt><ref id="option--cpu" name="--cpu"></tt>, the
disassembler may be told to recognize either the 65SC02 or 65C02 CPUs. The
latter understands the same opcodes as the former, plus 16 additional bit
manipulation and bit test-and-branch commands.
While there is some code for the 65816 in the sources, it is currently
unsupported.
<sect1>Attribute map<p>
The disassembler works by creating an attribute map for the whole address
space ($0000 - $FFFF). Initially, all attributes are cleared. Then, an
external info file (if given) is read. Disassembly is done in several passes.
In all passes with the exception of the last one, information about the
disassembled code is gathered and added to the symbol and attribute maps. The
last pass generates output using the information from the maps.
<sect1>Labels<p>
Some instructions may generate labels in the first pass, while most other
instructions do not generate labels, but use them if they are available. Among
others, the branch and jump instructions will generate labels for the target
of the branch in the first pass. External labels (taken from the info file)
have precedence over internally generated ones, They must be valid identifiers
as specified for the ca65 assembler. Internal labels (generated by the
disassembler) have the form <tt/Labcd/, where <tt/abcd/ is the hexadecimal
address of the label in upper case letters. You should probably avoid using
such label names for external labels.
<sect1>Info File<p>
The info file is used to pass additional information about the input code to
the disassembler. This includes label names, data areas or tables, and global
options like input and output file names. See the <ref id="infofile"
name="next section"> for more information.
<sect>Info File Format<label id="infofile"><p>
The info file contains lists of specifications grouped together. Each group
directive has an identifying token and an attribute list enclosed in curly
braces. Attributes have a name followed by a value. The syntax of the value
depends on the type of the attribute. String attributes are places in double
quotes, numeric attributes may be specified as decimal numbers or hexadecimal
with a leading dollar sign. There are also attributes where the attribute
value is a keyword, in this case the keyword is given as is (without quotes or
anything). Each attribute is terminated by a semicolon.
<tscreen><verb>
group-name { attribute1 attribute-value; attribute2 attribute-value; }
</verb></tscreen>
<sect1>Comments<p>
Comments start with a hash mark (<tt/#/) and extend from the position of
the mark to the end of the current line. Hash marks inside of strings will
of course <em/not/ start a comment.
<sect1>Specifying global options<label id="global-options"><p>
Global options may be specified in a group with the name <tt/GLOBAL/. The
following attributes are recognized:
<descrip>
<tag><tt/ARGUMENTCOLUMN/</tag>
This attribute specifies the column in the output, where the argument for
an opcode or pseudo instruction starts. The corresponding command line
option is
<tt><ref id="option--argument-column" name="--argument-column"></tt>.
<tag><tt/COMMENTCOLUMN/</tag>
This attribute specifies the column in the output, where the comment starts
in a line. It is only used for in-line comments. The corresponding command
line option is
<tt><ref id="option--comment-column" name="--comment-column"></tt>.
<label id="COMMENTS">
<tag><tt/COMMENTS/</tag>
This attribute may be used instead of the <tt><ref id="option--comments"
name="--comments"></tt> option on the command line. It takes a numerical
parameter between 0 and 4. Higher values increase the amount of information
written to the output file in form of comments.
<tag><tt/CPU/</tag>
This attribute may be used instead of the <tt><ref id="option--cpu"
name="--cpu"></tt> option on the command line. For possible values see
there. The value is a string and must be enclosed in quotes.
<tag><tt/HEXOFFS/</tag>
The attribute is followed by a boolean value. If true, offsets to labels are
output in hex, otherwise they're output in decimal notation. The default is
false. The attribute may be changed on the command line using the <tt><ref
id="option--hexoffs" name="--hexoffs"></tt> option.
<tag><tt/INPUTNAME/</tag>
The attribute is followed by a string value, which gives the name of the
input file to read. If it is present, the disassembler does not accept an
input file name on the command line.
<tag><tt/INPUTOFFS/</tag>
The attribute is followed by a numerical value that gives an offset into
the input file which is skipped before reading data. The attribute may be
used to skip headers or unwanted code sections in the input file.
<tag><tt/INPUTSIZE/</tag>
<tt/INPUTSIZE/ is followed by a numerical value that gives the amount of
data to read from the input file. Data beyond <tt/INPUTOFFS + INPUTSIZE/
is ignored.
<label id="LABELBREAK">
<tag><tt/LABELBREAK/</tag>
<tt/LABELBREAK/ is followed by a numerical value that specifies the label
length that will force a newline. To have all labels on their own lines,
you may set this value to zero.
See also the <tt><ref id="option--label-break" name="--label-break"></tt>
command line option. A <tt/LABELBREAK/ statement in the info file will
override any value given on the command line.
<tag><tt/MNEMONICCOLUMN/</tag>
This attribute specifies the column in the output, where the mnemonic or
pseudo instruction is placed. The corresponding command line option is
<tt><ref id="option--mnemonic-column" name="--mnemonic-column"></tt>.
<tag><tt/NEWLINEAFTERJMP/</tag>
This attribute is followed by a boolean value. When true, a newline is
inserted after each <tt/JMP/ instruction. The default is false.
<tag><tt/NEWLINEAFTERRTS/</tag>
This attribute is followed by a boolean value. When true, a newline is
inserted after each <tt/RTS/ instruction. The default is false.
<label id="OUTPUTNAME">
<tag><tt/OUTPUTNAME/</tag>
The attribute is followed by string value, which gives the name of the
output file to write. If it is present, specification of an output file on
the command line using the <tt><ref id="option-o" name="-o"></tt> option is
not allowed.
The default is to use <tt/stdout/ for output, so without this attribute or
the corresponding command line option <tt/<ref id="option-o" name="-o">/
the output will go to the terminal.
<tag><tt/PAGELENGTH/</tag>
This attribute may be used instead of the <tt><ref id="option--pagelength"
name="--pagelength"></tt> option on the command line. It takes a numerical
parameter. Using zero as page length (which is the default) means that no
pages are generated.
<tag><tt/STARTADDR/</tag>
This attribute may be used instead of the <tt><ref id="option--start-addr"
name="--start-addr"></tt> option on the command line. It takes a numerical
parameter. The default for the start address is $10000 minus the size of
the input file (this assumes that the input file is a ROM that contains the
reset and irq vectors).
<tag><tt/TEXTCOLUMN/</tag>
This attribute specifies the column, where the data bytes are output
translated into ASCII text. It is only used if
<tt><ref id="COMMENTS" name="COMMENTS"></tt> is set to at least 4. The
corresponding command line option is
<tt><ref id="option--text-column" name="--text-column"></tt>.
</descrip>
<sect1>Specifying Ranges<p>
The <tt/RANGE/ directive is used to give information about address ranges. The
following attributes are recognized:
<descrip>
<tag><tt>COMMENT</tt></tag>
This attribute is only allowed if a label is also given. It takes a string
as argument. See the description of the <tt><ref id="infofile-label"
name="LABEL"></tt> directive for an explanation.
<tag><tt>END</tt></tag>
This gives the end address of the range. The end address is inclusive, that
means, it is part of the range. Of course, it may not be smaller than the
start address.
<tag><tt>NAME</tt></tag>
This is a convenience attribute. It takes a string argument and will cause
the disassembler to define a label for the start of the range with the
given name. So a separate <tt><ref id="infofile-label" name="LABEL"></tt>
directive is not needed.
<tag><tt>START</tt></tag>
This gives the start address of the range.
<tag><tt>TYPE</tt></tag>
This attribute specifies the type of data within the range. The attribute
value is one of the following keywords:
<descrip>
<tag><tt>ADDRTABLE</tt></tag>
The range consists of data and is disassembled as a table of words
(16 bit values). The difference to the <tt/WORDTABLE/ type is that
a label is defined for each entry in the table.
<tag><tt>BYTETABLE</tt></tag>
The range consists of data and is disassembled as a byte table.
<tag><tt>CODE</tt></tag>
The range consists of code.
<tag><tt>DBYTETABLE</tt></tag>
The range consists of data and is disassembled as a table of dbytes
(double byte values, 16 bit values with the low byte containing the
most significant byte of the 16 bit value).
<tag><tt>DWORDTABLE</tt></tag>
The range consists of data and is disassembled as a table of double
words (32 bit values).
<tag><tt>RTSTABLE</tt></tag>
The range consists of data and is disassembled as a table of words (16 bit
values). The values are interpreted as words that are pushed onto the
stack and jump to it via <tt/RTS/. This means that they contain
<tt/address-1/ of a function, for which a label will get defined by the
disassembler.
<tag><tt>SKIP</tt></tag>
The range is simply ignored when generating the output file. Please note
that this means that reassembling the output file will <em/not/ generate
the original file, not only because the missing piece in between, but also
because the following code will be located on wrong addresses. Output
generated with <tt/SKIP/ ranges will need manual rework.
<tag><tt>TEXTTABLE</tt></tag>
The range consists of readable text.
<tag><tt>WORDTABLE</tt></tag>
The range consists of data and is disassembled as a table of words
(16 bit values).
</descrip>
</descrip>
<sect1>Specifying Labels<label id="infofile-label"><p>
The <tt/LABEL/ directive is used to give names for labels in the disassembled
code. The following attributes are recognized:
<descrip>
<tag><tt>ADDR</tt></tag>
Followed by a numerical value. Specifies the value of the label.
<tag><tt>COMMENT</tt></tag>
Attribute argument is a string. The comment will show up in a separate line
before the label, if the label is within code or data range, or after the
label if it is outside.
Example output:
<tscreen><verb>
foo := $0001 ; Comment for label named "foo"
; Comment for label named "bar"
bar:
</verb></tscreen>
<tag><tt>NAME</tt></tag>
The attribute is followed by a string value which gives the name of the
label. Empty names are allowed, in this case the disassembler will create
an unnamed label (see the assembler docs for more information about unnamed
labels).
<tag><tt>SIZE</tt></tag>
This attribute is optional and may be used to specify the size of the data
that follows. If a size greater than 1 is specified, the disassembler will
create labels in the form <tt/label+offs/ for all bytes within the given
range, where <tt/label/ is the label name given with the <tt/NAME/
attribute, and <tt/offs/ is the offset within the data.
</descrip>
<sect1>Specifying Segments<label id="infofile-segment"><p>
The <tt/SEGMENT/ directive is used to specify a segment within the
disassembled code. The following attributes are recognized:
<descrip>
<tag><tt>START</tt></tag>
Followed by a numerical value. Specifies the start address of the segment.
<tag><tt>END</tt></tag>
Followed by a numerical value. Specifies the end address of the segment. The
end address is last the address that is part of the segment.
<tag><tt>NAME</tt></tag>
The attribute is followed by a string value which gives the name of the
segment.
</descrip>
All attributes are mandatory. Segments may not overlap. Since there is no
explicit "end this segment" pseudo op, the disassembler cannot notify the
assembler that one segment has ended. This may lead to errors if you don't
define your segments carefully. As a rule of thumb, if you're using segments,
your should define segments for all disassembled code.
<sect1>Specifying Assembler Includes<label id="infofile-asminc"><p>
The <tt/ASMINC/ directive is used to give the names of input files containing
symbol assignments in assembler syntax:
<tscreen><verb>
Name = value
Name := value
</verb></tscreen>
The usual conventions apply for symbol names. Values may be specified as hex
(leading &dollar;), binary (leading %) or decimal. The values may optionally
be signed.
NOTE: The include file parser is very simple. Expressions are not allowed, and
anything but symbol assignments is flagged as an error (but see the
<tt/IGNOREUNKNOWN/ directive below).
The following attributes are recognized:
<descrip>
<tag><tt>FILE</tt></tag>
Followed by a string value. Specifies the name of the file to read.
<tag><tt>COMMENTSTART</tt></tag>
The optional attribute is followed by a character constant. It specifies the
character that starts a comment. The default value is a semicolon. This
value is ignored if <tt/IGNOREUNKNOWN/ is true.
<tag><tt>IGNOREUNKNOWN</tt></tag>
This attribute is optional and is followed by a boolean value. It allows to
ignore input lines that don't have a valid syntax. This allows to read in
assembler include files that contain more than just symbol assignments.
Note: When this attribute is used, the disassembler will ignore any errors
in the given include file. This may have undesired side effects.
</descrip>
<sect1>An Info File Example<p>
The following is a short example for an info file that contains most of the
directives explained above:
<tscreen><verb>
# This is a comment. It extends to the end of the line
GLOBAL {
OUTPUTNAME "kernal.s";
INPUTNAME "kernal.bin";
STARTADDR $E000;
PAGELENGTH 0; # No paging
CPU "6502";
};
# One segment for the whole stuff
SEGMENT { START $E000; END $FFFF; NAME kernal; };
RANGE { START $E612; END $E631; TYPE Code; };
RANGE { START $E632; END $E640; TYPE ByteTable; };
RANGE { START $EA51; END $EA84; TYPE RtsTable; };
RANGE { START $EC6C; END $ECAB; TYPE RtsTable; };
RANGE { START $ED08; END $ED11; TYPE AddrTable; };
# Zero page variables
LABEL { NAME "fnadr"; ADDR $90; SIZE 3; };
LABEL { NAME "sal"; ADDR $93; };
LABEL { NAME "sah"; ADDR $94; };
LABEL { NAME "sas"; ADDR $95; };
# Stack
LABEL { NAME "stack"; ADDR $100; SIZE 255; };
# Indirect vectors
LABEL { NAME "cinv"; ADDR $300; SIZE 2; }; # IRQ
LABEL { NAME "cbinv"; ADDR $302; SIZE 2; }; # BRK
LABEL { NAME "nminv"; ADDR $304; SIZE 2; }; # NMI
# Jump table at end of kernal ROM
LABEL { NAME "kscrorg"; ADDR $FFED; };
LABEL { NAME "kplot"; ADDR $FFF0; };
LABEL { NAME "kiobase"; ADDR $FFF3; };
LABEL { NAME "kgbye"; ADDR $FFF6; };
# Hardware vectors
LABEL { NAME "hanmi"; ADDR $FFFA; };
LABEL { NAME "hares"; ADDR $FFFC; };
LABEL { NAME "hairq"; ADDR $FFFE; };
</verb></tscreen>
<sect>Bugs/Feedback<p>
If you have problems using the disassembler, if you find any bugs, or if
you're doing something interesting with the assembler, 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>Copyright<p>
da65 (and all cc65 binutils) are (C) Copyright 1998-2007 Ullrich von
Bassewitz. For usage of the binaries and/or sources the following
conditions do apply:
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>

154
doc/debugging.sgml Normal file
View File

@ -0,0 +1,154 @@
<!doctype linuxdoc system>
<article>
<title>Using emulators with cc65
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
<date>03.12.2000
<abstract>
How to debug your code using the VICE and Oricutron emulators.
</abstract>
<!-- Table of contents -->
<toc>
<!-- Begin the document -->
<sect>Overview<p>
This document describes how to debug your programs using the cc65 development
tools and the VICE CBM emulator.
<sect>What is VICE?<p>
VICE is an emulator for many of the CBM machines. It runs on Unix, MS-DOS,
Win32, OS/2, Acorn RISC OS, BeOS, QNX 6.x, Amiga, GP2X and Mac OS X. It emulates
the Commodore 64, 128, VIC20, PET and the 600/700 machines. For more information
see the VICE home page:
<htmlurl url="http://www.viceteam.org/">
VICE has a builtin machine language monitor that may be used for debugging
your programs. Using an emulator for debugging has some advantages:
<itemize>
<item>Since you're using a crossassembler/-compiler anyway, you don't need to
transfer the program to the real machine until it is done.
<item>An emulator allows many things that are almost impossible one of the
original machines. You may set watchpoints (detect read or write access to
arbitary addresses), debug interrupt handlers and even debug routines that run
inside the 1541 floppy.
<item>You may use the label file generated by the linker to make much more use
from the monitor.
</itemize>
<sect>How to prepare your programs<p>
VICE support is mostly done via a label file that is generated by the linker
and that may be read by the VICE monitor, so it knows about your program.
Source level debugging is <tt/not/ available, you have to debug your programs
in the assembler view.
The first step is to generate object files that contain information about
<em/all/ labels in your sources, not just the exported ones. This can be done
by several means:
<itemize>
<item>Use the -g switch on the assembler command line.
<item>Use the
<tscreen><verb>
.debuginfo +
</verb></tscreen>
command in your source.
<item>Use the <tt/-g/ switch when invoking the compiler. The compiler will
then place a <tt/.debuginfo/ command into the generated assembler source.
</itemize>
So, if you have just C code, all you need is to invoke the compiler with
<tt/-g/. If you're using assembler code, you have to use <tt/-g/ for the
assembler, or add "<tt/.debuginfo on/" to your source files. Since the
generated debug info is not appended to the generated executables, it is a
good idea to always use <tt/-g/. It makes the object files and libraries
slightly larger (&tilde;30%), but this is usually not a problem.
The second step is to tell the linker that it should generate a VICE label
file. This is done by the <tt/-Ln/ switch followed by the name of the label
file (I'm usually using a <tt/.lbl/ extension for these files). An example for
a linker command line would be:
<tscreen><verb>
ld65 -o hello -t c64 -Ln hello.lbl -m hello.map hello.o c64.lib
</verb></tscreen>
or
<tscreen><verb>
ld65 -o hello.tap -t atmos -Ln hello.sym -m hello.map hello.o atmos.lib
</verb></tscreen>
This will generate a file named hello.lbl that contains all symbols used in
your program.
<bf>Note</bf>: The runtime libraries and startup files were generated with
debug info, so you don't have to care about this.
<sect>How to use the label file with VICE<p>
Load your program, then enter the monitor and use the "<tt/ll/" command to
load your label file like this:
<tscreen><verb>
ll "hello.lbl"
</verb></tscreen>
You will get lots of warnings and even a few errors. You may ignore safely all
these warnings and errors as long as they reference any problems VICE thinks
it has with the labels.
After loading the labels, they are used by VICE in the disassembler listing,
and you may use them whereever you need to specify an address. Try
<tscreen><verb>
d ._main
</verb></tscreen>
as an example (note that VICE needs a leading dot before all labels, and that
the compiler prepends an underline under most named labels).
<sect>How to use the label file with Oricutron<p>
Load your program, then enter the monitor and use the "<tt/sl/" command to
load your label file like this:
<tscreen><verb>
sl hello.sym
</verb></tscreen>
After loading the labels, they are used by Oricutron in the disassembler listing,
and you may use them whereever you need to specify an address. Try
<tscreen><verb>
d ._main
</verb></tscreen>
as an example (note that VICE needs a leading dot before all labels, and that
the compiler prepends an underline under most named labels).
</article>

134
doc/dio.sgml Normal file
View File

@ -0,0 +1,134 @@
<!doctype linuxdoc system>
<article>
<title>Diskette Sector I/O Routines
<author>Christian Groessler, <htmlurl url="mailto:chris@groessler.org" name="chris@groessler.org">
<date>20-Feb-2005
<abstract>
The cc65 library provides functions to read and write raw disk sectors.
Include the dio.h header file to get the necessary definitions.
</abstract>
<!-- Table of contents -->
<toc>
<!-- Begin the document -->
<sect>Opening the disk for low level I/O<p>
Prior to using these functions a handle to the device has to be obtained. This
is done with the <tt>dio_open</tt> function. After use, the handle should be
released with the <tt>dio_close</tt> function.
<tscreen><verb>
dhandle_t __fastcall__ dio_open (unsigned char device);
</verb></tscreen>
The <tt>device</tt> specifies the device to access, with 0 being the first
device, 1 the second, and so on.
<tscreen><verb>
unsigned char __fastcall__ dio_close (dhandle_t handle);
</verb></tscreen>
Closes a handle obtained by <tt>dio_open</tt>. Returns status code.
<p>
<sect>Reading and writing sectors<p>
The read and write functions are:
<tscreen><verb>
unsigned char __fastcall__ dio_read (dhandle_t handle,
unsigned sect_num,
void *buffer);
</verb></tscreen>
This function will read the sector specified by <tt>sect_num</tt> into the memory
location at buffer.
<tscreen><verb>
unsigned char __fastcall__ dio_write (dhandle_t handle,
unsigned sect_num,
const void *buffer);
</verb></tscreen>
This function will write the memory contents at buffer to the sector specified
by <tt>sect_num</tt>. No verify is performed.
<tscreen><verb>
unsigned char __fastcall__ dio_write_verify (dhandle_t handle,
unsigned sect_num,
const void *buffer);
</verb></tscreen>
This function will write the memory contents at buffer to the sector specified
by <tt>sect_num</tt>. A verification is performed.
<p>
Use the <tt><ref name="dio_query_sectsize" id="sectsizecount"></tt> function to query
the size of a sector and the <tt><ref name="dio_query_sectcount" id="sectsizecount"></tt>
function to query the number of available sectors.
<p>
All these functions will return 0 for success and an OS specific error code in
case of failure.
<p>
<sect>Querying sector size and count<label id="sectsizecount"><p>
Some systems support multiple diskette formats which have different sector sizes
and/or different sector counts.
<p>
The following function returns the sector size of the currently inserted disk:
<tscreen><verb>
unsigned __fastcall__ dio_query_sectsize (dhandle_t handle);
</verb></tscreen>
On the Atari platform, the sector size is handled specially. Please refer
to the DIO section in the <htmlurl url="atari.html" name="Atari">
specific platform documentation.
<p>
The following function returns the sector count of the currently inserted disk:
<tscreen><verb>
unsigned __fastcall__ dio_query_sectcount (dhandle_t handle);
</verb></tscreen>
<sect>Converting sector numbers<p>
Since the read and write functions expect a sector number, for systems where
the sectors aren't addressed by a logical sector number (e.g. CBM devices),
there are 2 conversion functions. One of them converts a logical sector number
to a head/track/sector triple. The other conversion function works the other
way round.
<tscreen><verb>
unsigned char __fastcall__ dio_phys_to_log (dhandle_t handle,
const dio_phys_pos *physpos,
unsigned *sectnum);
</verb></tscreen>
This function converts track/head/sector to logical sector number.
<tscreen><verb>
unsigned char __fastcall__ dio_log_to_phys (dhandle_t handle,
const unsigned *sectnum,
dio_phys_pos *physpos);
</verb></tscreen>
This function converts a logical sector number to track/head/sector notation.
<p>
Note, that on systems which natively use logical sector numbers (e.g. Atari),
the conversion functions are dummies. They ignore head/track
(<tt>dio_phys_to_log</tt>) or return them as zero (<tt>dio_log_to_phys</tt>).
The logical sector number is returned as physical sector and vice versa.
<p>
</article>

7439
doc/funcref.sgml Normal file
View File

File diff suppressed because it is too large Load Diff

1662
doc/geos.sgml Normal file
View File

File diff suppressed because it is too large Load Diff

392
doc/grc65.sgml Normal file
View File

@ -0,0 +1,392 @@
<!doctype linuxdoc system>
<article>
<!-- Title information -->
<title>grc65 -- GEOS Resource Compiler
<author><url name="Maciej 'YTM/Elysium' Witkowiak" url="mailto:ytm@elysium.pl">
<and><url name="Greg King" url="mailto:gngking@erols.com">
<date>VII 2000; VI,VII 2002; 2005-8-3
<abstract>
This document describes a compiler that can create GEOS headers and menues for
cc65-compiled programs.
</abstract>
<!-- Table of contents -->
<toc>
<!-- Begin the document -->
<sect>Overview
<p><bf/grc65/ is a part of cc65's GEOS support. The tool is necessary to
generate required and optional resources. A required resource for every GEOS
application is the header, that is: an icon, some strings, and some addresses.
Optional resources might be menu definitions, other headers (e.g., for data
files of an app.), dialog definitions, etc. Without an application's header,
GEOS is unable to load and start it.
Currently, <bf/grc65/ supports only menues and the required header definition,
along with support for building applications with VLIR-structured overlays.
<bf/grc65/ generates output in two formats: C header and <bf/ca65/ source (.s).
That is because the application header data must be in assembly format, while
the menu definitions can be translated easily into C. The purpose of the C
file is to include it as a header in only one project file. The assembly source
should be processed by <bf/ca65/ and linked to the application (read about
<ref name="the building process" id="building-seq">).
<sect>Usage
<p>grc65 accepts the following options:
<tscreen><verb>
---------------------------------------------------------------------------
Usage: grc65 [options] file
Short options:
-V Print the version number
-h Help (this text)
-o name Name the C output file
-s name Name the asm output file
-t sys Set the target system
Long options:
--help Help (this text)
--target sys Set the target system
--version Print the version number
---------------------------------------------------------------------------
</verb></tscreen>
Default output names are made from input names with extensions replaced by
<tt/.h/ and <tt/.s/.
<sect>Resource file format
<p>A resource file has the name extension <tt/.grc/. That is not required, but
it will make for an easier recognition of the file's purpose. Also, <bf/cl65/
recognizes those files. <bf/grc65/'s parser is very weak at the moment; so,
read the comments carefully, and write resources exactly as they are written
here. Look out for CAPS and small letters. Everything after a '<tt/;/'
until the end of the line is considered as a comment and ignored. See the
included <ref name="commented example .grc file" id="example-grc"> for a
better view of the situation.
<sect1>Menu definition
<p><tscreen><verb>
MENU menuName leftx,topy <ORIENTATION> {
"item name 1" <MENU_TYPE> pointer
...
"item name x" <MENU_TYPE> pointer
}</verb></tscreen>
The definition starts with the keyword <tt/MENU/, then comes the menu's name,
which will be represented in C as <tt/const void/. Then are the co-ordinates
of the top left corner of the menu box. The position of the bottom right
corner is estimated, based on the length of item names and the menu's
orientation. It means that the menu box always will be as large as it should
be. Then, there's the orientation keyword; it can be either <tt/HORIZONTAL/ or
<tt/VERTICAL/. Between <tt/&lcub;/ and <tt/&rcub;/, there's the menu's
content. It consists of item definitions. First is an item name -- it has to
be in quotes. Next is a menu-type bit. It can be <tt/MENU_ACTION/ or
<tt/SUB_MENU/; either of them can be combined with the <tt/DYN_SUB_MENU/ bit
(see <url name="the GEOSLib documentation" url="geos.html"> for descriptions of
them). You can use C logical operators in expressions, but you have to do it
without spaces. So a dynamically created submenu will be something like:
<tscreen><verb>
"dynamic" SUB_MENU|DYN_SUB_MENU create_dynamic</verb></tscreen>
The last part of the item definition is a pointer which can be any name that is
present in the C source code that includes the generated header. It can point
to a function or to another menu definition.
If you are doing sub(sub)menu definitions, remember to place the lowest level
definition first, and the top-level menu as the last one. That way the C
compiler won't complain about unknown names.
<sect1>Header definition
<p><tscreen><verb>
HEADER <GEOS_TYPE> "dosname" "classname" "version" {
author "Joe Schmoe"
info "This is my killer-app!"
date yy mm dd hh ss
dostype SEQ
mode any
structure SEQ
icon "sprite.raw"
}</verb></tscreen>
The header definition describes the GEOS header sector which is unique to
each file. The definition starts with the keyword <tt/HEADER/, then goes the
GEOS file-type. You can use only <tt/APPLICATION/ here at the moment. Then,
there are (each one in quotes) the DOS file-name (up to 16 characters), the GEOS
Class name (up to 12 characters), and the version info (up to 4 characters).
The version should be written as &dquot;<tt/V/x.y&dquot;, where <em/x/ is the
major, and <em/y/ is the minor, version number. Those fields, along with both
braces, are required. The lines between braces are optional, and will be replaced
by default and current values. The keyword <tt/author/ and its value in quotes name
the programmer, and can be up to 63 bytes long. <tt/info/ (in the same format) can
have up to 95 characters. If the <tt/date/ field is omitted, then the time of
that compilation will be placed into the header. Note that, if you do specify
the date, you have to write all 5 numbers. The <tt/dostype/ can be <tt/SEQ/,
<tt/PRG/, or <tt/USR/. <tt/USR/ is used by default; GEOS usually doesn't care.
The <tt/mode/ can be <tt/any/, <tt/40only/, <tt/80only/, or <tt/c64only/; and,
it describes system requirements. <tt/any/ will work on both 64-GEOS and
128-GEOS, in 40- and 80-column modes. <tt/40only/ will work on 128-GEOS in
40-column mode only. <tt/80only/ will work on only 128-GEOS in 80-column mode,
and <tt/c64only/ will work on only 64-GEOS. The default value for
<tt/structure/ is <tt/SEQ/ (sequential). You can put <tt/VLIR/ there, too; but
then, you also have to put in a third type of resource -- a memory definition.
The value of <tt/icon/ is a quoted file-name. The first 63 bytes of this file
are expected to represent a standard monochrome VIC sprite. The file gets accessed
when the generated assembly source is being processed by <bf/ca65/. Examples for
programs generating such files are <em/Sprite Painter/, <em/SpritePad/ and the
<url name="sp65 sprite and bitmap utility" url="sp65.html">. The default <tt/icon/
is an empty frame internally represented in the generated assembly file.
<sect1>Memory definition
<p><tscreen><verb>
MEMORY {
stacksize 0x0800
overlaysize 0x2000
overlaynums 0 1 2 4 5
}</verb></tscreen>
The memory definition is unique to each file and describes several attributes related
to the memory layout. It consists of the keyword <tt/MEMORY/ followed by braces which
contain optional lines. The value of <tt/stacksize/ can be either decimal (e.g.
<tt/4096/) or hexadecimal with a <tt/0x/ prefix (e.g. <tt/0x1000/). The default value
of 0x400 comes from the linker configuration file. The value of <tt/backbuffer/ can be
either <tt/yes/ or <tt/no/. The further means that the application uses the system-supplied
background screen buffer while the latter means that the program uses the memory of the
background screen buffer for own purposes. The default value of <tt/yes/ comes from the
linker configuration file. If the <tt/structure/ in the header definition is set to the
value <tt/VLIR/ then it is possible and necessary to provide here the attributes of the
VLIR overlays. <tt/overlaysize/ defines the maximal size for all VLIR records but number
0. It can be either decimal (e.g. <tt/4096/) or hexadecimal with a <tt/0x/ prefix (e.g.
<tt/0x1000/). <tt/overlaynums/ defines the VLIR record numbers used by the application.
Skipped numbers denote empty records. In the example, record number 3 is missing. Read
<ref name="this description" id="building-vlir"> for details.
<sect>Building a GEOS sequential application<label id="building-seq">
<p>Before proceeding, please read the <url name="compiler" url="cc65.html">,
<url name="assembler" url="ca65.html">, and <url name="linker" url="ld65.html">
documentation, and find the appropriate sections about building programs, in
general.
GEOS support in cc65 is based on the <em/Convert v2.5/ format, well-known in
the GEOS world. It means that each file built with the cc65 package has to be
deconverted in GEOS, before it can be run. You can read a step-by-step
description of that in the <url name="GEOS section of the cc65 Compiler Intro"
url="intro-6.html#ss6.5">.
Each project consists of four parts, two are provided by cc65. Those parts
are:<enum>
<item>application header
<item>start-up object
<item>application objects
<item>system library
</enum>
<bf/2./ and <bf/4./ come with cc65; however you have to write the application
yourself ;-)
The application header is defined in the <tt/HEADER/ section of the <tt/.grc/
file and is processed into an assembly <tt/.s/ file. You must assemble it, with
<bf/ca65/, into the object <tt/.o/ format.
Assume that there are three input files: &dquot;<tt/test.c/&dquot; (a C
source), &dquot;<tt/test.h/&dquot; (a header file), and
&dquot;<tt/testres.grc/&dquot; (with menu and header definitions). Note the
fact that I <em/don't recommend/ naming that file &dquot;<tt/test.grc/&dquot;
because you will have to be very careful with names (<bf/grc65/ will make
&dquot;<tt/test.s/&dquot; and &dquot;<tt/test.h/&dquot; out of
&dquot;<tt/test.grc/&dquot; by default; and you don't want that because
&dquot;<tt/test.s/&dquot; is compiled from &dquot;<tt/test.c/&dquot;, and
&dquot;<tt/test.h/&dquot; is something completely different)!
<bf/One important thing/ -- the top of &dquot;<tt/test.c/&dquot; looks like:
<tscreen><verb>
#include <geos.h>
#include "testres.h"
</verb></tscreen>
There are no other includes.
<sect1>Building the GEOS application using cl65
<p>This is a simple one step process:
<tscreen><verb>
cl65 -t geos-cbm -O -o test.cvt testres.grc test.c
</verb></tscreen>
Always place the <tt/.grc/ file as first input file on the command-line in order
to make sure that the generated <tt/.h/ file is available when it is needed for
inclusion by a <tt/.c/ file.
<sect1>Building the GEOS application without cl65
<sect2>First step -- compiling the resources
<p>
<tscreen><verb>
grc65 -t geos-cbm testres.grc
</verb></tscreen>
will produce two output files: &dquot;<tt/testres.h/&dquot; and
&dquot;<tt/testres.s/&dquot;.
Note that &dquot;<tt/testres.h/&dquot; is included at the top of
&dquot;<tt/test.c/&dquot;. So, resource compiling <em/must be/ the first step.
<sect2>Second step -- assembling the application header
<p>
<tscreen><verb>
ca65 -t geos-cbm testres.s
</verb></tscreen>
And, voil&aacute; -- &dquot;<tt/testres.o/&dquot; is ready.
<sect2>Third step -- compiling the code
<p>
<tscreen><verb>
cc65 -t geos-cbm -O test.c
ca65 -t geos-cbm test.s
</verb></tscreen>
That way, you have a &dquot;<tt/test.o/&dquot; object file which
contains all of the executable code.
<sect2>Fourth and last step -- linking the application
<p>
<tscreen><verb>
ld65 -t geos-cbm -o test.cvt testres.o test.o geos-cbm.lib
</verb></tscreen>
The last file is the GEOS system library.
The resulting file &dquot;<tt/test.cvt/&dquot; is an executable that's
contained in the well-known GEOS <em/Convert/ format. Note that its name
(<tt/test.cvt/) isn't important; the real name, after deconverting, is the DOS name
that was given in the header definition.
At each step, a <tt/-t geos-cbm/ was present on the command-line. That switch is
required for the correct process of GEOS sequential application building.
<sect>Building a GEOS VLIR overlay application<label id="building-vlir">
<p>Large GEOS applications typically don't fit in one piece in their designated
memory area. They are therefore split into overlays which are loaded into memory
on demand. The individual overlays are stored as records of a VLIR (Variable
Length Index Record) file. When GEOS starts a VLIR overlay appliation it loads
record number 0 which is supposed to contain the main program. The record numbers
starting with 1 are to be used for the actual overlays.
In "<tt>cc65/samples/geos</tt>" there's a VLIR overlay demo application consisting
of the files "<tt/overlay-demo.c/" and "<tt/overlay-demores.grc/".
<sect1>Building the GEOS overlay application using cl65
<p>This is a simple one step process:
<tscreen><verb>
cl65 -t geos-cbm -O -o overlay-demo.cvt -m overlay-demo.map overlay-demores.grc overlay-demo.c
</verb></tscreen>
Always place the <tt/.grc/ file as first input file on the command-line in order
to make sure that the generated <tt/.h/ file is available when it is needed for
inclusion by a <tt/.c/ file.
You will almost certainly want to generate a map file that shows (beside a lot of
other infos) how large your individual overlays are. This info is necessary to tune
the distribution of code into the overlays and to optimize the memory area reserved
for the overlays.
<sect1>Building the GEOS overlay application without cl65
<sect2>First step -- compiling the overlay resources
<p>
<tscreen><verb>
grc65 -t geos-cbm overlay-demores.grc
</verb></tscreen>
<sect2>Second step -- assembling the overlay application header
<p>
<tscreen><verb>
ca65 -t geos-cbm overlay-demores.s
</verb></tscreen>
<sect2>Third step -- compiling the overlay code
<p>
<tscreen><verb>
cc65 -t geos-cbm -O overlay-demo.c
ca65 -t geos-cbm overlay-demo.s
</verb></tscreen>
<sect2>Fourth and last step -- linking the overlay application
<p>
<tscreen><verb>
ld65 -t geos-cbm -o overlay-demo.cvt -m overlay-demo.map overlay-demores.o overlay-demo.o geos-cbm.lib
</verb></tscreen>
<sect>Bugs and feedback
<p>This is the first release of <bf/grc65/, and it contains bugs, for sure! I
am aware of them; I know that the parser is weak, and if you don't follow the
grammar rules strictly, then everything will crash. However, if you find an
interesting bug, mail me. :-) Mail me also for help with writing your
<tt/.grc/ file correctly if you have problems with it. I would appreciate
comments also, and help on this file because I am sure that it can be written
better.
<sect>Legal stuff
<p><bf/grc65/ is covered by the same license as the whole cc65 package, so you
should see its documentation for more info. Anyway, if you like it, and want
to encourage me to work more on it, send me a postcard with a sight of your
neighbourhood, city, region, etc. Or, just e-mail me with info that you
actually used it. See <url name="the GEOSLib documentation" url="geos.html">
for addresses.
<appendix>
<sect>Appendix A -- example.grc<label id="example-grc">
<p><tscreen><verb>
; Note that MENU can define both menues and submenues.
; If you want to use any C operators (such as "|", "&", etc.), do it WITHOUT
; any spaces between the arguments (the parser is simple and weak).
MENU subMenu1 15,0 VERTICAL
; This is a vertical menu, placed at (15,0).
{
; There are three items, all of them will call functions.
; The first and third ones are normal functions, see GEOSLib documentation for
; information about what the second function should return (it's a dynamic one).
"subitem1" MENU_ACTION smenu1
"subitem2" MENU_ACTION|DYN_SUB_MENU smenu2
"subitem3" MENU_ACTION smenu3
}
;; Format: MENU "name" left,top ALIGN { "itemname" TYPE pointer ... }
MENU mainMenu 0,0 HORIZONTAL
; Here, we have our main menu, placed at (0,0), and it is a horizontal menu.
; Because it is a top-level menu, you would register it in your C source by
; using: DoMenu(&ero;mainMenu);
{
; There are two items -- a submenu and an action.
; This calls a submenu named subMenu1 (see previous definition).
"first sub-menu" SUB_MENU subMenu1
; This will work the same as an EnterDeskTop() call in C source code.
"quit" MENU_ACTION EnterDeskTop
}
;; Format: HEADER <GEOS_TYPE> "dosname" "classname" "version"
HEADER APPLICATION "MyFirstApp" "Class Name" "V1.0"
; This is a header for an APPLICATION which will be seen in the directory as a
; file named MyFirstApp with the Class-string "Class Name V1.0"
{
; Not all fields are required, default and current values will be used.
author "Maciej Witkowiak" ; always in quotes!
info "Information text" ; always in quotes!
; date yy mm dd hh ss ; always 5 fields!
; dostype seq ; can be: PRG, SEQ, USR (only all UPPER- or lower-case)
; structure seq ; can be: SEQ, VLIR (only UPPER- or lower-case)
mode c64only ; can be: any, 40only, 80only, c64only
}</verb></tscreen>
</article>

179
doc/index.sgml Normal file
View File

@ -0,0 +1,179 @@
<!doctype linuxdoc system>
<article>
<title>cc65 Documentation Overview
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
<date>2005-8-6
<abstract>
Main documentation page, contains links to other available stuff.
</abstract>
<sect>Program documentation<p>
<descrip>
<tag><htmlurl url="ar65.html" name="ar65.html"></tag>
Describes the ar65 archiver.
<tag><htmlurl url="ca65.html" name="ca65.html"></tag>
Describes the ca65 macro assembler.
<tag><htmlurl url="ca65html.html" name="ca65html.html"></tag>
Describes the ca65html assembler-source-to-HTML converter.
<tag><htmlurl url="cc65.html" name="cc65.html"></tag>
Describes the cc65 C compiler.
<tag><htmlurl url="cl65.html" name="cl65.html"></tag>
Describes the cl65 compile &amp; link utility.
<tag><htmlurl url="co65.html" name="co65.html"></tag>
Describes the co65 object-file converter.
<tag><htmlurl url="da65.html" name="da65.html"></tag>
Describes the da65 6502/65C02 disassembler.
<tag><htmlurl url="grc65.html" name="grc65.html"></tag>
Describes the GEOS resource compiler (grc65).
<tag><htmlurl url="ld65.html" name="ld65.html"></tag>
Describes the ld65 linker.
<tag><htmlurl url="od65.html" name="od65.html"></tag>
Describes the od65 object-file analyzer.
<tag><htmlurl url="sp65.html" name="sp65.html"></tag>
Describes the sprite and bitmap utility.
</descrip>
<sect>Usage<p>
<descrip>
<tag><htmlurl url="intro.html" name="intro.html"></tag>
Describes the use of the tools, by building a short &dquot;hello world&dquot;
example.
<tag><htmlurl url="coding.html" name="coding.html"></tag>
Contains hints on creating the most effective code with cc65.
<tag><htmlurl url="compile.txt" name="compile.txt"></tag>
How to compile cc65 and the support tools.
<tag><htmlurl url="using-make.html" name="using-make.html"></tag>
Build programs, using the GNU Make utility.
<tag><htmlurl url="customizing.html" name="customizing.html"></tag>
How to use the cc65 toolset for a custom hardware platform (a target system
not currently supported by the cc65 library set).
<tag><htmlurl url="debugging.html" name="debugging.html"></tag>
Debug programs, using the VICE emulator.
</descrip>
<sect>Library information and other references<p>
<descrip>
<tag><htmlurl url="funcref.html" name="funcref.html"></tag>
A (currently incomplete) function reference.
<tag><htmlurl url="dio.html" name="dio.html"></tag>
Low-level disk I/O API.
<tag><htmlurl url="geos.html" name="geos.html"></tag>
The GEOSLib manual.
<tag><htmlurl url="internal.txt" name="internal.txt"></tag>
A somewhat older text describing several cc65 internals.
<tag><htmlurl url="library.html" name="library.html"></tag>
An overview over the cc65 runtime and C libraries.
<tag><htmlurl url="smc.html" name="smc.html"></tag>
Describes Christian Kr&uuml;gers macro package for writing self modifying
assembler code.
<tag><url name="6502 Binary Relocation Format document"
url="http://www.6502.org/users/andre/o65/fileformat.html"></tag>
Describes the o65 file format that is used for dynamically loadable modules
and LUnix programs.
</descrip>
<sect>Platform-specific information<p>
<descrip>
<tag><htmlurl url="apple2.html" name="apple2.html"></tag>
Topics specific to the Apple&nbsp;&rsqb;&lsqb;.
<tag><htmlurl url="apple2enh.html" name="apple2enh.html"></tag>
Topics specific to the enhanced&nbsp;Apple&nbsp;//e.
<tag><htmlurl url="atari.html" name="atari.html"></tag>
Topics specific to the Atari 8-bit machines.
<tag><htmlurl url="atmos.html" name="atmos.html"></tag>
Topics specific to the Oric Atmos.
<tag><htmlurl url="c128.html" name="c128.html"></tag>
Topics specific to the Commodore 128.
<tag><htmlurl url="c16.html" name="c16.html"></tag>
Topics specific to the Commodore 16/116.
<tag><htmlurl url="c64.html" name="c64.html"></tag>
Topics specific to the Commodore 64.
<tag><htmlurl url="cbm510.html" name="cbm510.html"></tag>
Topics specific to the Commodore 510.
<tag><htmlurl url="cbm610.html" name="cbm610.html"></tag>
Topics specific to the Commodore 610.
<tag><htmlurl url="lynx.html" name="lynx.html"></tag>
Topics specific to the Atari Lynx Game Console.
<tag><htmlurl url="nes.html" name="nes.html"></tag>
Topics specific to the Nintendo Entertainment System.
<tag><htmlurl url="pet.html" name="pet.html"></tag>
Topics specific to the Commodore PET machines.
<tag><htmlurl url="plus4.html" name="plus4.html"></tag>
Topics specific to the Commodore Plus/4.
<tag><htmlurl url="supervision.html" name="supervision.html"></tag>
Topics specific to the Supervision Console.
<tag><htmlurl url="vic20.html" name="vic20.html"></tag>
Topics specific to the Commodore VIC20.
</descrip>
<sect>Miscellaneous<p>
<descrip>
<tag><htmlurl url="newvers.txt" name="newvers.txt"></tag>
Somewhat outdated. Lists the differences between my cc65 releases
and the original Atari version that was created by J. R. Dunning.
<tag><htmlurl url="BUGS" name="BUGS"></tag>
Known cc65 bugs.
<tag><htmlurl url="CREDITS" name="CREDITS"></tag>
Here is who helped with the compiler and other tools.
</descrip>
</article>

207
doc/internal.txt Normal file
View File

@ -0,0 +1,207 @@
Internals doc for CC65
Stacks:
-------
The program stack used by programs compiled with CC65 is located in high
memory. The stack starts there and grows down. Arguments to functions, local
data etc are allocated on this stack, and deallocated when functions exit.
The program code and data is located in low memory. The heap is located
between the program code and the stack. The default size for the parameter
stack is 2K, you may change this for most platforms in the linker
configuration.
Note: The size of the stack is only needed if you use the heap, or if you
call the stack checking routine (_stkcheck) from somewhere in your program.
When calling other functions, the return address goes on the normal 6502
stack, *not* on the parameter stack.
Registers:
----------
Since CC65 is a member of the Small-C family of compilers, it uses the notion
of a 'primary register'. In the CC65 implementation, I used the AX register
pair as the primary register. Just about everything interesting that the
library code does is done by somehow getting a value into AX, and then calling
some routine or other. In places where Small-C would use a secondary
register, top-of-stack is used, so for instance two argument function like
integer-multiply work by loading AX, pushing it on the stack, loading the
second value, and calling the internal function. The stack is popped, and the
result comes back in AX.
Calling sequences:
------------------
C functions are called by pushing their args on the stack, and JSR'ing to the
entry point. (See ex 1, below) If the function returns a value, it comes back
in AX. NOTE!!! A potentially significant difference between the CC65
environment and other C environments is that the CALLEE pops arguments, not
the CALLER. (This is done so as to generate more compact code) In normal use,
this doesn't cause any problems, as the normal function entry/exit conventions
take care of popping the right number of things off the stack, but you may
have to worry about it when doing things like writing hand-coded assembly
language routines that take variable numbers of arguments. More about that
later.
Ex 1: Function call: Assuming 'i' declared int and 'c' declared
char, the following C code
i = baz(i, c);
in absence of a prototype generates this assembler code. I've added
the comments.
lda _i ; get 'i', low byte
ldx _i+1 ; get 'i', hi byte
jsr pushax ; push it
lda _c ; get 'c'
ldx #0 ; fill hi byte with 0
jsr pushax ; push it
ldy #4 ; arg size
jsr _baz ; call the function
sta _i ; store the result
stx _i+1
In presence of a prototype, the picture changes slightly, since the
compiler is able to do some optimizations:
lda _i ; get 'i', low byte
ldx _i+1 ; get 'i', hi byte
jsr pushax ; push it
lda _c ; get 'c'
jsr pusha ; push it
jsr _baz ; call the function
sta _i ; store the result
stx _i+1
Note that the two words of arguments to baz were popped before it exitted.
The way baz could tell how much to pop was by the argument count in Y at call
time. Thus, even if baz had been called with 3 args instead of the 2 it was
expecting, that would not cause stack corruption.
There's another tricky part about all this, though. Note that the args to baz
are pushed in FORWARD order, ie the order they appear in the C statement.
That means that if you call a function with a different number of args than it
was expecting, they wont end up in the right places, ie if you call baz, as
above, with 3 args, it'll operate on the LAST two, not the first two.
Symbols:
--------
CC65 does the usual trick of prepending an underbar ('_') to symbol names when
compiling them into assembler. Therefore if you have a C function named
'bar', CC65 will define and refer to it as '_bar'.
Systems:
--------
Supported systems at this time are: C64, C128, Plus/4, CBM 500, CBM 600/700,
the newer PET machines (not 2001), Atari 8bit, and the Apple ][ (thanks to
Kevin Ruland, who did the port).
C16: Works with unexpanded or memory expanded C16 and C116 machines.
However, a maximum of 32KB from the total memory is used. The Plus/4
target supports up to 64K of memory, but has a small code overhead
because of the banking routines involved. Apart from this additional
overhead, the Plus/4 target and the C16 target are the same. 16K
machines (unexpanded C16) have 12K of memory for C programs available,
machines with 32K or more have 28K available. The actual amount of
memory is auto detected.
C64: The program runs in a memory configuration, where only the kernal ROM
is enabled. The text screen is expected at the usual place ($400), so
50K of memory are available to the program.
C128: The startup code will reprogram the MMU, so that only the kernal ROM
is enabled. This means, there are 41K of memory available to the
program.
Plus/4: Works with bank switching so 59K of memory are available to the
program.
CBM 500:
The C program runs in bank #0 and has a total of 48K memory available.
This is less than what is available on its bigger brothers (CBM
600/700) because the character data and video RAM is placed in the
execution bank (#0) to allow the use of sprites.
CBM 600/700:
The C program runs in a separate segment and has almost full 64K of
memory available.
PET: The startup code will adjust the upper memory limit to the installed
memory. However, only linear memory is used, this limits the top to
$8000, so on a 8032 or similar machine, 31K of memory are available to
the program.
Apple ][:
The program starts at $803, end of RAM is $95FF, so 35.5K of memory
(including stack) are available to the program.
Atari: The startup code will adjust the upper memory limit to the installed
memory detected at runtime. The programmer can adjust the upper memory
limit by setting the __RESERVED_MEMORY__ variable at link time. The
given __RESERVED_MEMORY__ value will be subtracted from the upper
memory limit used by the runtine. This memory could be used as graphics
memory, for example.
In the default case (no setting of __RESERVED_MEMORY__) the upper
memory limit is $9C1F (with Basic cartridge) and $BC1F (without
cartridge). The program starts at $2E00 by default.
These values are for a 48K or 64K machine.
Note: The above numbers do not mean that the remaining memory is unusable.
However, it is not linear memory and must be accessed by other, nonportable
methods. I'm thinking about a library extension that allows access to the
additional memory as a far heap, but these routines do not exist until now.
Inline Assembly:
----------------
CC65 allows inline assembly by a special keyword named "asm". Inline assembly
looks like a function call. The string in parenthesis is output in the
assembler file.
Example, insert a break instruction into the code:
asm ("brk")
Beware: Be careful when inserting inline code since this may collide with
the work of the optimizer.
Pseudo variables:
-----------------
There are two special variables available named __AX__ and __EAX__. These
variables must never be declared (this gives an error), but may be used as any
other variable. However, accessing these variables will access the primary
register that is used by the compiler to evaluate expressions, return
functions results and pass parameters.
This feature is useful with inline assembly and macros. For example, a macro
that reads a CRTC register may be written like this:
#define wr(idx) (__AX__=(idx), \
asm ("sta $2000"), \
asm ("lda $2000"), \
asm ("ldx #$00"), \
__AX__)

527
doc/intro.sgml Normal file
View File

@ -0,0 +1,527 @@
<!doctype linuxdoc system>
<article>
<title>cc65 Compiler Intro
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">,
<and>CbmNut, <htmlurl url="mailto:cbmnut@hushmail.com" name="cbmnut@hushmail.com">,
<and><url name="Greg King" url="mailto:gngking@erols.com">
<date>2005-7-22
<abstract>
How to use the cc65 C language system -- an introduction.
</abstract>
<!-- Table of contents -->
<toc>
<!-- Begin the document -->
<sect>Overview<p>
This is a short intro of how to use the compiler and the bin-utils. It contains
a step-by-step example of how to build a complete application from one C and
one assembly modules. This file does <em/not/ contain a complete reference for
the tools used in the process. There are separate files describing those tools,
in detail (see <url url="index.html">).
I do assume that you have downloaded and installed the compiler and
target-specific files. Windows users should use the friendly .exe installer
(named cc65-2.13.0-1.exe for version 2.13.0 of the package - adjust the
version number if necessary). It does not only install the target files, but
will also set up necessary environment variables for you.
If you're going for the .ZIP archives, please note that there is one file for
the host platform (Windows, DOS or OS/2), one file for each target platform
(C64 or whatever) and a separate file containing the docs (which include the
file you're currently reading). So for most uses, you will need at least 3
files and unpack all three into one directory. In case of the .ZIP archives,
you will also need to set the environment variables <tt/CC65_INC/,
<tt/LD65_LIB/ and <tt/LD65_CFG/ as described below.
<bf/Note/: There is a much simpler way to compile this example, by using the
<bf/cl65/ compile-and-link utility. However, it makes sense to understand how
the separate steps work. How to do the example with the <bf/cl65/ utility is
described <ref id="using-cl65" name="later">.
<sect1>Before we start<p>
You will find a copy of the sample modules, used in the next section, in the
"<tt>cc65/samples/tutorial</tt>" directory. If you encounter problems with
missing include files and/or libraries, please check the environment variables
<tt/CC65_INC/, <tt/LD65_LIB/ and <tt/LD65_CFG/. They should point to the
<tt/include/, <tt/lib/ and <tt/cfg/ subdirectories of the directory, where you
installed cc65.
<sect1>The sample modules<p>
To explain the development flow, I will use the following example modules:
hello.c:
<tscreen><code>
#include <stdio.h>
#include <stdlib.h>
extern const char text[]; /* In text.s */
int main (void)
{
printf ("%s\n", text);
return EXIT_SUCCESS;
}
</code></tscreen>
text.s:
<tscreen><code>
.export _text
_text: .asciiz "Hello world!"
</code></tscreen>
<sect1>Translation phases<p>
We assume that the target file should be named "hello", and the target system
is the C64.
<tscreen><verb>
+---------+
| hello.c |
+---------+
|
cc65
\/
+---------+ +---------+ +---------+
| hello.s | | text.s | | crt0.o |
+---------+ +---------+ +---------+
| | |
ca65 ca65 ar65
\/ \/ \/
+---------+ +---------+ +---------+
| hello.o | | text.o | | c64.lib |
+---------+ +---------+ +---------+
| \ /
| \ /
| \ /
+----------------------->ld65<
\/
hello
</verb></tscreen>
<tt/crt0.o/ (the startup code) and <tt/c64.lib/ (the C64 version of the runtime
and C library) are provided in binary form in the cc65 package. Actually, the
startup code is contained in the library, so you won't need to care about it.
<sect>The compiler<p>
The compiler translates one C source into one assembly source, for each
invocation. It does <em/not/ create object files directly, and it is <em/not/
able to translate more than one file per run.
In the example above, we would use the following command line, to translate
<tt/hello.c/ into <tt/hello.s/:
<tscreen><verb>
cc65 -O -t c64 hello.c
</verb></tscreen>
The <tt/-O/ switch tells the compiler to do an additional optimizer run, which
is usually a good idea, since it makes the code smaller. If you don't care
about the size, but want to have slightly faster code, use <tt/-Oi/ to inline
some runtime functions.
The <tt/-t/ switch is followed by the target system name.
If the compiler does not complain about errors in our "hello world" program, we
will have a file named "<tt/hello.s/", in our directory, that contains the
assembly source for the <bf/hello/ module.
For more information about the compiler, see <url url="cc65.html">.
<sect>The assembler<p>
The assembler translates one assembly source into an object file, for each
invocation. The assembler is <em/not/ able to translate more than one source
file per run.
Let's translate the "hello.s" and "text.s" files from our example:
<tscreen><verb>
ca65 hello.s
ca65 -t c64 text.s
</verb></tscreen>
The <tt/-t/ switch is needed when translating the <tt/text.s/ file, so the
text is converted from the input character-set (usually ISO-8859-1) into the
target character-set (PETSCII, in this example) by the assembler. The
compiler-generated file <tt/hello.s/ does not contain any character constants,
so specification of a target is not necessary (it wouldn't do any harm,
however).
If the assembler does not complain, we should now have two object files (named
<tt/hello.o/ and <tt/text.o/) in the current directory.
For more information about the assembler, see <url url="ca65.html">.
<sect>The linker<p>
The linker combines several object and library files into one output file.
<bf/ld65/ is very configurable, but fortunately has built-in configurations,
so we don't need to mess with configuration files, here.
The compiler uses small functions to do things that cannot be done inline
without a big impact on code size. Those runtime functions, together with the
C library, are in an object-file archive named after the system, in this case,
"<tt/c64.lib/". We have to specify that file on the command line, so that the
linker can resolve those functions.
Let's link our files to get the final executable:
<tscreen><verb>
ld65 -o hello -t c64 hello.o text.o c64.lib
</verb></tscreen>
The argument after <tt/-o/ specifies the name of the output file, the argument
after <tt/-t/ gives the target system. The following arguments are object
files or libraries. Since the target library resolves imports in <tt/hello.o/
and <tt/text.o/, it must be specified <em/after/ those files.
After a successful linker run, we have a file named "<tt/hello/", ready for
our C64!
For more information about the linker, see <url url="ld65.html">.
<sect>The easy way (using the cl65 utility)<label id="using-cl65"><p>
The <bf/cl65/ utility is able to do all of the steps described above, in just
one command line, and it has defaults for some options that are very
well-suited for our example.
To compile both files into one executable, enter:
<tscreen><verb>
cl65 -O hello.c text.s
</verb></tscreen>
The <bf/cl65/ utility knows how to translate C files into object files (it will
call the compiler, and then the assembler). It does know also how to create
object files from assembly files (it will call only the assembler, for that).
It knows how to build an executable (it will pass all object files to the
linker). And finally, it has the C64 as a default target, and will supply the
correct startup file and runtime library names to the linker, so you don't
have to care about that.
The one-liner above should give you a C64 executable named "<tt/hello/" in the
current directory.
For more information about the compile &amp; link utility, see <url
url="cl65.html">.
<sect>Running The Executable<p>
<em/Note: this section is incomplete!/
Depending on the target, cc65 chooses several methods of making a program
available for execution. Here, we list sample emulators and instructions for
running the program. Unless noted, similar instructions would also apply to a
real machine. One word of advice: we suggest you clear the screen at the
start, and wait for a keypress at the end of your program, as each target
varies in its start and exit conditions.
<sect1>Apple
<sect2>AppleWin<p>
Available at <url
url="http://applewin.berlios.de/">:
Emulates Apple&nbsp;&rsqb;&lsqb;/enhanced&nbsp;Apple&nbsp;//e computers, with
sound, video, joysticks, serial port, and disk images. Includes monitor. Only
for Windows. The package comes with a DOS 3.3 disk (called "master.dsk") image;
however, you will need <bf/AppleCommander 1.3.5/ or later (available at <url
url="http://applecommander.sourceforge.net/">).
Compile the tutorial with
<tscreen><verb>
cl65 -O -t apple2 hello.c text.s
</verb></tscreen>
for the Apple&nbsp;&rsqb;&lsqb;, or:
<tscreen><verb>
cl65 -O -t apple2enh hello.c text.s
</verb></tscreen>
for the enhanced&nbsp;Apple&nbsp;//e.
Then, put the file onto an Apple disk image, for use with an emulator. Copy
the <tt/master.dsk/ which comes with <bf/AppleWin/, and rename it to
<tt/cc65.dsk/, then use <bf/AppleCommander/:
<tscreen><verb>
java -jar ac.jar -cc65 cc65.dsk test B < hello
</verb></tscreen>
Note that a convention in the Apple world is that "hello" is the file which is
run automatically upon booting a DOS disk, sort of like the "autoexec.bat" of
the MSDOS/Windows world. We've avoided that in the example, however. Also,
the <tt/B/ parameter must be in caps., and "test" is the name of the program as
it will appear on the Apple disk.
Start the emulator, click on the <bf/Disk 1/ icon, and point to <bf/cc65.dsk/;
then, click the big Apple logo, to boot the system. Then, type this on the
Apple:
<tscreen><verb>
BRUN TEST
</verb></tscreen>
You will see the "Hello, World!" appear on the same line. Thanks to Oliver
Schmidt, <htmlurl url="mailto:ol.sc@web.de" name="ol.sc@web.de"> for his help
in completing this section.
<sect1>Atari
<sect2>Atari800Win PLus<p>
Available at <url
url="http://www.atari.org.pl/PLus/index_us.htm">:
Emulates Atari 400/800/65XE/130XE/800XL/1200XL/5200, with stereo sound, disk
images, scanline-exact NTSC/PAL video, joysticks, mouse, cartridges, and RAM
expansions. Includes monitor. Unfortunately, only for Windows. You will need
the emulator, "atarixl.rom" or "atariosb.rom"/"ataribas.rom", and "dos25.xfd"
files (not supplied).
Compile the tutorial with
<tscreen><verb>
cl65 -O -t atari hello.c text.s
</verb></tscreen>
Start the emulator, choose <bf/File&gt;Autoboot image/ or <bf/File&gt;Load
executable/, and point to the "<bf/hello/" executable. It is customary to
rename executables of that type to "<bf/hello.xex/". The file has a 7-byte
header meant to be loaded directly from Atari DOS 2/2.5 or compatibles.
On a real Atari, you would need a disk drive, and Atari DOS 2.5 or compatible.
Turn on the computer, type
<tscreen><verb>
DOS
</verb></tscreen>
at the BASIC prompt, then choose <bf/N. CREATE MEM.SAV/,
then choose <bf/L. BINARY LOAD/, and enter <tt/HELLO/.
The emulation, also, supports that method. Look at <bf/Atari&gt;Settings/, and
check <bf/Enable H: Patch for Hard Disk Devices/, then <bf/Atari&gt;Hard
disks/, and set the path of <bf/H1:/ to your executables directory, then use
"<bf/H0:HELLO.XEX/" in the above procedure (after pressing <tt/L/), to access
your harddrive directly.
<bf/Note/: There is no delay after the program exits, as you are returned
to the DOS menu. Your C program should wait for a keypress if you want to see
any output.
<sect1>Atmos
<sect2>Oricutron<p>
Available at <url
url="http://code.google.com/p/oriculator/">:
Emulates Oric-1 and Atmos computers, with sound, disk images,
scanline-exact NTSC/PAL video, and movie export. Includes monitor.
Fortunately for all SDL platforms. You will just need the emulator, all
ROMs are supplied.
Compile the tutorial with
<tscreen><verb>
cl65 -O -t atmos hello.c text.s -o hello.tap
</verb></tscreen>
Start the emulator, choose <bf/F1/ and <bf/Insert tape.../, and point to
the "<bf/hello.tap/" executable. The file has an auto start header meant to
be loaded directly from tape.
On a real Atmos, you would need a tape drive.
Turn on the computer, type
<tscreen><verb>
CLOAD""
</verb></tscreen>
at the BASIC prompt.
The emulation, also, supports that method.
<sect1>Commodore
<sect2>VICE<p>
Available at <url
url="http://www.viceteam.org/">:
Emulates Commodore 64/128/VIC-20/PET/CBM II/Plus 4 computers. Supports
printers, serial port and adapters, stereo sound, disk drives and images, RAM
expansions, cartridges, ethernet connection, cycle-exact NTSC/PAL video, mice,
and joysticks. Includes monitor. Runs on MSDOS/PCDOS, Win9x/ME/NT/2000/XP, OS2,
BeOS x86, Acorn RISC OS, and most Unixes.
Compile the tutorial with
<tscreen><verb>
cl65 -O -t &lt;sys&gt; hello.c text.s
</verb></tscreen>
Substitute the name of a Commodore computer for that <tt/&lt;sys&gt;/:
<itemize>
<item><tt/c128/
<item><tt/c16/
<item><tt/c64/
<item><tt/cbm510/
<item><tt/cbm610/
<item><tt/pet/
<item><tt/plus4/
<item><tt/vic20/
</itemize>
Start the desired version of the emulator (CBM510 and CBM610 programs run on
the CBM II &lsqb;<tt/xcbm2/&rsqb; emulator).
In the Windows versions of VICE, choose <bf>File&gt;Autoboot disk/tape
image...</bf>, choose your executable, and click <bf/OK/.
In the Unix versions, hold down the mouse's first button. Move the pointer to
<bf>Smart-attach disk/tape...</bf>, and release the button. Choose your
executable, and click <bf/Autostart/.
The file has a 14-byte header which corresponds to a PRG-format BASIC program,
consisting of a single line, similar to this:
<tscreen><code>
1000 sys2061
</code></tscreen>
On a real Commodore with attached disk drive, you would type:
<tscreen><verb>
LOAD "0:HELLO",8
</verb></tscreen>
for VIC-20/C64, or:
<tscreen><verb>
DLOAD "HELLO"
</verb></tscreen>
on PET/CBM II/C128/C16/Plus 4; then, type
<tscreen><verb>
RUN
</verb></tscreen>
On a Commodore 128, you can combine those two commands:
<tscreen><verb>
RUN "HELLO"
</verb></tscreen>
The output will appear on a separate line, and you will be returned to a BASIC
prompt.
<sect1>GEOS<p>
Available at <it/Click Here Software's/ <url
url="http://cbmfiles.com/geos/index.html" name="GEOS download section">:
<it><bf/G/raphics <bf/E/nvironment <bf/O/perating <bf/S/ystem.</it>
It provides a WIMP GUI (Windows, Icons, and Mouse-Pointer Graphical User
Interface) for Commodore's computer models <bf/64/ and <bf/128/. It can be
controlled by many different types of input devices:
<itemize>
<item>keyboard
<item>joysticks
<item>mice
<item>trackballs
<item>graphics drawing tablets
<item>light-pens
</itemize>
The tutorial files are different for GEOS. You will find them "next door," in
"<tt>cc65/samples/geos</tt>"; they are called "<tt/hello1.c/" and
"<tt/hello1res.grc/".
Compile the tutorial with
<tscreen><verb>
cl65 -t geos-cbm -O -o hello1 hello1res.grc hello1.c
</verb></tscreen>
Copy the resulting file "<tt/hello1/" onto a (GEOS-format) disk.
Boot the GEOS master disk/image.
<quote>
When you want to run GEOS in an emulator, you must adjust that emulator so that
it does a "true drive" emulation. Each emulator has its own way of turning that
feature on.
</quote>
<quote>
VICE even has different ways that depend on which operating system is running
the emulator.
<itemize>
<item>In Windows, you must click on <bf/Options/ (in an always visible menu).
Then, you must click on <bf/True drive emulation/.
<item>In Unix, you must <em/hold down/ the second button on your mouse. Move
the pointer down to <bf/Drive settings/. Then, move the pointer over to
<bf/Enable true drive emulation/. (If there is a check-mark in front of
those words, that feature already is turned on -- then, move the pointer
off of that menu.) Release the mouse button.
</itemize>
</quote>
Find the <bf/CONVERT/ program on the boot disk &lsqb;tap the 6-key; then, you
should see its icon in the fourth position on the <bf/deskTop/'s directory
notePad&rsqb;. Move GEOS's pointer over to <bf/CONVERT/'s icon; double-click
it to run that program. Click on the <bf/Disk/ icon; put the disk with
"<tt/hello1/" into the drive; and, click the <bf/OK/ icon. Use the little
icons under the list of file-names to move through that list until you find
"<tt/hello1/". Click on it; and then, click on the <bf/Convrt/ icon.
<bf/CONVERT/ will ask you to confirm that you choose the correct file; click
<bf/YES/ if you did (or, click <bf/NO/ if you made a mistake). After the
program has converted "<tt/hello1/" from a CBM file into a GEOS file, it will
announce what it did -- click on <bf/OK/. <bf/CONVERT/ will show the file list
again. This time, click on <bf/Quit/.
(You might need to put the boot disk back into the drive, in order to reload
<bf/deskTop/. Then, you must swap back to the disk with the tutorial program
on it, and click on its disk icon &lsqb;on the right side of the screen&rsqb;.)
Now, you must find <bf/hello1/. Click on the lower left-hand corner of the
directory notePad. Look at the eight file-positions on each page until you see
<bf/hello1/. Double-click on its icon.
The output is shown in a GEOS dialog box; click <bf/OK/ when you have finished
reading it.
<sect1>Contributions wanted<p>
We need your help! Recommended emulators and instructions for other targets
are missing. We suggest that you choose emulators with good compatibility.
Also, being able to run all computers in the target series is good for
target compatibility testing. A machine-language monitor is almost essential
for debugging, but a native debugger could be used, as well.
Finally, emulators which run on Unix or Windows would help to reach a wider
audience.
</article>

1114
doc/ld65.sgml Normal file
View File

File diff suppressed because it is too large Load Diff

251
doc/library.sgml Normal file
View File

@ -0,0 +1,251 @@
<!doctype linuxdoc system>
<article>
<title>cc65 Library Overview
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
<date>2000-12-02, 2002-11-26
<abstract>
An overview over the runtime and C libraries that come with the cc65 compiler,
including a discussion of the differences to the ISO standard.
</abstract>
<!-- Table of contents -->
<toc>
<!-- Begin the document -->
<sect>Overview<p>
This file contains a short overview of the libraries available for the cc65 C
compiler. Please have a look at the <htmlurl url="funcref.html" name="function
reference"> for a list function by function. Since the function reference is
not complete (I'm working on that) it may happen that you don't find a
specific function. In this case, have a look into the header files. All
functions, that are not defined by the ISO C standard have a short comment in
the headers, explaining their use.
<sect>ISO C compatible library<p>
The C library contains a large subset of the ISO C library. Functions are
usually missing in areas, where there is no support on typical 6502 systems.
Wide character sets are an example for this.
I will not go into detail about the ISO functions. If a function is not
mentioned here explicitly, expect it to be available and to behave as defined
in the C standard.
Functions that are <em/not/ available:
<itemize>
<item><tt>tmpfile/tmpnam</tt>
<p>
<item><tt>system</tt>
<p>
<item>All functions that handle floating point numbers in some manner.
<p>
<item>The <tt/ldiv/ function (cc65 is currently not able to return structs
with a size not equal to 1, 2 or 4 bytes by value).
<p>
<item>All functions handling wide character strings.
<p>
<item>Signals and all related functions (having <tt/SIGSEGV/ would be
cool:-)
<p>
<item><tt>setbuf/setvbuf</tt>
</itemize>
Functions not available on all supported systems:
<itemize>
<item><tt>fopen/fread/fwrite/fclose/fputs/fgets/fscanf</tt>: The functions
are built on open/read/write/close. These latter functions are not available
on all systems.
<p>
<item><tt>ftell/fseek/fgetpos/fsetpos</tt>: Support depends on the
capabilities of the target machine.
<p>
<item><tt>rename/remove/rewind</tt>: Support depends on the capabilities of
the target machine.
<p>
<item><tt>time</tt>: Since many of the supported systems do not have a real
time clock, which means that the <tt/time/ function is not available. Please
note that the other functions from <tt/time.h/ <em/are/ available.
</itemize>
Functions that are limited in any way:
<itemize>
<item><tt>strcspn/strpbrk/strspn</tt>: These functions have a length
limitation of 256 for the second string argument. Since this string gives a
character set, and there are only 256 distinct characters, this shouldn't be
a problem.
<p>
<item><tt>getenv</tt>: Since there is no such thing as an environment on all
supported systems, the <tt/getenv/ function will always return a <tt/NULL/
pointer.
<p>
<item><tt>locale</tt>: There is no other locale than the "C" locale. The
native locale is identical to the "C" locale.
</itemize>
In addition to these limitations, some more functions are limited if inlined
versions are requested by using -Os:
<itemize>
<item>The <tt/strlen/ function only works for strings with a maximum length
of 255 characters.
<p>
<item>The <tt/isxxx/ character classification functions from
<tt/&lt;ctype.h&gt;/ will give unpredictable results if the argument is not
in character range (0..255). This limitation may be removed by #undef'ing
the function name (when using <tt/-Os/, the functions are actually macros
that expand to inline assembler code, but the real functions are still
available if the macro definition is removed).
</itemize>
<sect>CPU specific stuff - 6502.h<p>
The header file 6502.h contains some functions that make only sense with the
6502 CPU. Examples are macros to insert more or less useful instructions into
your C code, or a function to call arbitrary machine language subroutines,
passing registers in and out.
<sect>Target specific stuff<p>
For each supported system there's a header file that contains calls or defines
specific for this system. So, when programming for the C64, include c64.h, for
the C128, include c128.h and so on. To make the task for the Commodore systems
easier, there is also a header file named cbm.h that will define stuff common
for all CBM systems, and include the header file for the specific target
system.
The header files contain
<itemize>
<item>Defines for special keys (like function keys)
<item>Defines for special characters (like the graphics characters)
<item>Variables with a fixed address in memory that may be used to access
special hardware. For the C64 and C128 there is a variable struct named
<tt/SID/. Writing to the fields of this struct will write to the SID device
instead. Using these variables will make your program more readable and more
portable. Don't fear ineffective code when using these variables, the
compiler will translate reads and writes to these structs into direct memory
accesses.
<item>Other routines that make only sense for a specific system. One example
are routines to write memory locations in the system bank for the CBM PET-II
family.
</itemize>
<sect>Direct console I/O - <tt/conio.h/<p>
The <tt/conio.h/ header file contains a large set of functions that do screen
and keyboard I/O. The functions will write directly to the screen or poll the
keyboard directly with no more help from the operating system than needed.
This has some disadvantages, but on the other side it's fast and reasonably
portable. conio implementations exist for the following targets:
<itemize>
<item>apple2
<item>apple2enh
<item>atari
<item>atmos
<item>c16 (works also for the c116 with up to 32K memory)
<item>c64
<item>c128
<item>plus4 (or expanded c16/c116)
<item>cbm510 (40 column video)
<item>cbm610 (all CBM series-II computers with 80 column video)
<item>geos-apple
<item>geos-cbm
<item>nes
<item>pet (all CBM PET systems except the 2001)
<item>vic20
</itemize>
The conio.h header file does also include the system specific header files
which define constants for special characters and keys.
<sect>Using the joystick - <tt/joystick.h/<p>
For systems that have a joystick, <tt/joystick.h/ will define a subroutine to
read the current value, including constants to evaluate the result of this
function. To help in writing portable code, the header file will define the
symbol <tt/__JOYSTICK__/ on systems that have a joystick.
<sect>Using a mouse - <tt/mouse.h/<p>
Some target machines support a mouse. Mouse support is currently available for
the following targets:
<itemize>
<item>apple2
<item>apple2enh
<item>atari
<item>c64
<item>c128
<item>cbm510
</itemize>
The available functions are declared in <tt/mouse.h/ To help writing portable
code, the header file will define the symbol <tt/__MOUSE__/ in systems that
support a mouse.
<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>Copyright<p>
This C runtime library implementation for the cc65 compiler is (C)
Copyright 1998-2002 Ullrich von Bassewitz. For usage of the binaries
and/or sources the following conditions do apply:
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>

360
doc/lynx.sgml Normal file
View File

@ -0,0 +1,360 @@
<!doctype linuxdoc system>
<article>
<title>Atari Lynx specific information for cc65
<author>Karri Kaksonen, <htmlurl url="mailto:karri@sipo.fi" name="karri@sipo.fi">
Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
<date>2011-04-01
<abstract>
An overview over the Atari Lynx 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 Atari Lynx runtime system as it comes
with the cc65 C compiler. It describes the memory layout, Lynx specific header
files, available drivers, and any pitfalls specific to that platform.
Please note that Lynx 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>Building your first Hello World application<p>
Here is a small traditional Hello World program for the Atari Lynx.
<tscreen><verb>
#include <lynx.h>
#include <tgi.h>
#include <6502.h>
void main(void) {
tgi_install(tgi_static_stddrv);
tgi_init();
CLI();
while (tgi_busy())
;
tgi_clear();
tgi_setcolor(COLOR_GREEN);
tgi_outtextxy(0, 0, "Hello World");
tgi_updatedisplay();
while (1)
;
}
</verb></tscreen>
The lynx.h contains all kind of system dependent things.
The tgi.h contains the graphics driver functions.
The 6502.h is needed for executing the CLI() command.
As the Atari Lynx does not have ASCII characters available you need to use
the Tiny Graphics Interface library for producing letters on the screen.
The cc65 compiler suite has a graphics library called "Tiny Graphics
Interface". This interface has some relocatable code. In order to use this
in your own program you need to load it at run time.
Unfortunately the Lynx does not have a disk drive from where to load it.
Therefore you must already load it at compile time. The easiest way is to
automatically link it in statically from the Lynx C library.
<tscreen><verb>
cl65 -t lynx -o game.lnx main.c
</verb></tscreen>
This will create a bootable cart image called game.lnx
<sect>Binary format<p>
The standard binary output format generated by the linker for the Lynx target
is a cart image. By specifying the config file lynx-bll.cfg the linker will
generate BLL download compatible binary files.
It is of course possible to change this behaviour by using a modified startup
file and linker config.
The bootloader used in the cc65 lynx library uses a very minimal bootloader
that does not check the cart or show a title screen.
The advantage of this bootloader is that it allows creation of cart images to
many common formats.
Cart sizes
<tscreen><verb>
Block size Rom size Description
512 bytes 128k Standard old games like Warbirds
1024 bytes 256k Most common format for homebrew. Also newer games like Lemmings
2048 bytes 512k Largest games like EOTB
</verb></tscreen>
<sect>Memory layout<p>
cc65 generated programs with the default setup run with the I/O area and the
kernal enabled, which gives a usable memory range of &dollar;200 - &dollar;C037.
Special locations:
<tscreen><verb>
0000 - 00FF Zero page
0100 - 01FF Machine stack
A058 - C037 Collision buffer
C038 - E017 Screen buffer 1
E018 - FFF7 Screen buffer 0
FFF8 - FFFF Hardware vectors
</verb></tscreen>
<descrip>
<tag/Text screen/
No conio support is currently available for the Lynx.
<tag/Keyboard/
The Lynx "flabode" keys, Opt 1, Pause and Opt 2 are implemented using the
conio interface. The only characters the keyboard is able to produce are
'R' for Restart (Opt 1 + Pause), 'F' for flip (Opt 2 + Pause),
'P' for pause, '1' for Opt 1, '2' for Opt 2, '3' for Opt 1 + Opt 2 and
'?' for all keys down at the same time.
<tag/Stack/
The C runtime stack is located at &dollar;C037 (or &dollar;A057 if collision
detection is enabled) and growing downwards.
<tag/Heap/
The C heap is located at the end of the program and grows towards the C
runtime stack.
<tag/Screen/
The collision detection screen is at &dollar;A058 if it is enabled. The
double buffered screens are at &dollar;C038 and &dollar;E018.
</descrip><p>
<sect>Platform specific header files<p>
Programs containing Lynx specific code may use the <tt/lynx.h/ header file.
<sect1>Lynx specific functions<p>
<itemize>
<item>lynx_eeprom_erase
<item>lynx_eeprom_read
<item>lynx_eeprom_write
<item>lynx_eeread
<item>lynx_eewrite
<item>lynx_exec
<item>lynx_load
</itemize>
<sect1>Hardware access<p>
The following pseudo variables declared in the <tt/lynx.h/ header file do
allow access to hardware located in the address space. Some variables are
structures, accessing the struct fields will access the chip registers.
<descrip>
<tag><tt/MIKEY/</tag>
The <tt/MIKEY/ structure allows access to MIKEY chip. See the <tt/_mikey.h/
header file located in the include directory for the declaration of the
structure.
<tag><tt/SUZY/</tag>
The <tt/SUZY/ structure allows access to SUZY chip. See the <tt/_suzy.h/
header file located in the include directory for the declaration of the
structure.
</descrip><p>
<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/lynx-160-102-16.tgi (lynx_160_102_16)/</tag>
A TGI driver for the standard graphics mode (160&times;102 in 16 colors).
The TGI driver is implemented as an interrupt driven dual buffering device.
To use it as a single-buffer device set draw page and view page to the same
value 0 or 1;
The TGI driver has a few Lynx-specific extensions.
Calling tgi_sprite(spr) or tgi_ioctl(0, spr) will display a standard Lynx
sprite on screen.
Calling tgi_flip() or tgi_ioctl(1, 0) will do a flip screen.
Calling tgi_setbgcolor(bgcolor) or tgi_ioctl(2, bgindex) will set the text
background color to the index defined by bgindex. If bgindex is 0 then the
background color is transparent.
To set the framerate of the display hardware call tgi_setframerate(rate) or
tgi_ioctl(3, rate). The supported framerates are 50, 60 and 75 frames per
second. Actually there is no real reason to use anything else than 75 frames
per second.
To check if the drawing engine is busy with the previous swap you can
call tgi_busy or tgi_ioctl(4, 0). It returns 0 if idle and 1 if busy
To update displays you can call tgi_updatedisplay() or tgi_ioctl(4, 1) it
will wait for the next VBL interrupt and set the draw buffer to the
view buffer. The draw buffer is also changed to (drawbuffer xor 1).
You can also enable or disable collision detection by a call to
tgi_setcollisiondetection(active) or tgi_ioctl(5, active). The collision
result is located before the sprite structure by default in this driver.
In order to reserve memory for the collision detection buffer you need to
specify lynx-coll.cfg as the configuration file to the linker.
</descrip><p>
<sect1>Extended memory drivers<p>
No extended memory drivers are currently available for the Lynx.
<sect1>Joystick drivers<p>
<descrip>
<tag><tt/lynx-stdjoy.joy (lynx_stdjoy)/</tag>
A joystick driver for the standard buttons.
</descrip><p>
<sect1>Mouse drivers<p>
No mouse drivers are currently available for the Lynx.
<sect1>RS232 device drivers<p>
<descrip>
<tag><tt/lynx-comlynx.ser (lynx_comlynx)/</tag>
A serial driver for the ComLynx port.
The ComLynx port has Tx and Rx wired together. Every byte is sent
to all connected Lynxes. Only one Lynx can send at a time. There is no
protocol created for communication. You are on your own.
If the Lynx returns framing error then it is likely that another Lynx is
sending data at the same time.
The Lynx can also send a break and receive a break. The Lynx break is
recognized if the bit is down for 24 bit cycles or more.
To send a break you just set the break bit. The length of the break depends
on how long this bit is down.
The driver supports the baudrates:
<itemize>
<item>62500
<item>31250
<item>9600
<item>7200
<item>4800
<item>3600
<item>2400
<item>1800
<item>1200
<item>600
<item>300
<item>150
<item>134.5
<item>110
<item>75
</itemize>
The parity bit supports MARK and SPACE. It also supports EVEN and ODD parity
but the parity bit is included in the calculation. Most of us don't want it
this way. But there is nothing we can do about it.
The Lynx hardware will always check parity on incoming traffic. Currently
the driver cannot receive data from standard PC's due to this parity bug.
For working with Lynx to Lynx communication use EVEN parity.
To send data to standard PC's use MARK or SPACE as parity setting.
There is always only one stop bit. And the data length is always 8 bits.
We have no handshaking available. Even software handshake is impossible
as ComLynx has only one wire for the data.
Both transmit and receive are interrupt driven.
</descrip><p>
<sect>Limitations<p>
<sect>Cart access<p>
At this point in time there is no support for the cart filesystem yet. I have
a <tt/lynx-cart-demo/ example project that uses an interrupt driven display,
has support for the cart filesystem and an abcmusic sound module.
At some point in time we may find a way to rewrite these to fit the way the
cc65 drivers require. But for the time being you can create less portable
applications using these Lynx specific modules in <tt/lynx-cart-demo/.
<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>

197
doc/nes.sgml Normal file
View File

@ -0,0 +1,197 @@
<!doctype linuxdoc system>
<article>
<title>Nintendo Entertainment System specific information for cc65
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
Stefan A. Haubenthal, <htmlurl url="mailto:polluks@sdf.lonestar.org" name="polluks@sdf.lonestar.org">
<date>2005-07-17
<abstract>
An overview over the NES 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 NES runtime system as it comes
with the cc65 C compiler. It describes the memory layout, NES specific header
files, available drivers, and any pitfalls specific to that platform.
Please note that NES 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 NES target
is a machine language program with an INES cartridge header. It is of course
possible to change this behaviour by using a modified startup file and linker
config.
<sect>Memory layout<p>
cc65 generated programs with the default setup run with the I/O area and a
CHR bank enabled, which gives a usable memory range of &dollar;8000 - &dollar;FFF3.
All boot ROM entry points may be called directly without additional code.
Special locations:
<descrip>
<tag/Text screen/
The text screen is located at VRAM &dollar;2000.
<tag/Stack/
The C runtime stack is located at &dollar;7FFF and growing downwards.
<tag/Heap/
The C heap is located at the end of the program and grows towards the C
runtime stack.
</descrip><p>
<sect>Platform specific header files<p>
Programs containing NES specific code may use the <tt/nes.h/ header file.
<sect1>NES specific functions<p>
<itemize>
<item>waitvblank
<item>get_tv
</itemize>
<sect1>Hardware access<p>
The following pseudo variables declared in the <tt/nes.inc/ include file do
allow access to hardware located in the address space.
<descrip>
<tag><tt/PPU/</tag>
The <tt/PPU/ defines allow access to the PPU chip.
<tag><tt/APU/</tag>
The <tt/APU/ defines allow access to the APU chip.
</descrip><p>
<sect>Loadable drivers<p>
All drivers must be statically linked because no file I/O is available.
The names in the parentheses denote the symbols to be used for static linking of the drivers.
<sect1>Graphics drivers<p>
<descrip>
<tag><tt/nes-64-56-2.tgi (nes_64_56_2)/</tag>
This driver features a resolution of 64&times;56 with 2 colors using the
CHR bank.
</descrip><p>
<sect1>Extended memory drivers<p>
No extended memory drivers are currently available for the NES.
<sect1>Joystick drivers<p>
<descrip>
<tag><tt/nes-stdjoy.joy (nes_stdjoy)/</tag>
A joystick driver for the standard four buttons joypad is available.
</descrip><p>
<sect1>Mouse drivers<p>
No mouse drivers are currently available for the NES.
<sect1>RS232 device drivers<p>
No serial drivers are currently available for the NES.
<sect>Limitations<p>
<sect1>Disk I/O<p>
The existing library for the NES doesn't implement C file
I/O. There are no hacks for the <tt/read()/ and <tt/write()/ routines.
To be more concrete, this limitation means that you cannot use any of the
following functions (and a few others):
<itemize>
<item>fclose
<item>fopen
<item>fread
<item>fprintf
<item>fputc
<item>fscanf
<item>fwrite
<item>...
</itemize>
<sect>Other hints<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
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>

224
doc/od65.sgml Normal file
View File

@ -0,0 +1,224 @@
<!doctype linuxdoc system>
<article>
<title>od65 Users Guide
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
<date>2010-07-30
<abstract>
od65 is the object file dump utility. It is able to output most parts of
<htmlurl url="ca65.html" name="ca65"> generated object files in readable form.
</abstract>
<!-- Table of contents -->
<toc>
<!-- Begin the document -->
<sect>Overview<p>
od65 is an object file dump utility. It is able to output most parts of
<htmlurl url="ca65.html" name="ca65"> generated object files in readable form.
Since the contents and format of the object files are not documented
elsewhere and may change at any time, this tool is a portable way to look at
the contents.
Apart from curiosity, most people don't need to use this tool.
<sect>Usage<p>
The od65 utility dumps contents of one or more ca65 generated object file to
standard output. It has no cross-version compatibility, so you have to use
a version that matches the version of ca65 used to create the object files.
<sect1>Command line option overview<p>
The program may be called as follows:
<tscreen><verb>
---------------------------------------------------------------------------
Usage: od65 [options] file [options] [file]
Short options:
-h Help (this text)
-H Dump the object file header
-S Dump segments sizes
-V Print the version number and exit
Long options:
--dump-all Dump all object file information
--dump-dbgsyms Dump debug symbols
--dump-exports Dump exported symbols
--dump-files Dump the source files
--dump-header Dump the object file header
--dump-imports Dump imported symbols
--dump-lineinfo Dump line information
--dump-options Dump object file options
--dump-segments Dump the segments in the file
--dump-segsize Dump segments sizes
--help Help (this text)
--version Print the version number and exit
---------------------------------------------------------------------------
</verb></tscreen>
<sect1>Command line options in detail<label id="cmdline-opt-detail"><p>
Here is a description of all the command line options:
<descrip>
<tag><tt>--dump-all</tt></tag>
This will output all information, od65 is able to process. The option is a
shortcut for specifying all the other <tt/--dump/ options.
<tag><tt>--dump-dbgsyms</tt></tag>
Dump all debug symbols contained in the object file.
<tag><tt>--dump-exports</tt></tag>
Dump all exported symbols contained in the object file.
<tag><tt>--dump-files</tt></tag>
Dump the file table contained in the object file.
<tag><tt>-H, --dump-header</tt></tag>
Dump the object file header.
<tag><tt>--dump-imports</tt></tag>
Dump the list of imported symbols contained in the object file.
<tag><tt>--dump-lineinfo</tt></tag>
Dump the line info contained in the object file.
<tag><tt>--dump-segments</tt></tag>
Dump the list of segments contained in the object file.
<tag><tt>--dump-scopes</tt></tag>
Dump the scope (lexical level) information contained in the object file.
<tag><tt>-S, --dump-segsize</tt></tag>
Dump the sizes of all segments contained in the object file. This option is
quite useful to determine the effect of measures that increase or decrease
code size.
<tag><tt>-h, --help</tt></tag>
Print the short option summary shown above.
<tag><tt>-V, --version</tt></tag>
Print the version number of the compiler. When submitting a bug report,
please include the operating system you're using, and the compiler
version.
</descrip>
<sect>Input and output<p>
The converter will read one or more object files per invocation and write the
contents in readable format to standard output. Please note that you need to
specify any of the <tt/--dump/ options listed <ref id="cmdline-opt-detail"
name="above">, otherwise no useful output will be generated.
Example output for the command
<tscreen><verb>
od65 --dump-header --dump-files t.o
</verb></tscreen>
<tscreen><verb>
t.o:
Header:
Magic: 0x616E7A55
Version: 12
Flags: 0x0001 (OBJ_FLAGS_DBGINFO)
Options:
Offset: 88
Size: 9
Files:
Offset: 97
Size: 10
Segments:
Offset: 107
Size: 101
Imports:
Offset: 208
Size: 1
Exports:
Offset: 209
Size: 1
Debug symbols:
Offset: 210
Size: 55
Line infos:
Offset: 265
Size: 1
String pool:
Offset: 266
Size: 80
Files:
Count: 1
Index: 0
Name: "t.s"
Size: 402
Modification time: 1280498435 (Fri Jul 30 16:00:35 2010)
</verb></tscreen>
<sect>Bugs/Feedback<p>
If you have problems using the converter, if you find any bugs, or if you're
doing something interesting with the code, 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>Copyright<p>
od65 is (C) Copyright 2000-2009, Ullrich von Bassewitz. For usage of the
binaries and/or sources the following conditions apply:
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>

261
doc/pet.sgml Normal file
View File

@ -0,0 +1,261 @@
<!doctype linuxdoc system>
<article>
<title>Commodore PET specific information for cc65
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
Stefan A. Haubenthal, <htmlurl url="mailto:polluks@sdf.lonestar.org" name="polluks@sdf.lonestar.org">
<date>2005-05-24
<abstract>
An overview over the PET 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 PET runtime system as it comes with the
cc65 C compiler. It describes the memory layout, PET specific header files,
available drivers, and any pitfalls specific to that platform.
Please note that PET 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 PET target
is a machine language program with a one line BASIC stub, which calls the
machine language part via SYS. This means that a program can be loaded as
BASIC program and started with RUN. It is of course possible to change this
behaviour by using a modified startup file and linker config.
<sect>Memory layout<p>
cc65 generated programs with the default setup run with the I/O area and the
kernal and BASIC ROM enabled, which gives a usable memory range of
&dollar;0400 - &dollar;7FFF (32KB machine).
All ROM entry points may be called directly without additional code.
Special locations:
<descrip>
<tag/Text screen/
The text screen is located at &dollar;8000.
<tag/Stack/
The C runtime stack is located at &dollar;7FFF and growing downwards.
<tag/Heap/
The C heap is located at the end of the program and grows towards the C
runtime stack.
</descrip><p>
<sect>Platform specific header files<p>
Programs containing PET specific code may use the <tt/pet.h/ or <tt/cbm.h/
header files. Using the later may be an option when writing code for more than
one CBM platform, since it includes <tt/pet.h/ and declares several functions
common to all CBM platforms.
<sect1>PET specific functions<p>
There are currently no special PET functions.
<sect1>CBM specific functions<p>
Some functions are available for all (or at least most) of the Commodore
machines. See the <htmlurl url="funcref.html" name="function reference"> for
declaration and usage.
<itemize>
<item>cbm_close
<item>cbm_closedir
<item>cbm_k_setlfs
<item>cbm_k_setnam
<item>cbm_k_load
<item>cbm_k_save
<item>cbm_k_open
<item>cbm_k_close
<item>cbm_k_readst
<item>cbm_k_chkin
<item>cbm_k_ckout
<item>cbm_k_basin
<item>cbm_k_bsout
<item>cbm_k_clrch
<item>cbm_load
<item>cbm_open
<item>cbm_opendir
<item>cbm_read
<item>cbm_readdir
<item>cbm_save
<item>cbm_write
<item>get_tv
</itemize>
<sect1>Hardware access<p>
The following pseudo variables declared in the <tt/pet.h/ header file do allow
access to hardware located in the address space. Some variables are
structures, accessing the struct fields will access the chip registers.
<descrip>
<tag><tt/PIA1, PIA2/</tag>
Access to the two PIA (peripheral interface adapter) chips is available via
the <tt/PIA1/ and <tt/PIA2/ variables. The structure behind these variables
is explained in <tt/_pia.h/.
<tag><tt/VIA/</tag>
The <tt/VIA/ structure allows access to the VIA (versatile interface
adapter). See the <tt/_6522.h/ header file located in the include
directory for the declaration of the structure.
</descrip><p>
<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>
No graphics drivers are currently available for the PET.
<sect1>Extended memory drivers<p>
No extended memory drivers are currently available for the PET.
<sect1>Joystick drivers<p>
<descrip>
<tag><tt/pet-ptvjoy.joy (pet_ptvjoy)/</tag>
Driver for the Protovision 4-player adapter contributed by Groepaz. See
<htmlurl url="http://www.protovision-online.de/hardw/hardwstart.htm"
name="http://www.protovision-online.de/hardw/hardwstart.htm"> for prices and
building instructions. Up to two joysticks are supported.
<tag><tt/pet-stdjoy.joy (pet_stdjoy)/</tag>
Driver for the standard PET userport joystick.
</descrip><p>
<sect1>Mouse drivers<p>
No mouse drivers are currently available for the PET.
<sect1>RS232 device drivers<p>
No serial drivers are currently available for the PET.
<sect>Limitations<p>
<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 chosen:
<tscreen><verb>
RUN: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>Program return code<p>
The program return code (low byte) is passed back to BASIC by use of the
<tt/ST/ variable.
<sect1>Interrupts<p>
The runtime for the PET uses routines marked as <tt/.INTERRUPTOR/ for
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>Using extended memory<p>
The extended memory at $9000 of the CBM 8x96 may be added to the heap by using
the following code:
<tscreen><verb>
/* Check for the existence of RAM */
if (PEEK(0x9000) == POKE(0x9000, PEEK(0x9000)+1)) {
/* Add it to the heap */
_heapadd ((void *) 0x9000, 0x2000);
}
</verb></tscreen>
<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>

270
doc/plus4.sgml Normal file
View File

@ -0,0 +1,270 @@
<!doctype linuxdoc system>
<article>
<title>Commodore Plus/4 specific information for cc65
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
<date>2003-12-14
<abstract>
An overview over the Plus/4 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 Plus/4 runtime system as it comes with the
cc65 C compiler. It describes the memory layout, Plus/4 specific header files,
available drivers, and any pitfalls specific to that platform.
Please note that Plus/4 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.
Since the Plus/4 and the Commodore 16/116 are almost identical (the latter are
missing the 6551 ACIA and do only have 16KB of memory), the <htmlurl
url="c16.html" name="C16 documentation"> is also worth a look. The difference
between both cc65 targets is that the Plus/4 runtime uses banking to support
full 64K RAM, while the C16 does not use banking and supports up to 32K RAM.
Because banking is not needed, most C16 programs will be somewhat smaller than
the same program compiled for the Plus/4. However, programs compiled for the
C16 will always run on the Plus/4, while the reverse is not necessarily true.
<sect>Binary format<p>
The standard binary output format generated by the linker for the Plus/4
target is a machine language program with a one line BASIC stub, which calls
the machine language part via SYS. This means that a program can be loaded as
BASIC program and started with RUN. It is of course possible to change this
behaviour by using a modified startup file and linker config.
<sect>Memory layout<p>
cc65 generated programs with the default setup run with the kernal and basic
banked out. This gives a usable memory range of &dollar;1000 - &dollar;FD00.
Having the kernal and basic ROMs banked out means, that no ROM entry points
may be called directly from user code.
Special locations:
<descrip>
<tag/Text screen/
The text screen is located at &dollar;C00 (as in the standard setup).
<tag/Color RAM/
The color RAM is located at &dollar;800 (standard location).
<tag/Stack/
The C runtime stack is located at &dollar;FCFF and growing downwards.
<tag/Heap/
The C heap is located at the end of the program and grows towards the C
runtime stack.
</descrip><p>
<sect>Platform specific header files<p>
Programs containing Plus/4 specific code may use the <tt/plus4.h/ or <tt/cbm.h/
header files. Using the later may be an option when writing code for more than
one CBM platform, since it includes <tt/plus4.h/ and declares several functions
common to all CBM platforms.
Please note that most of the header file declarations from the <tt/plus4.h/
header file are shared between the C16 and Plus/4 configurations. For this
reason, most of it is located in a common header file named <tt/cbm264.h/.
<sect1>Plus/4 specific functions<p>
There are currently no special Plus/4 functions.
<sect1>CBM specific functions<p>
Some functions are available for all (or at least most) of the Commodore
machines. See the <htmlurl url="funcref.html" name="function reference"> for
declaration and usage.
<itemize>
<item>cbm_close
<item>cbm_closedir
<item>cbm_k_setlfs
<item>cbm_k_setnam
<item>cbm_k_load
<item>cbm_k_save
<item>cbm_k_open
<item>cbm_k_close
<item>cbm_k_readst
<item>cbm_k_chkin
<item>cbm_k_ckout
<item>cbm_k_basin
<item>cbm_k_bsout
<item>cbm_k_clrch
<item>cbm_load
<item>cbm_open
<item>cbm_opendir
<item>cbm_read
<item>cbm_readdir
<item>cbm_save
<item>cbm_write
<item>get_tv
</itemize>
<sect1>Hardware access<p>
The following pseudo variables declared in the <tt/plus4.h/ header file do
allow access to hardware located in the address space. Some variables are
structures, accessing the struct fields will access the chip registers.
<descrip>
<tag><tt/TED/</tag>
The <tt/TED/ structure allows access to the TED chip. See the
<tt/_ted.h/ header file located in the include directory for the
declaration of the structure.
<tag><tt/COLOR_RAM/</tag>
A character array that mirrors the color RAM of the Plus/4 at &dollar;0800.
</descrip><p>
<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>
No graphics drivers are currently available for the Plus/4.
<sect1>Extended memory drivers<p>
No extended memory drivers are currently available for the Plus/4.
<sect1>Joystick drivers<p>
<descrip>
<tag><tt/plus4-stdjoy.joy (plus4_stdjoy)/</tag>
Supports up to two joysticks connected to the standard joysticks port of
the Plus/4.
</descrip><p>
<sect1>Mouse drivers<p>
Currently no drivers available (in fact, the API for loadable mouse drivers
does not exist).
<sect1>RS232 device drivers<p>
<descrip>
<tag><tt/plus4-stdser.ser (plus4_stdser)/</tag>
Driver for the 6551 ACIA chip built into the Plus/4. 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.
You need an adapter to use the builtin port, since the output levels
available at the user port don't follow the RS232 standard.
</descrip><p>
<sect>Limitations<p>
<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 chosen:
<tscreen><verb>
RUN: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>Program return code<p>
The program return code (low byte) is passed back to BASIC by use of the
<tt/ST/ variable.
<sect1>Interrupts<p>
The runtime for the Plus/4 uses routines marked as <tt/.INTERRUPTOR/ for
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>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>

596
doc/smc.sgml Normal file
View File

@ -0,0 +1,596 @@
<!doctype linuxdoc system>
<article>
<title>ca65 Macros for Self Modifying Code
<author>Christian Kr&uuml;ger
<date>2012-02-19
<abstract>
The 'smc.inc' macro package for ca65 eases the use, increases the safeness and
self-explanation of 'self-modifying-code' (SMC).
</abstract>
<!-- Table of contents -->
<toc>
<!-- Begin the document -->
<sect>Overview<p>
When reading assembler sources, self modifying code is often hard to identify
and applying it needs a lot of discipline.
Since the cacheless 6502 is a thankful target of such kind of code, the macro
package will not only reduce this complexness, but also document the use. The
resulting source is more self-explanatory and so easier to maintain.
While for general purposes SMC is not a desired form for implementations, it
can be quite useful for a small range of scenarios. Normally SMC will be
introduced when optimizing code in respect to:
<itemize>
<item>speed and/or
<item>size.
</itemize>
Please mind that SMC can only be applied for code in RAM, which means that a
general purpose library with SMC excludes ROM targets!
The ca65 SMC macro package consists of two files:
<itemize>
<item><tt>smc.inc</tt>
<item><tt>opcodes.inc</tt>
</itemize>
The latter is only needed if you also plan to modify opcodes and not only data
within your code.
<sect>Usage<p>
The use of the macros is quite simple:
Original:
<tscreen><verb>
PHA
JSR SUBROUTINE
PLA
</verb></tscreen>
By applying SMC, the speed will now be increased by once cycle:
SMC:
<tscreen><verb>
SMC_StoreValue RestoreAccu
JSR SUBROUTINE
SMC RestoreAccu, { LDA #SMC_Value }
</verb></tscreen>
The first line stores the value of the accu into the '<tt>RestoreAccu</tt>'
labeled SMC target.
Please note:
<enum>
<item> for all SMC store or transfer operations, a second argument can be
given. This determines the register for the operation:
'<tt>SMC_StoreValue Label, y</tt>' will store the value of the
Y-register.
If the second argument is missing, the accu will be used automatically.
<item> The label targets a 'special SMC namespace'. It fits only to
destinations which are introduced with the macro '<tt>SMC</tt>'. A
normal label '<tt>RestoreAccu</tt>' wouldn't match and could even
coexist (even if you should abstain from doing so).
<item> The macro '<tt>SMC_StoreValue</tt>' takes care, that the store
operation will occur on the value-position of a SMC-instruction. As
you will see, other macros influence other instruction part positions.
There is no consistency check, if the targeted SMC instruction acually
contains a value. Storing a 'value' on an immplied SMC instruction
would corrupt the following memory cell!
</enum>
The second line needs no further explanation, this is just a placeholder for
some code in the example.
The third line is the code line which is about to be modified. It has to start
with the '<tt>SMC</tt>' macro and must be labeled, so that the modification
can be designated. Then the unmodified code is given in curly braces.
Please note the usage of the value placeholder 'SMC_Value'. Using such a
placeholder has two advantages:
<enum>
<item> The code is better documented. It is clearly visible that the given
value is about to be changed.
<item> When examining an (initial) disassembly (e.g. in a debugger), these
placegolders can be better identified: They are fixed and, you may
notice that below, quite eye catching defined.
</enum>
<sect1>Argument placeholders<p>
There are four kinds of placeholders:
<descrip>
<label id="Address placeholder">
<tag><tt>SMC_AbsAdr</tt></tag>
Used to indicate an address. The value is '<tt>$FADE</tt>'.
Example: <tt>STA SMC_AbsAdr</tt>
<label id="Zero-Page-Address placeholder">
<tag><tt>SMC_ZpAdr</tt></tag>
Used to indicate a zero-page-address. The value is '<tt>$00</tt>'.
Example: <tt>LDA SMC_ZpAdr</tt>
<label id="Opcode placeholder">
<tag><tt>SMC_Opcode</tt></tag>
Used to indicate an instruction. The value is '<tt>NOP</tt>'.
Example: <tt>SMC_Opcode</tt>
<label id="Immediate value placeholder">
<tag><tt>SMC_Value</tt></tag>
Used to indicate a value. The value is '<tt>$42</tt>'.
Example: <tt>LDX #SMC_Value</tt>
</descrip>
Attention: Often code is modified after the initial use - where using the
placeholders does not makes sense. Please mind also, that in very variable
expressions (e.g. opcode and argument is about to be changed), placeholders
can lead to unidentifyable code for a debugger/disassembler:
<tt>SMC Example, { SMC_Opcode SMC_AbsAdr } </tt>
Since the opcode is '<tt/NOP/', the value '<tt/$DE/' from '<tt/$FADE/' will
interpreted as opcode in a disassembler too. This breaks the correct
disassembly, because '<tt/$DE/' is interpreted as '<tt/DEC abx/'. Establishing
a valid placeholder instruction may be better:
<tt>SMC Example, { sta SMC_AbsAdr } ; Note: Opcode will be modified too!</tt>
<sect1>Accessing opcodes<p>
Some macros are designed to access the instruction of a code line. To increase
readability, please use the opcodes as defined in the '<tt>opcodes.inc</tt>'
file.
<descrip>
<label id="Transfer opcode">
<tag><tt>SMC_TransferOpcode label, opcode (, register)</tt></tag>
Loads and store an opcode to given SMC instruction.
Example:
<tscreen><verb>
SMC SumRegister, { LDA #10 }
JSR OUTPUT
SMC_TransferOpcode SumRegister, OPC_ADC_imm, x
</verb></tscreen>
The macro above will load the opcode '<tt>ADC #</tt>' into the x - register
and stores it at the place of the '<tt>LDA #</tt>'.
<label id="Load opcode">
<tag><tt>SMC_LoadOpcode label (, register)</tt></tag>
Loads the opcode of a SMC line to the given register.
Example:
<tscreen><verb>
SMC ShiftOrNothing, { LSL }
SMC_LoadOpcode ShiftOrNothing, y
CPY #OPC_NOP
BEQ Exit
</verb></tscreen>
<label id="Store opcode">
<tag><tt>SMC_StoreOpcode label (, register)</tt></tag>
Stores the value of the given register at the opcode place of a SMC line.
Example:
<tscreen><verb>
SetBoldMode:
LDA #OPC_INX
SMC_StoreOpcode AdaptCharWidth
SMC_StoreOpcode AdaptUnderlineWidth
RTS
...
SMC AdaptCharWidth, { NOP }
...
SMC AdaptUnderlineWidth, { NOP }
</verb></tscreen>
</descrip>
<sect1>Accessing arguments<p>
These marcos are determined to get, set and change arguments of instructions:
<descrip>
<label id="Change branch">
<tag><tt>SMC_ChangeBranch label, destination (, register)</tt></tag>
Used to modify the destination of a branch instruction. If the adress offset
exceeds the supported range of 8-bit of the 6502, a error will be thrown.
Example:
<tscreen><verb>
Disable Handler:
SMC_ChangeBranch BranchToHandler, Exit
RTS
...
LDA warning
SMC BranchToHandler, { BNE Handler }
Exit:
RTS
</verb></tscreen>
<label id="Transfer value">
<tag><tt>SMC_TransferValue label, value (, register)</tt></tag>
Changes the value of a SMC line.
Example:
<tscreen><verb>
ClearDefault:
SMC_TransferValue LoadDefault, 0
RTS
...
SMC LoadDefault, { LDX #25 }
</verb></tscreen>
<label id="Load value">
<tag><tt>SMC_LoadValue label (, register)</tt></tag>
Retreives the value of a SMC line.
Example:
<tscreen><verb>
ShowDefault:
SMC_LoadValue LoadDefault
JSR PrintValue
RTS
...
SMC LoadDefault, { LDX #25 }
</verb></tscreen>
<label id="Store value">
<tag><tt>SMC_StoreValue label (, register)</tt></tag>
Stores the value in the register to given SMC line.
Example:
<tscreen><verb>
InitCounters:
LDY #0
SMC_StoreValue GetI, y
SMC_StoreValue GetJ, y
SMC_StoreValue GetK, y
...
SMC GetI, { LDX #SMC_Value }
...
SMC GetJ, { LDX #SMC_Value }
...
SMC GetK, { LDX #SMC_Value }
</verb></tscreen>
<label id="Transfer low-byte">
<tag><tt>SMC_TransferLowByte label, value (, register)</tt></tag>
Does the same as '<tt>SMC_TransferValue</tt>' but should be used for
low-bytes of adresses for better readability.
Example:
<tscreen><verb>
ActivateSecondDataSet:
SMC_TransferLowByte LoadData, $40
RTS
...
SMC LoadData, { LDA $2000 }
</verb></tscreen>
<label id="Load low-byte">
<tag><tt>SMC_LoadLowByte label (, register)</tt></tag>
Does the same as '<tt>SMC_LoadValue</tt>' but should be used for low-bytes
of adresses for better readability.
Example:
<tscreen><verb>
IsSecondDataSetActive:
SMC_LoadLowByte LoadData, y
CPY #$40
BNE NotActive
...
SMC LoadData, { LDA $2000 }
</verb></tscreen>
<label id="Store low-byte">
<tag><tt>SMC_StoreLowByte label (, register)</tt></tag>
Does the same as '<tt>SMC_StoreValue</tt>' but should be used for low-bytes
of adresses for better readability.
Example:
<tscreen><verb>
InitStructureBaseAddresses:
LDX #0
SMC_StoreLowByte GetPlayerGraphic, x
SMC_StoreLowByte GetObjectGraphic, x
SMC_StoreLowByte StoreCollisionData, x
RTS
...
SMC GetPlayerGraphic, { LDX $2000 }
...
SMC GetObjectGraphic, { LDA $2100,x }
...
SMC StoreCollisionData, { STY $2200 }
</verb></tscreen>
<label id="Transfer high-byte">
<tag><tt>SMC_TransferHighByte label, value (, register)</tt></tag>
Loads and stores the given value via the named register to the high-byte
adress portion of an SMC-instruction.
Example:
<tscreen><verb>
PlaySFX:
SMC GetVolume { LDA $3200,x }
STA SoundOut
INX
BNE PlaySFX
...
PlayOtherSound:
SMC_TransferHighByte GetVolume, $34
</verb></tscreen>
<label id="Load high-byte">
<tag><tt>SMC_LoadHighByte label (, register)</tt></tag>
Loads the high-byte part of an SMC-instruction adress to the given register.
Example:
<tscreen><verb>
PlaySFX:
SMC GetVolume { LDA $3200,x }
...
SMC_LoadHighByte GetVolume
cmp #$34
beq OtherSoundPlaying
...
</verb></tscreen>
<label id="Store high-byte">
<tag><tt>SMC_StoreHighByte label (, register)</tt></tag>
Stores the high-byte adress part of an SMC-instruction from the given
register.
Example:
<tscreen><verb>
SetupLevel2:
LDX #(>Level2Base)
SMC_StoreHighByte GetLevelData, x
SMC_StoreHighByte GetScreenData, x
SMC_StoreHighByte GetSoundData, x
RTS
...
SMC GetLevelData, { LDA Level1Base+Data }
...
SMC GetScreenData, { LDA Level1Base+Screen, x }
...
SMC GetSoundData, { LDA Level1Base+Sound, y }
</verb></tscreen>
<label id="Transfer single adress">
<tag><tt>SMC_TransferAddressSingle label, address (, register)</tt></tag>
Transfers the contents of the given address via the given register to the
designated SMC instruction.
Example:
<tscreen><verb>
PrintHello:
SMC_TransferAddressSingle GetChar, #HelloMsg
...
LDX #0
NextChar:
SMC GetChar, { LDA SMC_AbsAdr, x }
BEQ leave
JSR CharOut
INX
BNE NextChar
</verb></tscreen>
<label id="Transfer adress">
<tag><tt>SMC_TransferAddress label, address</tt></tag>
Loads contents of given address to A/X and stores the result to SMC
instruction. Allows reuse of register contents by using
'<tt>SMC_StoreAddress</tt>' for multiple SMC instruction modifications.
Example:
<tscreen><verb>
SMC_TransferAddress JumpTo, #CloseChannel
...
SMC JumpTo, { JMP OpenChannel }
</verb></tscreen>
<label id="Store address">
<tag><tt>SMC_StoreAddress label</tt></tag>
Stores the address value in a/x to a SMC instruction address position.
Example:
<tscreen><verb>
SMC_StoreAddress GetData
...
SMC GetData, { LDA SMC_AbsAdr }
</verb></tscreen>
</descrip>
<sect1>Operational macros<p>
These marcos are determined to let read/modify/write opcodes work on parts of
SMC instructions.
<descrip>
<label id="Operate on value">
<tag><tt>SMC_OperateOnValue opcode, label</tt></tag>
Let given opcode work on the value part of a SMC instruction.
Example:
<tscreen><verb>
SMC_OperateOnValue ASL, LoadMask ; shift mask to left
...
SMC LoadMask, { LDA #$20 }
</verb></tscreen>
<label id="Operate on low-byte">
<tag><tt>SMC_OperateOnLowByte opcode, label</tt></tag>
Same as '<tt/SMC_OperateOnValue/' but renamed for better readability when
accessing low-bytes of address.
Example:
<tscreen><verb>
SMC_OperateOnLowByte DEC, AccessData
...
SMC AccessData, { LDX Data }
</verb></tscreen>
<label id="Operate on high-byte">
<tag><tt>SMC_OperateOnHighByte opcode, label</tt></tag>
Let the given opcode work on the high-byte part on a SMC-instruction.
Example:
<tscreen><verb>
NextPage:
SMC_OperateOnHighByte INC, GetPageData
...
SMC GetPageData, { LDA SourceData, X }
</verb></tscreen>
</descrip>
<sect1>Scope macros<p>
These marcos are determined to export and import SMC labels out of the current
file scope. Please handle with care! If you cannot abstain from leaving the
file scope, you should at least document the exported SMC lines very well. On
import side no checking is available if the SMC line is correct accessed (e.g.
invalid access to the value of an implied instruction)!
<descrip>
<label id="Export SMC line under given name">
<tag><tt>SMC_Export alias, label</tt></tag>
SMC label will be exported under given alias.
Example:
<tscreen><verb>
.proc GetValue
SMC LoadValue, { LDA #12 }
rts
.endproc
SMC_Export GetValueLoader, GetValue::LoadValue
</verb></tscreen>
<label id="Import SMC alias">
<tag><tt>SMC_Import alias</tt></tag>
SMC line is made accessible under given alias.
Example:
<tscreen><verb>
SMC_Import GetValueLoader
...
SMC_TransferValue GetValueLoader, #47
...
</verb></tscreen>
</descrip>
<sect>A complex example<p>
Let's have a look on a quite sophisticated example for the usage of SMC. It
not only modifies code, but also the modification of the code is modified -
allowing reuse of some instructions.
The code is from my 'memset()'implementation:
<descrip>
<tscreen><verb>
1: ...
2: SMC_StoreAddress StoreAccuFirstSection
3:
4: StoreToFirstSection:
5: SMC StoreAccuFirstSection, { sta SMC_AbsAdr, Y }
6: ...
7: RestoreCodeBranchBaseAdr:
8: SMC FirstIncHighByte, { SMC_OperateOnHighByte inc, StoreAccuFirstSection } ; code will be overwritten to 'beq RestoreCode' (*)
9: ...
10: SMC_TransferOpcode FirstIncHighByte, OPC_BEQ , x ; change code marked above with (*)
11: SMC_TransferValue FirstIncHighByte, #(restoreCode - RestoreCodeBranchBaseAdr-2), x ; set relative adress to 'RestoreCode'
12: ...
13: restoreCode:
14: SMC_TransferOpcode FirstIncHighByte, OPC_INC_abs , x ; restore original code...
15: SMC_TransferValue FirstIncHighByte, #(<(StoreToFirstSection+2)), x ; (second byte of inc contained low-byte of adress)
16: ...
</verb></tscreen>
Some explanation:
Line 2: The register pair A/X contains an address, which is stored on the
address location of a SMC line called 'StoreAccuFirstSection'. According to
cc65's calling convention, the low-byte is in accu while the high-byte is in
the X-register.
Line 5: The (modified) address is accessed.
Line 8: We have a line here, which is about to be modified (it begins with
SMC), but itself modifies code. Please note: Contrary to the rest of SMC-line
modifying macros, the 'OperateOn'-macros just expand their given arguments
into a single instruction line. These can be changed of course too.
Line 10,11: These lines construct a branch operation for line 8: The
X-register will be used to change it from 'inc StoreAccuFirstSection+2'
(high-byte operation) to 'beq restoreCode'. Please note: To calculate the
relaive branch offset, we introduced a second label
('RestoreCodeBranchBaseAdr') for to calculate it. Some could also use the
internal name of the SMC label, but you should abstain to do so - it may be
changed in the future...
Line 14,15: The original code from line 8 is reestablished.
</descrip>
</article>

424
doc/sp65.sgml Normal file
View File

@ -0,0 +1,424 @@
<!doctype linuxdoc system> <!-- -*- text-mode -*- -->
<article>
<title>sp65 Users Guide
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
<date>2012-03-11
<abstract>
sp65 is a sprite and bitmap utility that is part of the cc65 development suite.
It is used to convert graphics and bitmaps into the target formats of the
supported machines.
</abstract>
<!-- Table of contents -->
<toc>
<!-- Begin the document -->
<sect>Overview<p>
sp65 is a tool that converts images from common formats into formats used
on the 6502 platforms that are the targets of the cc65 compiler suite. In
addition, it allows some very simple operation with loaded graphics data, like
using part of an image for further processing.
The utility has been designed in a way that adding additional source or target
formats is easy. The final output is either binary, or C/assembler source.
<sect>Usage<p>
<sect1>Command line option overview<p>
The sp65 utility accepts the following options:
<tscreen><verb>
---------------------------------------------------------------------------
Usage: sp65 [options] file [options] [file]
Short options:
-V Print the version number and exit
-c fmt[,attrlist] Convert into target format
-h Help (this text)
-lc List all possible conversions
-r file[,attrlist] Read an input file
-v Increase verbosity
-w file[,attrlist] Write the output to a file
Long options:
--convert-to fmt[,attrlist] Convert into target format
--help Help (this text)
--list-conversions List all possible conversions
--pop Restore the original loaded image
--read file[,attrlist] Read an input file
--slice x,y,w,h Generate a slice from the loaded bitmap
--verbose Increase verbosity
--version Print the version number and exit
--write file[,attrlist] Write the output to a file
---------------------------------------------------------------------------
</verb></tscreen>
<sect1>Command line options in detail<p>
Below is a description of all the command line options. For the concept of
attribute lists see <ref id="attr-lists" name="below">.
<descrip>
<label id="option--convert-to">
<tag><tt>-c, --convert-to format[,attrlist]</tt></tag>
Convert a bitmap into one of the supported target formats. The option
argument must at least contain the "format" attribute. For more attributes,
see section <ref id="conversions" name="Conversions">.
<label id="option--help">
<tag><tt>-h, --help</tt></tag>
Print the short option summary shown above.
<label id="option--list-conversions">
<tag><tt>-lc, --list-conversions</tt></tag>
Print a list of possible conversions.
<label id="option--pop">
<tag><tt>--pop</tt></tag>
Restore the working copy of the bitmap from the one originally loaded from
the file. This may for example be used when creating several output files
from one input file.
<label id="option--read">
<tag><tt>-r, --read filename[,attrlist]</tt></tag>
Read an input file. The option argument must at least contain the "name"
attribute. See <ref id="input-formats" name="input formats"> for more
information.
<label id="option-v">
<tag><tt>-v, --verbose</tt></tag>
Increase verbosity. Usually only needed for debugging purposes. You may use
this option more than one time for even more verbose output.
<label id="option-V">
<tag><tt>-V, --version</tt></tag>
Print the version number of the assembler. If you send any suggestions or
bugfixes, please include the version number.
<label id="option--write">
<tag><tt>-w, --write filename[,attrlist]</tt></tag>
Write an output file. The option argument must at least contain the "name"
attribute. See <ref id="output-formats" name="output formats"> for more
information.
</descrip>
<p>
<sect>Processing pipeline<label id="processing-pipeline"><p>
sp65 consists of
<itemize>
<item>Front ends that read graphics data,
<item>processors for graphics data,
<item>converters
<item>and output modules for several formats.
</itemize>
These modules can be combined to a pipeline that reads data, does some
optional bitmap processing, converts the bitmap into a target format, and
writes this binary data to disk in one of several forms.
<sect>Attribute lists<label id="attr-lists"><p>
As described in <ref id="processing-pipeline" name="Processing pipeline">,
sp65 consists of lots of different modules that may be combined in different
ways, to convert an input bitmap to some output.
Many of the processors and converters have options to change the way, they're
working. To avoid having lots of command line options that must be parsed on
high level and passed down to the relevant parts of the program, sp65 features
something called "attribute lists". Attribute lists are lists of
attribute/value pairs. These lists are parsed by the main program module
without any knowledge about their meaning. Lower level parts just grab the
attributes they need.
In general, attribute lists look like this:
<tscreen><verb>
attr1=val1[,attr2=val2[,...]]
</verb></tscreen>
Instead of the comma, colons may also be used (even mixed).
To simplify things and to make the most common options look "normal", some
mandatory attributes may be given without an attribute name. If the attribute
name is missing, the default name is determined by the position. For example,
the option <tt/<ref id="option--read" name="--read">/ does always need a file
name. The attribute name for the file name is "name". To avoid having to type
<tscreen><verb>
sp65 --read name=ball.pcx ...
</verb></tscreen>
the first attribute gets the default name "name" assigned. So if the first
attribute doesn't have a name, it is assumed that it is the file name. This
means that instead of the line above, one can also use
<tscreen><verb>
sp65 --read ball.pcx ...
</verb></tscreen>
The second attribute for <tt/--read/ is the format of the input file. So when
using
<tscreen><verb>
sp65 --read ball.pic:pcx ...
</verb></tscreen>
a PCX file named "ball.pic" is read. The long form would be
<tscreen><verb>
sp65 --read name=ball.pic:format=pcx ...
</verb></tscreen>
Changing the order of the attributes is possible only when explicitly
specifying the names of the attributes. Using
<tscreen><verb>
sp65 --read pcx:ball.pic ...
</verb></tscreen>
will make sp65 complain, because it tries to read a file named "pcx" with an
(unknown) format of "ball.pic". The following however will work:
<tscreen><verb>
sp65 --read format=pcx:name=ball.pic ...
</verb></tscreen>
The attributes that are valid for each processor or converter are listed
below.
<sect>Input formats<label id="input-formats"><p>
Input formats are either specified explicitly when using <tt/<ref
id="option--read" name="--read">/, or are determined by looking at the
extension of the file name given.
<sect1>PCX<p>
While sp65 is prepared for more, this is currently the only possible input
format. There are no additional attributes for this format.
<sect>Conversions<label id="conversions"><p>
<sect1>GEOS bitmap<p>
The current bitmap working copy is converted to a GEOS compacted bitmap. This
format is used by several GEOS functions (i.e. 'BitmapUp') and is described
in 'The Official GEOS Programmers Reference Guide', chapter 4, section
'Bit-Mapped Graphics'.
<sect1>GEOS icon<p>
The current bitmap working copy is converted to GEOS icon format. A GEOS icon
has the same format as a C64 high resolution sprite (24x21, monochrome, 63
bytes). There are no additional attributes for this conversion.
<sect1>Koala image<p>
<sect1>Lynx sprite<p>
Lynx can handle 1, 2, 3 and 4 bits per pixel indexed sprites. The maximum size
of a sprite is roughly 508 pixels but in reality the Lynx screen is only 160 by
102 pixels which makes very large sprites useless.
The number per pixels is taken from the number of colors of the input bitmap.
There are a few attributes that you can give to the conversion software.
<descrip>
<tag/mode/
The first is what kind of encoding to use for the sprite. The attribute for
this is called "mode" and the possible values are "literal", "packed" or
"transparent". The default is "packed" if no mode is specified.
The "literal" is a totally literal mode with no packing. In this mode the
number of pixels per scanline will be a multiple of 8 both right and left from
the action point.
If the source bitmap edge ends with a color where the least significant bit is
one then there will be an extra 8 zero bits on that scan line.
So if you are using totally literal sprites and intend to change them at
runtime then please add a single pixel border far left and far right with
zeros in order to prevent graphical glitches in the game.
The standard encoding is called "packed". In this mode the sprite is packed
using run-length encoding and literal coding mixed for optimisation to
produce a small sprite.
The last encoding mode "transparent" is like packed. But here we know that
the index 0 will be transparent so we can clip off all 0 pixels from the left
and right edge of the sprite. This will produce the smallest sprite possible
on the Lynx. The sprite is not rectangular anymore.
<tag/ax/
The sprite is painted around the Anchor point. The anchor point x can be
between 0 and the width of the sprite - 1. If anchor point x is zero then
painting the sprite in location 10,20 will set the left edge of the sprite
10 pixels from the left of the Lynx screen. When the sprite is scaled by
hardware the anchor point stays in place and the sprite grows or shrinks
around the anchor point. The default value is 0 (left).
<tag/ay/
The sprite is painted around the Anchor point. The anchor point y can be
between 0 and the height of the sprite - 1. If anchor point y is zero then
painting the sprite in location 10,20 will set the top of the sprite 20
pixels from the top of the Lynx screen. When the sprite is scaled by
hardware the anchor point stays in place and the sprite grows or shrinks
around the anchor point. The default value is 0 (top).
</descrip>
<sect1>VIC2 sprite<p>
<sect>Output formats<label id="output-formats"><p>
Using <tt/<ref id="option--write" name="--write">/ it is possible to write
processed data to an output file. An attribute "name" is mandatory, it is used
as the file name for the output. The output format can be specified using an
attribute named "format". If this attribute doesn't exist, the output format
is determined by looking at the file name extension.
<sect1>Binary<p>
For this format, the processed data is written to the output file in raw
binary format. There are no additional attributes (besides "name" and
"format") for this output format.
<sect1>Assembler code<p>
For this format, the processed data is written to the output file in ca65
assembler format. There are several attributes for this output format:
<descrip>
<tag/base/
The value for this attribute specifies the numeric base for the data
values. It may be either 2, 10 or 16. The default is 16. If the base is
2, the numbers are prefixed by '%', if the base is 16, the numbers are
prefixed by '&dollar;'. For base 10, there is no prefix.
<tag/bytesperline/
The value for this attribute specifies the number of bytes output in one
line of the assembler file. The default is 16.
<tag/ident/
This is an optional attribute. When given, the output processor will wrap
the data into a <tt/.PROC/ with the given name. In addition, three constants
are added as local symbols within the <tt/.PROC/: <tt/COLORS/, <tt/WIDTH/
and <tt/HEIGHT/.
</descrip>
<sect1>C code<p>
When using C output format, a small piece of C source code is generated that
defines the data containing the output in an array of <tt/unsigned char/.
Possible attributes for this format are:
<descrip>
<tag/base/
The value for this attribute specifies the numeric base for the data values.
It may be either 10 or 16. The default is 16. If the base is 16, the numbers
are prefixed by 0x. For base 10, there is no prefix.
<tag/bytesperline/
The value for this attribute specifies the number of bytes output in one
line of the C source code. The default is 16.
<tag/ident/
This is an optional attribute. When given, the output processor will wrap
the data into an array of unsigned char with the given name. In addition,
three <tt/#define/s are added for <tt/&lt;ident&gt;_COLORS/,
<tt/&lt;ident&gt;_WIDTH/ and <tt/&lt;ident&gt;_HEIGHT/.
</descrip>
<sect>Bugs/Feedback<p>
If you have problems using the assembler, if you find any bugs, or if
you're doing something interesting with the assembler, 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>Copyright<p>
sp65 (and all cc65 binutils) are (C) Copyright 1998-2012 Ullrich von Bassewitz
and others. For usage of the binaries and/or sources the following conditions
do apply:
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>

179
doc/supervision.sgml Normal file
View File

@ -0,0 +1,179 @@
<!doctype linuxdoc system>
<article>
<title>Watara Supervision specific information for cc65
<author>Stefan A. Haubenthal, <htmlurl url="mailto:polluks@sdf.lonestar.org" name="polluks@sdf.lonestar.org">
<date>2005-07-17
<abstract>
An overview over the Supervision 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 Supervision runtime system as it comes
with the cc65 C compiler. It describes the memory layout, Supervision specific header
files, available drivers, and any pitfalls specific to that platform.
Please note that Supervision 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 Supervision target
is a 2&times;16 kbyte machine language program. It is of course
possible to change this behaviour by using one of the different linker configs.
<sect>Memory layout<p>
cc65 generated programs with the default setup run with the I/O area enabled,
which gives a usable memory range of &dollar;8000 - &dollar;FFF9.
More ROM may need additional bankswitching code.
Special locations:
<descrip>
<tag/Text screen/
<!-- The text screen is located at VRAM &dollar;4000.-->
No conio support is currently available for the Supervision.
<tag/Stack/
The C runtime stack is located at &dollar;1FFF and growing downwards.
<tag/Heap/
The C heap is located at the end of the program and grows towards the C
runtime stack.
</descrip><p>
<sect>Platform specific header files<p>
Programs containing Supervision specific code may use the <tt/supervision.h/ header file.
<sect1>Supervision specific functions<p>
<itemize>
<item>waitvblank
</itemize>
<sect1>Hardware access<p>
The following pseudo variables declared in the <tt/supervision.inc/ include file do
allow access to hardware located in the address space.
<descrip>
<tag><tt/IO/</tag>
The <tt/IO/ defines allow access to the IO chip.
</descrip><p>
<sect>Loadable drivers<p>
<sect1>Graphics drivers<p>
No graphics drivers are currently available for the Supervision.
<!--A TGI driver for the standard graphics mode (160&times;160 in 4 colors) is
available, but must be statically linked, because no file I/O is available.
See the documentation for the <htmlurl url="co65.html" name="co65 utility">
for information on how to do that.-->
<sect1>Extended memory drivers<p>
No extended memory drivers are currently available for the Supervision.
<sect1>Joystick drivers<p>
No joystick drivers are currently available for the Supervision.
<!--A joystick driver for the standard buttons is available, but must be
statically linked, because no file I/O is available. See the documentation for
the <htmlurl url="co65.html" name="co65 utility"> for information on how to do
that.-->
<sect1>Mouse drivers<p>
No mouse drivers are currently available for the Supervision.
<sect1>RS232 device drivers<p>
No communication port drivers are currently available for the Supervision.
<sect>Limitations<p>
<sect1>Disk I/O<p>
The existing library for the Supervision doesn't implement C file
I/O. There are even no hacks for the <tt/read()/ and <tt/write()/ routines.
To be more concrete, this limitation means that you cannot use any of the
following functions (and a few others):
<itemize>
<item>fclose
<item>fopen
<item>fread
<item>fprintf
<item>fputc
<item>fscanf
<item>fwrite
<item>...
</itemize>
<sect>Other hints<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
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>

156
doc/using-make.sgml Normal file
View File

@ -0,0 +1,156 @@
<!doctype linuxdoc system>
<article>
<title>Using GNU Make with cc65
<author>Oliver Schmidt, <htmlurl url="mailto:ol.sc@web.de" name="ol.sc@web.de">
<date>2009-06-26
<abstract>
How to build your program using the GNU Make utility.
</abstract>
<!-- Table of contents -->
<toc>
<!-- Begin the document -->
<sect>Overview<p>
This document describes how to build your programs using the cc65 development
tools and the GNU Make utility.
The cc65 development package doesn't come with a make utility. However this is
no issue because GNU Make works very nicely with cc65.
<sect>What is GNU Make?<p>
GNU Make is a both very powerful and very popular make utility. It might even
be called the de facto standard for make utilities. For more information see
the GNU Make home page:
<url url="http://www.gnu.org/software/make/">
The cc65 development package is available as binaries for several host systems
and can easily built for quite some additional systems. The very same is true
for GNU Make so a cc65-based project coming with a GNU Make Makefile can easily
be built by any cc65 developer no matter what host system is used.
Because of the strong alignment of the cc65 compiler with the ISO C standard it
is very well feasible to compile a single C code base both with the cc65
compiler and other C compilers like for example GCC. GNU Make turns out to be
very well suited to build projects for several target systems using multiple
compilers as it isn't tied to any C compiler.
<sect>A sample Makefile<p>
This Makefile is a fully functional sample for compiling several C sources
(here <tt/foo.c/ and <tt/bar.c/) and link the resulting object files into an
executable program (here <tt/foobar/):
<tscreen><verb>
SOURCES = foo.c bar.c
PROGRAM = foobar
ifdef CC65_TARGET
CC = $(CC65_HOME)/bin/cl65
CFLAGS = -t $(CC65_TARGET) --create-dep $(<:.c=.d) -O
LDFLAGS = -t $(CC65_TARGET) -m $(PROGRAM).map
else
CC = gcc
CFLAGS = -MMD -MP -O
LDFLAGS = -Wl,-Map,$(PROGRAM).map
endif
########################################
.SUFFIXES:
.PHONY: all clean
all: $(PROGRAM)
ifneq ($(MAKECMDGOALS),clean)
-include $(SOURCES:.c=.d)
endif
%.o: %.c
$(CC) -c $(CFLAGS) -o $@ $<
$(PROGRAM): $(SOURCES:.c=.o)
$(CC) $(LDFLAGS) -o $@ $^
clean:
$(RM) $(SOURCES:.c=.o) $(SOURCES:.c=.d) $(PROGRAM) $(PROGRAM).map
</verb></tscreen>
<bf/Important:/ When using the sample Makefile above via copy & paste it is
necessary to replace the eight spaces at the beginning of command lines (lines
26, 29 and 32) with a tab character (ASCII code 9).
<sect1>Invoking the sample Makefile<p>
Without any specific configuration the sample Makefile will compile and link
using GCC. In order to rather use cc65 the variable <tt/CC65_TARGET/ needs to be
defined. This may by done as an environment variable or simply as part of the
Makefile. However to quickly switch between compilers and/or cc65 targets it is
best done on the GNU Make command line like this:
<tscreen><verb>
make CC65_TARGET=c64
</verb></tscreen>
The sample Makefile presumes the variable <tt/CC65_HOME/ to point to the
directory cc65 is located in. Again there are several ways to define this
variable but as its value typically won't change often it is best done as an
environment variable. On Windows the cc65 .exe installer package takes care
of creating a <tt/CC65_HOME/ environment variable.
<sect1>Understanding the sample Makefile<p>
Most parts of the sample Makefile follow the guidelines in the
<htmlurl url="http://www.gnu.org/software/make/manual/make.html" name="GNU Make Manual">
that can be searched online for background information. The automatic generation of
dependency however rather works as described by the GNU Make maintainer Paul D. Smith in
<htmlurl url="http://make.paulandlesley.org/autodep.html#advanced" name="Advanced Auto-Dependencies">.
Fortunately both GCC and cc65 directly support this method in the meantime.
<sect1>Invoking the sample Makefile on Windows<p>
The recommended way to use GNU Make on Windows is to install it as part of a
Cygwin environment. For more information see the Cygwin home page:
<url url="http://www.cygwin.com/">
If however installing Cygwin shouldn't be an option for one or the other reason
then the sample Makefile may be invoked from the Windows Command Prompt (cmd.exe)
by downloading the following programs:
<itemize>
<item>make.exe: <url url="http://gnuwin32.sourceforge.net/packages/make.htm">
<item>rm.exe: <url url="http://gnuwin32.sourceforge.net/packages/coreutils.htm">
</itemize>
<sect>Target-specific Variable Values<p>
The very limited resources of the cc65 target machines now and then require
manual optimization of the build process by compiling individual source files
with different compiler options. GNU Make offers
<htmlurl url="http://www.gnu.org/software/make/manual/html_node/Target_002dspecific.html" name="Target-specific Variable Values">
perfectly suited for doing so. For example placing the code of the two modules
<tt/foo/ and <tt/bar/ in the segment <tt/FOOBAR/ can be archived with this
target-specific variable definition:
<tscreen><verb>
foo.o bar.o: CFLAGS += --code-name FOOBAR
</verb></tscreen>
</article>

269
doc/vic20.sgml Normal file
View File

@ -0,0 +1,269 @@
<!doctype linuxdoc system>
<article>
<title>Commodore VIC20 (aka VC20) specific information for cc65
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
Stefan A. Haubenthal, <htmlurl url="mailto:polluks@sdf.lonestar.org" name="polluks@sdf.lonestar.org">
<date>2004-09-13
<abstract>
An overview over the VIC20 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 VIC20 runtime system as it comes with the
cc65 C compiler. It describes the memory layout, VIC20 specific header files,
available drivers, and any pitfalls specific to that platform.
Please note that VIC20 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 VIC20 target
is a machine language program with a one line BASIC stub, which calls the
machine language part via SYS. This means that a program can be loaded as
BASIC program and started with RUN. It is of course possible to change this
behaviour by using a modified startup file and linker config.
<sect>Memory layout<p>
cc65 generated programs with the default setup run with unexpanded memory
(RAM at &dollar;A000 - &dollar;BFFF may be used for the heap),
which gives a usable memory range of &dollar;1000 - &dollar;1DFF.
All ROM entry points may be called directly without additional code.
Special locations:
<descrip>
<tag/Text screen/
The text screen is located at &dollar;1E00 (as in the standard setup).
<tag/Stack/
The C runtime stack is located at &dollar;1DFF and growing downwards.
<tag/Heap/
The C heap is located at the end of the program and grows towards the C
runtime stack.
</descrip><p>
<sect>Platform specific header files<p>
Programs containing VIC20 specific code may use the <tt/vic20.h/ or <tt/cbm.h/
header files. Using the later may be an option when writing code for more than
one CBM platform, since it includes <tt/vic20.h/ and declares several functions
common to all CBM platforms.
<sect1>VIC20 specific functions<p>
There are currently no special VIC20 functions.
<sect1>CBM specific functions<p>
Some functions are available for all (or at least most) of the Commodore
machines. See the <htmlurl url="funcref.html" name="function reference"> for
declaration and usage.
<itemize>
<item>cbm_close
<item>cbm_closedir
<item>cbm_k_setlfs
<item>cbm_k_setnam
<item>cbm_k_load
<item>cbm_k_save
<item>cbm_k_open
<item>cbm_k_close
<item>cbm_k_readst
<item>cbm_k_chkin
<item>cbm_k_ckout
<item>cbm_k_basin
<item>cbm_k_bsout
<item>cbm_k_clrch
<item>cbm_load
<item>cbm_open
<item>cbm_opendir
<item>cbm_read
<item>cbm_readdir
<item>cbm_save
<item>cbm_write
<item>get_tv
</itemize>
<sect1>Hardware access<p>
The following pseudo variables declared in the <tt/vic20.h/ header file do allow
access to hardware located in the address space. Some variables are
structures, accessing the struct fields will access the chip registers.
<descrip>
<tag><tt/VIC/</tag>
The <tt/VIC/ structure allows access to the VIC (the graphics
controller). See the <tt/_vic.h/ header file located in the include
directory for the declaration of the structure.
<tag><tt/VIA1, VIA2/</tag>
Access to the two VIA (versatile interface adapter) chips is available via
the <tt/VIA1/ and <tt/VIA2/ variables. The structure behind these variables
is explained in <tt/_6522.h/.
<tag><tt/COLOR_RAM/</tag>
A character array that mirrors the color RAM of the VIC20 at &dollar;9600.
</descrip><p>
<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>
No graphics drivers are currently available for the VIC20.
<sect1>Extended memory drivers<p>
No extended memory drivers are currently available for the VIC20.
<sect1>Joystick drivers<p>
<descrip>
<tag><tt/vic20-stdjoy.joy (vic20_stdjoy)/</tag>
Supports one standard joystick connected to the joysticks port of the VIC20.
<tag><tt/vic20-ptvjoy.joy (vic20_ptvjoy)/</tag>
Driver for the Protovision 4-player adapter contributed by Groepaz. See
<htmlurl url="http://www.protovision-online.de/hardw/hardwstart.htm"
name="http://www.protovision-online.de/hardw/hardwstart.htm"> for prices and
building instructions. Up to three joysticks are supported.
</descrip><p>
<sect1>Mouse drivers<p>
No mouse drivers are currently available for the VIC20.
<sect1>RS232 device drivers<p>
No VIC1011 drivers are currently available for the VIC20.
<sect>Limitations<p>
<sect>Other hints<p>
<sect1>Escape code<p>
For an Esc press CTRL and [ key.
<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 chosen:
<tscreen><verb>
RUN: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>Program return code<p>
The program return code (low byte) is passed back to BASIC by use of the
<tt/ST/ variable.
<sect1>Using extended memory<p>
The extended memory at $A000 may be added to the heap by using the following
code:
<tscreen><verb>
/* Check for the existence of RAM */
if (PEEK(0xA000) == POKE(0xA000, PEEK(0xA000)+1)) {<br>
/* Add it to the heap */
_heapadd ((void *) 0xA000, 0x2000);
}
</verb></tscreen>
<sect1>Interrupts<p>
The runtime for the VIC20 uses routines marked as <tt/.INTERRUPTOR/ for
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>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>