path: root/m68k-unknown-amigaos/recipes/files/gcc/gcc/doc/gcc-amigaos.texi

\input texinfo.tex  @c -*-texinfo-*-
@c %**start of header
@setfilename gcc-amigaos.info
@settitle AmigaOS-only features of GCC
@set lastupdate Nov 5th, 2003
@c %**end of header

@ifinfo
This document describes implementation specific features of the GCC
compiler collection port for the AmigaOS.

@copying
Copyright @copyright{} 1996, 1997 Kamil Iskra

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
@end copying
@end ifinfo

@titlepage
@sp 10
@center @titlefont{GCC Amiga}
@subtitle Description of the AmigaOS-only features of GCC
@subtitle @value{lastupdate}
@author Kamil Iskra
@page
@end titlepage

@ifinfo
@node Top, Introduction, (dir), (dir)
This document describes the AmigaOS-only features of the @samp{GCC}
compiler collection.

Last updated @value{lastupdate}.
@end ifinfo

@menu
* Introduction::  Purpose of this document.

* Invocation::    Command line options.
* Attributes::    Variable and function attributes.
* Defines::       Preprocessor symbols.
* Miscellaneous:: Uncategorizable.

* Index::         Concept index.
@end menu

@node Introduction, Invocation, Top, Top
@chapter Introduction
@cindex Introduction
@cindex Purpose of this document

This document is supposed to be an addendum to the baseline @samp{GCC}
documentation.
Note that given email addresses and urls might be obsolete!

It focuses on the features that are visible by users and are important
to them. It is not supposed to document the internals of the AmigaOS
port of @samp{GCC}.

It describes features implemented in the @samp{Geek Gadgets GCC} port.
For more information about @samp{Geek Gadgets}, please refer to:

@format
http://www.geekgadgets.org/
ftp://ftp.geekgadgets.org/pub/geekgadgets/README
@end format

This document focuses on @samp{GCC}. It does not describe the
AmigaOS-only features of other @samp{GNU} packages, such as
@samp{binutils}, unless they are very closely connected to @samp{GCC}.

This means, that, unless stated otherwise, when we talk about the
``compiler'', we mean the @file{gcc}, @file{cpp} and @file{cc1}
executables, i.e., the executables that convert @samp{C} source code
to assembly source code. The assembler and linker are generally beyond
the scope of this document.

The primary source of information used to create this document was the
@samp{GCC} source code. Some parts of this document are based on:

@itemize @bullet
@item
The @samp{LibNIX} manual, written by Matthias Fleischer and Gunther
Nikl:

@format
fleischr@@izfm.uni-stuttgart.de
gnikl@@informatik.uni-rostock.de
@end format

@item
The @samp{A2IXLibrary} manual, written by Hans Verkuil:

@format
hans@@wyst.hobby.nl
@end format

@item
The @samp{README} file, maintained by Rask Ingemann Lambertsen:

@format
gc948374@@gbar.dtu.dk
http://www.gbar.dtu.dk/~c948374/GNU/
@end format

@item
The @samp{Geek Gadgets FAQ}, maintained by Lynn Winebarger:

@format
owinebar@@indiana.edu
http://nickel.ucs.indiana.edu/~owinebar/interests/amiga/amiga.html
@end format

@item
The @samp{FAQ for g++ and libg++}, written by Joe Buck:

@format
jbuck@@synopsys.com
http://www.cygnus.com/misc/g++FAQ_toc.html
@end format

@item
Discussions on the @samp{Geek Gadgets} mailing list:

@format
gg@@geekgadgets.org
@end format
@end itemize

This document was created by Kamil Iskra. Please email any questions,
suggestions etc. to <iskra@@student.uci.agh.edu.pl> or, even better,
to the <gg@@geekgadgets.org> mailing list.

The author would like to thank Kriton Kyrimis <kyrimis@@cti.gr> and
Lars Hecking <lhecking@@nmrc.ucc.ie> for correcting an awful lot of
language mistakes in this document.

@node Invocation, Attributes, Introduction, Top
@chapter Invocation
@cindex Invocation
@cindex Command line options

The AmigaOS port of @samp{GCC} supports the following non-standard
command line options:

@menu
* -noixemul::           Link with @samp{LibNIX}.

* -fbaserel::           Produce @samp{a4}-relative data.
* -resident::           Produce a @samp{pure} executable.
* -fbaserel32::         Produce @samp{a4}-relative data with no size limits.
* -resident32::         Produce a @samp{pure} executable with no size limits.
* -msmall-code::        Produce @samp{PC}-relative code.

* -mstackcheck::        Produce stack-checking code.
* -mstackextend::       Produce stack-extending code.
* -mfixedstack::        Produce plain code.

