diff options
Diffstat (limited to 'm68k-unknown-amigaos/recipes/files/gcc/gcc/doc/gcc-amigaos.texi')
| -rw-r--r-- | m68k-unknown-amigaos/recipes/files/gcc/gcc/doc/gcc-amigaos.texi | 1116 |
1 files changed, 1116 insertions, 0 deletions
diff --git a/m68k-unknown-amigaos/recipes/files/gcc/gcc/doc/gcc-amigaos.texi b/m68k-unknown-amigaos/recipes/files/gcc/gcc/doc/gcc-amigaos.texi new file mode 100644 index 0000000..481c676 --- /dev/null +++ b/m68k-unknown-amigaos/recipes/files/gcc/gcc/doc/gcc-amigaos.texi @@ -0,0 +1,1116 @@ +\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 |