<article>
-<title>c64 specific information for cc65
+<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
<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. 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.
+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>
<tag/Stack/
The C runtime stack is located at $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 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 <configfile>/.
+
+
+<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 $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 $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>
for the declaration of the structure.
<tag><tt/CIA1, CIA2/</tag>
- Access to the two CIA (complex interface adapater) chips is available via
+ 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/_cia.h/.
+ is explained in <tt/_6526.h/.
<tag><tt/COLOR_RAM/</tag>
A character array that mirrors the color RAM of the C64 at $D800.
<sect1>Graphics drivers<p>
-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.
+<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/</tag>
This driver features a resolution of 320*200 with two colors and an
- adjustable palette (that means that the two colors can be choosen out of a
+ adjustable palette (that means that the two colors can be chosen out of a
palette of the 16 C64 colors).
</descrip><p>
<descrip>
+ <tag><tt/c64-c256k.emd/</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/</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/</tag>
- A driver for the GeoRam cartridge. The driver will always assume 2048 pages
- of 256 bytes each.
+ 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/</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/</tag>
A driver for the hidden RAM below the I/O area and kernal ROM. Supports 48
graphics drivers!
<tag><tt/c64-ramcart.emd/</tag>
- A driver for the RamCart 64/128. Will test the hardware for the available
- RAM.
+ 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/</tag>
A driver for the CBM REUs. The driver will determine from the connected REU
it has better knowledge about the hardware than the driver.
<tag><tt/c64-vdc.emd/</tag>
- A driver for the VDC memory of the C128. 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.
+ 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/</tag>
+ A driver for the C64 D2TV (the second or PAL version). This driver offers
+ indeed 7680 pages of 256 bytes each.
</descrip><p>
<descrip>
+ <tag><tt/c64-hitjoy.joy/</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/</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/</tag>
Supports up to two standard joysticks connected to the joysticks port of
the C64.
-</descrip><p>
+ <tag><tt/c64-numpad.joy/</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>
-Currently no drivers available (in fact, the API for loadable mouse drivers
-does not exist).
+<descrip>
+
+ <tag><tt/c64-1351.mou/</tag>
+ Supports a standard mouse connected to port #0 of the C64.
+
+ <tag><tt/c64-joy.mou/</tag>
+ Supports a mouse emulated by a standard joystick e.g. 1350 mouse in port
+ #1 of the C64.
+
+ <tag><tt/c64-pot.mou/</tag>
+ Supports a potentiometer device e.g. Koala Pad connected to port #1 of
+ the C64.
+
+</descrip><p>
<sect1>RS232 device drivers<p>
<tag><tt/c64-swlink.ser/</tag>
Driver for the SwiftLink cartridge. Supports up to 38400 baud, hardware flow
- control (RTS/CTS) and interrupt driven receives.
+ 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">.
</enum>
</article>
-
-
-
projects / cc65 / blobdiff