* -mrestore-a4::        Reload @samp{a4} in public functions.
* -malways-restore-a4:: Reload @samp{a4} in all functions.

* -mregparm::           Pass function arguments in registers.

* -frepo::              Enable @samp{C++} Template Repository.
@end menu

Accordingly, the AmigaOS port of @samp{GCC} supports several flavors
of linker libraries. @xref{Library flavors, Relation between library
flavors and compile-time options}.

@node -noixemul, -fbaserel, Invocation, Invocation
@section -noixemul
@cindex -noixemul
@cindex Link with LibNIX

@cindex IXEmul
By default, the executables created with @samp{GCC} require
@samp{ixemul.library} to run. This has its advantages (easy porting of
@samp{UN*X} programs, resource tracking, debugging, profiling, etc)
and disadvantages (@samp{UN*X}-style pathnames, large shared library,
etc).

@cindex LibNIX
If @samp{-noixemul} is specified on the @samp{GCC} command line, the
executable created will not require @samp{ixemul.library} --- it will
use the static linker library @samp{LibNIX} instead. This library is
very Amiga-like and @samp{SAS/C}-like, so it is convenient for the
AmigaOS-specific development.

@quotation
@emph{Note}: There is no great mystery about the @samp{-noixemul}
option. It has absolutely no effect on the code generated by the
compiler, only instructing the @samp{gcc} driver to pass different
options to the linker and preprocessor (@pxref{Options information},
@pxref{Library flavors}).

This option has no negative form.
@end quotation

For more information, please refer to the @samp{LibNIX} documentation.

@node -fbaserel, -resident, -noixemul, Invocation
@section -fbaserel
@cindex -fbaserel
@cindex Produce a4-relative data

By default, the code generated by @samp{GCC} references data using
32-bit, absolute addressing.

@cindex a4
@cindex 64 KB data limit
The @samp{-fbaserel} option will make @samp{GCC} generate code that
references data with 16 bit offsets relative to the @samp{a4} address
register. This makes executables smaller and faster. Unfortunately,
the size of the data section cannot exceed 64 KB, so this option
cannot be used for large programs, like @samp{GCC} itself.

@quotation
@emph{Note}: For a base-relative executable, @samp{-fbaserel} needs to
be specified for compiling @emph{and} linking. Base-relative programs
require special startup code and special versions of linker libraries.
Since not all linker libraries are available in both plain and base
relative versions, the usefulness of this option is limited. It is
important to note that when the base-relative library is missing, the
linker will attempt to use the plain one. This might result in strange
link-time or even run-time errors.

@cindex -fpic
This option is the AmigaOS equivalent of the standard @samp{GCC}
option @samp{-fpic}, which is not supported by the AmigaOS port.
@samp{-fpic} generates code that references data indirectly, through a
@dfn{global offset table}. The special addressing modes available on
the @samp{m68k} processor family allow for a much more efficient
implementation with @samp{-fbaserel}.

The negative form of @samp{-fbaserel} is @samp{-fno-baserel}, and is
on by default.
@end quotation

For more information, please refer to the @samp{LibNIX} documentation.

@node -resident, -fbaserel32, -fbaserel, Invocation
@section -resident
@cindex -resident
@cindex Produce a pure executable

Executables produced with the @samp{-resident} option are @dfn{pure},
so they can be made @dfn{resident} using the AmigaShell
@samp{resident} command. @samp{resident} executables are loaded to
memory just once, and several concurrent instances share the code
section.

@quotation
@emph{Note}: The compiler generates the same code for @samp{-resident}
as for @samp{-fbaserel} (@pxref{-fbaserel}). Only the linking stage is
different (special startup code is linked).

This option has no negative form.
@end quotation

For more information, please refer to the @samp{LibNIX} documentation.

@node -fbaserel32, -resident32, -resident, Invocation
@section -fbaserel32
@cindex -fbaserel32
@cindex Produce a4-relative data with no size limits

The difference between the @samp{-fbaserel32} and @samp{-fbaserel}
options (@pxref{-fbaserel}) is the same as between the standard
@samp{GCC} options @samp{-fPIC} and @samp{-fpic}.

Code generated with @samp{-fbaserel32} references data with 32 bit
offsets relative to the @samp{a4} address register. In contrast to the
@samp{-fbaserel} (@pxref{-fbaserel}) option, there is no 64 KB size
limit. Unfortunately, the addressing modes with 32 bit offsets are
only available on 68020 and higher processors. Therefore, it is
necessary to specify @samp{-m68020} or higher to use this option.

@quotation
@emph{Note}: This option used to be called @samp{-flarge-baserel}
before @samp{Geek Gadgets} snapshot @samp{970109}. Since it was not
functional then, this should not cause any compatibility problems.

