]> git.sur5r.net Git - cc65/blob - doc/c64.sgml
grc is now named grc65.
[cc65] / doc / c64.sgml
1 <!doctype linuxdoc system>
2
3 <article>
4
5 <title>Commodore 64 specific information for cc65
6 <author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
7 <date>2003-09-23
8
9 <abstract>
10 An overview over the C64 runtime system as it is implemented for the cc65 C
11 compiler.
12 </abstract>
13
14 <!-- Table of contents -->
15 <toc>
16
17 <!-- Begin the document -->
18
19 <sect>Overview<p>
20
21 This file contains an overview of the C64 runtime system as it comes with the
22 cc65 C compiler. It describes the memory layout, C64 specific header files,
23 available drivers, and any pitfalls specific to that platform.
24
25 Please note that C64 specific functions are just mentioned here, they are
26 described in detail in the separate <htmlurl url="funcref.html" name="function
27 reference">. Even functions marked as "platform dependent" may be available on
28 more than one platform. Please see the function reference for more
29 information.
30
31
32 <sect>Binary format<p>
33
34 The standard binary output format generated by the linker for the C64 target
35 is a machine language program with a one line BASIC stub, which calls the
36 machine language part via SYS. This means that a program can be loaded as
37 BASIC program and started with RUN. It is of course possible to change this
38 behaviour by using a modified startup file and linker config.
39
40
41 <sect>Memory layout<p>
42
43 cc65 generated programs with the default setup run with the I/O area and the
44 kernal ROM enabled (memory under the kernal may be used for graphics or as
45 extended memory - see the sections about graphics and extended memory
46 drivers). The BASIC ROM is disabled, which gives a usable memory range of
47 &dollar;0800 - &dollar;CFFF. This means that kernal entry points may be called
48 directly, but using the BASIC ROM is not possible without additional code.
49
50 Special locations:
51
52 <descrip>
53   <tag/Text screen/
54   The text screen is located at &dollar;400 (as in the standard setup).
55
56   <tag/Stack/
57   The C runtime stack is located at &dollar;CFFF and growing downwards.
58
59   <tag/Heap/
60   The C heap is located at the end of the program and grows towards the C
61   runtime stack.
62
63 </descrip><p>
64
65
66 <sect>Linker configurations<p>
67
68 The ld65 linker comes with a builtin config file for the Commodore&nbsp;64,
69 which is used via <tt/-t c64/ (and displayed via <tt/--dump-config c64/). The
70 c64 package comes with additional secondary linker config files, which are
71 used via <tt/-C &lt;configfile&gt;/.
72
73
74 <sect1>builtin config file<p>
75
76 The builtin configuration is tailored to C programs. It supplies the load
77 address and a small BASIC stub that starts the compiled program using a SYS
78 command.
79
80
81 <sect1><tt/c64-asm.cfg/<p>
82
83 This configuration is made for assembler programmers who don't need a special
84 setup. The default start address is &dollar;801. It can be changed with the
85 linker command line option <tt/--start-addr/. All standard segments with the
86 exception of <tt/zeropage/ are written to the output file and a two byte load
87 address is prepended.
88
89 To use this config file, assemble with <tt/-t c64/ and link with <tt/-C
90 c64-asm.cfg/. The former will make sure that correct character translation is
91 in effect, while the latter supplies the actual config. When using <tt/cl65/,
92 use both command line options.
93
94 Sample command line for <tt/cl65/:
95
96 <tscreen><verb>
97 cl65 -o file.prg -t c64 -C c64-asm.cfg source.s
98 </verb></tscreen>
99
100 To generate code that loads to &dollar;C000:
101
102 <tscreen><verb>
103 cl65 -o file.prg --start-addr $C000 -t c64 -C c64-asm.cfg source.s
104 </verb></tscreen>
105
106 It is also possible to add a small BASIC header to the program, that uses SYS
107 to jump to the program entry point (which is the start of the code segment).
108 The advantage is that the program can be started using RUN.
109
110 To generate a program with a BASIC SYS header, use
111
112 <tscreen><verb>
113 cl65 -o file.prg -u __EXEHDR__ -t c64 -C c64-asm.cfg source.s
114 </verb></tscreen>
115
116 Please note that in this case a changed start address doesn't make sense,
117 since the program must be loaded to the BASIC start address.
118
119
120 <sect>Platform specific header files<p>
121
122 Programs containing C64 specific code may use the <tt/c64.h/ or <tt/cbm.h/
123 header files. Using the later may be an option when writing code for more than
124 one CBM platform, since it includes <tt/c64.h/ and declares several functions
125 common to all CBM platforms.
126
127
128 <sect1>C64 specific functions<p>
129
130 The functions listed below are special for the C64. See the <htmlurl
131 url="funcref.html" name="function reference"> for declaration and usage.
132
133 <itemize>
134 <item>get_ostype
135 </itemize>
136
137
138 <sect1>CBM specific functions<p>
139
140 Some functions are available for all (or at least most) of the Commodore
141 machines. See the <htmlurl url="funcref.html" name="function reference"> for
142 declaration and usage.
143
144 <itemize>
145 <item>cbm_close
146 <item>cbm_closedir
147 <item>cbm_k_setlfs
148 <item>cbm_k_setnam
149 <item>cbm_k_load
150 <item>cbm_k_save
151 <item>cbm_k_open
152 <item>cbm_k_close
153 <item>cbm_k_readst
154 <item>cbm_k_chkin
155 <item>cbm_k_ckout
156 <item>cbm_k_basin
157 <item>cbm_k_bsout
158 <item>cbm_k_clrch
159 <item>cbm_load
160 <item>cbm_open
161 <item>cbm_opendir
162 <item>cbm_read
163 <item>cbm_readdir
164 <item>cbm_save
165 <item>cbm_write
166 <item>get_tv
167 </itemize>
168
169
170 <sect1>Hardware access<p>
171
172 The following pseudo variables declared in the <tt/c64.h/ header file do allow
173 access to hardware located in the address space. Some variables are
174 structures, accessing the struct fields will access the chip registers.
175
176 <descrip>
177
178   <tag><tt/VIC/</tag>
179   The <tt/VIC/ structure allows access to the VIC II (the graphics
180   controller). See the <tt/_vic2.h/ header file located in the include
181   directory for the declaration of the structure.
182
183   <tag><tt/SID/</tag>
184   The <tt/SID/ structure allows access to the SID (the sound interface
185   device). See the <tt/_sid.h/ header file located in the include directory
186   for the declaration of the structure.
187
188   <tag><tt/CIA1, CIA2/</tag>
189   Access to the two CIA (complex interface adapter) chips is available via
190   the <tt/CIA1/ and <tt/CIA2/ variables. The structure behind these variables
191   is explained in <tt/_6526.h/.
192
193   <tag><tt/COLOR_RAM/</tag>
194   A character array that mirrors the color RAM of the C64 at &dollar;D800.
195
196 </descrip><p>
197
198
199
200 <sect>Loadable drivers<p>
201
202 <sect1>Graphics drivers<p>
203
204 <em>Note:</em> All available graphics drivers for the TGI interface will use
205 the space below the I/O area and kernal ROM, so you can have hires graphics in
206 the standard setup without any memory loss or need for a changed
207 configuration.
208
209 <descrip>
210   <tag><tt/c64-hi.tgi/</tag>
211   This driver features a resolution of 320*200 with two colors and an
212   adjustable palette (that means that the two colors can be chosen out of a
213   palette of the 16 C64 colors).
214 </descrip><p>
215
216
217 <sect1>Extended memory drivers<p>
218
219 <descrip>
220
221   <tag><tt/c64-c256k.emd/</tag>
222   A driver for the C64 256K memory expansion. This driver offers 768 pages of
223   256 bytes each. Written and contributed by Marco van den Heuvel.
224
225   <tag><tt/c64-dqbb.emd/</tag>
226   A driver for the Double Quick Brown Box cartridge. This driver offers
227   64 pages of 256 bytes each. Written and contributed by Marco van den Heuvel.
228
229   <tag><tt/c64-georam.emd/</tag>
230   A driver for the Berkeley Softworks GeoRam cartridge. The driver will
231   determine the available RAM from the connected cartridge. It supports 64KB
232   up to 2048KB of RAM.
233
234   <tag><tt/c64-isepic.emd/</tag>
235   A driver for the ISEPIC cartridge. This driver offers just 8 pages of 256
236   bytes each. Written and contributed by Marco van den Heuvel.
237
238   <tag><tt/c64-ram.emd/</tag>
239   A driver for the hidden RAM below the I/O area and kernal ROM. Supports 48
240   256 byte pages. Please note that this driver is incompatible with any of the
241   graphics drivers!
242
243   <tag><tt/c64-ramcart.emd/</tag>
244   A driver for the RamCart 64/128 written and contributed by Maciej Witkowiak.
245   Will test the hardware for the available RAM.
246
247   <tag><tt/c64-reu.emd/</tag>
248   A driver for the CBM REUs. The driver will determine from the connected REU
249   if it supports 128KB of RAM or more. In the latter case, 256KB are assumed,
250   but since there are no range checks, the application can use more memory if
251   it has better knowledge about the hardware than the driver.
252
253   <tag><tt/c64-vdc.emd/</tag>
254   A driver for the VDC memory of the C128. Written and contributed by Maciej
255   Witkowiak. Can be used if the program is running in C64 mode of the C128.
256   Autodetects the amount of memory available (16 or 64K) and offers 64 or 256
257   pages of 256 bytes each.
258
259   <tag><tt/dtv-himem.emd/</tag>
260   A driver for the C64 D2TV (the second or PAL version). This driver offers
261   indeed 7680 pages of 256 bytes each.
262
263 </descrip><p>
264
265
266 <sect1>Joystick drivers<p>
267
268 <descrip>
269
270   <tag><tt/c64-hitjoy.joy/</tag>
271   Driver for the Digital Excess & Hitmen adapter contributed by Groepaz. See
272   <htmlurl url="http://www.digitalexcess.de/downloads/productions.php"
273   name="http://www.digitalexcess.de/downloads/productions.php"> on
274   instructions how to build one. Up to four joysticks are supported.
275
276   <tag><tt/c64-ptvjoy.joy/</tag>
277   Driver for the Protovision 4-player adapter contributed by Groepaz. See
278   <htmlurl url="http://www.protovision-online.de/hardw/hardwstart.htm"
279   name="http://www.protovision-online.de/hardw/hardwstart.htm"> for prices and
280   building instructions. Up to four joysticks are supported.
281
282   <tag><tt/c64-stdjoy.joy/</tag>
283   Supports up to two standard joysticks connected to the joysticks port of
284   the C64.
285
286   <tag><tt/c64-numpad.joy/</tag>
287   Supports one joystick emulated by the numberpad of the C128 in C64 mode,
288   the firebutton is labeled &dquot;5&dquot; and ENTER.
289
290 </descrip><p>
291
292
293 <sect1>Mouse drivers<p>
294
295 <descrip>
296
297   <tag><tt/c64-1351.mou/</tag>
298   Supports a standard mouse connected to port #0 of the C64.
299
300   <tag><tt/c64-joy.mou/</tag>
301   Supports a mouse emulated by a standard joystick e.g. 1350 mouse in port
302   #1 of the C64.
303
304   <tag><tt/c64-pot.mou/</tag>
305   Supports a potentiometer device e.g. Koala Pad connected to port #1 of
306   the C64.
307
308 </descrip><p>
309
310
311 <sect1>RS232 device drivers<p>
312
313 <descrip>
314
315   <tag><tt/c64-swlink.ser/</tag>
316   Driver for the SwiftLink cartridge. Supports up to 38400 baud, hardware flow
317   control (RTS/CTS) and interrupt driven receives. Note that because of the
318   peculiarities of the 6551 chip together with the use of the NMI, transmits
319   are not interrupt driven, and the transceiver blocks if the receiver asserts
320   flow control because of a full buffer.
321
322 </descrip><p>
323
324
325
326 <sect>Limitations<p>
327
328
329
330 <sect>Other hints<p>
331
332 <sect1>Passing arguments to the program<p>
333
334 Command line arguments can be passed to <tt/main()/. Since this is not
335 supported by BASIC, the following syntax was chosen:
336
337 <tscreen><verb>
338     RUN:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5
339 </verb></tscreen>
340
341 <enum>
342 <item>Arguments are separated by spaces.
343 <item>Arguments may be quoted.
344 <item>Leading and trailing spaces around an argument are ignored. Spaces within
345       a quoted argument are allowed.
346 <item>The first argument passed to <tt/main/ is the program name.
347 <item>A maximum number of 10 arguments (including the program name) are
348       supported.
349 </enum>
350
351
352 <sect1>Program return code<p>
353
354 The program return code (low byte) is passed back to BASIC by use of the
355 <tt/ST/ variable.
356
357
358 <sect1>Interrupts<p>
359
360 The runtime for the C64 uses routines marked as <tt/.INTERRUPTOR/ for
361 interrupt handlers. Such routines must be written as simple machine language
362 subroutines and will be called automatically by the interrupt handler code
363 when they are linked into a program. See the discussion of the <tt/.CONDES/
364 feature in the <htmlurl url="ca65.html" name="assembler manual">.
365
366
367
368 <sect>Bugs/Feedback<p>
369
370 If you have problems using the library, if you find any bugs, or if you're
371 doing something interesting with it, I would be glad to hear from you. Feel
372 free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
373 name="uz@cc65.org">).
374
375
376
377 <sect>License<p>
378
379 This software is provided 'as-is', without any expressed or implied
380 warranty.  In no event will the authors be held liable for any damages
381 arising from the use of this software.
382
383 Permission is granted to anyone to use this software for any purpose,
384 including commercial applications, and to alter it and redistribute it
385 freely, subject to the following restrictions:
386
387 <enum>
388 <item>  The origin of this software must not be misrepresented; you must not
389         claim that you wrote the original software. If you use this software
390         in a product, an acknowledgment in the product documentation would be
391         appreciated but is not required.
392 <item>  Altered source versions must be plainly marked as such, and must not
393         be misrepresented as being the original software.
394 <item>  This notice may not be removed or altered from any source
395         distribution.
396 </enum>
397
398 </article>