20 |
23 |
26 |
ar65 is a replacement for the libr65 archiver that was part of the cc65 C 35 | compiler suite developed by John R. Dunning. libr65 had some problems and 36 | the copyright does not permit some things which I wanted to be possible, 37 | so I decided to write a completely new assembler/linker/archiver suite 38 | for the cc65 compiler. ar65 is part of this suite.
39 | 40 |The archiver is called as follows:
45 |46 |
47 |
48 | Usage: ar65 <operation ...> lib file|module ...
49 | Operations are some of:
50 | r Add modules
51 | d Delete modules
52 | t List library table
53 | v Increase verbosity (put before other operation)
54 | x Extract modules
55 | V Print the archiver version
56 |
57 | You may add modules to a library using the 'r' command ('a' is deprecated). If the library
60 | does not exist, it is created (and a warning message is printed which you
61 | may ignore if creation of the library was your intention). You may
62 | 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 64 | the new one. The archiver prints a warning, if the module in the library 65 | has a newer timestamp than the one to add.
66 |Here's an example:
67 |68 |
69 |
70 | ar65 r mysubs.lib sub1.o sub2.o
71 |
72 | This will add two modules to the library 'mysubs.lib' creating the 75 | library if necessary. If the library contains modules named sub1.o or 76 | sub2.o, they are replaced by the new ones.
77 |Modules names in the library are stored without the path, so, using
78 |79 |
80 |
81 | ar65 v v r mysubs.lib ofiles/sub1.o ofiles/sub2.o
82 |
83 | will verbose add two modules named 'sub1.o' and 'sub2.o' to the library.
86 |Deleting modules from a library is done with the 'd' command. You may not
87 | give a path when naming the modules.
Example:
89 |90 |
91 |
92 | ar65 d mysubs.lib sub1.o
93 |
94 | This will delete the module named 'sub1.o' from the library, printing an 97 | error if the library does not contain that module.
98 | 99 |The 't' command prints a table of all modules in the library ('l' is deprecated).
100 | Any module names on the command line are ignored.
Example:
102 |103 |
104 |
105 | ar65 tv mysubs.lib
106 |
107 | Using the 'x' command, you may extract modules from the library. The
111 | modules named on the command line are extracted from the library and put
112 | into the current directory.
Note: Because of the indexing done by the archiver, the modules may have 114 | a changed binary layout, that is, a binary compare with the old module 115 | (before importing it into the library) may yield differences. The 116 | extracted modules are accepted by the linker and archiver, however, so 117 | this is not a problem.
118 |Example for extracting a module from the library:
119 |120 |
121 |
122 | ar65 x mysubs.lib sub1.o
123 |
124 | The 'V' command prints the version number of the assembler. If you send
128 | any suggestions or bugfixes, please include your version number.
In addition to these operations, the archiver will check for, and warn 130 | about duplicate external symbols in the library, every time when an 131 | operation does update the library. This is only a warning, the linker 132 | will ignore one of the duplicate symbols (which one is unspecified).
133 | 134 | 135 |ar65 (and all cc65 binutils) are (C) Copyright 1998-2000 Ullrich von 139 | Bassewitz. For usage of the binaries and/or sources the following conditions 140 | do apply:
141 |This software is provided 'as-is', without any expressed or implied 142 | warranty. In no event will the authors be held liable for any damages 143 | arising from the use of this software.
144 |Permission is granted to anyone to use this software for any purpose, 145 | including commercial applications, and to alter it and redistribute it 146 | freely, subject to the following restrictions:
147 |148 |
19 |
22 |
25 |
28 |
31 |
34 |
37 |
40 |
43 |
This file contains an overview of the Atari 2600 runtime system as it 51 | comes with the cc65 C compiler. It describes the memory layout, Atari 52 | 2600 specific header files and any pitfalls specific to that platform.
53 | 54 |The default binary output format generated by the linker for the Atari 58 | 2600 target is a 4K cartridge image.
59 | 60 |cc65 generated programs with the default setup can use RAM from 64 | $0080 to $00FF - __STACKSIZE__, where __STACKSIZE__ is 65 | the size of the system stack with a default value of 16 bytes. The 66 | size of the system stack can be customized by defining the 67 | __STACKSIZE__ linker variable.
68 |Special locations:
69 |70 |
The C runtime stack is located at $00FF - 73 | __STACKSIZE__ and growing downwards.
74 | 75 |The C heap is located at $0080 and grows upwards.
77 | 78 |When powered-up, the Atari 2600 TIA registers contain random 86 | values. During the initialization phase, the start-up code needs to 87 | initialize the TIA registers to sound values (or else the console has 88 | an unpredictable behavior). In this implementation, zeros are written 89 | to all of TIA registers during the start-up phase.
90 |Note that RIOT registers (mostly timers) are left uninitialized, as 91 | they don't have any consequence on the console behavior.
92 | 93 |Programs containing Atari 2600 specific code may use the
97 | atari2600.h header file.
The following pseudo variables declared in the atari2600.h header
99 | file allow access to the Atari 2600 TIA & RIOT chips registers.
101 |
TIAThe TIA structure allows read/write access
105 | to the Atari 2600 TIA chip registers. See the _tia.h header
106 | file located in the include directory for the declaration of the
107 | structure. Also refer to the Stella Programmer's Guide by Steve
108 | Wright for a detailed description of the chip and its registers.
RIOTThe RIOT structure allows read/write
112 | access to the Atari 2600 RIOT chip registers. See the
113 | _riot.h header file located in the include directory for the
114 | declaration of the structure. Also refer to the Stella Programmer's
115 | Guide by Steve Wright for a detailed description of the chip and its
116 | registers.
There are no drivers for the Atari 2600.
127 | 128 | 129 |TBD
133 | 134 | 135 |One may write a custom linker configuration file to tune the memory
139 | layout of a program. See the atari2600.cfg file in the cfg
140 | directory as a starting point.
This software is provided 'as-is', without any expressed or implied 147 | warranty. In no event will the authors be held liable for any damages 148 | arising from the use of this software.
149 |Permission is granted to anyone to use this software for any purpose, 150 | including commercial applications, and to alter it and redistribute it 151 | freely, subject to the following restrictions:
152 |153 |
19 |
22 |
25 |
28 |
31 |
34 |
37 |
40 |
43 |
46 |
49 |
This file contains an overview of the Atari 7800 runtime system as it 57 | comes with the cc65 C compiler. It describes the memory layout, Atari 58 | 7800 specific header files and any pitfalls specific to that platform.
59 | 60 |The default binary output format generated by the linker for the Atari 64 | 7800 target is a 48K cartridge image.
65 | 66 |There is lots of different cart hardware available for the atari7800. 70 | Some carts have ROM, RAM, sound hardware, non-volatile high score chips. 71 | In order to know what kind of hardware the cart build requires there is 72 | a header file of 128 bytes in front of the binary.
73 |The default build creates a cart file for a 48K rom cart without any 74 | extra features like the pokey audio chip or extra RAM.
75 |In order to make cc65 more user friendly the build will add the a78 76 | header automatically. This allows you to run the binary on emulators 77 | and flash carts on the real console.
78 | 79 |In order to boot the game in a mode that supports atari7800 functions 83 | the cart must be encrypted after the linking phase. 84 | There is a program called sign7800 that can be used to sign the cart. 85 | The encryption is not required for running the cart on emulators. 86 | You can also run atari2600 games without encryption.
87 | 88 |cc65 generated programs with the default setup can use RAM from 92 | from $1800 to $203f. 93 | The 4k RAM is then mapped to zero page area. 94 | $2040 to $20ff is visible as zero page. 95 | After that we have a vero small RAM area that is unused. 96 | $2100 to $213f. 97 | Then we mirror a second block from the RAM to become the hardware stack. 98 | This would be from $2140 to $21ff.
99 |The C-stack starts at $2800 and it can grow down to $2200.
100 |size of the system stack can be customized by defining the 101 | __STACKSIZE__ linker variable.
102 |Special locations:
103 |104 |
The C runtime stack is located at $2800 - 107 | __STACKSIZE__ and growing downwards.
108 | 109 |The C heap is located at $2200 and grows upwards.
111 | 112 |When powered-up, the Atari 7800 TIA registers contain random 120 | values. During the initialization phase, the start-up code needs to 121 | initialize the TIA registers to sound values (or else the console has 122 | an unpredictable behavior). In this implementation, zeros are written 123 | to all of TIA registers during the start-up phase.
124 |Note that RIOT registers (mostly timers) are left uninitialized, as 125 | they don't have any consequence on the console behavior.
126 | 127 |Programs containing Atari 7800 specific code may use the
131 | atari7800.h header file.
The following pseudo variables declared in the atari7800.h header
133 | file allow access to the Atari 7800 TIA, MARIA & RIOT chips registers.
135 |
TIAThe TIA structure allows read/write access
139 | to the Atari 7800 TIA chip registers. See the _tia.h header
140 | file located in the include directory for the declaration of the
141 | structure. Also refer to the Stella Programmer's Guide by Steve
142 | Wright for a detailed description of the chip and its registers.
RIOTThe RIOT structure allows read/write
146 | access to the Atari 7800 RIOT chip registers. See the
147 | _riot.h header file located in the include directory for the
148 | declaration of the structure. Also refer to the Stella Programmer's
149 | Guide by Steve Wright for a detailed description of the chip and its
150 | registers.
MARIAThe MARIA structure allows read/write
154 | access to the Atari 7800 MARIA chip registers. See the
155 | _maria.h header file located in the include directory for the
156 | declaration of the structure.
There are no drivers for the Atari 7800.
167 | 168 | 169 |TBD
173 | 174 | 175 |One may write a custom linker configuration file to tune the memory
179 | layout of a program. See the atari7800.cfg file in the cfg
180 | directory as a starting point.
This software is provided 'as-is', without any expressed or implied 187 | warranty. In no event will the authors be held liable for any damages 188 | arising from the use of this software.
189 |Permission is granted to anyone to use this software for any purpose, 190 | including commercial applications, and to alter it and redistribute it 191 | freely, subject to the following restrictions:
192 |193 |
19 |
22 |
25 |
28 |
37 |
47 |
50 |
58 |
This file contains an overview of the C16 runtime system as it comes with the 66 | cc65 C compiler. It describes the memory layout, C16/116 specific header 67 | files, available drivers, and any pitfalls specific to that platform.
68 |Please note that C16 specific functions are just mentioned here, they are 69 | described in detail in the separate 70 | function reference. Even functions marked as "platform dependent" may be available on 71 | more than one platform. Please see the function reference for more 72 | information.
73 |Since the C16/C116 and the Commodore Plus/4 are almost identical (the former 74 | don't have the 6551 ACIA and only 16KB of memory), the 75 | Plus/4 documentation is also worth a look. The 76 | difference between both cc65 targets is that the Plus/4 runtime uses banking 77 | to support full 64K RAM, while the C16 does not use banking and supports up to 78 | 32K RAM. Because banking is not needed, most C16 programs will be somewhat 79 | smaller than the same program compiled for the Plus/4. However, programs C16 80 | will always run on the Plus/4, while the reverse is not necessarily true.
81 | 82 | 83 |The standard binary output format generated by the linker for the C16/116 87 | target is a machine language program with a one line BASIC stub which, calls 88 | the machine language part via SYS. This means that a program can be loaded as 89 | BASIC program and started with RUN. It is of course possible to change this 90 | behaviour by using a modified startup file and linker config.
91 | 92 | 93 |cc65 generated programs with the default setup run with the kernal and basic 97 | banked in. This gives a usable memory range of $1000 - $4000 98 | (or $8000 if the machine is equipped with 32K RAM or more). Having the 99 | kernal and basic ROMs banked in means, that ROM entry points may be called 100 | directly from user code.
101 |Special locations:
102 |103 |
The text screen is located at $C00 (as in the standard setup).
106 | 107 |The color RAM is located at $800 (standard location).
109 | 110 |The C runtime stack is located at $3FFF ($7FFF in case of a 112 | machine with 32K of memory or more) and growing downwards.
113 | 114 |The C heap is located at the end of the program and grows towards the C 116 | runtime stack.
117 | 118 |Programs containing C16 specific code may use the c16.h or cbm.h
128 | header files. Using the later may be an option when writing code for more than
129 | one CBM platform, since it includes c16.h and declares several functions
130 | common to all CBM platforms.
Please note that most of the header file declarations from the c16.h
132 | header file are shared between the C16 and Plus/4 configurations. For this
133 | reason, most of it is located in a common header file named cbm264.h.
There are currently no special C16/C116 functions.
142 | 143 | 144 |Some functions are available for all (or at least most) of the Commodore 149 | machines. See the 150 | function reference for 151 | declaration and usage.
152 |153 |
Some CPU related functions are available for some of the Commodore 188 | machines. See the 189 | function reference for 190 | declaration and usage.
191 |192 |
The following pseudo variables declared in the c16.h header file do
204 | allow access to hardware located in the address space. Some variables are
205 | structures, accessing the struct fields will access the chip registers.
207 |
TEDThe TED structure allows access to the TED chip. See the
211 | _ted.h header file located in the include directory for the
212 | declaration of the structure.
COLOR_RAMA character array that mirrors the color RAM of the C16 at $0800.
216 | 217 |The names in the parentheses denote the symbols to be used for static linking of the drivers.
227 | 228 | 229 |No graphics drivers are currently available for the C16/C116.
234 | 235 | 236 |241 |
c16-ram.emd (c16_ram_emd)A driver for the hidden RAM below the BASIC and KERNAL ROMs. Supports 125 245 | pages with 256 bytes each if the machine is equipped with 64K of memory 246 | (a Plus/4 or a memory extended C16/116).
247 | 248 |259 |
c16-stdjoy.joy (c16_stdjoy_joy)Supports up to two joysticks connected to the standard joysticks port of 263 | the Commodore 16/116.
264 | 265 |No mouse drivers are currently available for the C16/C116.
276 | 277 | 278 |The Commodore 16 does not have a builtin ACIA and no RS232 extensions are 283 | known. For this reason, there are no RS232 drivers available. Please note that 284 | the standard Plus/4 driver will not run together with the C16 285 | library, because the latter does not support interrupts needed by the driver.
286 | 287 | 288 |Command line arguments can be passed to main(). Since this is not
303 | supported by BASIC, the following syntax was chosen:
305 |
306 |
307 | RUN:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5
308 |
309 | 312 |
main is the program name.The program return code (low byte) is passed back to BASIC by use of the
329 | ST variable.
The runtime for the C16 uses routines marked as .INTERRUPTOR for
337 | interrupt handlers. Such routines must be written as simple machine language
338 | subroutines and will be called automatically by the interrupt handler code
339 | when they are linked into a program. See the discussion of the .CONDES
340 | feature in the
341 | assembler manual.
This software is provided 'as-is', without any expressed or implied 349 | warranty. In no event will the authors be held liable for any damages 350 | arising from the use of this software.
351 |Permission is granted to anyone to use this software for any purpose, 352 | including commercial applications, and to alter it and redistribute it 353 | freely, subject to the following restrictions:
354 |355 |
20 |
ZEROPAGE segment
24 | STARTUP segment
25 | CODE segment
26 | BSS segment
27 | DATA segment
28 | RODATA segment
29 | FEATURES table
30 | 32 |
The C libraries and code generation depend directly on a suitable linker configuration.
45 | There are premade configuration files in the cfg/ directory, normally chosen by the
46 | linker's selected target. These can be used as a template for customization.
The C libraries depend on several special segments to be defined in your linker configuration. 48 | Generated code will also use some of them by default. 49 | Some platform libraries have additional special segments.
50 |Memory areas are free to be defined in a way that is appropriate to each platform, 51 | and the segments they contain are used as a layer of semantics and abstraction, 52 | to allow much of the reorganization to be done with the linker config, 53 | rather than requiring platform-specific code source changes.
54 | 55 |ZEROPAGE segment
56 | Used by the C library and generated code for efficient internal and temporary state storage, 60 | also called "pseudo-registers".
61 | 62 |STARTUP segment
63 | Used by each platform instance of the C library in crt0.s to contain the entry point
67 | of the program.
The startup module will export __STARTUP__ : absolute = 1 to force the linker to
69 | always include crt0.s from the library.
CODE segment
72 | The default segment for generated code, and most C library code will be located here.
76 |Use #pragma code-name to redirect generated code to another segment.
BSS segment
79 | Used for uninitialized variables. 83 | Originally an acronym for "Block Started by Symbol", but the meaning of this is now obscure.
84 |Use #pragma bss-name to redirect uninitialized variables to another segment.
DATA segment
87 | Used for initialized variables.
91 |On some platforms, this may be initialized as part of the program loading process,
92 | but on others it may have a separate LOAD and RUN address,
93 | allowing copydata to copy the initialization from the loaded location
94 | into their run destination in RAM.
Use #pragma data-name to redirect initialized variables to another segment.
RODATA segment
98 | Used for read-only (constant) data.
102 |Use #pragma rodata-name to redirect constant data to another segment.
FEATURES table
105 | This currently defines table locations for the CONDES
109 | constructor, destructor, and interruptor features.
110 | Some platform libraries use these.
The constructors will be called with initlib at startup,
112 | and the destructors with donelib at program exit.
113 | Interruptors are called with callirq.
There are two calling conventions used in cc65:
126 |127 |
cdecl - passes all parameters on the C-stack.
129 |
130 | fastcall - passes the rightmost parameter in
132 | registers A/X/sreg and all others on the C-stack.
133 |
134 | The default convention is fastcall, but this can be changed with
138 | the --all-cdecl command line option. If a convention is specified in
139 | the function's declaration, that convention will be used instead.
140 | Variadic functions will always use cdecl convention.
If the --standard command line option is used,
142 | the cdecl and fastcall keywords will not be available.
143 | The standard compliant variations __cdecl__ and __fastcall__ are always available.
If a function has a prototype, parameters are pushed to the C-stack as their respective types
145 | (i.e. a char parameter will push 1 byte), but if a function has no prototype, default
146 | promotions will apply. This means that with no prototype, char will be promoted
147 | to int and be pushed as 2 bytes. "K & R"-style forward declarations may be used,
148 | but they will function the same as if no prototype was used.
If the function is declared as fastcall, the rightmost argument will be loaded into
155 | the A/X/sreg registers:
157 |
A - 8-bit parameter, or low byte of larger types
159 |
160 | X - 16-bit high byte, or second byte of 32-bits
162 |
163 | sreg - Zeropage pseudo-register including high 2 bytes of 32-bit parameter
165 |
166 | All other parameters will be pushed to the C-stack from left to right. 170 | The rightmost parameter will have the lowest address on the stack, 171 | and multi-byte parameters will have their least significant byte at the lower address.
172 |The sp pseudo-register is a zeropage pointer to the base of the C-stack.
173 | If the function is variadic, the Y register will contain the number of
174 | bytes pushed to the stack for this function.
Example: 176 |
177 |
178 | // C prototype
179 | void cdecl foo(unsigned bar, unsigned char baz);
180 |
181 | ; C-stack layout within the function:
182 | ;
183 | ; +------------------+
184 | ; | High byte of bar |
185 | ; Offset 2 ->+------------------+
186 | ; | Low byte of bar |
187 | ; Offset 1 ->+------------------+
188 | ; | baz |
189 | ; Offset 0 ->+------------------+
190 |
191 | ; Example code for accessing bar. The variable is in A/X after this code snippet:
192 | ;
193 | ldy #2 ; Offset of high byte of bar
194 | lda (sp),y ; High byte now in A
195 | tax ; High byte now in X
196 | dey ; Offset of low byte of bar
197 | lda (sp),y ; Low byte now in A
198 |
199 | If the function has a return value, it will appear in the A/X/sreg registers.
Functions with an 8-bit return value (char or unsigned char) are expected
212 | to promote this value to a 16-bit integer on return, and store the high byte in X.
213 | The compiler will depend on the promoted value in some cases (e.g. implicit conversion to int),
214 | and failure to return the high byte in X will cause unexpected errors.
215 | This problem does not apply to the sreg pseudo-register, which is only
216 | used if the return type is 32-bit.
If the function has a void return type, the compiler will not depend on the result
218 | of A/X/sreg, so these may be clobbered by the function.
The C-stack pointer sp must be restored by the function to its value before the
220 | function call prologue. It may pop all of its parameters from the C-stack
221 | (e.g. using the runtime function popa),
222 | or it could adjust sp directly.
223 | If the function is variadic, the Y register contains the number of bytes
224 | pushed to the stack on entry, which may be added to sp to restore its
225 | original state.
The internal pseudo-register regbank must not be changed by the function.
The Y register may be clobbered by the function.
232 | The compiler will not depend on its state after a function call.
The A/X/sreg registers may be clobbered if any of them
234 | are not used by the return value (see above).
Many of the internal pseudo-registers used by cc65 are available for 236 | free use by any function called by C, and do not need to be preserved. 237 | Note that if another C function is called from your assembly function, 238 | it may clobber any of these itself:
239 |240 |
tmp1 .. tmp4
242 |
243 | ptr1 .. ptr4
245 |
246 | regsave
248 |
249 | sreg (if unused by return)
251 |
252 | 19 |
22 |
29 |
32 |
chrcvt65 is a vector font converter. It is able to convert a "BGI Stroked 40 | Font" to a compact TGI native vector font. See the function 41 | tgi_load_vectorfont for usage.
42 | 43 | 44 | 45 |The chrcvt65 utility converts the font of one Borland file to its cc65 equivalent.
49 | 50 | 51 |The program may be called as follows:
56 |57 |
58 |
59 | ---------------------------------------------------------------------------
60 | Usage: chrcvt65 [options] file [options] [file]
61 | Short options:
62 | -h Help (this text)
63 | -v Be more verbose
64 | -V Print the version number and exit
65 |
66 | Long options:
67 | --help Help (this text)
68 | --verbose Be more verbose
69 | --version Print the version number and exit
70 | ---------------------------------------------------------------------------
71 |
72 | Here is a description of all the command line options:
81 |82 |
-v, --verboseIncrease the converter verbosity.
86 | 87 | 88 |-h, --helpPrint the short option summary shown above.
90 | 91 | 92 |-V, --versionPrint the version number of the utility. When submitting a bug report, 94 | please include the operating system you're using, and the compiler 95 | version.
96 |The converter will read one CHR file per invocation and write the font 104 | in TCH format to a new file.
105 |Example output for the command 106 |
107 |
108 | chrcvt65 --verbose LITT.CHR
109 |
110 |
113 |
114 | BGI Stroked Font V1.1 - Aug 12, 1991
115 | Copyright (c) 1987,1988 Borland International
116 |
117 | chrcvt65 is (C) Copyright 2009, Ullrich von Bassewitz. For usage of the 126 | binaries and/or sources the following conditions apply:
127 |This software is provided 'as-is', without any expressed or implied 128 | warranty. In no event will the authors be held liable for any damages 129 | arising from the use of this software.
130 |Permission is granted to anyone to use this software for any purpose, 131 | including commercial applications, and to alter it and redistribute it 132 | freely, subject to the following restrictions:
133 |134 |
This will not only help to find errors between separate modules, it will also 21 | generate better code, since the compiler must not assume that a variable sized 22 | parameter list is in place and must not pass the argument count to the called 23 | function. This will lead to shorter and faster code.
24 | 25 | 26 | 27 |Variable declarations in nested blocks are usually a good thing. But with 31 | cc65, there is a drawback: Since the compiler generates code in one pass, it 32 | must create the variables on the stack each time the block is entered and 33 | destroy them when the block is left. This causes a speed penalty and larger 34 | code.
35 | 36 | 37 | 38 |The compiler needs hints from you about the code to generate. It will try to 42 | optimize the generated code, but follow the outline you gave in your C 43 | program. So for example, when accessing indexed data structures, get a pointer 44 | to the element and use this pointer instead of calculating the index again and 45 | again. If you want to have your loops unrolled, or loop invariant code moved 46 | outside the loop, you have to do that yourself.
47 | 48 | 49 | 50 |While long support is necessary for some things, it's really, really slow on 54 | the 6502. Remember that any long variable will use 4 bytes of memory, and any 55 | operation works on double the data compared to an int.
56 | 57 | 58 | 59 |The 6502 CPU has no opcodes to handle signed values greater than 8 bit. So 63 | sign extension, test of signedness etc. has to be done with extra code. As a 64 | consequence, the code to handle signed operations is usually a bit larger and 65 | slower than the same code for unsigned types.
66 | 67 | 68 | 69 |While in arithmetic operations, chars are immediately promoted to ints, they 73 | are passed as chars in parameter lists and are accessed as chars in variables. 74 | The code generated is usually not much smaller, but it is faster, since 75 | accessing chars is faster. For several operations, the generated code may be 76 | better if intermediate results that are known not to be larger than 8 bit are 77 | casted to chars.
78 |You should especially use unsigned chars for loop control variables if the 79 | loop is known not to execute more than 255 times.
80 | 81 | 82 | 83 |When indexing into an array, the compiler has to calculate the byte offset 87 | into the array, which is the index multiplied by the size of one element. When 88 | doing the multiplication, the compiler will do a strength reduction, that is, 89 | replace the multiplication by a shift if possible. For the values 2, 4 and 8, 90 | there are even more specialized subroutines available. So, array access is 91 | fastest when using one of these sizes.
92 | 93 | 94 | 95 |Since cc65 is not building an explicit expression tree when parsing an 99 | expression, constant subexpressions may not be detected and optimized properly 100 | if you don't help. Look at this example:
101 |102 |
103 |
104 | #define OFFS 4
105 | int i;
106 | i = i + OFFS + 3;
107 |
108 | The expression is parsed from left to right, that means, the compiler sees 'i', 111 | and puts it contents into the secondary register. Next is OFFS, which is 112 | constant. The compiler emits code to add a constant to the secondary register. 113 | Same thing again for the constant 3. So the code produced contains a fetch 114 | of 'i', two additions of constants, and a store (into 'i'). Unfortunately, the 115 | compiler does not see, that "OFFS + 3" is a constant for itself, since it does 116 | its evaluation from left to right. There are some ways to help the compiler 117 | to recognize expression like this:
118 |119 |
The compiler is not always smart enough to figure out, if the rvalue of an 137 | increment is used or not. So it has to save and restore that value when 138 | producing code for the postincrement and postdecrement operators, even if this 139 | value is never used. To avoid the additional overhead, use the preincrement 140 | and predecrement operators if you don't need the resulting value. That means, 141 | use
142 |143 |
144 |
145 | ...
146 | ++i;
147 | ...
148 |
149 | instead of
152 |153 |
154 |
155 | ...
156 | i++;
157 | ...
158 |
159 | The compiler produces optimized code, if the value of a pointer is a constant. 168 | So, to access direct memory locations, use
169 |170 |
171 |
172 | #define VDC_STATUS 0xD601
173 | *(char*)VDC_STATUS = 0x01;
174 |
175 | That will be translated to
178 |179 |
180 |
181 | lda #$01
182 | sta $D601
183 |
184 | The constant value detection works also for struct pointers and arrays, if the 187 | subscript is a constant. So
188 |189 |
190 |
191 | #define VDC ((unsigned char*)0xD600)
192 | #define STATUS 0x01
193 | VDC[STATUS] = 0x01;
194 |
195 | will also work.
198 |If you first load the constant into a variable and use that variable to access 199 | an absolute memory location, the generated code will be much slower, since the 200 | compiler does not know anything about the contents of the variable.
201 | 202 | 203 | 204 |Initialization of local variables when declaring them gives shorter and faster 208 | code. So, use
209 |210 |
211 |
212 | int i = 1;
213 |
214 | instead of
217 |218 |
219 |
220 | int i;
221 | i = 1;
222 |
223 | But beware: To maximize your savings, don't mix uninitialized and initialized 226 | variables. Create one block of initialized variables and one of uniniitalized 227 | ones. The reason for this is, that the compiler will sum up the space needed 228 | for uninitialized variables as long as possible, and then allocate the space 229 | once for all these variables. If you mix uninitialized and initialized 230 | variables, you force the compiler to allocate space for the uninitialized 231 | variables each time, it parses an initialized one. So do this:
232 |233 |
234 |
235 | int i, j;
236 | int a = 3;
237 | int b = 0;
238 |
239 | instead of
242 |243 |
244 |
245 | int i;
246 | int a = 3;
247 | int j;
248 | int b = 0;
249 |
250 | The latter will work, but will create larger and slower code.
253 | 254 | 255 | 256 |When addressing an array via a pointer, don't use the plus and dereference 260 | operators, but the array operator. This will generate better code in some 261 | common cases.
262 |Don't use
263 |264 |
265 |
266 | char* a;
267 | char b, c;
268 | char b = *(a + c);
269 |
270 | Use
273 |274 |
275 |
276 | char* a;
277 | char b, c;
278 | char b = a[c];
279 |
280 | instead.
283 | 284 | 285 | 286 |Register variables may give faster and shorter code, but they do also have an 290 | overhead. Register variables are actually zero page locations, so using them 291 | saves roughly one cycle per access. The calling routine may also use register 292 | variables, so the old values have to be saved on function entry and restored 293 | on exit. Saving and restoring has an overhead of about 70 cycles per 2 byte 294 | variable. It is easy to see, that - apart from the additional code that is 295 | needed to save and restore the values - you need to make heavy use of a 296 | variable to justify the overhead.
297 |As a general rule: Use register variables only for pointers that are 298 | dereferenced several times in your function, or for heavily used induction 299 | variables in a loop (with several 100 accesses).
300 |When declaring register variables, try to keep them together, because this 301 | will allow the compiler to save and restore the old values in one chunk, and 302 | not in several.
303 |And remember: Register variables must be enabled with -r or -Or.
The language rules for constant numeric values specify that decimal constants 311 | without a type suffix that are not in integer range must be of type long int 312 | or unsigned long int. So a simple constant like 40000 is of type long int! 313 | This is often unexpected and may cause an expression to be evaluated with 32 314 | bits. While in many cases the compiler takes care about it, in some places it 315 | can't. So be careful when you get a warning like
316 |317 |
318 |
319 | test.c(7): Warning: Constant is long
320 |
321 | Use the U, L or UL suffixes to tell the compiler the desired
324 | type of a numeric constant.
Since cc65 has the "wrong" calling order, the location of the fixed parameters 332 | in a variadic function (a function with a variable parameter list) depends on 333 | the number and size of variable arguments passed. Since this number and size 334 | is unknown at compile time, the compiler will generate code to calculate the 335 | location on the stack when needed.
336 |Because of this additional code, accessing the fixed parameters in a variadic 337 | function is much more expensive than access to parameters in a "normal" 338 | function. Unfortunately, this additional code is also invisible to the 339 | programmer, so it is easy to forget.
340 |As a rule of thumb, if you access such a parameter more than once, you should 341 | think about copying it into a normal variable and using this variable instead.
342 | 343 | 344 | 345 | 346 | -------------------------------------------------------------------------------- /creativision.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 |19 |
22 |
25 |
28 |
34 |
44 |
50 |
53 |
This file contains an overview of the Creativision runtime system as it comes 61 | with the cc65 C compiler. It describes the memory layout, Creativision specific header 62 | files, available drivers, and any pitfalls specific to that platform.
63 |Please note that Creativision specific functions are just mentioned here, they are 64 | described in detail in the separate 65 | function reference. Even functions marked as "platform dependent" may be available on 66 | more than one platform. Please see the function reference for more information.
67 | 68 | 69 |The standard binary output format generated by the linker for the Creativision target 73 | is a 4 KB ROM image. To create an 8 KB ROM a custom linker script has 74 | to be used.
75 | 76 |cc65 generated programs with the default setup are 4 KB in size, 80 | occupying $B000 - $BFFF. Usable memory space for the 81 | user program is $B000 - $BEFF. $BF00 - 82 | $BFFF is reserved for the runtime and cartridge configuration 83 | area.
84 |Special locations:
85 |86 |
The text screen is located at VRAM $1000.
89 | 90 |The C runtime stack is located at $03FF and growing downwards.
92 | 93 |The available RAM for cc65 programs of an unexpanded Creativision 95 | starts at $01FA and ends at $03FF.
96 | 97 |The C heap is located at the end of the program's data area and 99 | grows towards the C runtime stack.
100 | 101 |Programs containing Creativision specific code may use the creativision.h header file.
118 |
No graphics drivers are currently available for the Creativision.
140 | 141 | 142 |No extended memory drivers are currently available for the Creativision.
147 | 148 | 149 |154 |
creativision-stdjoy.joy (creativisionstd_joy)A joystick driver for the standard joystick is available.
158 | 159 |No mouse drivers are currently available for the Creativision.
168 | 169 | 170 |No communication port drivers are currently available for the Creativision.
175 | 176 | 177 | 178 |The existing library for the Creativision doesn't implement C file
187 | I/O. There are even no hacks for the read() and write() routines.
To be more concrete, this limitation means that you cannot use any of the 189 | following functions (and a few others):
190 |191 |
This software is provided 'as-is', without any expressed or implied 215 | warranty. In no event will the authors be held liable for any damages 216 | arising from the use of this software.
217 |Permission is granted to anyone to use this software for any purpose, 218 | including commercial applications, and to alter it and redistribute it 219 | freely, subject to the following restrictions:
220 |221 |
18 |
21 |
24 |
27 |
30 |
This document describes how to debug your programs using the cc65 development 38 | tools and the VICE or Oricutron emulator.
39 | 40 | 41 | 42 |VICE is an emulator for many of the CBM machines. It runs on Unix, MS-DOS, 46 | Win32, OS/2, Acorn RISC OS, BeOS, QNX 6.x, Amiga, GP2X and Mac OS X. It emulates 47 | the Commodore 64, 128, VIC20, PET and the 600/700 machines. For more information 48 | see the VICE home page:
49 |50 | http://vice-emu.sourceforge.net/.
51 |VICE has a builtin machine language monitor that may be used for debugging 52 | your programs. Using an emulator for debugging has some advantages:
53 |54 |
VICE support is mostly done via a label file that is generated by the linker
75 | and that may be read by the VICE monitor, so it knows about your program.
76 | Source level debugging is not available, you have to debug your programs
77 | in the assembler view.
The first step is to generate object files that contain information about 79 | all labels in your sources, not just the exported ones. This can be done 80 | by several means:
81 |82 |
87 |
88 | .debuginfo +
89 |
90 | -g switch when invoking the compiler. The compiler will
95 | then place a .debuginfo command into the generated assembler source.
96 | So, if you have just C code, all you need is to invoke the compiler with
100 | -g. If you're using assembler code, you have to use -g for the
101 | assembler, or add ".debuginfo on" to your source files. Since the
102 | generated debug info is not appended to the generated executables, it is a
103 | good idea to always use -g. It makes the object files and libraries
104 | slightly larger (~30%), but this is usually not a problem.
The second step is to tell the linker that it should generate a VICE label
106 | file. This is done by the -Ln switch followed by the name of the label
107 | file (I'm usually using a .lbl extension for these files). An example for
108 | a linker command line would be:
110 |
111 |
112 | ld65 -o hello -t c64 -Ln hello.lbl -m hello.map hello.o c64.lib
113 |
114 |
118 |
119 | ld65 -o hello.tap -t atmos -Ln hello.sym -m hello.map hello.o atmos.lib
120 |
121 | This will generate a file named hello.lbl that contains all symbols used in 124 | your program.
125 |Note: The runtime libraries and startup files were generated with 126 | debug info, so you don't have to care about this.
127 | 128 | 129 | 130 |Load your program, then enter the monitor and use the "ll" command to
134 | load your label file like this:
136 |
137 |
138 | ll "hello.lbl"
139 |
140 | You will get lots of warnings and even a few errors. You may ignore safely all 143 | these warnings and errors as long as they reference any problems VICE thinks 144 | it has with the labels.
145 |After loading the labels, they are used by VICE in the disassembler listing, 146 | and you may use them wherever you need to specify an address. Try
147 |148 |
149 |
150 | d ._main
151 |
152 | as an example (note that VICE needs a leading dot before all labels, and that 155 | the compiler prepends an underline under most named labels).
156 |If you start the emulator from the commandline, you can also load the labels 157 | directly using something like this:
158 |159 |
160 |
161 | x64sc -moncommands hello.lbl hello.prg
162 |
163 | Load your program, then enter the monitor and use the "sl" command to
171 | load your label file like this:
173 |
174 |
175 | sl hello.sym
176 |
177 | After loading the labels, they are used by Oricutron in the disassembler listing, 180 | and you may use them wherever you need to specify an address. Try
181 |182 |
183 |
184 | d ._main
185 |
186 | as an example.
189 | 190 | 191 | 192 | 193 | 194 | -------------------------------------------------------------------------------- /dio.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 |19 |
22 |
25 |
28 |
Prior to using these functions a handle to the device has to be obtained. This
36 | is done with the dio_open function. After use, the handle should be
37 | released with the dio_close function.
39 |
40 |
41 | dhandle_t __fastcall__ dio_open (unsigned char device);
42 |
43 | The device specifies the device to access.
47 |
48 |
49 | unsigned char __fastcall__ dio_close (dhandle_t handle);
50 |
51 | Closes a handle obtained by dio_open. Returns status code.
The read and write functions are:
60 |61 |
62 |
63 | unsigned char __fastcall__ dio_read (dhandle_t handle,
64 | unsigned sect_num,
65 | void *buffer);
66 |
67 | This function will read the sector specified by sect_num into the memory
70 | location at buffer.
72 |
73 |
74 | unsigned char __fastcall__ dio_write (dhandle_t handle,
75 | unsigned sect_num,
76 | const void *buffer);
77 |
78 | This function will write the memory contents at buffer to the sector specified
81 | by sect_num. No verify is performed.
83 |
84 |
85 | unsigned char __fastcall__ dio_write_verify (dhandle_t handle,
86 | unsigned sect_num,
87 | const void *buffer);
88 |
89 | This function will write the memory contents at buffer to the sector specified
92 | by sect_num. A verification is performed.
Use the
95 | dio_query_sectsize function to query
96 | the size of a sector and the
97 | dio_query_sectcount
98 | function to query the number of available sectors.
All these functions will return 0 for success and an OS specific error code in 101 | case of failure.
102 | 103 | 104 |Some systems support multiple diskette formats which have different sector sizes 108 | and/or different sector counts.
109 | 110 |The following function returns the sector size of the currently inserted disk:
111 |112 |
113 |
114 | unsigned __fastcall__ dio_query_sectsize (dhandle_t handle);
115 |
116 | On the Atari platform, the sector size is handled specially. Please refer 119 | to the DIO section in the 120 | Atari-specific platform documentation.
121 | 122 |The following function returns the sector count of the currently inserted disk:
123 |124 |
125 |
126 | unsigned __fastcall__ dio_query_sectcount (dhandle_t handle);
127 |
128 | Since the read and write functions expect a sector number, for systems where 135 | the sectors aren't addressed by a logical sector number (e.g. CBM devices), 136 | there are 2 conversion functions. One of them converts a logical sector number 137 | to a head/track/sector triple. The other conversion function works the other 138 | way round.
139 |140 |
141 |
142 | unsigned char __fastcall__ dio_phys_to_log (dhandle_t handle,
143 | const dio_phys_pos *physpos,
144 | unsigned *sectnum);
145 |
146 | This function converts track/head/sector to logical sector number.
149 |150 |
151 |
152 | unsigned char __fastcall__ dio_log_to_phys (dhandle_t handle,
153 | const unsigned *sectnum,
154 | dio_phys_pos *physpos);
155 |
156 | This function converts a logical sector number to track/head/sector notation.
159 | 160 |Note, that on systems which natively use logical sector numbers (e.g. Atari),
161 | the conversion functions are dummies. They ignore head/track
162 | (dio_phys_to_log) or return them as zero (dio_log_to_phys).
163 | The logical sector number is returned as physical sector and vice versa.
19 |
22 |
25 |
31 |
41 |
47 |
50 |
This file contains an overview of the Gamate runtime system as it comes 58 | with the cc65 C compiler. It describes the memory layout, Gamate specific header 59 | files, available drivers, and any pitfalls specific to that platform.
60 |Please note that Gamate specific functions are just mentioned here, they are 61 | described in detail in the separate 62 | function reference. Even functions marked as "platform dependent" may be available on 63 | more than one platform. Please see the function reference for more 64 | information.
65 | 66 | 67 |The standard binary output format generated by the linker for the Gamate target 71 | is a cartridge image with header. It is of course possible to change this 72 | behaviour by using a modified startup file and linker config.
73 |Note: the first two bytes of the header contain a checksum that must be inserted 74 | by an external program. Such an utility is provided in util/gamate/gamate-fixcart.c
75 | 76 |Programs containing Gamate specific code may use the gamate.h header file.
87 |
All drivers must be statically linked because no file I/O is available. 98 | The names in the parentheses denote the symbols to be used for static linking of the drivers.
99 | 100 | 101 |No TGI graphics drivers are currently available for the Gamate.
106 | 107 | 108 |No extended memory drivers are currently available for the Gamate.
113 | 114 | 115 |120 |
gamate-stdjoy.joy (gamate_stdjoy)A joystick driver for the standard two buttons joypad is available.
124 | 125 |No mouse drivers are currently available for the Gamate.
135 | 136 | 137 |No serial drivers are currently available for the Gamate.
142 | 143 | 144 | 145 |149 |
The existing library for the Gamate doesn't implement C file
160 | I/O. There are no hacks for the read() and write() routines.
To be more concrete, this limitation means that you cannot use any of the 162 | following functions (and a few others):
163 |164 |
181 |
This software is provided 'as-is', without any expressed or implied 191 | warranty. In no event will the authors be held liable for any damages 192 | arising from the use of this software.
193 |Permission is granted to anyone to use this software for any purpose, 194 | including commercial applications, and to alter it and redistribute it 195 | freely, subject to the following restrictions:
196 |197 |
18 |
Describes the ar65 archiver.
23 | 24 |Describes the ca65 macro assembler.
27 | 28 |Describes the cc65 C compiler.
31 | 32 |Describes the vector font converter.
35 | 36 |Describes the cl65 compile & link utility.
39 | 40 |Describes the co65 object-file converter.
43 | 44 |Describes the da65 6502/65C02 disassembler.
47 | 48 |Describes the GEOS resource compiler.
51 | 52 |Describes the ld65 linker.
55 | 56 |Describes the od65 object-file analyzer.
59 | 60 |Describes the 6502 and 65C02 simulator.
63 | 64 |Describes the sprite and bitmap utility.
67 | 68 |76 |
Describes the use of the tools, by building a short "hello world" 81 | example.
82 | 83 |Contains hints on creating the most effective code with cc65.
86 | 87 |Describes internal details of cc65: linker configuration, calling conventions, etc.
90 | 91 |Build programs, using the GNU Make utility.
94 | 95 |How to use the cc65 toolset for a custom hardware platform (a target system 98 | not currently supported by the cc65 library set).
99 | 100 |Debug programs, using the VICE emulator.
103 | 104 |112 |
A (currently incomplete) function reference.
117 | 118 |Low-level disk I/O API.
121 | 122 |Tiny Graphics Interface.
125 | 126 |The GEOSLib manual.
129 | 130 |An overview over the cc65 runtime and C libraries.
133 | 134 |Describes Christian Krüger's macro package for writing self modifying 137 | assembler code.
138 | 139 |Describes the o65 file format that is used for dynamically loadable modules 142 | and LUnix programs.
143 | 144 |152 |
Topics specific to the Apple ][.
157 | 158 |Topics specific to the enhanced Apple //e.
161 | 162 |Topics specific to the Atari 8-bit machines.
165 | 166 |Topics specific to the Atari 2600 Game Console.
169 | 170 |Topics specific to the Atari 5200 Game Console.
173 | 174 |Topics specific to the Atari 7800 Game Console.
177 | 178 |Topics specific to the Oric Atmos.
181 | 182 |Topics specific to the Commodore 128.
185 | 186 |Topics specific to the Commodore 16/116.
189 | 190 |Topics specific to the Commodore 64.
193 | 194 |Topics specific to the Commodore 510.
197 | 198 |Topics specific to the Commodore 610.
201 | 202 |Topics specific to the Creativision Console.
205 | 206 |Topics specific to the Commander X16.
209 | 210 |Topics specific to the Bit Corporation Gamate Console.
213 | 214 |Topics specific to the MOS Technology KIM-1.
217 | 218 |Topics specific to the Atari Lynx Game Console.
221 | 222 |Topics specific to the Nintendo Entertainment System.
225 | 226 |Topics specific to the Ohio Scientific machines.
229 | 230 |Topics specific to the NEC PC-Engine (TurboGrafx-16) Console.
233 | 234 |Topics specific to the Commodore PET machines.
237 | 238 |Topics specific to the Commodore Plus/4.
241 | 242 |Topics specific to the Picocomputer 6502.
245 | 246 |Topics specific to the Watara Supervision Console.
249 | 250 |Topics specific to the Synertek Systems Sym-1.
253 | 254 |Topics specific to the Oric Telestrat.
257 | 258 |Topics specific to the Commodore VIC20.
261 | 262 |18 |
21 |
24 |
27 |
30 |
39 |
45 |
53 |
This file contains an overview of the KIM-1 runtime system as it comes with the cc65 C compiler. 61 | It describes the memory layout, KIM-1 specific header files, available drivers, and any pitfalls 62 | specific to the platform.
63 |Please note that KIM-1 specific functions are just mentioned here, they are described in detail 64 | in the separate 65 | function reference. Even functions marked as 66 | "platform dependent" may be available on more than one platform. Please see the 67 | function reference for more information.
68 | 69 |The output format generated by the linker for the KIM-1 target is a raw binary BIN file, which 73 | is essentially a memory image. You can convert this to a papertape format file using 74 | Convert8bithexformat or KIMPaper, which are open-source conversion utility programs. 75 | A papertape format files can be transferred to the KIM-1 using the RS-232 terminal port (TTY), 76 | just as if the machine-code was entered by hand. Enter 'L' in the TTY and start the paper tape file 77 | transfer.
78 | 79 | 80 |Included with this distribution is a 4k configuration file and a 60k config file. The KIM-1 81 | on-board memory is limited to 4 kbytes but system memory can be increased to 60 kbytes of 82 | contiguous RAM with aftermarket add-on boards. So choose the config file that matches your 83 | system configuration before compiling and linking user programs.
84 | 85 |The ROMs and I/O areas are defined in the configuration files, as are most of the entry points 89 | for useful subroutines in the KIM-1 monitor ROM. cc65 generated programs compiled and linked 90 | using 4k config run in the memory range of $200 - $0FFF. The 60k config expands 91 | this range to $DFFF. When using the 4k config the starting memory location and entry point 92 | for running the program is $200, so when the program is transferred to the KIM-1, it is 93 | executed by typing '200 G'. With the 60k config the default starting memory location and entry 94 | point is $2000.
95 |Special locations:
96 |97 |
Conio support is not currently available for the KIM-1. But stdio console functions are available.
100 | 101 |The C runtime stack is located at $0FFF on 4kb KIM-1s, or at $DFFF for 60kb systems. 103 | The stack always grows downwards.
104 | 105 |The C heap is located at the end of the program and grows towards the C runtime stack.
107 | 108 |Programs containing KIM-1 code may use the kim1.h header file. See the header file for more information.
No graphics drivers are currently available for the KIM-1.
126 | 127 |No joystick driver is currently available for the KIM-1.
132 | 133 |No mouse drivers are currently available for the KIM-1.
138 | 139 |No communication port drivers are currently available for the KIM-1. It has only the "master console" 144 | e.g. stdin and stdout.
145 | 146 |The existing library for the KIM-1 doesn't implement C file I/O.
155 |To be more specific, this limitation means that you cannot use any of the following functions (and a few others):
156 |157 |
This header exposes KIM-1 specific I/O functions that are useful for reading and writing its ports and front panel.
174 | See the kim1.h include file for a list of the functions available.
As stated earlier, there are config files for 4kb and 60kb systems. If you have 60kb RAM, then you will probably 181 | want to use the kim1-60k configuration, but if not - if you are using the kim1-4k configuration - then you may 182 | want to use functions like getchar, putchar, gets and puts rather than functions like scanf and printf. 183 | Printf, for example, requires about 1KB because it needs to know how to process all the format specifiers.
184 | 185 |These sample programs can be found in the samples/kim1 directory:
190 |191 |
This software is provided 'as-is', without any expressed or implied warranty. In no event will the authors be held 203 | liable for any damages arising from the use of this software.
204 |Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter 205 | it and redistribute it freely, subject to the following restrictions:
206 |207 |
19 |
22 |
25 |
28 |
31 |
conio.h34 |
joystick.h37 |
mouse.h40 |
This file contains a short overview of the libraries available for the cc65 C 48 | compiler. Please have a look at the 49 | function reference for a function-by-function list. Because the function reference is 50 | not complete (we're working on that), it may happen that you don't find a 51 | specific function. In that case, have a look into the header files. All 52 | functions, that are not defined by the ISO C standard, have a short comment in 53 | the headers, explaining their use.
54 | 55 | 56 | 57 |The C library contains a large subset of the ISO C library. Functions usually 61 | are missing in areas where there are no support on typical 6502 systems. 62 | Wide-character sets are an example for that.
63 |I will not go into detail about the ISO functions. If a function is not 64 | mentioned here explicitly, expect it to be available, and to behave as defined 65 | in the C standard.
66 |Functions that are not available:
67 |68 |
tmpfile/tmpnam
70 |
71 | system (cc65 alternative exec)
73 |
74 | ldiv function (cc65 currently is not able to return structs,
79 | by value, with a size not equal to 1, 2, or 4 bytes).
80 |
81 | SIGSEGV would be
86 | cool. :-)
87 |
88 | setbuf/setvbufFunctions not available on all supported systems:
93 |94 |
clock: Support depends on the capabilities of the target
96 | machine.
97 |
98 | fopen/fread/fwrite/fclose/fputs/fgets/fscanf: The functions
100 | are built on open/read/write/close. Those latter functions are not available
101 | on all systems.
102 |
103 | ftell/fseek/fgetpos/fsetpos: Support depends on the
105 | capabilities of the target machine.
106 |
107 | rename/remove/rewind: Support depends on the capabilities of
109 | the target machine.
110 |
111 | time: Many of the supported systems don't have a real-time
113 | clock, which means that the time function is not available. Please note
114 | that the other functions from time.h are available.Functions that are limited in any way:
119 |120 |
strcspn/strpbrk/strspn: Those functions have a length
122 | limitation of 256 for the second string argument. Since that string gives a
123 | character set, and there are only 256 distinct characters, that shouldn't be
124 | a problem.
125 |
126 | getenv: Since there is no such thing as an environment on all
128 | supported systems, the getenv function always will return a NULL
129 | pointer.
130 |
131 | locale: There is no locale other than the "C" locale. The
133 | native locale is identical to the "C" locale.In addition to those limitations, some more functions are limited if inlined
138 | versions are requested by using the -Os command-line option:
140 |
strlen function works for only strings with a maximum length
142 | of 255 characters.
143 |
144 | isXXX character classification functions from
146 | <ctype.h> will give unpredictable results if the argument is not
147 | in character range (0..255). That limitation may be removed by #undef'ing
148 | the function name (when using -Os, the functions are actually macros
149 | that expand to inline assembly code, but the real functions still are
150 | available if the macro definition is removed).The header file 6502.h contains some functions that make sense only with the 160 | 6502 CPU. Examples are macros to insert more or less useful instructions into 161 | your C code, or a function to call arbitrary machine language subroutines, 162 | passing registers in and out.
163 | 164 | 165 | 166 |For each supported system, there's a header file that contains calls or
170 | defines specific for that system. So, when programming for the C64, include
171 | <c64.h>, for the C128, include <c128.h>, and so on.
172 | To make the task for the Commodore systems easier, there is also a header file
173 | named <cbm.h> that will define stuff common for all CBM systems,
174 | and include the header file for the specific target system.
The header files contain
176 |177 |
SID. Writing to the fields of that struct will write to the SID device
185 | instead. Using those variables will make your program more readable and more
186 | portable. Don't fear ineffective code when using those variables, the
187 | compiler will translate reads and writes to those structs into direct memory
188 | accesses.
189 | conio.hThe conio.h header file contains a large set of functions that do screen
203 | and keyboard I/O. The functions will write directly to the screen or poll the
204 | keyboard directly with no more help from the operating system than needed.
205 | This has some disadvantages, but on the other side it's fast and reasonably
206 | portable. Conio implementations exist for the following targets:
208 |
The conio.h header file does include the system-specific header files also,
235 | which define constants for special characters and keys.
joystick.hFor systems that have a joystick, joystick.h will define a subroutine to
243 | read the current value, including constants to evaluate the result of that
244 | function.
mouse.hSome target machines support a mouse. Mouse support currently is available for 252 | the following targets:
253 |254 |
The available functions are declared in mouse.h.
This C runtime library implementation for the cc65 compiler is (C) 273 | Copyright 1998-2002 Ullrich von Bassewitz. For usage of the binaries 274 | and/or sources, the following conditions do apply:
275 |This software is provided 'as-is', without any expressed or implied 276 | warranty. In no event will the authors be held liable for any damages 277 | arising from the use of this software.
278 |Permission is granted to anyone to use this software for any purpose, 279 | including commercial applications, and to alter it and redistribute it 280 | freely, subject to the following restrictions:
281 |282 |
20 |
23 |
26 |
29 |
36 |
46 |
52 |
55 |
This file contains an overview of the NES runtime system as it comes 63 | with the cc65 C compiler. It describes the memory layout, NES specific header 64 | files, available drivers, and any pitfalls specific to that platform.
65 |Please note that NES specific functions are just mentioned here, they are 66 | described in detail in the separate 67 | function reference. Even functions marked as "platform dependent" may be available on 68 | more than one platform. Please see the function reference for more 69 | information.
70 | 71 | 72 |The standard binary output format generated by the linker for the NES target 76 | is a machine language program with an INES cartridge header. It is of course 77 | possible to change this behaviour by using a modified startup file and linker 78 | config.
79 | 80 |cc65 generated programs with the default setup run with the I/O area and a 84 | CHR bank enabled, which gives a usable memory range of $8000 - $FFF3. 85 | All boot ROM entry points may be called directly without additional code.
86 |Special locations:
87 |88 |
The text screen is located at VRAM $2000.
91 | 92 |The C runtime stack is located at $7FFF and growing downwards.
94 | 95 |The C heap is located at the end of the program and grows towards the C 97 | runtime stack.
98 | 99 |Programs containing NES specific code may use the nes.h header file.
116 |
The following pseudo variables declared in the nes.inc include file do
129 | allow access to hardware located in the address space.
131 |
PPUThe PPU defines allow access to the PPU chip.
APUThe APU defines allow access to the APU chip.
All drivers must be statically linked because no file I/O is available. 149 | The names in the parentheses denote the symbols to be used for static linking of the drivers.
150 | 151 | 152 |157 |
nes-64-56-2.tgi (nes_64_56_2)This driver features a resolution of 64×56 with 2 colors using the 161 | CHR bank.
162 | 163 |No extended memory drivers are currently available for the NES.
173 | 174 | 175 |180 |
nes-stdjoy.joy (nes_stdjoy)A joystick driver for the standard four buttons joypad is available.
184 | 185 |The generic interface doesn't export the start and select buttons. To 189 | test for those, use the defines in nes.h instead of the generic masks.
190 |Example: 191 |
192 |
193 | if (joy_read(0) & KEY_A)
194 |
195 | No mouse drivers are currently available for the NES.
204 | 205 | 206 |No serial drivers are currently available for the NES.
211 | 212 | 213 | 214 |The existing library for the NES doesn't implement C file
223 | I/O. There are no hacks for the read() and write() routines.
To be more concrete, this limitation means that you cannot use any of the 225 | following functions (and a few others):
226 |227 |
This software is provided 'as-is', without any expressed or implied 251 | warranty. In no event will the authors be held liable for any damages 252 | arising from the use of this software.
253 |Permission is granted to anyone to use this software for any purpose, 254 | including commercial applications, and to alter it and redistribute it 255 | freely, subject to the following restrictions:
256 |257 |
19 |
22 |
29 |
32 |
od65 is an object file dump utility. It is able to output most parts of 40 | ca65-generated object files in readable form. 41 | Since the contents and format of the object files are not documented 42 | elsewhere and may change at any time, this tool is a portable way to look at 43 | the contents.
44 |Apart from curiosity, most people don't need to use this tool.
45 | 46 | 47 | 48 |The od65 utility dumps contents of one or more ca65 generated object file to 52 | standard output. It has no cross-version compatibility, so you have to use 53 | a version that matches the version of ca65 used to create the object files.
54 | 55 | 56 |The program may be called as follows:
61 |62 |
63 |
64 | ---------------------------------------------------------------------------
65 | Usage: od65 [options] file [options] [file]
66 | Short options:
67 | -h Help (this text)
68 | -H Dump the object file header
69 | -S Dump segments sizes
70 | -V Print the version number and exit
71 |
72 | Long options:
73 | --dump-all Dump all object file information
74 | --dump-dbgsyms Dump debug symbols
75 | --dump-exports Dump exported symbols
76 | --dump-files Dump the source files
77 | --dump-header Dump the object file header
78 | --dump-imports Dump imported symbols
79 | --dump-lineinfo Dump line information
80 | --dump-options Dump object file options
81 | --dump-segments Dump the segments in the file
82 | --dump-segsize Dump segments sizes
83 | --help Help (this text)
84 | --version Print the version number and exit
85 | ---------------------------------------------------------------------------
86 |
87 | Here is a description of all the command line options:
96 |97 |
--dump-allThis will output all information, od65 is able to process. The option is a
101 | shortcut for specifying all the other --dump options.
--dump-dbgsymsDump all debug symbols contained in the object file.
106 | 107 | 108 |--dump-exportsDump all exported symbols contained in the object file.
110 | 111 | 112 |--dump-filesDump the file table contained in the object file.
114 | 115 | 116 |-H, --dump-headerDump the object file header.
118 | 119 | 120 |--dump-importsDump the list of imported symbols contained in the object file.
122 | 123 | 124 |--dump-lineinfoDump the line info contained in the object file.
126 | 127 | 128 |--dump-segmentsDump the list of segments contained in the object file.
130 | 131 | 132 |--dump-scopesDump the scope (lexical level) information contained in the object file.
134 | 135 | 136 |-S, --dump-segsizeDump the sizes of all segments contained in the object file. This option is 138 | quite useful to determine the effect of measures that increase or decrease 139 | code size.
140 | 141 | 142 |-h, --helpPrint the short option summary shown above.
144 | 145 | 146 |-V, --versionPrint the version number of the compiler. When submitting a bug report, 148 | please include the operating system you're using, and the compiler 149 | version.
150 |The converter will read one or more object files per invocation and write the
158 | contents in readable format to standard output. Please note that you need to
159 | specify any of the --dump options listed
160 | above, otherwise no useful output will be generated.
Example output for the command 162 |
163 |
164 | od65 --dump-header --dump-files t.o
165 |
166 |
169 |
170 | t.o:
171 | Header:
172 | Magic: 0x616E7A55
173 | Version: 12
174 | Flags: 0x0001 (OBJ_FLAGS_DBGINFO)
175 | Options:
176 | Offset: 88
177 | Size: 9
178 | Files:
179 | Offset: 97
180 | Size: 10
181 | Segments:
182 | Offset: 107
183 | Size: 101
184 | Imports:
185 | Offset: 208
186 | Size: 1
187 | Exports:
188 | Offset: 209
189 | Size: 1
190 | Debug symbols:
191 | Offset: 210
192 | Size: 55
193 | Line infos:
194 | Offset: 265
195 | Size: 1
196 | String pool:
197 | Offset: 266
198 | Size: 80
199 | Files:
200 | Count: 1
201 | Index: 0
202 | Name: "t.s"
203 | Size: 402
204 | Modification time: 1280498435 (Fri Jul 30 16:00:35 2010)
205 |
206 | od65 is (C) Copyright 2000-2009, Ullrich von Bassewitz. For usage of the 214 | binaries and/or sources the following conditions apply:
215 |This software is provided 'as-is', without any expressed or implied 216 | warranty. In no event will the authors be held liable for any damages 217 | arising from the use of this software.
218 |Permission is granted to anyone to use this software for any purpose, 219 | including commercial applications, and to alter it and redistribute it 220 | freely, subject to the following restrictions:
221 |222 |
20 |
23 |
26 |
29 |
32 |
osic1p.cfg)
36 | osic1p-asm.cfg
37 | 39 |
46 |
49 |
52 |
58 |
65 |
This file contains an overview of the Ohio Scientific runtime system as it comes with the 73 | cc65 C compiler. It describes the memory layout, Ohio Scientific-specific header files, 74 | and any pitfalls specific to that platform.
75 |Please note that Ohio Scientific-specific functions are just mentioned here, they are 76 | described in detail in the separate 77 | function reference. Even functions marked as "platform dependent" may be available on 78 | more than one platform. Please see the function reference for more 79 | information.
80 | 81 |Currently the target "osic1p" is implemented. This works for the Ohio Scientific 85 | Challenger 1P machine and for the Briel Superboard /// replica.
86 | 87 |91 |
The standard binary output format generated by the linker for the osic1p 94 | target is a pure machine language program.
95 |For uploading into a real machine over its serial port or into an emulator, 96 | that program must be converted into a text file that can be understood by 97 | the 65V PROM monitor. For that purpose, the srec_cat program from 98 | the SRecord tool collection 99 | can be used.
100 |Care must be taken that the -offset and -execution-start-address
101 | options for the srec_cat program correspond to the start address
102 | of the executable.
Example for converting an executable "hello" file that was built for the 104 | default start address $0200 to an uploadable file "hello.c1p":
105 |106 |
107 |
108 | srec_cat hello -bin -of 0x200 -o hello.c1p -os -esa=0x200
109 |
110 |
111 | The linker can create an alternate format that contains two parts: 116 |
You can make the alternate format by adding the option -u __BOOT__ to
123 | cl65's or ld65's command lines.
This format doesn't need to be converted. It is smaller than the text-only
125 | format. But, it cannot be loaded by
126 | C1Pjs; you must use the
127 | SRecord-produced text-only format with that emulator. (However, if you know
128 | that you never will use C1Pjs, then you can edit the
129 | cfg/osic1p*.cfg files; uncomment the lines that import __BOOT__.
130 | Then, you won't need to use -u __BOOT__ on your command lines.)
By default programs compiled for the osic1p target are configured for 32 kB RAM.
139 | The RAM size can be configured via the symbol __HIMEM__.
Special locations:
141 |142 |
The default start address is $0200. The start address is configurable
145 | via the linker option --start-addr.
The C runtime stack is located at the top of RAM and growing downwards.
149 | The size is configurable via the symbol __STACKSIZE__. The default
150 | stack size is $0400.
The C heap is located at the end of the program and grows towards the C 154 | runtime stack.
155 | 156 |The 1 kB video RAM is located at $D000. On the monitor, only a subset 158 | of the available video RAM is visible. The address of the upper left corner 159 | of the visible area is $D085 and corresponds to conio cursor 160 | position (0, 0).
161 | 162 |Example for building a program with start address $0300, stack size 166 | $0200 and RAM size $2000:
167 |168 |
169 |
170 | cl65 --start-addr 0x300 -Wl -D,__HIMEM__=$2000,-D,__STACKSIZE__=$0200 -t osic1p hello.c
171 |
172 | The ld65 linker comes with a default config file "osic1p.cfg" for the Ohio Scientific
179 | Challenger 1P, which is implicitly used via -t osic1p. The
180 | osic1p package comes with additional secondary linker config files, which are
181 | used via -t osic1p -C <configfile>.
osic1p.cfg)
184 | The default configuration is tailored to C programs.
188 | 189 |osic1p-asm.cfg
190 | This configuration is made for assembler programmers who don't need a special 194 | setup.
195 |To use this config file, assemble with -t osic1p and link with
196 | -C osic1p-asm.cfg. The former will make sure that correct runtime library
197 | is used, while the latter supplies the actual config. When using cl65,
198 | use both command line options.
Sample command lines for cl65:
201 |
202 |
203 | cl65 -t osic1p -C osic1p-asm.cfg -o program source.s
204 | cl65 -t osic1p -C osic1p-asm.cfg -u __BOOT__ -o program.lod source.s
205 |
206 | Programs containing Ohio Scientific-specific code may use the osic1p.h
213 | header file.
There are currently no special Ohio Scientific functions.
220 | 221 |There is no specific support for direct hardware access.
226 | 227 |There are no loadable drivers available.
231 | 232 |By default the conio library uses a 24 columns by 24 lines screen layout 236 | for the Challenger 1P, like under BASIC. In addition to that there is support 237 | for other screen layouts with extra modules.
238 |There is a module screen-c1p-24x24.o in the OSI-specific
239 | cc65 runtime library that contains all conio functions that depend
240 | on the screen layout. No further configuration is needed for using the
241 | default screen layout of the Challenger 1P.
For other screen layouts additional versions of the screen module are 243 | available. The linker finds these modules without further configuration 244 | if they are specified on the compiler or linker command line. The 245 | extra module then overrides the default module.
246 |Sample cl65 command line to override the default screen
247 | module with the module osic1p-screen-s3-32x28.o:
249 |
250 |
251 | cl65 -o hello -t osic1p osic1p-screen-s3-32x28.o hello.c
252 |
253 | Currently the following extra screen configuration modules are implemented:
256 |257 |
osic1p-screen-s3-32x28.o: 32 columns by 28 lines mode
259 | for Briel Superboard ///osic1p-screen-c1p-48x12.s: 48 columns by 12 lines mode
261 | for Challenger 1POn the Briel Superboard /// you enter 32 column mode by holding down 265 | the BREAK key on powerup.
266 |On the Challenger 1P you can enable 48 column mode by writing a 1 to 267 | bit 0 of address $D800, and writing a 0 to go back to 24 column mode. 268 | You can use code like the following to do this:
269 |270 |
271 |
272 | *(char*)0xd800 = 1; /* Switch to 48 column mode */
273 |
274 | There is no support for stdio at the moment.
286 | 287 |There is currently no support for passing arguments to a program.
296 | 297 |The program return code currently has no effect. When the main() function 302 | finishes, the boot prompt is shown again.
303 | 304 |This software is provided 'as-is', without any expressed or implied 308 | warranty. In no event will the authors be held liable for any damages 309 | arising from the use of this software.
310 |Permission is granted to anyone to use this software for any purpose, 311 | including commercial applications, and to alter it and redistribute it 312 | freely, subject to the following restrictions:
313 |314 |
20 |
23 |
26 |
29 |
36 |
46 |
52 |
55 |
This file contains an overview of the PCE runtime system as it comes 63 | with the cc65 C compiler. It describes the memory layout, PCE-specific header 64 | files, available drivers, and any pitfalls specific to that platform.
65 |Please note that PCE-specific functions are just mentioned here; they are 66 | described, in detail, in the separate 67 | function reference. Even functions marked as "platform dependent" might be available on 68 | more than one platform. Please see the function reference for more 69 | information.
70 | 71 | 72 | 73 |The binary output file generated by the linker, for the PCE target, is an 77 | image, with no header, that has 8K bytes in the wrong place. That file must be 78 | post-processed; the 8K at the end must be moved to the front of the image.
79 |On POSIX systems, the dd command and the shell give a convenient way to do
80 | it. Here is an example of their use:
81 |
82 |
83 | dd if=conio.bin bs=8K skip=3 > conio.pce
84 | dd if=conio.bin bs=8K count=3 >> conio.pce
85 |
86 |
92 |
93 | +--------+--------+--------+--------+
94 | | Bank 1 | Bank 2 | Bank 3 | Bank 0 | <-- "conio.bin"
95 | +--------+--------+--------+--------+
96 |
97 | +--------+--------+--------+--------+
98 | | Bank 0 | Bank 1 | Bank 2 | Bank 3 | <-- "conio.pce"
99 | +--------+--------+--------+--------+
100 |
101 | .pce file shows the format of the ROM cartridge that is
104 | plugged into a PC-Engine. But, that .bin file shows what programs
105 | actually see when they execute the code in that cartridge.
106 |
107 |
108 |
109 | cc65-generated programs with the default setup run with the memory map that was 113 | used by many PC-Engine games: 114 |
Special locations:
127 |128 |
The text screen is located at Video RAM (VRAM) address $0000; 131 | the Font is located at VRAM address $2000.
132 | 133 |The C run-time stack is located in system RAM at $3FFF; 135 | and, grows downwards.
136 | 137 |The Data (initialized variables) and BSS (uninitialized variables) sections are 139 | placed one after the other into system RAM at $2200.
140 | 141 |The C heap is located after the end of the BSS section; 143 | and, extends up to the C run-time stack.
144 | 145 |In an 8K ROM cartridge, code and read-only data are located between 147 | $E000 and $FFF5 in the System bank.
148 |In a 16K cartridge, code and read-only data are located between $C000 149 | and $FFF5.
150 |In a 32K cartridge, code and read-only data are located between $8000 151 | and $FFF5.
152 |Programs containing PCE-specific code may use the pce.h header file.
168 |
The following constants, defined in the pce.inc include file, do
180 | allow access to hardware that is located in the address space.
182 |
PSGThe PSG defines allow access to the PSG (Programmable Sound Generator).
VCEThe VCE defines allow access to the VCE chip (Video Color Encoder).
VDCThe VDC defines allow access to the VDC chip (Video Display Controller).
192 | 32K of 16-bit words of Video RAM can be accessed only through this chip.
All drivers must be statically linked because no file I/O is available. 203 | The names in the parentheses denote the symbols to be used for static linking of the drivers.
204 | 205 | 206 |No TGI graphics drivers are currently available for the PCE.
211 | 212 | 213 |No extended memory drivers are currently available for the PCE.
218 | 219 | 220 |225 |
pce-stdjoy.joy (pce_stdjoy)A joystick driver for the standard two-button joypad is available.
229 |Note that the Japanese 6-button pad currently is not supported.
230 | 231 |No mouse drivers are currently available for the PCE.
240 | 241 | 242 |No serial drivers are currently available for the PCE.
247 | 248 | 249 | 250 |The existing library for the PCE doesn't implement C file
260 | I/O. There are no hacks for the read() and write() routines.
To be more concrete, that limitation means that you cannot use any of the 262 | following functions (and a few others):
263 |264 |
Some useful resources on PCE coding:
283 |284 |
This software is provided "as-is", without any expressed or implied 310 | warranty. In no event will the authors be held liable for any damages 311 | arising from the use of this software.
312 |Permission is granted to anyone to use this software for any purpose, 313 | including commercial applications, and to alter it and redistribute it 314 | freely, subject to the following restrictions:
315 |316 |
20 |
23 |
26 |
29 |
37 |
47 |
50 |
59 |
This file contains an overview of the PET runtime system as it comes with the 67 | cc65 C compiler. It describes the memory layout, PET-specific header files, 68 | available drivers, and any pitfalls specific to that platform.
69 |Please note that PET-specific functions are just mentioned here, they are 70 | described in detail in the separate 71 | function reference. Even functions marked as "platform dependent" may be available on 72 | more than one platform. Please see the function reference for more 73 | information.
74 | 75 | 76 |The standard binary output format generated by the linker for the PET target 80 | is a machine language program with a one line BASIC stub, which calls the 81 | machine language part via SYS. This means that a program can be loaded as 82 | BASIC program and started with RUN. It is of course possible to change this 83 | behaviour by using a modified startup file and linker config.
84 | 85 | 86 |cc65 generated programs with the default setup run with the I/O area and the 90 | kernal and BASIC ROM enabled, which gives a usable memory range of 91 | $0400 - $7FFF (32KB machine). 92 | All ROM entry points may be called directly without additional code.
93 |Special locations:
94 |95 |
The text screen is located at $8000.
98 | 99 |The C runtime stack is located at $7FFF and growing downwards.
101 | 102 |The C heap is located at the end of the program and grows towards the C 104 | runtime stack.
105 | 106 |Programs containing PET-specific code may use the pet.h or cbm.h
116 | header files. Using the later may be an option when writing code for more than
117 | one CBM platform, since it includes pet.h and declares several functions
118 | common to all CBM platforms.
There are currently no special PET functions.
126 | 127 | 128 | 129 |Some functions are available for all (or at least most) of the Commodore 134 | machines. See the 135 | function reference for 136 | declaration and usage.
137 |138 |
The following pseudo variables declared in the pet.h header file do allow
171 | access to hardware located in the address space. Some variables are
172 | structures, accessing the struct fields will access the chip registers.
174 |
PIA1, PIA2Access to the two PIA (peripheral interface adapter) chips is available via
178 | the PIA1 and PIA2 variables. The structure behind these variables
179 | is explained in _pia.h.
VIAThe VIA structure allows access to the VIA (versatile interface
183 | adapter). See the _6522.h header file located in the include
184 | directory for the declaration of the structure.
The names in the parentheses denote the symbols to be used for static linking of the drivers.
196 | 197 | 198 |No graphics drivers are currently available for the PET.
203 | 204 | 205 |No extended memory drivers are currently available for the PET.
210 | 211 | 212 |The default drivers, joy_stddrv (joy_static_stddrv), point to pet-stdjoy.joy (pet_stdjoy_joy).
218 |
pet-ptvjoy.joy (pet_ptvjoy_joy)Driver for the Protovision 4-player adapter contributed by Groepaz. See 222 | Protovision shop for prices and building instructions. Up to two 223 | joysticks are supported.
224 | 225 |pet-stdjoy.joy (pet_stdjoy_joy)Driver for the standard PET userport joystick.
227 | 228 |No mouse drivers are currently available for the PET.
238 | 239 | 240 |No serial drivers are currently available for the PET.
245 | 246 | 247 | 248 |Command-line arguments can be passed to main(). Since that is not
264 | supported directly by BASIC, the following syntax was chosen:
266 |
267 |
268 | RUN:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5
269 |
270 | 273 |
main() is the program name.The program return code (low byte) is passed back to BASIC by use of the
290 | ST variable.
The runtime for the PET uses routines marked as .INTERRUPTOR for
298 | interrupt handlers. Such routines must be written as simple machine language
299 | subroutines and will be called automatically by the interrupt handler code
300 | when they are linked into a program. See the discussion of the .CONDES
301 | feature in the
302 | assembler manual.
The extended memory at $9000 of the CBM 8x96 may be added to the heap by using 310 | the following code:
311 |312 |
313 |
314 | /* Check for the existence of RAM */
315 | if (PEEK(0x9000) == POKE(0x9000, PEEK(0x9000)+1)) {
316 | /* Add it to the heap */
317 | _heapadd ((void *) 0x9000, 0x2000);
318 | }
319 |
320 | This software is provided 'as-is', without any expressed or implied 329 | warranty. In no event will the authors be held liable for any damages 330 | arising from the use of this software.
331 |Permission is granted to anyone to use this software for any purpose, 332 | including commercial applications, and to alter it and redistribute it 333 | freely, subject to the following restrictions:
334 |335 |
19 |
22 |
25 |
28 |
37 |
47 |
50 |
58 |
This file contains an overview of the Plus/4 runtime system as it comes with the 66 | cc65 C compiler. It describes the memory layout, Plus/4 specific header files, 67 | available drivers, and any pitfalls specific to that platform.
68 |Please note that Plus/4 specific functions are just mentioned here, they are 69 | described in detail in the separate 70 | function reference. Even functions marked as "platform dependent" may be available on 71 | more than one platform. Please see the function reference for more 72 | information.
73 |Since the Plus/4 and the Commodore 16/116 are almost identical (the latter are 74 | missing the 6551 ACIA and do only have 16KB of memory), the 75 | C16 documentation is also worth a look. The difference 76 | between both cc65 targets is that the Plus/4 runtime uses banking to support 77 | full 64K RAM, while the C16 does not use banking and supports up to 32K RAM. 78 | Because banking is not needed, most C16 programs will be somewhat smaller than 79 | the same program compiled for the Plus/4. However, programs compiled for the 80 | C16 will always run on the Plus/4, while the reverse is not necessarily true.
81 | 82 | 83 |The standard binary output format generated by the linker for the Plus/4 87 | target is a machine language program with a one line BASIC stub, which calls 88 | the machine language part via SYS. This means that a program can be loaded as 89 | BASIC program and started with RUN. It is of course possible to change this 90 | behaviour by using a modified startup file and linker config.
91 | 92 | 93 |cc65 generated programs with the default setup run with the kernal and basic 97 | banked out. This gives a usable memory range of $1000 - $FD00. 98 | Having the kernal and basic ROMs banked out means, that no ROM entry points 99 | may be called directly from user code.
100 |Special locations:
101 |102 |
The text screen is located at $C00 (as in the standard setup).
105 | 106 |The color RAM is located at $800 (standard location).
108 | 109 |The C runtime stack is located at $FCFF and growing downwards.
111 | 112 |The C heap is located at the end of the program and grows towards the C 114 | runtime stack.
115 | 116 |Programs containing Plus/4 specific code may use the plus4.h or cbm.h
126 | header files. Using the later may be an option when writing code for more than
127 | one CBM platform, since it includes plus4.h and declares several functions
128 | common to all CBM platforms.
Please note that most of the header file declarations from the plus4.h
130 | header file are shared between the C16 and Plus/4 configurations. For this
131 | reason, most of it is located in a common header file named cbm264.h.
There are currently no special Plus/4 functions.
140 | 141 | 142 |Some functions are available for all (or at least most) of the Commodore 147 | machines. See the 148 | function reference for 149 | declaration and usage.
150 |151 |
Some CPU related functions are available for some of the Commodore 186 | machines. See the 187 | function reference for 188 | declaration and usage.
189 |190 |
The following pseudo variables declared in the plus4.h header file do
203 | allow access to hardware located in the address space. Some variables are
204 | structures, accessing the struct fields will access the chip registers.
206 |
TEDThe TED structure allows access to the TED chip. See the
210 | _ted.h header file located in the include directory for the
211 | declaration of the structure.
COLOR_RAMA character array that mirrors the color RAM of the Plus/4 at $0800.
215 | 216 |The names in the parentheses denote the symbols to be used for static linking of the drivers.
226 | 227 | 228 |No graphics drivers are currently available for the Plus/4.
233 | 234 | 235 |No extended memory drivers are currently available for the Plus/4.
240 | 241 | 242 |247 |
plus4-stdjoy.joy (plus4_stdjoy_joy)Supports up to two joysticks connected to the standard joysticks port of 251 | the Plus/4.
252 | 253 |No mouse drivers are currently available for the Plus/4.
263 | 264 | 265 |270 |
plus4-stdser.ser (plus4_stdser_ser)Driver for the 6551 ACIA chip built into the Plus/4. Supports up to 19200 274 | baud, requires hardware flow control (RTS/CTS) and does interrupt driven 275 | receives. Note that because of the peculiarities of the 6551 chip transmits 276 | are not interrupt driven, and the transceiver blocks if the receiver asserts 277 | flow control because of a full buffer.
278 |You need an adapter to use the builtin port, since the output levels 279 | available at the user port don't follow the RS232 standard.
280 | 281 |Command line arguments can be passed to main(). Since this is not
302 | supported by BASIC, the following syntax was chosen:
304 |
305 |
306 | RUN:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5
307 |
308 | 311 |
main is the program name.The program return code (low byte) is passed back to BASIC by use of the
329 | ST variable.
The runtime for the Plus/4 uses routines marked as .INTERRUPTOR for
337 | interrupt handlers. Such routines must be written as simple machine language
338 | subroutines and will be called automatically by the interrupt handler code
339 | when they are linked into a program. See the discussion of the .CONDES
340 | feature in the
341 | assembler manual.
This software is provided 'as-is', without any expressed or implied 349 | warranty. In no event will the authors be held liable for any damages 350 | arising from the use of this software.
351 |Permission is granted to anyone to use this software for any purpose, 352 | including commercial applications, and to alter it and redistribute it 353 | freely, subject to the following restrictions:
354 |355 |
19 |
22 |
25 |
28 |
31 |
The Picocomputer 6502 is a modern W65C02S computer with a custom operating 39 | system designed to be POSIX-like. The reference design includes a W65C02S, 40 | W65C22S, RP6502-RIA, and optionally a RP6502-VGA. Peripheral devices like 41 | keyboards, mice, and flash storage are connected by USB to the RP6502-RIA. 42 | Audio is generated by the RP6502-RIA. Video is generated by the RP6502-VGA.
43 | 44 | 45 | 46 |The standard binary output format generated by the linker for the RP6502 target 50 | is a plain machine language program without any prefix or postfix.
51 |The RP6502 Integrated Development Environment, based on Visual Studio Code, 52 | will convert the cc65 binary output into RP6502 ROM files that can be loaded 53 | directly from the RP6502 monitor or installed on the RIA to be loaded at boot.
54 | 55 | 56 | 57 |61 |
The C run-time stack is located at $FEFF, and grows downward.
64 | 65 |The C heap is located at the end of the program, and grows toward the C 67 | run-time stack.
68 | 69 |RAM is located at $0000 - $FEFF. Default binaries load and 71 | start at $0200.
72 | 73 |The RP6502 is designed with no ROM in the 6502 address space.
75 | 76 |A Versatile Interface Adapter (6522) is 16 registers located 78 | at $FFD0.
79 | 80 |The RP6502 Interface Adapter is 32 registers located at $FFE0.
82 | 83 |User I/O expansion is from $FF00 to $FFCF.
85 | 86 |Programs containing RP6502-specific code may use the rp6502.h or
96 | rp6502.inc include files.
This software is provided "as-is", without any expressed or implied 104 | warranty. In no event will the authors be held liable for any damages 105 | arising from the use of this software.
106 |Permission is granted to anyone to use this software for any purpose, 107 | including commercial applications, and to alter it and redistribute it 108 | freely, subject to the following restrictions: 109 |
19 |
22 |
25 |
28 |
34 |
44 |
50 |
53 |
This file contains an overview of the Supervision runtime system as it comes 61 | with the cc65 C compiler. It describes the memory layout, Supervision specific header 62 | files, available drivers, and any pitfalls specific to that platform.
63 |Please note that Supervision specific functions are just mentioned here, they are 64 | described in detail in the separate 65 | function reference. Even functions marked as "platform dependent" may be available on 66 | more than one platform. Please see the function reference for more information.
67 | 68 | 69 |The standard binary output format generated by the linker for the Supervision target 73 | is a 2×16 kbyte machine language program. It is of course 74 | possible to change this behaviour by using one of the different linker configs.
75 | 76 |cc65 generated programs with the default setup run with the I/O area enabled, 80 | which gives a usable memory range of $8000 - $FFF9. 81 | More ROM may need additional bankswitching code.
82 |Special locations:
83 |84 |
No conio support is currently available for the Supervision.
87 | 88 |The C runtime stack is located at $1FFF and growing downwards.
90 | 91 |The C heap is located at the end of the program and grows towards the C 93 | runtime stack.
94 | 95 |Programs containing Supervision specific code may use the supervision.h header file.
The following pseudo variables declared in the supervision.inc include file do
112 | allow access to hardware located in the address space.
114 |
IOThe IO defines allow access to the IO chip.
No graphics drivers are currently available for the Supervision.
134 | 135 |No extended memory drivers are currently available for the Supervision.
140 | 141 | 142 |147 |
supervision-stdjoy.joy (supervision_stdjoy_joy)A joystick driver for the standard two buttons joypad is available.
151 | 152 |No mouse drivers are currently available for the Supervision.
161 | 162 | 163 |No communication port drivers are currently available for the Supervision.
168 | 169 | 170 | 171 |The existing library for the Supervision doesn't implement C file
180 | I/O. There are even no hacks for the read() and write() routines.
To be more concrete, this limitation means that you cannot use any of the 182 | following functions (and a few others):
183 |184 |
This software is provided 'as-is', without any expressed or implied 208 | warranty. In no event will the authors be held liable for any damages 209 | arising from the use of this software.
210 |Permission is granted to anyone to use this software for any purpose, 211 | including commercial applications, and to alter it and redistribute it 212 | freely, subject to the following restrictions:
213 |214 |
18 |
21 |
24 |
27 |
33 |
43 |
49 |
55 |
This file contains an overview of the Sym-1 runtime system as it comes with the cc65 C compiler. 63 | It describes the memory layout, Sym-1 specific header files, available drivers, and any pitfalls 64 | specific to the platform.
65 |Please note that Sym-1 specific functions are just mentioned here, they are described in detail 66 | in the separate 67 | function reference. Even functions marked as 68 | "platform dependent" may be available on more than one platform. Please see the 69 | function reference for more information.
70 | 71 |The output format generated by the linker for the Sym-1 target is a raw binary BIN file, which 75 | is essentially a memory image. You can convert this to a HEX file using BIN2HEX, which is a 76 | popular open-source conversion utility program. A HEX file has ASCII representations of the 77 | hexadecimal byte values of the machine-language program. So the HEX file can be transferred 78 | to the Sym-1 using the RS-232 terminal port, just as if the machine-code was entered by hand. 79 | Enter 'm 200' in the monitor and start the HEX file transfer.
80 | 81 | 82 |Included with this distribution is a 4k configuration file and a 32k config file. The Sym-1 83 | on-board memory is limited to 4 kbytes but system memory can be increased to 32 kbytes of 84 | contiguous RAM with aftermarket add-on boards. So choose the config file that matches your 85 | system configuration before compiling and linking user programs.
86 | 87 |The ROMs and I/O areas are defined in the configuration files, as are most of the entry points 91 | for useful subroutines in the Sym-1 monitor ROM. cc65 generated programs compiled and linked 92 | using 4k config run in the memory range of $200 - $0FFF. The 32k config expands 93 | this range to $7FFF. Memory above 32k can be used to extend the heap, as described below. 94 | The starting memory location and entry point for running the program is $200, so when the 95 | program is transferred to the Sym-1, it is executed by typing 'g 200'. The system returns control 96 | back to the monitor ROM when the program terminates, providing the '.' prompt.
97 |Special locations:
98 |99 |
Conio support is not currently available for the Sym-1. But stdio console functions are available.
102 | 103 |The C runtime stack is located at $0FFF on 4kb Syms, or at $7FFF for 32kb systems. 105 | The stack always grows downwards.
106 | 107 |The C heap is located at the end of the program and grows towards the C runtime stack. Extended 109 | memory can be added to the heap, as described below.
110 | 111 |Programs containing Sym-1 code may use the sym1.h header file. See the header file for more information.
The pseudo variables declared in the sym1.inc include file allow access to hardware located in the
125 | address space. See the include file for more information.
No graphics drivers are currently available for the Sym-1.
136 | 137 |There are no extended memory drivers for the Sym-1. However, there is a way to access memory beyond the 142 | 32kb boundary, if extended memory is physically present in the system. See the example program, 143 | symExtendedMemory, in the samples directory.
144 | 145 |No joystick driver is currently available for the Sym-1.
150 | 151 |No mouse drivers are currently available for the Sym-1.
156 | 157 |No communication port drivers are currently available for the Sym-1. It has only the "master console" 162 | e.g. stdin and stdout.
163 | 164 |The existing library for the Sym-1 doesn't implement C file I/O.
173 |To be more specific, this limitation means that you cannot use any of the following functions (and a few others):
174 |175 |
This header exposes Sym-specific I/O functions that are useful for reading and writing its ports and front panel.
192 | See the sym1.h include file for a list of the functions available.
As stated earlier, there are config files for 4kb and 32kb systems. If you have 32kb RAM, then you will probably 198 | want to use the sym1-32k configuration, but if not - if you are using the sym1-4k configuration - then you may 199 | want to use functions like getchar, putchar, gets and puts rather than functions like scanf and printf. 200 | Printf, for example, requires about 1KB because it needs to know how to process all the format specifiers.
201 | 202 |Memory may be physically present that is addressed at locations above the monitor ROM at $8000. This extended 206 | memory is accessible by adding to the heap, as described in the symExtendedMemory sample program.
207 | 208 |All the samples will run on the "stock" 4kb Sym-1, except for symIO and symNotepad, which require 32kb. 212 | Additionally, symExtendedMemory shows how to access memory above 32kb, so it expects more than 32kb. 213 | These sample programs can be found in the samples/sym1 directory:
214 |215 |
This software is provided 'as-is', without any expressed or implied warranty. In no event will the authors be held 231 | liable for any damages arising from the use of this software.
232 |Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter 233 | it and redistribute it freely, subject to the following restrictions:
234 |235 |
18 |
21 |
24 |
27 |
34 |
44 |
51 |
54 |
This file contains an overview of the Telestrat runtime system as it comes 62 | with the cc65 C compiler. It describes the memory layout, Telestrat-specific 63 | header files, available drivers, and any pitfalls specific to that platform.
64 |Please note that Telestrat-specific functions are just mentioned here, they are 65 | described in detail in the separate 66 | function reference. Even functions marked as "platform dependent" may be available on 67 | more than one platform. Please see the function reference for more 68 | information.
69 |Oric Telestrat is the last Oric computer (Released in 1986, mainly in France). 70 | This computer is an Atmos with extra hardware: RS232, cardridge(banking system), 71 | joysticks (2 ports) or mouse (on joystick port), FDC.
72 |Video chip, CPU, keyboard management, tape hardware are the same than Atmos.
73 |Telestrat can start in Atmos mode with Atmos Cardridge (which is only the atmos 74 | Basic 1.1 ROM).
75 |Telestrat can start in Sedoric (Atmos OS) and Atmos mode with Stratoric Cardridge. 76 | This Cardridge has 3 banks of 16KB of rom with: 77 |
The main Telestrat's configuration is the Telemon/Hyperbasic Cardridge inserted 84 | with Stratsed in floppy drive.
85 |Anyway, there is no way to load a tape file in Telemon/Hyperbasic mode without 86 | alternative program.
87 |There is also no software to write a Stratsed dsk file on PC.
88 |This Telestrat target build an Orix binary file. But, in the future, it will be possible 89 | to build a Stratsed disk. Orix uses the same systems calls than Telemon mode.
90 |That is why if you need to do software for telestrat target, you have the choice to: 91 |
Telestrat (from cardridge) can handle 8 banks (from $C000 to $FFFF): Bank 0 is the overlay ram. Others banks can be ROM or RAM.
101 | 102 |The standard binary output format generated the linker for the Telestrat 106 | target is a machine language program with a 20 bytes header described 107 | here
108 |This header is used for Telemon 3.0.
109 |Anyway, for Telemon 2.4, there is no file management, there is no TAPE routine 110 | in Telemon, there is no way to load a binary easily.
111 |Stratsed (the Telestrat operating system) handles files management. Stratsed 112 | is loaded to memory from floppy disk. Stratsed vector are declared in asminc/telestrat.inc. 113 | But, reverse engineering is required to find how these vectors works. Please, note that 114 | Stratsed is located in overlay memory (bank 0)
115 |There is no tool to insert a binary in a Stratsed floppy disk.
116 |The only way to load a binary (for Telemon 2.4) is to: 117 |
Please note also, that the binary converted into TAP file, will not produce 127 | a right stratsed file when tap2dsk and old2mfm are used. You will be in the 128 | case that Telestrat/Stratsed crashed when you do "DIR" command.
129 |If you know the Stratsed disk format, please contact the author of this doc.
130 | 131 | 132 |In the standard setup, cc65-generated programs use the memory from 136 | $0801 to $9800; so, nearly 37K of memory (including the stack) is 137 | available. ROM calls are possible with BRK feature.
138 | 139 |Special locations:
140 |141 |
The C runtime stack is located at $97FF (or $B3FF), and grows 144 | downwards.
145 | 146 |The C heap is located at the end of the program, and grows towards the C 148 | runtime stack.
149 | 150 |Programs containing Telestrat-specific code may use the telestrat.h header file.
The functions listed below are special for the Telestrat. See the 167 | function reference for declaration and usage.
168 |169 |
The following pseudo variables declared in the telestrat.h header file do allow
184 | access to hardware located in the address space. Some variables are
185 | structures; accessing the struct fields will access the chip registers.
187 |
VIAAccess to the VIA (Versatile Interface Adapter) chip is available via the
191 | VIA variable. The structure behind this variable is explained in _6522.h.
VIA2Access to the VIA2 (Versatile Interface Adapter) chip is available via the
195 | VIA2 variable. The structure behind this variable is explained in _6522.h.
ACIAAccess to the 6551 ACIA chip is available via the
199 | ACIA variable. The structure behind this variable is explained in _6551.h.
TGI drivers is available on Oric Telestrat with some functions:
215 |216 |
No extended memory drivers are currently available for the Telestrat. 233 | This feature could be done because telestrat can manage RAM inserted in his 234 | port cardridge.
235 | 236 |Telemon 2.4 returns in keyboard buffer the direction of the joysticks. This means that 241 | if you get input from keyboard by conio cgetc function, you will get direction from joysticks.
242 |Anyway, if you don't want to use ROM, you can use joysticks standard drivers in your code.
243 |The standard driver manages two joysticks. Only one button is managed for these joysticks.
244 |Telestrat can handle one button for the left port, and three buttons for the right port (but this port was designed for a mouse).
245 |If you find a Telestrat mouse (which is almost impossible :), these driver will work too because there is some extra hardware in the mouse to send direction.
246 | 247 |Telestrat manages also mouse (Joystick port) 252 | Telestrat mouse is really difficult to find.
253 | 254 |Telestrat has a RS232 port, but it's not usable in cc65. It is possible to use 259 | RS232 port with Telemon calls (see XSOUT primitive for example)
260 | 261 |Telemon 3.0 handles fopen, fread, fclose primitives. It means that this 270 | function will crash the Telestrat because Telemon 2.4 does not have these 271 | primitives. By the way, Telemon 3.0 uses an extension "ch376 card" which 272 | handles sdcard and FAT 32 usb key. In the next version of Telemon, FT DOS, 273 | Sedoric, Stratsed will be handled in these 3 primitives (fopen, fread, fclose).
274 |275 |
Functions textcolor and bgcolor are available only with Telemon 3.0 (Orix). 286 | Telemon 2.4 primitives can't handle any change of colors in text mode except with XINK or 287 | XPAPER primitives which put on the first and second columns ink and paper attributes. 288 | The only way to change color on the same line for text is to handle it in pure assembly 289 | without systems calls.
290 | 291 |This software is provided 'as-is', without any expressed or implied 300 | warranty. In no event will the authors be held liable for any damages 301 | arising from the use of this software.
302 |Permission is granted to anyone to use this software for any purpose, 303 | including commercial applications, and to alter it and redistribute it 304 | freely, subject to the following restrictions:
305 |306 |
18 |
21 |
24 |
32 |
This document describes how to build your programs using the cc65 development 40 | tools and the GNU Make utility.
41 |The cc65 development package doesn't come with a make utility. However this is 42 | no issue because GNU Make works very nicely with cc65.
43 | 44 | 45 | 46 |GNU Make is a both very powerful and very popular make utility. It might even 50 | be called the de facto standard for make utilities. For more information see 51 | the GNU Make home page:
52 |53 | http://www.gnu.org/software/make/
54 |The cc65 development package is available as binaries for several host systems 55 | and can easily built for quite some additional systems. The very same is true 56 | for GNU Make so a cc65-based project coming with a GNU Make Makefile can easily 57 | be built by any cc65 developer no matter what host system is used.
58 |Because of the strong alignment of the cc65 compiler with the ISO C standard it 59 | is very well feasible to compile a single C code base both with the cc65 60 | compiler and other C compilers like for example GCC. GNU Make turns out to be 61 | very well suited to build projects for several target systems using multiple 62 | compilers as it isn't tied to any C compiler.
63 | 64 | 65 | 66 |This Makefile is a fully functional sample for compiling several C sources
70 | (here foo.c and bar.c) and link the resulting object files into an
71 | executable program (here foobar):
73 |
74 |
75 | SOURCES = foo.c bar.c
76 |
77 | PROGRAM = foobar
78 |
79 | ifdef CC65_TARGET
80 | CC = cl65
81 | CFLAGS = -t $(CC65_TARGET) --create-dep $(<:.c=.d) -O
82 | LDFLAGS = -t $(CC65_TARGET) -m $(PROGRAM).map
83 | else
84 | CC = gcc
85 | CFLAGS = -MMD -MP -O
86 | LDFLAGS = -Wl,-Map,$(PROGRAM).map
87 | endif
88 |
89 | ########################################
90 |
91 | .SUFFIXES:
92 | .PHONY: all clean
93 | all: $(PROGRAM)
94 |
95 | ifneq ($(MAKECMDGOALS),clean)
96 | -include $(SOURCES:.c=.d)
97 | endif
98 |
99 | %.o: %.c
100 | $(CC) -c $(CFLAGS) -o $@ $<
101 |
102 | $(PROGRAM): $(SOURCES:.c=.o)
103 | $(CC) $(LDFLAGS) -o $@ $^
104 |
105 | clean:
106 | $(RM) $(SOURCES:.c=.o) $(SOURCES:.c=.d) $(PROGRAM) $(PROGRAM).map
107 |
108 | Important: When using the sample Makefile above via copy & paste it is 111 | important to make sure that command lines (lines 26, 29 and 32) start 112 | with a tab character (ASCII code 9).
113 | 114 | 115 |Without any specific configuration the sample Makefile will compile and link
120 | using GCC. In order to rather use cc65 the variable CC65_TARGET needs to be
121 | defined. This may by done as an environment variable or simply as part of the
122 | Makefile. However to quickly switch between compilers and/or cc65 targets it is
123 | best done on the GNU Make command line like this:
125 |
126 |
127 | make CC65_TARGET=c64
128 |
129 | Most parts of the sample Makefile follow the guidelines in the 138 | GNU Make Manual 139 | that can be searched online for background information. The automatic generation of 140 | dependency however rather works as described by the GNU Make maintainer Paul D. Smith in 141 | "Advanced Auto-Dependencies". 142 | Fortunately both GCC and cc65 directly support this method in the meantime.
143 | 144 | 145 |The recommended way to use GNU Make on Windows is to install it as part of a 150 | Cygwin environment. For more information see the Cygwin home page:
151 |152 | http://www.cygwin.com/
153 |If however installing Cygwin shouldn't be an option for one or the other reason 154 | then the sample Makefile may be invoked from the Windows Command Prompt (cmd.exe) 155 | by downloading the following programs:
156 |157 |
163 | 164 | 165 | 166 | 167 |The very limited resources of the cc65 target machines now and then require
171 | manual optimization of the build process by compiling individual source files
172 | with different compiler options. GNU Make offers
173 | Target-specific Variable Values
174 | perfectly suited for doing so. For example placing the code of the two modules
175 | foo and bar in the segment FOOBAR can be achieved with this
176 | target-specific variable definition:
178 |
179 |
180 | foo.o bar.o: CFLAGS += --code-name FOOBAR
181 |
182 |