The negative form of @samp{-fbaserel32} is @samp{-fno-baserel32}, and
is on by default.
@end quotation

@node -resident32, -msmall-code, -fbaserel32, Invocation
@section -resident32
@cindex -resident32
@cindex Produce a pure executable with no size limits

This option is an improved version of @samp{-resident}
(@pxref{-resident}) --- it does not impose any limits on data section
size. Unfortunately, just like @samp{-fbaserel32}
(@pxref{-fbaserel32}), it is only available for 68020 or higher
processors. Therefore, it is necessary to specify @samp{-m68020} or
higher to use this option.

@quotation
@emph{Note}: This option was first made available in the @samp{GCC}
2.7.2.1, @samp{Geek Gadgets} snapshot @samp{970109}.

This option has no negative form.
@end quotation

@node -msmall-code, -mstackcheck, -resident32, Invocation
@section -msmall-code
@cindex -msmall-code
@cindex Produce PC-relative code

By default, the code generated by the compiler references functions
using 32-bit, absolute addressing.

@cindex 32 KB code limit
Code generated by @samp{GCC} with the @samp{-msmall-code} option
references symbols in the code section with 16 bit offsets, relative
to the @samp{PC} (@dfn{program counter}). This makes executables
smaller and faster. Unfortunately, the size of the code section is
generally limited to 32 KB, so this option can only be used for
relatively small programs.

@quotation
@emph{Note}: Actually, the compiler always generates 32-bit code
references. If the assembler can calculate the offset between the
referencing instruction and the referenced symbol (in other words, if
the referenced symbol is in the same source file), it replaces the
32-bit reference with the @samp{PC}-relative one. External references
are left intact, unless @samp{-msmall-code} is used, in which case the
assembler generates @samp{PC}-relative references, and the exact
offsets are calculated by the linker.

This option has no negative form.
@end quotation

For more information, please refer to the @samp{LibNIX} documentation.

@node -mstackcheck, -mstackextend, -msmall-code, Invocation
@section -mstackcheck
@cindex -mstackcheck
@cindex Produce stack-checking code

By default, the code generated by @samp{GCC} does not check if there
is enough stack available before performing stack-consuming
operations. This is generally not necessary on @samp{UN*X} systems,
where the stack is extended automagically whenever needed.

Unfortunately, the AmigaOS provides tasks with a static, fixed size
stack.

However, if a program is compiled with @samp{-mstackcheck}, it will
check if there is enough stack available before performing any
stack-hungry operations. If there is a danger of stack overflow, the
program will abort and the user will be notified.

Needless to say, stack checking increases the executable size and the
execution time.

@quotation
@emph{Note}: Stack checking cannot be used for functions that might be
called from outside your task. This includes interrupt handlers,
shared library functions, hooks etc. In such cases, you should either
avoid using @samp{-mstackcheck} for files containing such functions,
or use @code{__attribute__((interrupt))} (@pxref{interrupt}).

It is safe to call a function that performs stack checking from one
that does not, and vice versa.

The negative form of @samp{-mstackcheck} is @samp{-mno-stackcheck},
and is on by default.

@emph{Warning}: @samp{-mno-stackcheck} used to be called
@samp{-mnostackcheck} before @samp{Geek Gadgets} snapshot
@samp{961012}.
@end quotation

For more information, please refer to the @samp{LibNIX} documentation.

@node -mstackextend, -mfixedstack, -mstackcheck, Invocation
@section -mstackextend
@cindex -mstackextend
@cindex Produce stack-extending code

@samp{-mstackextend} is very similar to @samp{-mstackcheck}
(@pxref{-mstackcheck}).

The main difference is that when a program runs out of stack, it is
not aborted, but a new stack area is allocated and the program
continues to run.

@quotation
@emph{Note}: Stack extension can slow down programs significantly. It
is advised that programs are written in such a way that they do not
require too much stack. This can generally be achieved by explicitly
allocating memory for large structures and arrays using functions like
@samp{malloc()} or @samp{AllocMem()}, instead of creating them as
local variables. Another method is replacing recursion with iteration.
In addition, it might be considered to use stack extension only for
selected, ``dangerous'' functions (@pxref{stackext}), not for all
functions in a given program.

The negative form of @samp{-mstackextend} is @samp{-mno-stackextend},
and is on by default.

@emph{Warning}: @samp{-mno-stackextend} used to be called
@samp{-mnostackextend} before @samp{Geek Gadgets} snapshot
@samp{961012}.
@end quotation

For more information, please refer to the @samp{LibNIX} documentation.

