2 This document is slightly outdated! See cc65.txt and library.txt for a more
7 Discussion of some of the features/non features of the current cc65 version
8 ---------------------------------------------------------------------------
12 2. Differences to the original version
14 3. Known bugs and limitations
26 This is the original compiler copyright:
28 --------------------------------------------------------------------------
31 This is the copyright notice for RA65, LINK65, LIBR65, and other
32 Atari 8-bit programs. Said programs are Copyright 1989, by John R.
33 Dunning. All rights reserved, with the following exceptions:
35 Anyone may copy or redistribute these programs, provided that:
37 1: You don't charge anything for the copy. It is permissable to
38 charge a nominal fee for media, etc.
40 2: All source code and documentation for the programs is made
41 available as part of the distribution.
43 3: This copyright notice is preserved verbatim, and included in
46 You are allowed to modify these programs, and redistribute the
47 modified versions, provided that the modifications are clearly noted.
49 There is NO WARRANTY with this software, it comes as is, and is
50 distributed in the hope that it may be useful.
52 This copyright notice applies to any program which contains
53 this text, or the refers to this file.
55 This copyright notice is based on the one published by the Free
56 Software Foundation, sometimes known as the GNU project. The idea
57 is the same as theirs, ie the software is free, and is intended to
58 stay that way. Everybody has the right to copy, modify, and re-
59 distribute this software. Nobody has the right to prevent anyone
60 else from copying, modifying or redistributing it.
62 --------------------------------------------------------------------------
64 In acknowledgment of this copyright, I will place my own changes to the
65 compiler under the same copyright.
67 However, since the library and all binutils (assembler, archiver, linker)
68 are a complete rewrite, they are covered by another copyright:
71 --------------------------------------------------------------------------
73 CC65 C Library and Binutils
75 (C) Copyright 1998 Ullrich von Bassewitz
80 This software is provided 'as-is', without any expressed or implied
81 warranty. In no event will the authors be held liable for any damages
82 arising from the use of this software.
84 Permission is granted to anyone to use this software for any purpose,
85 including commercial applications, and to alter it and redistribute it
86 freely, subject to the following restrictions:
88 1. The origin of this software must not be misrepresented; you must not
89 claim that you wrote the original software. If you use this software
90 in a product, an acknowledgment in the product documentation would be
91 appreciated but is not required.
92 2. Altered source versions must be plainly marked as such, and must not
93 be misrepresented as being the original software.
94 3. This notice may not be removed or altered from any source
98 --------------------------------------------------------------------------
100 I will try to contact John, maybe he is also willing to place his sources
101 under a less restrictive copyright, after all these years:-)
106 2. Differences to the original version
107 --------------------------------------
109 This is a list of changes against the cc65 archives. I got the originals
112 http://www.umich.edu/~archive/atari/8bit/Languages/Cc65/
116 * Removed all assembler code from the compiler. It was unportable because
117 it made assumptions about the character set (ATASCII) and made the
118 sources hard to read and to debug.
120 * All programs do return an error code, so they may be used by make. All
121 programs try to remove the target file, if there were errors.
123 * The assembler now checks several error conditions (others still go
124 undetected - see "known bugs").
126 * Removed many bugs from the compiler. One error was invalid code
127 produced by the compiler that went through the assembler since the
128 assembler did not check for ranges itself.
130 * Removed many non-portable constructs from the compiler. Code cleanups,
131 rewrite of the function headers and more.
133 * New style function prototypes supported instead of the old K&R syntax.
134 The new syntax is a must, that is, the old style syntax is no longer
135 understood. As an extension, unnamed parameters may be used to avoid
136 warnings about unused parameters.
138 * New void type. May also be used as a function return type.
140 * Changed the memory management in the compiler. Use malloc/free instead
141 of the old homebrew (and unportable) stuff.
143 * Default character type is unsigned. This is much more what you want in
144 small systems environments, since a char is often used to represent a
145 small numerical value, and the integer promotion does the wrong thing
146 in those cases. Look at the follwing piece of code:
148 char c = read_char ();
150 case 0x80: printf ("c is 0x80\n"); break;
151 default: printf ("c is something else\n"); break;
154 With signed chars, the code above, will *always* run into the default
155 selector. c is promoted to int, and since it is signed, 0x80 will get
156 promoted to 0xFF80 - which will select the default label. With unsigned
157 chars, the code works as intended (but note: the code works for cc65
158 but it is non portable anyway, since many other compilers have signed
159 chars by default, so be careful! Having unsigned chars is just a
162 * Shorter code when using the builtin operators and the lhs of an expr
163 is a constant (e.g. expressions like "c == 0x80" are encoded two
166 * Some optimizations when pushing constants.
168 * Character set translation by the compiler. A new -t option was added
169 to set the target system type. Use
171 -t0 For no spefic target system (default)
172 -t1 For the atari (does not work completely, since I did not
173 have an ATASCII translation table).
174 -t2 Target system is C64.
175 -t3 Target system is C128.
176 -t4 Target system is ACE.
177 -t5 Target system is Plus/5.
179 * Dito for the linker: Allow an option to set the target system and add
180 code to the linker to produce different headers and set the correct
183 * Complete rewrite of the C library. See extra chapter.
185 * Many changes in the runtime library. Splitted it into more than one
186 file to allow for smaller executables if not all of the code is needed.
188 * Allow longer names. Now the first 12 characters are sigificant at the
189 expense of some more memory used at runtime.
191 * String constants are now concatenated in all places. This allows
195 " -b bomb computer\n"
196 " -f format hard disk\n"
200 saving code for more than one call to the function.
202 * Several new macros are defined:
204 M6502 This one is old - don't use!
205 __CC65__ Use this instead. Defined when compiling with cc65.
206 __ATARI__ Defined when the target system is atari.
207 __CBM__ Defined when compiling for a CBM system as target.
208 __C64__ Defined when the C64 is the target system.
209 __C128__ Defined when compiling for the 128.
210 __ACE__ Defined when compiling for ACE.
211 __PLUS4__ Defined when compiling for the Plus/4.
213 The __CC65__ macro has the compiler version as its value, version
214 1.0 of the compiler will define this macro as 0x100.
216 * The -a option is gone.
218 * The compiler will generate external references (via .globl) only if a
219 function is defined as extern in a module, or not defined but called
220 from a module. The old behaviour was to generate a reference for every
221 function prototype ever seen, which meant that using a header file like
222 stdio.h got most of the C library linked in, even if it was never used.
224 * Many new warnings added (about unused parameters, unused variables,
225 compares of unsigneds against zero, function call without prototype
228 * Added a new compiler option (-W) to suppress all warnings.
230 * New internal variable __fixargs__ that gives the size of fixed
231 arguments, a function takes. This allows to work (somehow) around the
232 problem, that cc65 has the "wrong" (that is, pascal) calling order. See
233 below ("Known problems") for a discussion.
235 * The "empty" preprocessor directive ("#" on a line) is now ignored.
237 * Added a "#error" directive to force user errors.
239 * Optimization of the code generation. Constant parts of expressions are
240 now detected in many places where the old compiler evaluated the
241 constants at runtime.
243 * Allow local static variables (there was code in the original compiler for
244 that, but it did not work). Allow also initialization in this case (no
245 code for that in the original). Local static variables in the top level
246 function block have no penalty, for static variables in nested blocks, the
247 compiler generates a jump around the variable space. To eliminate this,
248 an assembler/linker with support for segments is needed.
250 * You cannot return a value from a void function, and must return a value
251 in a non-void function. Violations are flagged as an error.
255 * The nonstandard evaluation of the NOARGC and FIXARGC macros has been
256 replaced by a smart algorithm that does the same thing automagically
257 and without user help (provided there are function prototypes).
259 * Function pointers may now be used to call a function without
260 dereferencing. Given a function
262 void f1 (void (*f2) ())
264 the following was valid before:
268 The ANSI standard allows a second form (because there's no ambiguity)
269 which is now also allowed:
273 * Pointer subtraction was completely messed up and did not work (that is,
274 subtraction of a pointer from a pointer produced wrong results).
276 * Local struct definitions are allowed.
278 * Check types in assignments, parameters for function calls and more.
280 * A new long type (32 bit) is available. The integer promotion rules
281 are applied if needed. This includes much more type checking and a
282 better handling of chars (they are handled as chars, not as ints, in
283 all places where this is possible).
285 * Integer constants now have an associated type, 'U' and 'L' modifers
288 * The old #asm statement is gone. Instead, there's now a asm ("xxx")
289 statement that has the syntax that is defined by the C++ standard
290 (the C standard does not define an ASM statement). The string literal
291 in parenthesis is inserted in the assembler output. You may also
292 use __asm__ instead of asm (see below).
296 * New compiler option -A (ANSI) that disables several extensions (asm
297 directive, // comments, unnamed function parameters) and also defines
298 a macro named __STRICT_ANSI__. The header files will exclude some
299 non-ANSI functions if __STRICT_ANSI__ is defined (that is, -A is given
300 on the command line).
301 -A will not disable the __asm__ directive (identifiers starting with
302 __ are in the namespace of the implementation).
304 * Create optimized code if the address of a variable is a constant. This
305 may be achieved by constructs like "*(char*)0x200 = 0x01" and is used
306 to access absolute memory locations. The compiler detects this case
307 also if structs or arrays are involved and generates direct stores and
317 * Only simple automatic variables may be initialized (no arrays).
319 * "Wrong" order of arguments on the stack. The arguments are pushed in
320 the order, the arguments are parsed. That means that the va_xxx macros
321 in stdarg.h are ok (they work as expected), but the fixed parameters of
322 a function with a variable argument list do not match and must be
323 determined with the (non-standard) va_fix macro.
325 Using the __fixargs__ kludge, it is possible to write standard conform
326 va_xxx macros to work with variable sized argument lists. However, the
327 fixed parameters in the function itself usually have the wrong values,
328 because the order of the arguments on the stack is reversed compared to
329 a stock C compiler. Pushing the args the other way round requires much
330 work and a more elaborated intermediate code than cc65 has.
332 To understand the problem, have a look at this (non working!) sprintf
335 int sprintf (char* buf, char* format, ...)
336 /* Non working version */
340 va_start (ap, format);
341 count = vsprintf (buf, format, ap);
346 The problem here is in the "format" and "buf" parameters. They do (in
347 most cases) not contain, what the caller gave us as arguments. To
348 access the "real" arguments, use the va_fix macro. It is only valid
349 before the first call to va_arg, and takes the va_list and the number
350 of the fixed argument as parameters. So the right way would be
352 int sprintf (char* buf, char* format, ...)
353 /* Working version */
357 va_start (ap, format);
358 count = vsprintf (va_fix (ap, 1), va_fix (ap, 2), ap);
363 The fixed parameter are obtained by using the va_fix macro with the
364 number of the parameter given as second argument. Beware: Since the
365 fixed arguments declared are usually one of the additional parameters,
366 the following code, which tries to be somewhat portable, does *not*
367 work. The assignment will overwrite the other parameters instead,
368 causing unexpected results:
370 int sprintf (char* buf, char* format, ...)
371 /* Non working version */
375 va_start (ap, format);
377 buf = va_fix (ap, 1);
378 format = va_fix (ap, 2);
380 count = vsprintf (buf, format, ap);
385 To write a portable version of sprintf, use code like this instead:
387 int sprintf (char* buf, char* format, ...)
388 /* Working version */
392 va_start (ap, format);
394 count = vsprintf (va_fix (ap, 1), va_fix (ap, 2), ap);
396 count = vsprintf (buf, format, ap);
402 I know, va_fix is a kludge, but at least it *is* possible to write
403 functions with variable sized argument lists in a comfortable manner.
405 * The assembler still accepts lots of illegal stuff without an error (and
406 creates wrong code). Be careful!
408 * When starting a compiled program twice on the C64 (or 128), you may get
409 other results or the program may even crash. This is because static
410 variables do not have their startup values, they were changed in the
413 * There's only *one* symbol table level. It is - via a flag - used for both,
414 locals and global symbols. However, if you have variables in nested
415 blocks, the names may collide with the ones in the upper block. I will
416 probably add real symbol tables some time to remove this problem.
418 * Variables in nested blocks are handled inefficiently, especially in loops.
419 The frame on the stack is allocated and deallocated for each loop
420 iteration. There's no way around this, since the compiler has not enough
421 memory to hold a complete function body in memory (it would be able to
422 backpatch the frame generating code on function entry).
430 The C library is a complete rewrite and has nothing in common with the old
431 Atari stuff. When rewriting the library, I was guided by the following
434 * Use standard conform functions as far as possible. In addition, if
435 there's a ANSI-C compatible function, it should act as defined in the
436 ANSI standard. If if does not act as defined, this is an error.
438 * Do not use non-standard functions if the functionality of those
439 functions is covered by a standard function. Use exceptions only, if
440 there is a non-ANSI function that is very popular (example: itoa).
442 * Use new style prototpyes and header files.
444 * Make the library portable. For example, the complete stdio stuff is
445 based on only four system dependent functions:
447 open, read, write, close
449 So, if you rewrite these functions for a new system, all others
450 (printf, fprintf, fgets, fputc ...) will work, too.
452 * Do not expect a common character set. Unfortunately, I was not able to
453 be completely consequent in this respect. C sources are no problem
454 since the compiler does character translation, but the assembler
455 sources make assumptions about the following characters:
461 All other functions (especially the isxxx ones) are table driven, so
462 only the classification table is system dependent.
465 The first port was for the ACE operating system. The current version has also
466 support for the C64, the C128 and the Plus/4 in native mode. The ACE port has
467 disk support but no conio module, all others don't have disk support but
470 Currently the following limitations the are known:
472 * getwd (ace) does not work. I get an error (carry flag) with an error
473 code of zero (aceErrStopped). Maybe my code is wrong...
475 * The error codes are currently system error codes. They should be
476 translated to something system independent. The ace codes are a good
477 starting point. However, I don't like the idea, that zero is a valid
478 error code, and some other codes are missing ("invalid parameter" and
479 more). As soon as this is done, it is also possible to write a
480 strerror() function to give more descriptive error messages to the
483 * Many functions not very good tested.
485 * The printf and heap functions are way too big. Rewritting _printf
486 and malloc/free in assembler will probably squeeze 2K out of the
489 * The isxxx functions do not handle EOF correctly. This is probably
490 a permanent restriction, even if it is non-standard. It would require
491 extra code in each of the isxxx functions, since EOF is defined as -1
492 and cannot be handled effectively with the table approach and 8 bit
495 * The strcspn, strpbrk and strspn functions have a string length limitation
496 of 256 for the second argument. This is usually not a problem since the
497 second argument gives a character set, and a character set cannot be
498 larger than 256 chars for all known 6502 systems.
506 Please note that the compiler and the libraries are beta! Send bug reports to