mirror of
https://github.com/cc65/cc65.git
synced 2024-08-19 02:29:33 +00:00
672 lines
20 KiB
Plaintext
672 lines
20 KiB
Plaintext
|
|
|
|
cc65
|
|
|
|
A C Compiler for 6502 Systems
|
|
|
|
(C) Copyright 1989 John R. Dunning
|
|
(C) Copyright 1998-2000 Ullrich von Bassewitz
|
|
(uz@musoftware.de)
|
|
|
|
|
|
|
|
Contents
|
|
--------
|
|
|
|
1. Overview
|
|
|
|
2. Usage
|
|
|
|
3. Input and output
|
|
|
|
4. Differences to the ISO standard
|
|
|
|
5. Extensions
|
|
|
|
6. Predefined macros
|
|
|
|
7. #pragmas
|
|
|
|
8. Bugs/Feedback
|
|
|
|
9. Copyright
|
|
|
|
|
|
|
|
1. Overview
|
|
-----------
|
|
|
|
cc65 was originally a C compiler for the Atari 8-bit machines written by
|
|
John R. Dunning. In prior releases I've described the compiler by listing
|
|
up the changes made by me. I have made many more changes in the meantime
|
|
(and rewritten major parts of the compiler), so I will no longer do that,
|
|
since the list would be too large and of no use to anyone. Instead I will
|
|
describe the compiler in respect to the ANSI/ISO C standard. In fact, I'm
|
|
planning a complete rewrite (that is, a complete new compiler) for the
|
|
next release, since there are too many limitations in the current code,
|
|
and removing these limitations would mean a rewrite of many more parts of
|
|
the compiler.
|
|
|
|
There is a separate document named "library.txt" that covers the library
|
|
available for the compiler. If you know C and are interested in doing
|
|
actual programming, the library documentation is probably of much more use
|
|
than this document.
|
|
|
|
If you need some hints for getting the best code out of the compiler, you
|
|
may have a look at "coding.txt" which covers some code generation issues.
|
|
|
|
|
|
|
|
2. Usage
|
|
--------
|
|
|
|
The compiler translates C files into files containing assembler code that
|
|
may be translated by the ca65 macroassembler (for more information about
|
|
the assembler, have a look at ca65.txt).
|
|
|
|
The compiler may be called as follows:
|
|
|
|
---------------------------------------------------------------------------
|
|
Usage: cc65 [options] file
|
|
Short options:
|
|
-d Debug mode
|
|
-g Add debug info to object file
|
|
-h Help (this text)
|
|
-j Default characters are signed
|
|
-o name Name the output file
|
|
-t sys Set the target system
|
|
-v Increase verbosity
|
|
-A Strict ANSI mode
|
|
-Cl Make local variables static
|
|
-Dsym[=defn] Define a symbol
|
|
-I dir Set an include directory search path
|
|
-O Optimize code
|
|
-Oi Optimize code, inline more code
|
|
-Or Enable register variables
|
|
-Os Inline some known functions
|
|
-T Include source as comment
|
|
-V Print the compiler version number
|
|
-W Suppress warnings
|
|
|
|
Long options:
|
|
--ansi Strict ANSI mode
|
|
--cpu type Set cpu type
|
|
--debug Debug mode
|
|
--debug-info Add debug info to object file
|
|
--help Help (this text)
|
|
--include-dir dir Set an include directory search path
|
|
--signed-chars Default characters are signed
|
|
--static-locals Make local variables static
|
|
--target sys Set the target system
|
|
--verbose Increase verbosity
|
|
--version Print the compiler version number
|
|
---------------------------------------------------------------------------
|
|
|
|
|
|
-A
|
|
--ansi
|
|
|
|
This option disables any compiler exensions. Have a look at section 5
|
|
for a discussion of compiler extensions. In addition, the macro
|
|
|
|
__STRICT_ANSI__
|
|
|
|
is defined, when using one of these options.
|
|
|
|
|
|
--cpu CPU
|
|
|
|
A new, still experimental option. You may specify "6502" or "65C02" as
|
|
the CPU. 6502 is the default, so this will not change anything.
|
|
Specifying 65C02 will use a few 65C02 instructions when generating code.
|
|
Don't expect too much from this option: It is still new (and may have
|
|
bugs), and the additional instructions for the 65C02 are not that
|
|
overwhelming.
|
|
|
|
|
|
-d
|
|
--debug
|
|
|
|
Enables debug mode, something that should not be needed for mere
|
|
mortals:-)
|
|
|
|
|
|
-D sym[=definition]
|
|
|
|
Define a macro on the command line. If no definition is given, the macro
|
|
is defined to the value "1".
|
|
|
|
|
|
-g
|
|
--debug-info
|
|
|
|
This will cause the compiler to insert a .DEBUGINFO command into the
|
|
generated assembler code. This will cause the assembler to include all
|
|
symbols in a special section in the object file.
|
|
|
|
|
|
-h
|
|
--help
|
|
|
|
Print the short option summary shown above.
|
|
|
|
|
|
-j
|
|
--signed-chars
|
|
|
|
Using this option, you can make the default characters signed. Since the
|
|
6502 has no provisions for sign extending characters (which is needed on
|
|
almost any load operation), this will make the code larger and slower. A
|
|
better way is to declare characters explicitly as "signed" if needed.
|
|
You can also use "#pragma signedchars" for better control of this option
|
|
(see section 7).
|
|
|
|
|
|
-t target
|
|
--target target
|
|
|
|
This option is used to set the target system. The target system
|
|
determines things like the character set that is used for strings and
|
|
character constants. The following target systems are supported:
|
|
|
|
none
|
|
c64
|
|
c128
|
|
ace (no library support)
|
|
plus4
|
|
cbm610
|
|
pet (all CBM PET systems except the 2001)
|
|
nes (Nintendo Entertainment System)
|
|
apple2
|
|
geos
|
|
|
|
|
|
-v
|
|
--verbose
|
|
|
|
Using this option, the compiler will be somewhat more verbose if errors
|
|
or warnings are encountered.
|
|
|
|
|
|
-Cl
|
|
--static-locals
|
|
|
|
Use static storage for local variables instead of storage on the stack.
|
|
Since the stack is emulated in software, this gives shorter and usually
|
|
faster code, but the code is no longer reentrant. The difference between
|
|
-Cl and declaring local variables as static yourself is, that
|
|
initializer code is executed each time, the function is entered. So when
|
|
using
|
|
|
|
void f (void)
|
|
{
|
|
unsigned a = 1;
|
|
...
|
|
}
|
|
|
|
the variable a will always have the value 1 when entering the function
|
|
and using -Cl, while in
|
|
|
|
void f (void)
|
|
{
|
|
static unsigned a = 1;
|
|
....
|
|
}
|
|
|
|
the variable a will have the value 1 only the first time, the function
|
|
is entered, and will keep the old value from one call of the function to
|
|
the next.
|
|
|
|
You may also use #pragma staticlocals to change this setting in your
|
|
sources (see section 7).
|
|
|
|
|
|
-I dir
|
|
--include-dir dir
|
|
|
|
Set a directory where the compiler searches for include files. You may
|
|
use this option multiple times to add more than one directory to the
|
|
search list.
|
|
|
|
|
|
-o name
|
|
|
|
Specify the name of the output file. If you don't specify a name, the
|
|
name of the C input file is used, with the extension replaced by ".s".
|
|
|
|
|
|
-O, -Oi, -Or, -Os
|
|
|
|
Enable an optimizer run over the produced code.
|
|
|
|
Using -Oi, the code generator will inline some code where otherwise a
|
|
runtime functions would have been called, even if the generated code is
|
|
larger. This will not only remove the overhead for a function call, but
|
|
will make the code visible for the optimizer.
|
|
|
|
-Or will make the compiler honor the "register" keyword. Local variables
|
|
may be placed in registers (which are actually zero page locations).
|
|
There is some overhead involved with register variables, since the old
|
|
contents of the registers must be saved and restored. In addition, the
|
|
current implementation does not make good use of register variables, so
|
|
using -Or may make your program even slower and larger. Use with care!
|
|
|
|
Using -Os will force the compiler to inline some known functions from
|
|
the C library like strlen. Note: This has two consequences:
|
|
|
|
* You may not use names of standard C functions in your own code. If
|
|
you do that, your program is not standard compliant anyway, but
|
|
using -Os will actually break things.
|
|
|
|
* The inlined string and memory functions will not handle strings or
|
|
memory areas larger than 255 bytes. Similar, the inlined is..()
|
|
functions will not work with values outside char range.
|
|
|
|
It is possible to concatenate the modifiers for -O. For example, to
|
|
enable register variables and inlining of known functions, you may use
|
|
-Ors.
|
|
|
|
|
|
-T
|
|
|
|
This include the source code as comments in the generated code. This is
|
|
normally not needed.
|
|
|
|
|
|
-V
|
|
--version
|
|
|
|
Print the version number of the compiler. When submitting a bug report,
|
|
please include the operating system you're using, and the compiler
|
|
version.
|
|
|
|
|
|
-W
|
|
|
|
This option will suppress any warnings generated by the compiler. Since
|
|
any source file may be written in a manner that it will not produce
|
|
compiler warnings, using this option is usually not a good idea.
|
|
|
|
|
|
|
|
3. Input and output
|
|
-------------------
|
|
|
|
The compiler will accept one C file per invocation and create a file with
|
|
the same base name, but with the extension replaced by ".s". The output
|
|
file contains assembler code suitable for the use with the ca65 macro
|
|
assembler.
|
|
|
|
In addition to the paths named in the -I option on the command line, the
|
|
directory named in the environment variable CC65_INC is added to the
|
|
search path for include files on startup.
|
|
|
|
|
|
|
|
4. Differences to the ISO standard
|
|
----------------------------------
|
|
|
|
Here is a list of differences between the language, the compiler accepts,
|
|
and the one defined by the ISO standard:
|
|
|
|
|
|
* The compiler allows single line comments that start with //. This
|
|
feature is disabled in strict ANSI mode.
|
|
|
|
* The compiler allows unnamed parameters in parameter lists. The
|
|
compiler will not issue warnings about unused parameters that don't
|
|
have a name. This feature is disabled in strict ANSI mode.
|
|
|
|
* The compiler has some additional keywords:
|
|
|
|
asm, __asm__, fastcall, __fastcall__, __AX__, __EAX__, __func__,
|
|
__attribute__
|
|
|
|
The keywords without the underlines are disabled in strict ANSI mode.
|
|
|
|
* The "const" modifier is available, but has no effect.
|
|
|
|
* The datatypes "float" and "double" are not available.
|
|
|
|
* The compiler does not support bit fields.
|
|
|
|
* Initialization of local variables is only possible for scalar data
|
|
types (that is, not for arrays and structs).
|
|
|
|
* Because of the "wrong" order of the parameters on the stack, there is
|
|
an additional macro needed to access parameters in a variable
|
|
parameter list in a C function.
|
|
|
|
* Functions may not return structs. However, struct assignment *is*
|
|
possible.
|
|
|
|
* Part of the C library is available only with fastcall calling
|
|
conventions (see below). This means, that you may not mix pointers to
|
|
those functions with pointers to user written functions.
|
|
|
|
There may be some more minor differences, I'm currently not aware off. The
|
|
biggest problem is the missing float data type. With this limitation in
|
|
mind, you should be able to write fairly portable code.
|
|
|
|
|
|
|
|
5. Extensions
|
|
-------------
|
|
|
|
This cc65 version has some extensions to the ISO C standard.
|
|
|
|
* The compiler allows // comments (like in C++ and in the proposed C9x
|
|
standard). This feature is disabled by -A.
|
|
|
|
* The compiler allows to insert assembler statements into the output
|
|
file. The syntax is
|
|
|
|
asm (<string literal>) ;
|
|
|
|
or
|
|
|
|
__asm__ (<string literal>) ;
|
|
|
|
The first form is in the user namespace and is disabled if the -A
|
|
switch is given.
|
|
|
|
The given string is inserted literally into the output file, and a
|
|
newline is appended. The statements in this string are not checked by
|
|
the compiler, so be careful!
|
|
|
|
The asm statement may be used inside a function and on global file
|
|
level.
|
|
|
|
* There is a special calling convention named "fastcall". This calling
|
|
convention is currently only usable for functions written in
|
|
assembler. The syntax for a function declaration using fastcall is
|
|
|
|
<return type> fastcall <function name> (<parameter list>)
|
|
|
|
or
|
|
|
|
<return type> __fastcall__ <function name> (<parameter list>)
|
|
|
|
An example would be
|
|
|
|
void __fastcall__ f (unsigned char c)
|
|
|
|
The first form of the fastcall keyword is in the user namespace and is
|
|
therefore disabled in strict ANSI mode.
|
|
|
|
For functions declared as fastcall, the rightmost parameter is not
|
|
pushed on the stack but left in the primary register when the function
|
|
is called. This will reduce the cost when calling assembler functions
|
|
significantly, especially when the function itself is rather small.
|
|
|
|
* There are two pseudo variables named __AX__ and __EAX__. Both refer to
|
|
the primary register that is used by the compiler to evaluate
|
|
expressions or return function results. __AX__ is of type unsigned int
|
|
and __EAX__ of type long unsigned int respectively. The pseudo
|
|
variables may be used as lvalue and rvalue as every other variable.
|
|
They are most useful together with short sequences of assembler code.
|
|
For example, the macro
|
|
|
|
#define hi(x) (__AX__=(x),asm("\ttxa\n\tldx\t#$00",__AX__)
|
|
|
|
will give the high byte of any unsigned value.
|
|
|
|
* Inside a function, the identifier __func__ gives the name of the
|
|
current function as a string. Outside of functions, __func__ is
|
|
undefined.
|
|
Example:
|
|
|
|
#define PRINT_DEBUG(s) printf ("%s: %s\n", __func__, s);
|
|
|
|
The macro will print the name of the current function plus a given
|
|
string.
|
|
|
|
|
|
|
|
6. Predefined macros
|
|
--------------------
|
|
|
|
The compiler defines several macros at startup:
|
|
|
|
|
|
__CC65__ This macro is always defined. Its value is the version
|
|
number of the compiler in hex. Version 2.0.1 of the
|
|
compiler will have this macro defined as 0x0201.
|
|
|
|
__CBM__ This macro is defined if the target system is one of the
|
|
CBM targets.
|
|
|
|
__C64__ This macro is defined if the target is the c64 (-t c64).
|
|
|
|
__C128__ This macro is defined if the target is the c128 (-t c128).
|
|
|
|
__PLUS4__ This macro is defined if the target is the plus/4
|
|
(-t plus4).
|
|
|
|
__CBM610__ This macro is defined if the target is one of the CBM
|
|
600/700 family of computers (called B series in the US).
|
|
|
|
__PET__ This macro is defined if the target is the PET family of
|
|
computers (-t pet).
|
|
|
|
__NES__ This macro is defined if the target is the Nintendo
|
|
Entertainment System (-t nes).
|
|
|
|
__ATARI__ This macro is defined if the target is one of the Atari
|
|
computers (400/800/130XL/800XL). Note that there is no
|
|
runtime and C library support for atari systems.
|
|
|
|
__ACE__ This macro is defined if the target is Bruce Craigs ACE
|
|
operating system. Note that there is no longer runtime
|
|
and library support for ACE.
|
|
|
|
__APPLE2__ This macro is defined if the target is the Apple ][
|
|
(-t apple2).
|
|
|
|
__GEOS__ This macro is defined if you are compiling for the GEOS
|
|
system (-t geos).
|
|
|
|
__FILE__ This macro expands to a string containing the name of
|
|
the C source file.
|
|
|
|
__LINE__ This macro expands to the current line number.
|
|
|
|
__STRICT_ANSI__ This macro is defined to 1 if the -A compiler option was
|
|
given, and undefined otherwise.
|
|
|
|
__OPT__ Is defined if the compiler was called with the -O command
|
|
line option.
|
|
|
|
__OPT_i__ Is defined if the compiler was called with the -Oi command
|
|
line option.
|
|
|
|
__OPT_r__ Is defined if the compiler was called with the -Or command
|
|
line option.
|
|
|
|
__OPT_s__ Is defined if the compiler was called with the -Os command
|
|
line option.
|
|
|
|
|
|
|
|
7. #pragmas
|
|
-----------
|
|
|
|
The compiler understands some pragmas that may be used to change code
|
|
generation and other stuff.
|
|
|
|
|
|
#pragma bssseg (<name>)
|
|
|
|
This pragma changes the name used for the BSS segment (the BSS segment
|
|
is used to store uninitialized data). The argument is a string enclosed
|
|
in double quotes.
|
|
|
|
Note: The default linker configuration file does only map the standard
|
|
segments. If you use other segments, you have to create a new linker
|
|
configuration file.
|
|
|
|
Beware: The startup code will zero only the default BSS segment. If you
|
|
use another BSS segment, you have to do that yourself, otherwise
|
|
uninitialized variables do not have the value zero.
|
|
|
|
Example:
|
|
|
|
#pragma bssseg ("MyBSS")
|
|
|
|
|
|
#pragma codeseg (<name>)
|
|
|
|
This pragma changes the name used for the CODE segment (the CODE segment
|
|
is used to store executable code). The argument is a string enclosed in
|
|
double quotes.
|
|
|
|
Note: The default linker configuration file does only map the standard
|
|
segments. If you use other segments, you have to create a new linker
|
|
configuration file.
|
|
|
|
Example:
|
|
|
|
#pragma bssseg ("MyCODE")
|
|
|
|
|
|
#pragma dataseg (<name>)
|
|
|
|
This pragma changes the name used for the DATA segment (the DATA segment
|
|
is used to store initialized data). The argument is a string enclosed in
|
|
double quotes.
|
|
|
|
Note: The default linker configuration file does only map the standard
|
|
segments. If you use other segments, you have to create a new linker
|
|
configuration file.
|
|
|
|
Example:
|
|
|
|
#pragma bssseg ("MyDATA")
|
|
|
|
|
|
#pragma rodataseg (<name>)
|
|
|
|
This pragma changes the name used for the RODATA segment (the RODATA
|
|
segment is used to store readonly data). The argument is a string
|
|
enclosed in double quotes.
|
|
|
|
Note: The default linker configuration file does only map the standard
|
|
segments. If you use other segments, you have to create a new linker
|
|
configuration file.
|
|
|
|
Example:
|
|
|
|
#pragma bssseg ("MyRODATA")
|
|
|
|
|
|
#pragma regvaraddr (<const int>)
|
|
|
|
The compiler does not allow to take the address of register variables.
|
|
The regvaraddr pragma changes this. Taking the address of a register
|
|
variable is allowed after using this pragma, if the argument is not
|
|
zero. Using an argument of zero changes back to the default behaviour.
|
|
|
|
Beware: The C standard does not allow taking the address of a variable
|
|
declared as register. So your programs become non-portable if you use
|
|
this pragma. In addition, your program may not work. This is usually the
|
|
case if a subroutine is called with the address of a register variable,
|
|
and this subroutine (or a subroutine called from there) uses itself
|
|
register variables. So be careful with this #pragma.
|
|
|
|
Example:
|
|
|
|
#pragma regvaraddr(1) /* Allow taking the address
|
|
* of register variables
|
|
*/
|
|
|
|
|
|
#pragma signedchars (<const int>)
|
|
|
|
Changed the signedness of the default character type. If the argument
|
|
is not zero, default characters are signed, otherwise characters are
|
|
unsigned. The compiler default is to make characters unsigned since this
|
|
creates a lot better code.
|
|
|
|
|
|
#pragma staticlocals (<const int>)
|
|
|
|
Use variables in the bss segment instead of variables on the stack. This
|
|
pragma changes the default set by the compiler option -Cl. If the argument
|
|
is not zero, local variables are allocated in the BSS segment, leading to
|
|
shorter and in most cases faster, but non-reentrant code.
|
|
|
|
|
|
#pragma zpsym (<name>)
|
|
|
|
Tell the compiler that the - previously as external declared - symbol with
|
|
the given name is a zero page symbol (usually from an assembler file).
|
|
The compiler will create a matching import declaration for the assembler.
|
|
|
|
Example:
|
|
|
|
extern int foo;
|
|
#pragma zpsym ("foo"); /* foo is in the zeropage */
|
|
|
|
|
|
|
|
8. Bugs/Feedback
|
|
----------------
|
|
|
|
If you have problems using the compiler, if you find any bugs, or if
|
|
you're doing something interesting with the compiler, I would be glad to
|
|
hear from you. Feel free to contact me by email (uz@musoftware.de).
|
|
|
|
|
|
|
|
9. Copyright
|
|
------------
|
|
|
|
This is the original compiler copyright:
|
|
|
|
--------------------------------------------------------------------------
|
|
-*- Mode: Text -*-
|
|
|
|
This is the copyright notice for RA65, LINK65, LIBR65, and other
|
|
Atari 8-bit programs. Said programs are Copyright 1989, by John R.
|
|
Dunning. All rights reserved, with the following exceptions:
|
|
|
|
Anyone may copy or redistribute these programs, provided that:
|
|
|
|
1: You don't charge anything for the copy. It is permissable to
|
|
charge a nominal fee for media, etc.
|
|
|
|
2: All source code and documentation for the programs is made
|
|
available as part of the distribution.
|
|
|
|
3: This copyright notice is preserved verbatim, and included in
|
|
the distribution.
|
|
|
|
You are allowed to modify these programs, and redistribute the
|
|
modified versions, provided that the modifications are clearly noted.
|
|
|
|
There is NO WARRANTY with this software, it comes as is, and is
|
|
distributed in the hope that it may be useful.
|
|
|
|
This copyright notice applies to any program which contains
|
|
this text, or the refers to this file.
|
|
|
|
This copyright notice is based on the one published by the Free
|
|
Software Foundation, sometimes known as the GNU project. The idea
|
|
is the same as theirs, ie the software is free, and is intended to
|
|
stay that way. Everybody has the right to copy, modify, and re-
|
|
distribute this software. Nobody has the right to prevent anyone
|
|
else from copying, modifying or redistributing it.
|
|
|
|
--------------------------------------------------------------------------
|
|
|
|
In acknowledgment of this copyright, I will place my own changes to the
|
|
compiler under the same copyright. Please note however, that the library
|
|
and all binutils are covered by another copyright, and that I'm planning
|
|
to do a complete rewrite of the compiler, after which the compiler
|
|
copyright will also change.
|
|
|
|
For the list of changes requested by this copyright see newvers.txt.
|
|
|
|
|
|
|