@node -mfixedstack, -mrestore-a4, -mstackextend, Invocation
@section -mfixedstack
@cindex -mfixedstack
@cindex Produce plain code

This option makes @samp{GCC} generate plain code, that does neither
stack checking nor extension. Since this is the default, there is
generally no need to use this option.

@quotation
@emph{Note}: This option has no negative form.
@end quotation

@node -mrestore-a4, -malways-restore-a4, -mfixedstack, Invocation
@section -mrestore-a4
@cindex -mrestore-a4
@cindex Reload a4 in public functions

This option is used to create the @samp{IXEmul} shared libraries
(those @file{*.ixlibrary} files).

It sets @samp{a4} to the appropriate value in the prologues of all
public functions (i.e., functions with external linkage). This is
necessary if these functions are called from the code of application.

@quotation
@emph{Note}: This option should not be used except for the creation of
an @samp{IXEmul} shared library.

This option was first made available in the @samp{GCC} 2.7.2,
@samp{Geek Gadgets} snapshot @samp{960902}. It used to be called
@samp{-frestore-a4}, and was relabeled to its current name in the
@samp{GCC} 2.7.2.1, @samp{Geek Gadgets} snapshot @samp{961012}.

The negative form of @samp{-mrestore-a4} is @samp{-mno-restore-a4},
and is on by default.
@end quotation

For more information, please refer to the @samp{A2IXLibrary}
documentation.

@node -malways-restore-a4, -mregparm, -mrestore-a4, Invocation
@section -malways-restore-a4
@cindex -malways-restore-a4
@cindex Reload a4 in all functions

This option is very similar to @samp{-mrestore-a4}
(@pxref{-mrestore-a4}).

The only difference is that it sets @samp{a4} in all functions,
including private ones (i.e., functions with internal linkage,
@samp{static}). This is safer than @samp{-mrestore-a4}
(@pxref{-mrestore-a4}), but is also slower.

@quotation
@emph{Note}: This option should not be used except for the creation of
an @samp{IXEmul} shared library.

This option was first made available in the @samp{GCC} 2.7.2,
@samp{Geek Gadgets} snapshot @samp{960902}. It used to be called
@samp{-falways-restore-a4}, and was relabeled to its current name in
the @samp{GCC} 2.7.2.1, @samp{Geek Gadgets} snapshot @samp{961012}.

The negative form of @samp{-malways-restore-a4} is
@samp{-mno-always-restore-a4}, and is on by default.
@end quotation

For more information, please refer to the @samp{A2IXLibrary}
documentation.

@node -mregparm, -frepo, -malways-restore-a4, Invocation
@section -mregparm
@cindex -mregparm
@cindex Pass function arguments in registers

On the @samp{m68k} architecture, @samp{GCC} passes function arguments
on the stack by default.

@samp{-mregparm} allows for passing arguments in registers. This can
be slightly faster than the standard method of passing arguments on
the stack.

The full syntax of this option is:

@format
-mregparm[=<value>]
@end format

@samp{value} should be an integer ranging from 1 to 4. If no
@samp{value} is provided, 2 will be used.

Four types of function arguments are recognized:

@table @samp
@item Integer
Integer numbers (this includes enumerations, small structures and
@samp{bool} in @samp{C++}, but excludes @samp{long long}, which is too
large). They are passed in data registers, starting from @samp{d0}.

@item Pointer
Pointers to objects or functions (this includes @samp{C++} references
and the implicit @samp{this} argument). They are passed in address
registers, starting from @samp{a0}.

@item Float
Floating point numbers. If the floating point code generation is
enabled, they are passed in floating point registers, starting from
@samp{fp0}. Otherwise, they are handled like the next type.

@item Other
All the other types of arguments, like large structures, pointers to
class methods in @samp{C++}, etc. They are always passed on the stack.
@end table

The value given for @samp{-mregparm} indicates how many arguments of
each of the above first three types should be passed in registers.

Example: @samp{GCC} is invoked with @samp{-mregparm} (without any
value, so 2 will be used) to compile a source containing the function:

@example
void fun(int a, char *str, char b, int c);
@end example

@samp{a} and @samp{b} will be passed in @samp{d0} and @samp{d1},
respectively, @samp{str} will be passed in @samp{a0}, and @samp{c}
will be passed on the stack.

@quotation
@emph{Note}: To use this option properly, it is very important that
all sources are fully prototyped. There may be very serious problems
if they are not, since @samp{GCC} will have to ``guess'' where to put
arguments, potentially making a wrong decission. Example:

@example
[in file1.c]
void f(void)
@{
   g(0); /* Call to a function with no prototype.  The argument
            will be put in d0, since it is an integer.  */
@}

[in file2.c]
void g(char *a) /* The argument is expected in a0, since it is
                   a pointer.  */
