mirror of
https://github.com/cc65/cc65.git
synced 2024-12-23 04:30:10 +00:00
1046 lines
36 KiB
Plaintext
1046 lines
36 KiB
Plaintext
<!doctype linuxdoc system>
|
|
|
|
<article>
|
|
<title>cc65 Users Guide
|
|
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
|
|
<date>03.09.2000, 02.10.2001
|
|
|
|
<abstract>
|
|
cc65 is a C compiler for 6502 targets. It supports several 6502 based home
|
|
computers like the Commodore and Atari machines, but it is easily retargetable.
|
|
</abstract>
|
|
|
|
<!-- Table of contents -->
|
|
<toc>
|
|
|
|
<!-- Begin the document -->
|
|
|
|
|
|
<sect>Overview<p>
|
|
|
|
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.
|
|
|
|
|
|
|
|
<sect>Usage<p>
|
|
|
|
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).
|
|
|
|
|
|
<sect1>Command line option overview<p>
|
|
|
|
The compiler may be called as follows:
|
|
|
|
<tscreen><verb>
|
|
---------------------------------------------------------------------------
|
|
Usage: cc65 [options] file
|
|
Short options:
|
|
-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
|
|
-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
|
|
-r Enable register variables
|
|
-t sys Set the target system
|
|
-v Increase verbosity
|
|
|
|
Long options:
|
|
--add-source Include source as comment
|
|
--ansi Strict ANSI mode
|
|
--bss-name seg Set the name of the BSS segment
|
|
--check-stack Generate stack overflow checks
|
|
--code-name seg Set the name of the CODE segment
|
|
--codesize x Accept larger code by factor x
|
|
--cpu type Set cpu type
|
|
--create-dep Create a make dependency file
|
|
--data-name seg Set the name of the DATA segment
|
|
--debug Debug mode
|
|
--debug-info Add debug info to object file
|
|
--help Help (this text)
|
|
--include-dir dir Set an include directory search path
|
|
--register-space b Set space available for register variables
|
|
--register-vars Enable register variables
|
|
--rodata-name seg Set the name of the RODATA segment
|
|
--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
|
|
---------------------------------------------------------------------------
|
|
</verb></tscreen>
|
|
|
|
|
|
<sect1>Command line options in detail<p>
|
|
|
|
Here is a description of all the command line options:
|
|
|
|
<descrip>
|
|
|
|
<label id="option-A">
|
|
<tag><tt>-A, --ansi</tt></tag>
|
|
|
|
This option disables any compiler exensions. Have a look at section 5
|
|
for a discussion of compiler extensions. In addition, the macro
|
|
<tt/__STRICT_ANSI__/ is defined, when using one of these options.
|
|
|
|
|
|
<tag><tt>--bss-name seg</tt></tag>
|
|
|
|
Set the name of the bss segment.
|
|
|
|
|
|
<tag><tt>--check-stack</tt></tag>
|
|
|
|
Tells the compiler to generate code that checks for stack overflows. See
|
|
<tt><ref id="pragma-checkstack" name="#pragma checkstack"></tt> for an
|
|
explanation of this feature.
|
|
|
|
|
|
<tag><tt>--code-name seg</tt></tag>
|
|
|
|
Set the name of the code segment.
|
|
|
|
|
|
<tag><tt>--codesize x</tt></tag>
|
|
|
|
This options allows finer control about speed vs. size decisions in the
|
|
code generation phase. It gives the allowed size increase factor (in
|
|
percent). The default is 100 when not using <tt/-Oi/ and 200 when using
|
|
<tt/-Oi/ (<tt/-Oi/ is the same as <tt/--codesize 200/).
|
|
|
|
|
|
<tag><tt>--cpu CPU</tt></tag>
|
|
|
|
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.
|
|
|
|
|
|
<tag><tt>--create-dep</tt></tag>
|
|
|
|
Tells the compiler to generate a file containing the dependency list for
|
|
the compiled module in makefile syntax. The file is named as the C input
|
|
file with the extension replaced by <tt/.u/.
|
|
|
|
|
|
<tag><tt>-d, --debug</tt></tag>
|
|
|
|
Enables debug mode, something that should not be needed for mere
|
|
mortals:-)
|
|
|
|
|
|
<tag><tt>-D sym[=definition]</tt></tag>
|
|
|
|
Define a macro on the command line. If no definition is given, the macro
|
|
is defined to the value "1".
|
|
|
|
|
|
<tag><tt>-g, --debug-info</tt></tag>
|
|
|
|
This will cause the compiler to insert a <tt/.DEBUGINFO/ command into the
|
|
generated assembler code. This will cause the assembler to include all
|
|
symbols in a special section in the object file.
|
|
|
|
|
|
<tag><tt>-h, --help</tt></tag>
|
|
|
|
Print the short option summary shown above.
|
|
|
|
|
|
<tag><tt>-o name</tt></tag>
|
|
|
|
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".
|
|
|
|
|
|
<tag><tt>-r, --register-vars</tt></tag>
|
|
|
|
<tt/-r/ will make the compiler honor the <tt/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. Since register
|
|
variables are of limited use without the optimizer, there is also a combined
|
|
switch: <tt/-Or/ will enable both, the optmizer and register variables.
|
|
|
|
For more information about register variables see <ref id="regvars"
|
|
name="register variables">.
|
|
|
|
The compiler setting can also be changed within the source file by using
|
|
<tt><ref id="pragma-regvars" name="#pragma regvars"></tt>.
|
|
|
|
|
|
<tag><tt>--register-space</tt></tag>
|
|
|
|
This option takes a numeric parameter and is used to specify, how much
|
|
zero page register space is available. Please note that just giving this
|
|
option will not increase or decrease by itself, it will just tell the
|
|
compiler about the available space. You will have to allocate that space
|
|
yourself using an assembler module with the necessary allocations, and a
|
|
linker configuration that matches the assembler module. The default value
|
|
for this option is 6 (bytes).
|
|
|
|
If you don't know what all this means, please don't use this option.
|
|
|
|
|
|
<tag><tt>--rodata-name seg</tt></tag>
|
|
|
|
Set the name of the rodata segment (the segment used for readonly data).
|
|
|
|
|
|
<tag><tt>-j, --signed-chars</tt></tag>
|
|
|
|
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 <tt><ref id="pragma-signedchars" name="#pragma
|
|
signedchars"></tt> for better control of this option.
|
|
|
|
|
|
<tag><tt>-t target, --target target</tt></tag>
|
|
|
|
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:
|
|
|
|
<itemize>
|
|
<item>none
|
|
<item>apple2
|
|
<item>atari
|
|
<item>atmos
|
|
<item>c16 (works also for the c116 with memory up to 32K)
|
|
<item>c64
|
|
<item>c128
|
|
<item>plus4
|
|
<item>cbm510 (CBM-II series with 40 column video)
|
|
<item>cbm610 (all CBM-II II computers with 80 column video)
|
|
<item>pet (all CBM PET systems except the 2001)
|
|
<item>geos
|
|
</itemize>
|
|
|
|
<tag><tt>-v, --verbose</tt></tag>
|
|
|
|
Using this option, the compiler will be somewhat more verbose if errors
|
|
or warnings are encountered.
|
|
|
|
|
|
<tag><tt>-Cl, --static-locals</tt></tag>
|
|
|
|
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
|
|
<tt/-Cl/ and declaring local variables as static yourself is, that
|
|
initializer code is executed each time, the function is entered. So when
|
|
using
|
|
|
|
<tscreen><verb>
|
|
void f (void)
|
|
{
|
|
unsigned a = 1;
|
|
...
|
|
}
|
|
</verb></tscreen>
|
|
|
|
the variable a will always have the value 1 when entering the function
|
|
and using <tt/-Cl/, while in
|
|
|
|
<tscreen><verb>
|
|
void f (void)
|
|
{
|
|
static unsigned a = 1;
|
|
....
|
|
}
|
|
</verb></tscreen>
|
|
|
|
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 <tt><ref id="pragma-staticlocals" name="#pragma
|
|
staticlocals"></tt> to change this setting in your sources.
|
|
|
|
|
|
<tag><tt>-I dir, --include-dir dir</tt></tag>
|
|
|
|
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.
|
|
|
|
|
|
<tag><tt>-O, -Oi, -Or, -Os</tt></tag>
|
|
|
|
Enable an optimizer run over the produced code.
|
|
|
|
Using <tt/-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. <tt/-Oi/ is an alias for
|
|
<tt/--codesize 200/.
|
|
|
|
<tt/-Or/ will make the compiler honor the <tt/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 <tt/-Or/ may make your program even slower and larger. Use with care!
|
|
|
|
Using <tt/-Os/ will force the compiler to inline some known functions from
|
|
the C library like strlen. Note: This has two consequences:
|
|
<p>
|
|
<itemize>
|
|
<item>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
|
|
<tt/-Os/ will actually break things.
|
|
<p>
|
|
<item>The inlined string and memory functions will not handle strings or
|
|
memory areas larger than 255 bytes. Similar, the inlined <tt/is..()/
|
|
functions will not work with values outside char range.
|
|
<p>
|
|
</itemize>
|
|
<p>
|
|
It is possible to concatenate the modifiers for <tt/-O/. For example, to
|
|
enable register variables and inlining of known functions, you may use
|
|
<tt/-Ors/.
|
|
|
|
|
|
<tag><tt>-T, --add-source</tt></tag>
|
|
|
|
This include the source code as comments in the generated code. This is
|
|
normally not needed.
|
|
|
|
|
|
<tag><tt>-V, --version</tt></tag>
|
|
|
|
Print the version number of the compiler. When submitting a bug report,
|
|
please include the operating system you're using, and the compiler
|
|
version.
|
|
|
|
|
|
<tag><tt>-W</tt></tag>
|
|
|
|
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.
|
|
|
|
</descrip><p>
|
|
|
|
|
|
<sect>Input and output<p>
|
|
|
|
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 <tt/-I/ option on the command line, the
|
|
directory named in the environment variable <tt/CC65_INC/ is added to the
|
|
search path for include files on startup.
|
|
|
|
|
|
|
|
<sect>Differences to the ISO standard<p>
|
|
|
|
Here is a list of differences between the language, the compiler accepts,
|
|
and the one defined by the ISO standard:
|
|
|
|
<itemize>
|
|
|
|
<item> The compiler allows single line comments that start with //. This
|
|
feature is disabled in strict ANSI mode.
|
|
<p>
|
|
<item> 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.
|
|
<p>
|
|
<item> The compiler has some additional keywords:
|
|
<p>
|
|
<itemize>
|
|
<item><tt/asm/
|
|
<item><tt/__asm__/
|
|
<item><tt/fastcall/
|
|
<item><tt/__fastcall__/
|
|
<item><tt/__AX__/
|
|
<item><tt/__EAX__/
|
|
<item><tt/__func__/
|
|
<item><tt/__attribute__/
|
|
</itemize>
|
|
<p>
|
|
The keywords without the underlines are disabled in strict ANSI mode.
|
|
<p>
|
|
<item> The datatypes "float" and "double" are not available.
|
|
<p>
|
|
<item> The compiler does not support bit fields.
|
|
<p>
|
|
<item> C Functions may not return structs (or unions), and structs may not
|
|
be passed as parameters by value. However, struct assignment *is*
|
|
possible.
|
|
<p>
|
|
<item> 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.
|
|
<p>
|
|
</itemize>
|
|
|
|
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.
|
|
|
|
|
|
|
|
<sect>Extensions<p>
|
|
|
|
This cc65 version has some extensions to the ISO C standard.
|
|
|
|
<itemize>
|
|
|
|
<item> The compiler allows // comments (like in C++ and in the proposed C9x
|
|
standard). This feature is disabled by <tt><ref id="option-A"
|
|
name="-A"></tt>.
|
|
<p>
|
|
|
|
<item> The compiler allows to insert assembler statements into the output
|
|
file. The syntax is
|
|
|
|
<tscreen><verb>
|
|
asm (<string literal>[, optional parameters]) ;
|
|
</verb></tscreen>
|
|
or
|
|
<tscreen><verb>
|
|
__asm__ (<string literal>[, optional parameters]) ;
|
|
</verb></tscreen>
|
|
|
|
The first form is in the user namespace and is disabled if the <tt/-A/
|
|
switch is given.
|
|
|
|
There is a whole section covering inline assembler statements,
|
|
<ref id="inline-asm" name="see there">.
|
|
<p>
|
|
|
|
<item> 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
|
|
|
|
<tscreen><verb>
|
|
<return type> fastcall <function name> (<parameter list>)
|
|
</verb></tscreen>
|
|
or
|
|
<tscreen><verb>
|
|
<return type> __fastcall__ <function name> (<parameter list>)
|
|
</verb></tscreen>
|
|
An example would be
|
|
<tscreen><verb>
|
|
void __fastcall__ f (unsigned char c)
|
|
</verb></tscreen>
|
|
The first form of the fastcall keyword is in the user namespace and is
|
|
therefore disabled in strict ANSI mode.
|
|
|
|
For functions declared as <tt/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.
|
|
<p>
|
|
|
|
<item> There are two pseudo variables named <tt/__AX__/ and <tt/__EAX__/.
|
|
Both refer to the primary register that is used by the compiler to
|
|
evaluate expressions or return function results. <tt/__AX__/ is of
|
|
type <tt/unsigned int/ and <tt/__EAX__/ of type <tt/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
|
|
|
|
<tscreen><verb>
|
|
#define hi(x) (__AX__=(x),asm("\ttxa\n\tldx\t#$00",__AX__)
|
|
</verb></tscreen>
|
|
|
|
will give the high byte of any unsigned value.
|
|
<p>
|
|
|
|
<item> Inside a function, the identifier <tt/__func__/ gives the name of the
|
|
current function as a string. Outside of functions, <tt/__func__/ is
|
|
undefined.
|
|
Example:
|
|
|
|
<tscreen><verb>
|
|
#define PRINT_DEBUG(s) printf ("%s: %s\n", __func__, s);
|
|
</verb></tscreen>
|
|
|
|
The macro will print the name of the current function plus a given
|
|
string.
|
|
<p>
|
|
|
|
<item> cc65 allows the initialization of <tt/void/ variables. This may be
|
|
used to create variable structures that are more compatible with
|
|
interfaces written for assembler languages. Here is an example:
|
|
|
|
<tscreen><verb>
|
|
void GCmd = { (char)3, (unsigned)0x2000, (unsigned)0x3000 };
|
|
</verb></tscreen>
|
|
|
|
This will be translated as follows:
|
|
|
|
<tscreen><verb>
|
|
_GCmd:
|
|
.byte 3
|
|
.word $2000
|
|
.word $3000
|
|
</verb></tscreen>
|
|
|
|
Since the variable is of type <tt/void/ you may not use it as is.
|
|
However, taking the address of the variable results in a <tt/void*/
|
|
which may be passed to any function expecting a pointer.
|
|
|
|
See the <htmlurl url="geos.html" name="GEOS library"> for examples on
|
|
how to use this feature.
|
|
<p>
|
|
|
|
<item> cc65 implements flexible array struct members as defined in the C99 ISO
|
|
standard. As an extension, in non ANSI mode, these fields may be
|
|
initialized. There are several exceptions, however (which is probably
|
|
the reason why the standard does not define this feature, because it is
|
|
highly unorthogonal). Flexible array members cannot be initialized...
|
|
|
|
<itemize>
|
|
<item> ...when defining an array of structs with flexible members.
|
|
<item> ...if such a struct is a member field of another struct which
|
|
is not the last field.
|
|
<item> If the struct which contains a flexible array member is
|
|
declared as <tt/register/ and the size and compiler settings
|
|
do allow the compiler to actually place the struct into the
|
|
register bank in the zero page.
|
|
</itemize>
|
|
|
|
Please note that - as defined in the ISO C standard - the <tt/sizeof/
|
|
operator returns the struct size with the flexible array member having
|
|
size zero, even if it is initialized.
|
|
<p>
|
|
|
|
</itemize>
|
|
<p>
|
|
|
|
|
|
<sect>Predefined macros<p>
|
|
|
|
The compiler defines several macros at startup:
|
|
|
|
<descrip>
|
|
|
|
<tag><tt>__CC65__</tt></tag>
|
|
|
|
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.
|
|
|
|
<tag><tt>__APPLE2__</tt></tag>
|
|
|
|
This macro is defined if the target is the Apple ][ (-t apple2).
|
|
|
|
<tag><tt>__ATARI__</tt></tag>
|
|
|
|
This macro is defined if the target is one of the Atari computers
|
|
(400/800/130XL/800XL).
|
|
|
|
<tag><tt>__ATMOS__</tt></tag>
|
|
|
|
This macro is defined if the target is the Oric Atmos (-t atmos).
|
|
|
|
<tag><tt>__CBM__</tt></tag>
|
|
|
|
This macro is defined if the target system is one of the CBM targets.
|
|
|
|
<tag><tt>__C16__</tt></tag>
|
|
|
|
This macro is defined if the target is the c16 (-t c16).
|
|
|
|
<tag><tt>__C64__</tt></tag>
|
|
|
|
This macro is defined if the target is the c64 (-t c64).
|
|
|
|
<tag><tt>__C128__</tt></tag>
|
|
|
|
This macro is defined if the target is the c128 (-t c128).
|
|
|
|
<tag><tt>__CBM510__</tt></tag>
|
|
|
|
This macro is defined if the target is the CBM 500 series of computers.
|
|
|
|
<tag><tt>__CBM610__</tt></tag>
|
|
|
|
This macro is defined if the target is one of the CBM 600/700 family of
|
|
computers (called B series in the US).
|
|
|
|
<tag><tt>__GEOS__</tt></tag>
|
|
|
|
This macro is defined if you are compiling for the GEOS system (-t geos).
|
|
|
|
<tag><tt>__PET__</tt></tag>
|
|
|
|
This macro is defined if the target is the PET family of computers (-t pet).
|
|
|
|
<tag><tt>__PLUS4__</tt></tag>
|
|
|
|
This macro is defined if the target is the plus/4 (-t plus4).
|
|
|
|
<tag><tt>__VIC20__</tt></tag>
|
|
|
|
This macro is defined if the target is the vic20 (-t vic20).
|
|
|
|
<tag><tt>__FILE__</tt></tag>
|
|
|
|
This macro expands to a string containing the name of the C source file.
|
|
|
|
<tag><tt>__LINE__</tt></tag>
|
|
|
|
This macro expands to the current line number.
|
|
|
|
<tag><tt>__STRICT_ANSI__</tt></tag>
|
|
|
|
This macro is defined to 1 if the <tt/-A/ compiler option was given, and
|
|
undefined otherwise.
|
|
|
|
<tag><tt>__OPT__</tt></tag>
|
|
|
|
Is defined if the compiler was called with the <tt/-O/ command line option.
|
|
|
|
<tag><tt>__OPT_i__</tt></tag>
|
|
|
|
Is defined if the compiler was called with the <tt/-Oi/ command line option.
|
|
|
|
<tag><tt>__OPT_r__</tt></tag>
|
|
|
|
Is defined if the compiler was called with the <tt/-Or/ command line option.
|
|
|
|
<tag><tt>__OPT_s__</tt></tag>
|
|
|
|
Is defined if the compiler was called with the <tt/-Os/ command line option.
|
|
|
|
</descrip>
|
|
|
|
|
|
<sect>#pragmas<label id="pragmas"><p>
|
|
|
|
The compiler understands some pragmas that may be used to change code
|
|
generation and other stuff. Some of these pragmas understand a special form:
|
|
If the first parameter is <tt/push/, the old value is saved onto a stack
|
|
before changing it. The value may later be restored by using the <tt/pop/
|
|
parameter with the <tt/#pragma/.
|
|
|
|
<sect1><tt>#pragma bssseg (<name>)</tt><p>
|
|
|
|
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.
|
|
|
|
The <tt/#pragma/ understands the push and pop parameters as explained above.
|
|
|
|
Example:
|
|
<tscreen><verb>
|
|
#pragma bssseg ("MyBSS")
|
|
</verb></tscreen>
|
|
|
|
|
|
<sect1><tt>#pragma charmap (<index>, <code>)</tt><p>
|
|
|
|
Each literal string and each literal character in the source is translated
|
|
by use of a translation table. This translation table is preset when the
|
|
compiler is started depending on the target system, for example to map
|
|
ISO-8859-1 characters into PETSCII if the target is a commodore machine.
|
|
|
|
This pragma allows to change entries in the translation table, so the
|
|
translation for individual characters, or even the complete table may be
|
|
adjusted.
|
|
|
|
Both arguments are assumed to be unsigned characters with a valid range of
|
|
1-255.
|
|
|
|
Beware of two pitfalls:
|
|
|
|
<itemize>
|
|
<item>The character index is actually the code of the character in the
|
|
C source, so character mappings do always depend on the source
|
|
character set. This means that <tt/#pragma charmap/ is not portable
|
|
- it depends on the build environment.
|
|
<item>While it is possible to use character literals as indices, the
|
|
result may be somewhat unexpected, since character literals are
|
|
itself translated. For this reason I would suggest to avoid
|
|
character literals and use numeric character codes instead.
|
|
</itemize>
|
|
|
|
Example:
|
|
<tscreen><verb>
|
|
/* Use a space wherever an 'a' occurs in ISO-8859-1 source */
|
|
#pragma charmap (0x61, 0x20);
|
|
</verb></tscreen>
|
|
|
|
|
|
<sect1><tt>#pragma checkstack (on|off)</tt><label id="pragma-checkstack"><p>
|
|
|
|
Tells the compiler to insert calls to a stack checking subroutine to detect
|
|
stack overflows. The stack checking code will lead to somewhat larger and
|
|
slower programs, so you may want to use this pragma when debugging your
|
|
program and switch it off for the release version. If a stack overflow is
|
|
detected, the program is aborted.
|
|
|
|
If the argument is "off", stack checks are disabled (the default), otherwise
|
|
they're enabled.
|
|
|
|
The <tt/#pragma/ understands the push and pop parameters as explained above.
|
|
|
|
<sect1><tt>#pragma codeseg (<name>)</tt><p>
|
|
|
|
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.
|
|
|
|
The <tt/#pragma/ understands the push and pop parameters as explained above.
|
|
|
|
Example:
|
|
<tscreen><verb>
|
|
#pragma codeseg ("MyCODE")
|
|
</verb></tscreen>
|
|
|
|
|
|
<sect1><tt>#pragma dataseg (<name>)</tt><p>
|
|
|
|
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.
|
|
|
|
The <tt/#pragma/ understands the push and pop parameters as explained above.
|
|
|
|
Example:
|
|
<tscreen><verb>
|
|
#pragma dataseg ("MyDATA")
|
|
</verb></tscreen>
|
|
|
|
|
|
<sect1><tt>#pragma rodataseg (<name>)</tt><p>
|
|
|
|
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.
|
|
|
|
The <tt/#pragma/ understands the push and pop parameters as explained above.
|
|
|
|
Example:
|
|
<tscreen><verb>
|
|
#pragma rodataseg ("MyRODATA")
|
|
</verb></tscreen>
|
|
|
|
|
|
<sect1><tt>#pragma regvaraddr ([push,]on|off)</tt><p>
|
|
|
|
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 with "on" as argument.
|
|
Using "off" as an argument switches 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.
|
|
|
|
The <tt/#pragma/ understands the push and pop parameters as explained above.
|
|
|
|
Example:
|
|
<tscreen><verb>
|
|
#pragma regvaraddr(on) /* Allow taking the address
|
|
* of register variables
|
|
*/
|
|
</verb></tscreen>
|
|
|
|
|
|
<sect1><tt>#pragma regvars ([push,]on|off)</tt><label id="pragma-regvars"><p>
|
|
|
|
Enables or disables use of register variables. If register variables are
|
|
disabled (the default), the <tt/register/ keyword is ignored. Register
|
|
variables are explained in more detail in <ref id="regvars" name="a separate
|
|
chapter">.
|
|
|
|
The <tt/#pragma/ understands the push and pop parameters as explained above.
|
|
|
|
|
|
<sect1><tt>#pragma signedchars (on|off)</tt><label id="pragma-signedchars"><p>
|
|
|
|
Changes the signedness of the default character type. If the argument is
|
|
"on", default characters are signed, otherwise characters are unsigned.
|
|
The compiler default is to make characters unsigned since this creates a
|
|
lot better code. This default may be overridden by the <tt/--signed-chars/
|
|
command line option.
|
|
|
|
The <tt/#pragma/ understands the push and pop parameters as explained above.
|
|
|
|
|
|
<sect1><tt>#pragma staticlocals (on|off)</tt><label id="pragma-staticlocals"<p>
|
|
|
|
Use variables in the bss segment instead of variables on the stack. This
|
|
pragma changes the default set by the compiler option <tt/-Cl/. If the
|
|
argument is "on", local variables are allocated in the BSS segment,
|
|
leading to shorter and in most cases faster, but non-reentrant code.
|
|
|
|
The <tt/#pragma/ understands the push and pop parameters as explained above.
|
|
|
|
|
|
<sect1><tt>#pragma zpsym (<name>)</tt><p>
|
|
|
|
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:
|
|
<tscreen><verb>
|
|
extern int foo;
|
|
#pragma zpsym ("foo"); /* foo is in the zeropage */
|
|
</verb></tscreen>
|
|
|
|
|
|
|
|
|
|
<sect>Register variables<label id="regvars"><p>
|
|
|
|
The runtime for all supported platforms has 6 bytes of zero page space
|
|
available for register variables (this could be increased, but I think it's a
|
|
good value). So you can declare register variables up to a total size of 6 per
|
|
function. The compiler will allocate register space on a "first come, first
|
|
served" base and convert any <tt/register/ declarations that exceed the
|
|
available register space silently to <tt/auto/. Parameters can also be
|
|
declared as <tt/register/, this will in fact give slightly shorter code than
|
|
using a register variable.
|
|
|
|
Since a function must save the current values of the registers on entry and
|
|
restore them on exit, there is an overhead associated with register variables,
|
|
and this overhead is quite high (about 20 bytes per variable). This means that
|
|
just declaring anything as <tt/register/ is not a good idea.
|
|
|
|
The best use for register variables are pointers, especially those that point
|
|
to structures. The magic number here is about 3 uses of a struct field: If the
|
|
function contains this number or even more, the generated code will be usually
|
|
shorter and faster when using a register variable for the struct pointer. The
|
|
reason for this is that the register variable can in many cases be used as a
|
|
pointer directly. Having a pointer in an auto variable means that this pointer
|
|
must first be copied into a zero page location, before it can be dereferenced.
|
|
|
|
Second best use for register variables are counters. However, there is not
|
|
much difference in the code generated for counters, so you will need at least
|
|
100 operations on this variable (for example in a loop) to make it worth the
|
|
trouble. The only savings you get here are by the use of a zero page variable
|
|
instead of one on the stack or in the data segment.
|
|
|
|
Register variables must be explicitly enabled by using <tt/-Or/ or <tt/-r/ on
|
|
the command line. Register variables are only accepted on function top level,
|
|
register variables declared in interior blocks are silently converted to
|
|
<tt/auto/. With register variables disabled, all variables declared as
|
|
<tt/register/ are actually auto variables.
|
|
|
|
Please take care when using register variables: While they are helpful and can
|
|
lead to a tremendous speedup when used correctly, improper usage will cause
|
|
bloated code and a slowdown.
|
|
|
|
|
|
|
|
<sect>Inline assembler<label id="inline-asm"><p>
|
|
|
|
The compiler allows to insert assembler statements into the output file. The
|
|
syntax is
|
|
|
|
<tscreen><verb>
|
|
asm (<string literal>[, optional parameters]) ;
|
|
</verb></tscreen>
|
|
or
|
|
<tscreen><verb>
|
|
__asm__ (<string literal>[, optional parameters]) ;
|
|
</verb></tscreen>
|
|
<p>
|
|
|
|
The first form is in the user namespace and is disabled by <tt><ref
|
|
id="option-A" name="-A"></tt>.
|
|
|
|
The asm statement may be used inside a function and on global file level. An
|
|
inline assembler statement is a primary expression, so it may also be used as
|
|
part of an expression. Please note however that the result of an expression
|
|
containing just an inline assembler statement is always of type <tt/void/.
|
|
|
|
The contents of the string literal are preparsed by the compiler and inserted
|
|
into the generated assembly output, so that the can be further processed by
|
|
the backend and especially the optimizer. For this reason, the compiler does
|
|
only allow regular 6502 opcodes to be used with the inline assembler. Pseudo
|
|
instructions (like <tt/.import/, <tt/.byte/ and so on) are <em/not/ allowed,
|
|
even if the ca65 assembler (which is used to translate the generated assembler
|
|
code) would accept them. The builtin inline assembler is not a replacement for
|
|
the full blown macro assembler which comes with the compiler.
|
|
|
|
Note: Inline assembler statements are subject to all optimizations done by the
|
|
compiler. There is currently no way to protect an inline assembler statement
|
|
from being moved or removed completely by the optimizer. If in doubt, check
|
|
the generated assembler output, or disable optimizations.
|
|
|
|
The string literal may contain format specifiers from the following list. For
|
|
each format specifier, an argument is expected which is inserted instead of
|
|
the format specifier before passing the assembly code line to the backend.
|
|
|
|
<itemize>
|
|
<item><tt/%b/ - Numerical 8 bit value
|
|
<item><tt/%w/ - Numerical 16 bit value
|
|
<item><tt/%l/ - Numerical 32 bit value
|
|
<item><tt/%v/ - Assembler name of a (global) variable or function
|
|
<item><tt/%o/ - Stack offset of a (local) variable
|
|
<item><tt/%s/ - The argument is converted to a string
|
|
<item><tt/%%/ - The % sign itself
|
|
</itemize><p>
|
|
|
|
Using these format specifiers, you can access C <tt/#defines/, variables or
|
|
similar stuff from the inline assembler. For example, to load the value of
|
|
a C <tt/#define/ into the Y register, one would use
|
|
|
|
<tscreen><verb>
|
|
#define OFFS 23
|
|
__asm__ ("ldy #%b", OFFS);
|
|
</verb></tscreen>
|
|
|
|
Or, to access a struct member of a static variable:
|
|
|
|
<tscreen><verb>
|
|
typedef struct {
|
|
unsigned char x;
|
|
unsigned char y;
|
|
unsigned char color;
|
|
} pixel_t;
|
|
static pixel_t pixel;
|
|
__asm__ ("ldy #%b", offsetof(pixel_t, color));
|
|
__asm__ ("lda %v,y", pixel);
|
|
</verb></tscreen>
|
|
<p>
|
|
|
|
Note: Do not embedd the assembler labels that are used as names of global
|
|
variables or functions into your asm statements. Code like this
|
|
|
|
<tscreen><verb>
|
|
int foo;
|
|
int bar () { return 1; }
|
|
__asm__ ("lda _foo"); /* DON'T DO THAT! */
|
|
...
|
|
__asm__ ("jsr _bar"); /* DON'T DO THAT EITHER! */
|
|
</verb></tscreen>
|
|
<p>
|
|
|
|
may stop working if the way, the compiler generates these names is changed in
|
|
a future version. Instead use the format specifiers from the table above.
|
|
<p>
|
|
|
|
|
|
<sect>Bugs/Feedback<p>
|
|
|
|
If you have problems using the compiler, if you find any bugs, or if you're
|
|
doing something interesting with it, I would be glad to hear from you. Feel
|
|
free to contact me by email (<htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">).
|
|
|
|
|
|
|
|
<sect>Copyright<p>
|
|
|
|
This is the original compiler copyright:
|
|
|
|
<tscreen><verb>
|
|
--------------------------------------------------------------------------
|
|
-*- 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.
|
|
|
|
--------------------------------------------------------------------------
|
|
</verb></tscreen>
|
|
|
|
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.
|
|
|
|
|
|
</article>
|
|
|