@{
@}
@end example

@samp{-Wimplicit -Wstrict-prototypes} should be used to ensure that
there are no prototypes missing.

In case of @samp{stdargs} functions, such as @samp{printf}, all
arguments are passed on the stack.

As of this writing, @samp{-mregparm} is supported by neither
@samp{IXEmul} nor @samp{LibNIX}, so its usefulness is very limited.

This option was first made available in the @samp{GCC} 2.7.2.1,
@samp{Geek Gadgets} snapshot @samp{961012}.

The negative form of @samp{-mregparm} is @samp{-mno-regparm}, and is
on by default.
@end quotation

@node -frepo, , -mregparm, Invocation
@section -frepo
@cindex -frepo
@cindex Enable C++ Template Repository

The AmigaOS port of @samp{GCC} includes @samp{C++} @dfn{Template
Repository} patch, so-called @samp{repo} patch.

In order to activate it, please compile @samp{C++} source files with
@samp{-frepo}. The compiler will not generate unnecessary
@samp{template} code, and will create @samp{.rpo} files that contain
information about @samp{template} symbols used in each source file.
Afterwards, during linking stage, a special tool called
@samp{collect2} will make sure that every required instantiation of
each @samp{template} is linked into the executable, recompiling some
source files if necessary.

@quotation
@emph{Note}: This option was first made available in the @samp{GCC}
2.7.2.1, @samp{Geek Gadgets} snapshot @samp{970109}.

This option is not specific to the AmigaOS port of
@samp{GCC}, nevertheless it is not fully supported in the baseline
sources.

This patch has been created in Cygnus Support, a company that is a
major contributor to the @samp{GNU} project. It has not been
integrated into the baseline sources due to design disagreements.

The negative form of @samp{-frepo} is @samp{-fno-repo}, and is on by
default.
@end quotation

For more information, please refer to the @samp{G++ FAQ}.

@node Attributes, Defines, Invocation, Top
@chapter Attributes
@cindex Attributes
@cindex Variable and function attributes

The following non-standard attributes are available in the AmigaOS
port of @samp{GCC}:

@menu
Variable attributes:
* chip::      Put object in @samp{chip} memory.

Function attributes:
* saveds::    Reload @samp{a4}.
* interrupt:: Do not mess with the stack.
* stackext::  Generate stack extension.
* regparm::   Pass arguments in registers.
* stkparm::   Pass arguments on the stack.
@end menu

@node chip, saveds, Attributes, Attributes
@section chip
@cindex chip
@cindex Put object in chip memory

Amiga hardware requires some data to be located in @samp{chip} memory.

Typically, if an initialized buffer is required (containing a picture
bitmap, for example), a plain, statically initialized buffer is used,
and the data is copied into a dynamically allocated @samp{MEMF_CHIP}
buffer.

This is not necessary with the @samp{chip} attribute. If this
attribute is specified for an initialized, static variable, it will be
allocated in @samp{chip} memory automagically by the AmigaOS.

A small example:

@example
UWORD __attribute__((chip)) bitmap1[] = @{ ... @};
@end example

@quotation
@emph{Note}: For compatibility with other AmigaOS @samp{C} compilers,
a preprocessor symbol @samp{__chip} is available, which expands to
@code{__attribute__((chip))} (@pxref{Keyword macros}).

All the @samp{chip} attribute does is specifying that data should go
to a section called @samp{.datachip}. Therefore, the standard
@samp{GCC} feature @code{__attribute__((section(".datachip")))} can be
used instead.

This attribute was first made available in the @samp{GCC} 2.7.2.1,
@samp{Geek Gadgets} snapshot @samp{970328}.

For proper operation, this attribute requires a special version of the
assembler, which generates standard AmigaOS object files. This version
is not yet available in @samp{Geek Gadgets} in binary form, since
support for this object files format is not yet complete.
@end quotation

@format
This attribute is not supported with @samp{GCC} 3.3 or newer!
@end format

@node saveds, interrupt, chip, Attributes
@section saveds
@cindex saveds
@cindex Reload a4

This attribute is ignored, unless base-relative data
(@pxref{-fbaserel}) is compiled.

To improve speed, programs compiled with the AmigaOS port of
@samp{GCC} set the @samp{a4} register to the appropriate value only
once, in the startup code. Code generated with the standard @samp{GCC}
option @samp{-fpic}, in contrast, sets the @samp{a4} register in every
function which references global data.

This is only safe as long as all function calls are performed from
within your own code. Things become ``tricky'' if callback functions,
like the AmigaOS hooks, interrupt handlers etc. are used. If global
data is referenced in such functions, @samp{a4} has to be set
properly.

This is exactly what the @samp{saveds} attribute does: it initializes
@samp{a4} in the function prologue, and restores it to its original
value in the function epilogue.

@quotation
@emph{Note}: For compatibility with other AmigaOS @samp{C} compilers,
a preprocessor symbol @samp{__saveds} is available, which expands to
@code{__attribute__((saveds))} (@pxref{Keyword macros}).

Please do not use this attribute in pure executables
(@pxref{-resident}, @pxref{-resident32}). This is because several
invocations of pure executables can run concurrently, each one having
its own data section, and there is no way to find out to which of
these sections should @samp{a4} be set.

The @samp{saveds} attribute is not necessary in function declarations
(prototypes).
@end quotation

This attribute was first made available in the @samp{GCC} 2.7.2.1,
@samp{Geek Gadgets} snapshot @samp{961012}.

@node interrupt, stackext, saveds, Attributes
@section interrupt
@cindex interrupt
@cindex Do not mess with the stack

This attribute should be used for any kind of callback functions that
can be called from outside your task. This includes interrupt
handlers, shared library functions, etc.

Most often, the @samp{interrupt} attribute is only necessary if a
program is compiled with stack checking or extension
(@pxref{-mstackcheck}, @pxref{-mstackextend}). It will prevent the
compiler from generating stack checking or extension code for the
function it was specified for.

Additionally, it will set @samp{CC} (@dfn{condition codes register})
in the function epilogue to return value, by performing @code{tstl
d0}.

@quotation
@emph{Note}: For compatibility with other AmigaOS @samp{C} compilers,
a preprocessor symbol @samp{__interrupt} is available, which expands
to @code{__attribute__((interrupt))} (@pxref{Keyword macros}).

The @samp{interrupt} attribute is mutually exclusive with the
@samp{stackext} attribute (@pxref{stackext}).

This attribute is not necessary in function declarations (prototypes).
@end quotation

This attribute was first made available in the @samp{GCC} 2.7.2.1,
@samp{Geek Gadgets} snapshot @samp{961012}.

@node stackext, regparm, interrupt, Attributes
@section stackext
@cindex stackext
@cindex Generate stack extension

This attribute makes @samp{GCC} generate stack extension code for the
function for which it was used (@pxref{-mstackextend}). This makes it
possible to use stack extension selectively, only for the
``dangerous'' functions --- recursive functions, functions with large
local variables, etc.

@quotation
@emph{Note}: For compatibility with other AmigaOS @samp{C} compilers,
a preprocessor symbol @samp{__stackext} is available, which expands to
@code{__attribute__((stackext))} (@pxref{Keyword macros}).

The @samp{stackext} attribute is mutually exclusive with the
@samp{interrupt} attribute (@pxref{interrupt}).

This attribute is not necessary in function declarations (prototypes).
@end quotation

This attribute was first made available in the @samp{GCC} 2.7.2.1,
@samp{Geek Gadgets} snapshot @samp{961012}.

@node regparm, stkparm, stackext, Attributes
@section regparm
@cindex regparm
@cindex Pass arguments in registers

The @samp{regparm} attribute, together with the @samp{stkparm}
attribute (@pxref{stkparm}), can be used to fine-tune the way
arguments are passed. It makes @samp{GCC} pass arguments in registers
for the function for which it was used, regardless of whether the
global @samp{-mregparm} option was used or not (@pxref{-mregparm}).

An optional integer argument ranging from 1 to 4 indicates how many
arguments of each type should be passed in registers
(@pxref{-mregparm}). The syntax is the following:

@example
void __attribute__((regparm(3))) fun(int a, char *str, char b, int c);
@end example

This will make @samp{GCC} pass @samp{a}, @samp{b} and @samp{c} in
@samp{d0}, @samp{d1} and @samp{d2}, respectively, and @samp{str} in
@samp{a0}.

If the argument is not provided, the value given for @samp{-mregparm}
will be used (or 2 if that option was not specified,
@pxref{-mregparm}).

@quotation
@emph{Note}: There is generally no need to use this attribute unless
files compiled with different calling conventions are linked together.

For compatibility with other AmigaOS @samp{C} compilers, a
preprocessor symbol @samp{__regargs} is available, which expands to
@code{__attribute__((regparm))} (@pxref{Keyword macros}).

The @samp{regparm} attribute is mutually exclusive with the
@samp{stkparm} attribute (@pxref{stkparm}).

This attribute is necessary both in function declarations (prototypes)
and definitions (function code).
@end quotation

This attribute was first made available in the @samp{GCC} 2.7.2.1,
@samp{Geek Gadgets} snapshot @samp{961012}.

@node stkparm, , regparm, Attributes
@section stkparm
@cindex stkparm
@cindex Pass arguments on the stack

The @samp{stkparm} attribute, together with the @samp{regparm}
attribute (@pxref{regparm}), can be used to fine-tune the way
arguments are passed. It makes @samp{GCC} pass arguments on stack for
the function for which it was used, regardless of whether the global
@samp{-mregparm} option was used or not (@pxref{-mregparm}).

@quotation
@emph{Note}: There is generally no need to use this attribute unless
files compiled with different calling conventions are linked together.

For compatibility with other AmigaOS @samp{C} compilers, a
preprocessor symbol @samp{__stdargs} is available, which expands to
@code{__attribute__((stkparm))} (@pxref{Keyword macros}).

The @samp{stkparm} attribute is mutually exclusive with the
@samp{regparm} attribute (@pxref{regparm}).

This attribute is necessary both in function declarations (prototypes)
and definitions (function code).
@end quotation

This attribute was first made available in the @samp{GCC} 2.7.2.1,
@samp{Geek Gadgets} snapshot @samp{961012}.

@node Defines, Miscellaneous, Attributes, Top
@chapter Defines
@cindex Defines
@cindex Preprocessor symbols

The AmigaOS-specific preprocessor symbols available in @samp{GCC} can
be divided into three groups:

@menu
* Identifying machine:: What machine is this?
* Options information:: Which options have been specified?
* Keyword macros::      Compatibility with other compilers.
@end menu

@node Identifying machine, Options information, Defines, Defines
@section Symbols identifying machine
@cindex Symbols identifying machine
@cindex What machine is this

The following machine-identifying preprocessor symbols are available:

@table @samp
@item mc68000
This macro identifies the machine as having a CPU from the Motorola
68000 family.

@item amiga
@item amigaos
@item amigados
These macros identify the machine as being an Amiga, running the
AmigaOS.

@item AMIGA
@item MCH_AMIGA
These macros are provided for compatibility with other AmigaOS
@samp{C} compilers.
@end table

@quotation
@emph{Note}: These symbols are available in three groups: plain (as
specified above), with two leading underscores, and with two leading
and two tailing underscores. The plain ones are not available when
compiling with the @samp{-ansi} option.

The @samp{amigados} symbol is obsolete and will be removed in future.
Please use @samp{amigaos}, which was first made available in the
@samp{GCC} 2.7.2.1, @samp{Geek Gadgets} snapshot @samp{961012}.
@end quotation

@node Options information, Keyword macros, Identifying machine, Defines
@section Symbols identifying specified options
@cindex Symbols identifying specified options
@cindex Symbols identifying CPU
@cindex Symbols identifying ixemul
@cindex Which CPU model options have been specified

@samp{GCC} has several options to choose the CPU model that the code
should be generated for. The following preprocessor symbols identify
which options have been specified on the command line:

@table @samp
@item mc68020
Either one of @samp{-m68020}, @samp{-mc68020} or @samp{-mc68020-40}
has been specified.

@item mc68030
@samp{-m68030} has been specified.

@item mc68040
@samp{-m68040} has been specified.

@item mc68060
@samp{-m68060} @emph{[EXPERIMENTAL]} has been specified.

@item __HAVE_68881__
@samp{-m68881} has been specified.
@end table

@quotation
@emph{Note}: The symbols beginning with @samp{mc} are available in
three groups: plain (as specified above), with two leading
underscores, and with two leading and two tailing underscores. The
plain ones are not available when compiling with the @samp{-ansi}
option. The ``underscored'' ones were first made available in the
@samp{GCC} 2.7.2.1, @samp{Geek Gadgets} snapshot @samp{970109}.

@samp{mc68000} is defined regardless of which @samp{-m680x0} options
have been used.
@end quotation

In addition to the above, a preprocessor symbol @samp{ixemul}
(together with the ``underscored'' versions) is available when not
compiling with @samp{-noixemul} (@pxref{-noixemul}) and identifies the
runtime environment as @samp{IXEmul}. This symbol was first made
available in the @samp{GCC} 2.7.2.1, @samp{Geek Gadgets} snapshot
@samp{970328}.

@node Keyword macros, , Options information, Defines
@section ``Keyword'' macros
@cindex Keyword macros
@cindex Compatibility with other compilers

Most AmigaOS-specific @samp{C} compilers have special ``custom
keywords'', which make the AmigaOS-specific development easier.
Unfortunately, the idea of ``custom keywords'' is not available in
@samp{GCC}. However, @samp{attributes} are available, and they provide
virtually identical functionality. For compatibility with other
AmigaOS @samp{C} compilers, preprocessor symbols are provided, which
expand to the appropriate @samp{attributes} (@pxref{Attributes}).

@table @samp
@item __chip
@xref{chip}.

@item __saveds
@xref{saveds}.

@item __interrupt
@xref{interrupt}.

@item __stackext
@xref{stackext}.

@item __regargs
@xref{regparm}.

@item __stdargs
@xref{stkparm}.

@item __aligned
This expands to the standard @samp{GCC}
@samp{__attribute__((aligned(4)))}.
@end table

@quotation
@emph{Note}: With @samp{SAS/C}, these keywords may be specified either
before or after the type, so the following declaration is correct:

@example
__saveds void func(void);
@end example

Unfortunately, the syntax rules of @samp{GCC} 2.7.2.1 do not allow to
specify the attributes before the type, so the above example must be
changed to:

@example
void __saveds func(void);
@end example

This will be fixed in @samp{GCC} 2.8.0.
@end quotation

@node Miscellaneous, Index, Defines, Top
@chapter Miscellaneous
@cindex Miscellaneous
@cindex Uncategorizable

The following ``hard to categorize'' features are available in the
AmigaOS port of @samp{GCC}:

@menu
* Explicit register specification:: Specify registers for arguments.
* Case sensitive CPP::              <String.h> is not the same as <string.h>
* Library flavors::                 Linker libraries.
@end menu

@node Explicit register specification, Case sensitive CPP, Miscellaneous, Miscellaneous
@section Explicit register specification
@cindex Explicit register specification
@cindex Specify registers for arguments

In certain situations, like writing callback hooks, ``patchers'',
standard shared libraries, etc., functions have to receive arguments
in particular registers.

@samp{-mregparm} (@pxref{-mregparm}) is not appropriate in this case,
since it does not give the programmer enough control on @emph{which}
registers will be used.

To overcome this problem in the AmigaOS port of @samp{GCC}, explicit
register specification has been extended to be available for function
arguments, as well:

@example
void myhook(struct Hook* hook __asm("a0"), APTR object __asm("a2"),
            APTR message __asm("a1"))
@{
	...
@}
@end example

@quotation
@emph{Note}: This feature is currently not available in @samp{G++}.

Only the @samp{ANSI}-style declarations (prototypes) are supported.

Registers have to be specified both in function declarations
(prototypes) and definitions (function code).
@end quotation

This feature was first made available in the @samp{GCC} 2.7.2.1,
@samp{Geek Gadgets} snapshot @samp{961012}.

@node Case sensitive CPP, Library flavors, Explicit register specification, Miscellaneous
@section Case sensitive CPP
@cindex Case sensitive CPP
@cindex <String.h> is not the same as <string.h>

The preprocessor available in the AmigaOS port of @samp{GCC} is case
sensitive. This means, that the header names provided in the
@code{#include} directives have to be correct, including upper and
lower case letters. This affects only the way the preprocessor works.
Currently available native AmigaOS file systems are case insensitive.

@quotation
@emph{Note}: This might seem like a horrible hack and a crazy attempt
to implement a ``ridiculous'' UNIX feature on Amiga. However, this
feature has been introduced to terminate the endless @samp{G++}
problems with a standard @samp{ANSI C} header @file{string.h}: under
the AmigaOS, a @samp{C++} header @file{String.h} would be included,
instead.
@end quotation

@node Library flavors, , Case sensitive CPP, Miscellaneous
@section Library flavors
@cindex Library flavors
@cindex Linker libraries

The AmigaOS port of @samp{GCC} may use different linker libraries
depending upon the options used while invoking the compiler. These
libraries reside in subdirectories of the standard locations, such as
@file{GG:lib/} or, with @samp{GCC} 2.7.2.1,
@file{GG:lib/gcc-lib/m68k-amigaos/2.7.2.1/}.

If you invoke @code{gcc} with @samp{-v}, you'll see the precise flavor
of libraries used as a @samp{-fl} option in the @code{ld} invocation.
Here is a list of the available flavors (and hence the subdirectories
names):

@itemize @bullet
@item 
@file{libb} corresponds to the @ref{-fbaserel} option.
@item
@file{libb32} corresponds to the @ref{-fbaserel32} option.
@item
@file{libm020} corresponds to the @samp{-m68020} (or higher) options.
@item
@file{libm881} corresponds to the @samp{-m68881} option.
@item
@file{libnix} corresponds to the @ref{-noixemul} option.
@end itemize

More than one flavor can be specified simultaneously. For example,
when both @ref{-fbaserel} and @samp{-m68020} are specified, the
libraries will be searched in @file{libb/libm020} subdirectory (as
well as in @file{libb} subdirectory and in the standard location).

@node Index, , Miscellaneous, Top
@chapter Index
@printindex cp

@contents
@bye