tm.texi revision 169689
1132718Skan@c Copyright (C) 1988,1989,1992,1993,1994,1995,1996,1997,1998,1999,2000,2001, 2169689Skan@c 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc. 390075Sobrien@c This is part of the GCC manual. 490075Sobrien@c For copying conditions, see the file gcc.texi. 590075Sobrien 690075Sobrien@node Target Macros 790075Sobrien@chapter Target Description Macros and Functions 890075Sobrien@cindex machine description macros 990075Sobrien@cindex target description macros 1090075Sobrien@cindex macros, target description 1190075Sobrien@cindex @file{tm.h} macros 1290075Sobrien 1390075SobrienIn addition to the file @file{@var{machine}.md}, a machine description 1490075Sobrienincludes a C header file conventionally given the name 1590075Sobrien@file{@var{machine}.h} and a C source file named @file{@var{machine}.c}. 1690075SobrienThe header file defines numerous macros that convey the information 1790075Sobrienabout the target machine that does not fit into the scheme of the 1890075Sobrien@file{.md} file. The file @file{tm.h} should be a link to 1990075Sobrien@file{@var{machine}.h}. The header file @file{config.h} includes 2090075Sobrien@file{tm.h} and most compiler source files include @file{config.h}. The 2190075Sobriensource file defines a variable @code{targetm}, which is a structure 2290075Sobriencontaining pointers to functions and data relating to the target 2390075Sobrienmachine. @file{@var{machine}.c} should also contain their definitions, 2490075Sobrienif they are not defined elsewhere in GCC, and other functions called 2590075Sobrienthrough the macros defined in the @file{.h} file. 2690075Sobrien 2790075Sobrien@menu 2890075Sobrien* Target Structure:: The @code{targetm} variable. 2990075Sobrien* Driver:: Controlling how the driver runs the compilation passes. 3090075Sobrien* Run-time Target:: Defining @samp{-m} options like @option{-m68000} and @option{-m68020}. 3190075Sobrien* Per-Function Data:: Defining data structures for per-function information. 3290075Sobrien* Storage Layout:: Defining sizes and alignments of data. 3390075Sobrien* Type Layout:: Defining sizes and properties of basic user data types. 3490075Sobrien* Registers:: Naming and describing the hardware registers. 3590075Sobrien* Register Classes:: Defining the classes of hardware registers. 36169689Skan* Old Constraints:: The old way to define machine-specific constraints. 3790075Sobrien* Stack and Calling:: Defining which way the stack grows and by how much. 3890075Sobrien* Varargs:: Defining the varargs macros. 3990075Sobrien* Trampolines:: Code set up at run time to enter a nested function. 4090075Sobrien* Library Calls:: Controlling how library routines are implicitly called. 4190075Sobrien* Addressing Modes:: Defining addressing modes valid for memory operands. 42169689Skan* Anchored Addresses:: Defining how @option{-fsection-anchors} should work. 4390075Sobrien* Condition Code:: Defining how insns update the condition code. 4490075Sobrien* Costs:: Defining relative costs of different operations. 4590075Sobrien* Scheduling:: Adjusting the behavior of the instruction scheduler. 4690075Sobrien* Sections:: Dividing storage into text, data, and other sections. 4790075Sobrien* PIC:: Macros for position independent code. 4890075Sobrien* Assembler Format:: Defining how to write insns and pseudo-ops to output. 4990075Sobrien* Debugging Info:: Defining the format of debugging output. 50117395Skan* Floating Point:: Handling floating point for cross-compilers. 5190075Sobrien* Mode Switching:: Insertion of mode-switching instructions. 5290075Sobrien* Target Attributes:: Defining target-specific uses of @code{__attribute__}. 53117395Skan* MIPS Coprocessors:: MIPS coprocessor support and how to customize it. 54132718Skan* PCH Target:: Validity checking for precompiled headers. 55169689Skan* C++ ABI:: Controlling C++ ABI changes. 5690075Sobrien* Misc:: Everything else. 5790075Sobrien@end menu 5890075Sobrien 5990075Sobrien@node Target Structure 6090075Sobrien@section The Global @code{targetm} Variable 6190075Sobrien@cindex target hooks 6290075Sobrien@cindex target functions 6390075Sobrien 6490075Sobrien@deftypevar {struct gcc_target} targetm 6590075SobrienThe target @file{.c} file must define the global @code{targetm} variable 6690075Sobrienwhich contains pointers to functions and data relating to the target 6790075Sobrienmachine. The variable is declared in @file{target.h}; 6890075Sobrien@file{target-def.h} defines the macro @code{TARGET_INITIALIZER} which is 6990075Sobrienused to initialize the variable, and macros for the default initializers 7090075Sobrienfor elements of the structure. The @file{.c} file should override those 7190075Sobrienmacros for which the default definition is inappropriate. For example: 7290075Sobrien@smallexample 7390075Sobrien#include "target.h" 7490075Sobrien#include "target-def.h" 7590075Sobrien 7690075Sobrien/* @r{Initialize the GCC target structure.} */ 7790075Sobrien 7890075Sobrien#undef TARGET_COMP_TYPE_ATTRIBUTES 7990075Sobrien#define TARGET_COMP_TYPE_ATTRIBUTES @var{machine}_comp_type_attributes 8090075Sobrien 8190075Sobrienstruct gcc_target targetm = TARGET_INITIALIZER; 8290075Sobrien@end smallexample 8390075Sobrien@end deftypevar 8490075Sobrien 8590075SobrienWhere a macro should be defined in the @file{.c} file in this manner to 8690075Sobrienform part of the @code{targetm} structure, it is documented below as a 8790075Sobrien``Target Hook'' with a prototype. Many macros will change in future 8890075Sobrienfrom being defined in the @file{.h} file to being part of the 8990075Sobrien@code{targetm} structure. 9090075Sobrien 9190075Sobrien@node Driver 9290075Sobrien@section Controlling the Compilation Driver, @file{gcc} 9390075Sobrien@cindex driver 9490075Sobrien@cindex controlling the compilation driver 9590075Sobrien 9690075Sobrien@c prevent bad page break with this line 9790075SobrienYou can control the compilation driver. 9890075Sobrien 99132718Skan@defmac SWITCH_TAKES_ARG (@var{char}) 10090075SobrienA C expression which determines whether the option @option{-@var{char}} 10190075Sobrientakes arguments. The value should be the number of arguments that 10290075Sobrienoption takes--zero, for many options. 10390075Sobrien 10490075SobrienBy default, this macro is defined as 10590075Sobrien@code{DEFAULT_SWITCH_TAKES_ARG}, which handles the standard options 10690075Sobrienproperly. You need not define @code{SWITCH_TAKES_ARG} unless you 10790075Sobrienwish to add additional options which take arguments. Any redefinition 10890075Sobrienshould call @code{DEFAULT_SWITCH_TAKES_ARG} and then check for 10990075Sobrienadditional options. 110132718Skan@end defmac 11190075Sobrien 112132718Skan@defmac WORD_SWITCH_TAKES_ARG (@var{name}) 11390075SobrienA C expression which determines whether the option @option{-@var{name}} 11490075Sobrientakes arguments. The value should be the number of arguments that 11590075Sobrienoption takes--zero, for many options. This macro rather than 11690075Sobrien@code{SWITCH_TAKES_ARG} is used for multi-character option names. 11790075Sobrien 11890075SobrienBy default, this macro is defined as 11990075Sobrien@code{DEFAULT_WORD_SWITCH_TAKES_ARG}, which handles the standard options 12090075Sobrienproperly. You need not define @code{WORD_SWITCH_TAKES_ARG} unless you 12190075Sobrienwish to add additional options which take arguments. Any redefinition 12290075Sobrienshould call @code{DEFAULT_WORD_SWITCH_TAKES_ARG} and then check for 12390075Sobrienadditional options. 124132718Skan@end defmac 12590075Sobrien 126132718Skan@defmac SWITCH_CURTAILS_COMPILATION (@var{char}) 12790075SobrienA C expression which determines whether the option @option{-@var{char}} 12890075Sobrienstops compilation before the generation of an executable. The value is 12990075Sobrienboolean, nonzero if the option does stop an executable from being 13090075Sobriengenerated, zero otherwise. 13190075Sobrien 13290075SobrienBy default, this macro is defined as 13390075Sobrien@code{DEFAULT_SWITCH_CURTAILS_COMPILATION}, which handles the standard 13490075Sobrienoptions properly. You need not define 13590075Sobrien@code{SWITCH_CURTAILS_COMPILATION} unless you wish to add additional 13690075Sobrienoptions which affect the generation of an executable. Any redefinition 13790075Sobrienshould call @code{DEFAULT_SWITCH_CURTAILS_COMPILATION} and then check 13890075Sobrienfor additional options. 139132718Skan@end defmac 14090075Sobrien 141132718Skan@defmac SWITCHES_NEED_SPACES 14290075SobrienA string-valued C expression which enumerates the options for which 14390075Sobrienthe linker needs a space between the option and its argument. 14490075Sobrien 14590075SobrienIf this macro is not defined, the default value is @code{""}. 146132718Skan@end defmac 14790075Sobrien 148132718Skan@defmac TARGET_OPTION_TRANSLATE_TABLE 14990075SobrienIf defined, a list of pairs of strings, the first of which is a 15090075Sobrienpotential command line target to the @file{gcc} driver program, and the 15190075Sobriensecond of which is a space-separated (tabs and other whitespace are not 15290075Sobriensupported) list of options with which to replace the first option. The 15390075Sobrientarget defining this list is responsible for assuring that the results 15490075Sobrienare valid. Replacement options may not be the @code{--opt} style, they 15590075Sobrienmust be the @code{-opt} style. It is the intention of this macro to 15690075Sobrienprovide a mechanism for substitution that affects the multilibs chosen, 15790075Sobriensuch as one option that enables many options, some of which select 158169689Skanmultilibs. Example nonsensical definition, where @option{-malt-abi}, 159169689Skan@option{-EB}, and @option{-mspoo} cause different multilibs to be chosen: 16090075Sobrien 161103445Skan@smallexample 16290075Sobrien#define TARGET_OPTION_TRANSLATE_TABLE \ 16390075Sobrien@{ "-fast", "-march=fast-foo -malt-abi -I/usr/fast-foo" @}, \ 16490075Sobrien@{ "-compat", "-EB -malign=4 -mspoo" @} 165103445Skan@end smallexample 166132718Skan@end defmac 16790075Sobrien 168132718Skan@defmac DRIVER_SELF_SPECS 169117395SkanA list of specs for the driver itself. It should be a suitable 170117395Skaninitializer for an array of strings, with no surrounding braces. 171117395Skan 172132718SkanThe driver applies these specs to its own command line between loading 173132718Skandefault @file{specs} files (but not command-line specified ones) and 174132718Skanchoosing the multilib directory or running any subcommands. It 175132718Skanapplies them in the order given, so each spec can depend on the 176132718Skanoptions added by earlier ones. It is also possible to remove options 177132718Skanusing @samp{%<@var{option}} in the usual way. 178117395Skan 179117395SkanThis macro can be useful when a port has several interdependent target 180117395Skanoptions. It provides a way of standardizing the command line so 181117395Skanthat the other specs are easier to write. 182117395Skan 183117395SkanDo not define this macro if it does not need to do anything. 184132718Skan@end defmac 185117395Skan 186132718Skan@defmac OPTION_DEFAULT_SPECS 187132718SkanA list of specs used to support configure-time default options (i.e.@: 188132718Skan@option{--with} options) in the driver. It should be a suitable initializer 189132718Skanfor an array of structures, each containing two strings, without the 190132718Skanoutermost pair of surrounding braces. 191132718Skan 192132718SkanThe first item in the pair is the name of the default. This must match 193132718Skanthe code in @file{config.gcc} for the target. The second item is a spec 194132718Skanto apply if a default with this name was specified. The string 195132718Skan@samp{%(VALUE)} in the spec will be replaced by the value of the default 196132718Skaneverywhere it occurs. 197132718Skan 198132718SkanThe driver will apply these specs to its own command line between loading 199132718Skandefault @file{specs} files and processing @code{DRIVER_SELF_SPECS}, using 200132718Skanthe same mechanism as @code{DRIVER_SELF_SPECS}. 201132718Skan 202132718SkanDo not define this macro if it does not need to do anything. 203132718Skan@end defmac 204132718Skan 205132718Skan@defmac CPP_SPEC 20690075SobrienA C string constant that tells the GCC driver program options to 20790075Sobrienpass to CPP@. It can also specify how to translate options you 20890075Sobriengive to GCC into options for GCC to pass to the CPP@. 20990075Sobrien 21090075SobrienDo not define this macro if it does not need to do anything. 211132718Skan@end defmac 21290075Sobrien 213132718Skan@defmac CPLUSPLUS_CPP_SPEC 21490075SobrienThis macro is just like @code{CPP_SPEC}, but is used for C++, rather 21590075Sobrienthan C@. If you do not define this macro, then the value of 21690075Sobrien@code{CPP_SPEC} (if any) will be used instead. 217132718Skan@end defmac 21890075Sobrien 219132718Skan@defmac CC1_SPEC 22090075SobrienA C string constant that tells the GCC driver program options to 22190075Sobrienpass to @code{cc1}, @code{cc1plus}, @code{f771}, and the other language 22290075Sobrienfront ends. 22390075SobrienIt can also specify how to translate options you give to GCC into options 22490075Sobrienfor GCC to pass to front ends. 22590075Sobrien 22690075SobrienDo not define this macro if it does not need to do anything. 227132718Skan@end defmac 22890075Sobrien 229132718Skan@defmac CC1PLUS_SPEC 23090075SobrienA C string constant that tells the GCC driver program options to 23190075Sobrienpass to @code{cc1plus}. It can also specify how to translate options you 23290075Sobriengive to GCC into options for GCC to pass to the @code{cc1plus}. 23390075Sobrien 23490075SobrienDo not define this macro if it does not need to do anything. 23590075SobrienNote that everything defined in CC1_SPEC is already passed to 23690075Sobrien@code{cc1plus} so there is no need to duplicate the contents of 23790075SobrienCC1_SPEC in CC1PLUS_SPEC@. 238132718Skan@end defmac 23990075Sobrien 240132718Skan@defmac ASM_SPEC 24190075SobrienA C string constant that tells the GCC driver program options to 24290075Sobrienpass to the assembler. It can also specify how to translate options 24390075Sobrienyou give to GCC into options for GCC to pass to the assembler. 24490075SobrienSee the file @file{sun3.h} for an example of this. 24590075Sobrien 24690075SobrienDo not define this macro if it does not need to do anything. 247132718Skan@end defmac 24890075Sobrien 249132718Skan@defmac ASM_FINAL_SPEC 25090075SobrienA C string constant that tells the GCC driver program how to 25190075Sobrienrun any programs which cleanup after the normal assembler. 25290075SobrienNormally, this is not needed. See the file @file{mips.h} for 25390075Sobrienan example of this. 25490075Sobrien 25590075SobrienDo not define this macro if it does not need to do anything. 256132718Skan@end defmac 25790075Sobrien 258132718Skan@defmac AS_NEEDS_DASH_FOR_PIPED_INPUT 259132718SkanDefine this macro, with no value, if the driver should give the assembler 260132718Skanan argument consisting of a single dash, @option{-}, to instruct it to 261132718Skanread from its standard input (which will be a pipe connected to the 262132718Skanoutput of the compiler proper). This argument is given after any 263132718Skan@option{-o} option specifying the name of the output file. 264132718Skan 265132718SkanIf you do not define this macro, the assembler is assumed to read its 266132718Skanstandard input if given no non-option arguments. If your assembler 267132718Skancannot read standard input at all, use a @samp{%@{pipe:%e@}} construct; 268132718Skansee @file{mips.h} for instance. 269132718Skan@end defmac 270132718Skan 271132718Skan@defmac LINK_SPEC 27290075SobrienA C string constant that tells the GCC driver program options to 27390075Sobrienpass to the linker. It can also specify how to translate options you 27490075Sobriengive to GCC into options for GCC to pass to the linker. 27590075Sobrien 27690075SobrienDo not define this macro if it does not need to do anything. 277132718Skan@end defmac 27890075Sobrien 279132718Skan@defmac LIB_SPEC 28090075SobrienAnother C string constant used much like @code{LINK_SPEC}. The difference 28190075Sobrienbetween the two is that @code{LIB_SPEC} is used at the end of the 28290075Sobriencommand given to the linker. 28390075Sobrien 28490075SobrienIf this macro is not defined, a default is provided that 28590075Sobrienloads the standard C library from the usual place. See @file{gcc.c}. 286132718Skan@end defmac 28790075Sobrien 288132718Skan@defmac LIBGCC_SPEC 28990075SobrienAnother C string constant that tells the GCC driver program 29090075Sobrienhow and when to place a reference to @file{libgcc.a} into the 29190075Sobrienlinker command line. This constant is placed both before and after 29290075Sobrienthe value of @code{LIB_SPEC}. 29390075Sobrien 29490075SobrienIf this macro is not defined, the GCC driver provides a default that 29590075Sobrienpasses the string @option{-lgcc} to the linker. 296169689Skan@end defmac 297146895Skan 298169689Skan@defmac REAL_LIBGCC_SPEC 299146895SkanBy default, if @code{ENABLE_SHARED_LIBGCC} is defined, the 300146895Skan@code{LIBGCC_SPEC} is not directly used by the driver program but is 301146895Skaninstead modified to refer to different versions of @file{libgcc.a} 302146895Skandepending on the values of the command line flags @option{-static}, 303169689Skan@option{-shared}, @option{-static-libgcc}, and @option{-shared-libgcc}. On 304169689Skantargets where these modifications are inappropriate, define 305169689Skan@code{REAL_LIBGCC_SPEC} instead. @code{REAL_LIBGCC_SPEC} tells the 306169689Skandriver how to place a reference to @file{libgcc} on the link command 307169689Skanline, but, unlike @code{LIBGCC_SPEC}, it is used unmodified. 308132718Skan@end defmac 30990075Sobrien 310146895Skan@defmac USE_LD_AS_NEEDED 311169689SkanA macro that controls the modifications to @code{LIBGCC_SPEC} 312169689Skanmentioned in @code{REAL_LIBGCC_SPEC}. If nonzero, a spec will be 313146895Skangenerated that uses --as-needed and the shared libgcc in place of the 314146895Skanstatic exception handler library, when linking without any of 315146895Skan@code{-static}, @code{-static-libgcc}, or @code{-shared-libgcc}. 316146895Skan@end defmac 317146895Skan 318146895Skan@defmac LINK_EH_SPEC 319146895SkanIf defined, this C string constant is added to @code{LINK_SPEC}. 320146895SkanWhen @code{USE_LD_AS_NEEDED} is zero or undefined, it also affects 321169689Skanthe modifications to @code{LIBGCC_SPEC} mentioned in 322169689Skan@code{REAL_LIBGCC_SPEC}. 323146895Skan@end defmac 324146895Skan 325132718Skan@defmac STARTFILE_SPEC 32690075SobrienAnother C string constant used much like @code{LINK_SPEC}. The 32790075Sobriendifference between the two is that @code{STARTFILE_SPEC} is used at 32890075Sobrienthe very beginning of the command given to the linker. 32990075Sobrien 33090075SobrienIf this macro is not defined, a default is provided that loads the 33190075Sobrienstandard C startup file from the usual place. See @file{gcc.c}. 332132718Skan@end defmac 33390075Sobrien 334132718Skan@defmac ENDFILE_SPEC 33590075SobrienAnother C string constant used much like @code{LINK_SPEC}. The 33690075Sobriendifference between the two is that @code{ENDFILE_SPEC} is used at 33790075Sobrienthe very end of the command given to the linker. 33890075Sobrien 33990075SobrienDo not define this macro if it does not need to do anything. 340132718Skan@end defmac 34190075Sobrien 342132718Skan@defmac THREAD_MODEL_SPEC 34390075SobrienGCC @code{-v} will print the thread model GCC was configured to use. 34490075SobrienHowever, this doesn't work on platforms that are multilibbed on thread 34590075Sobrienmodels, such as AIX 4.3. On such platforms, define 34690075Sobrien@code{THREAD_MODEL_SPEC} such that it evaluates to a string without 34790075Sobrienblanks that names one of the recognized thread models. @code{%*}, the 34890075Sobriendefault value of this macro, will expand to the value of 34990075Sobrien@code{thread_file} set in @file{config.gcc}. 350132718Skan@end defmac 35190075Sobrien 352132718Skan@defmac SYSROOT_SUFFIX_SPEC 353132718SkanDefine this macro to add a suffix to the target sysroot when GCC is 354132718Skanconfigured with a sysroot. This will cause GCC to search for usr/lib, 355132718Skanet al, within sysroot+suffix. 356132718Skan@end defmac 357132718Skan 358132718Skan@defmac SYSROOT_HEADERS_SUFFIX_SPEC 359132718SkanDefine this macro to add a headers_suffix to the target sysroot when 360132718SkanGCC is configured with a sysroot. This will cause GCC to pass the 361132718Skanupdated sysroot+headers_suffix to CPP, causing it to search for 362132718Skanusr/include, et al, within sysroot+headers_suffix. 363132718Skan@end defmac 364132718Skan 365132718Skan@defmac EXTRA_SPECS 36690075SobrienDefine this macro to provide additional specifications to put in the 36790075Sobrien@file{specs} file that can be used in various specifications like 36890075Sobrien@code{CC1_SPEC}. 36990075Sobrien 37090075SobrienThe definition should be an initializer for an array of structures, 37190075Sobriencontaining a string constant, that defines the specification name, and a 37290075Sobrienstring constant that provides the specification. 37390075Sobrien 37490075SobrienDo not define this macro if it does not need to do anything. 37590075Sobrien 37690075Sobrien@code{EXTRA_SPECS} is useful when an architecture contains several 37790075Sobrienrelated targets, which have various @code{@dots{}_SPECS} which are similar 37890075Sobriento each other, and the maintainer would like one central place to keep 37990075Sobrienthese definitions. 38090075Sobrien 38190075SobrienFor example, the PowerPC System V.4 targets use @code{EXTRA_SPECS} to 38290075Sobriendefine either @code{_CALL_SYSV} when the System V calling sequence is 38390075Sobrienused or @code{_CALL_AIX} when the older AIX-based calling sequence is 38490075Sobrienused. 38590075Sobrien 38690075SobrienThe @file{config/rs6000/rs6000.h} target file defines: 38790075Sobrien 388132718Skan@smallexample 38990075Sobrien#define EXTRA_SPECS \ 39090075Sobrien @{ "cpp_sysv_default", CPP_SYSV_DEFAULT @}, 39190075Sobrien 39290075Sobrien#define CPP_SYS_DEFAULT "" 393132718Skan@end smallexample 39490075Sobrien 39590075SobrienThe @file{config/rs6000/sysv.h} target file defines: 39690075Sobrien@smallexample 39790075Sobrien#undef CPP_SPEC 39890075Sobrien#define CPP_SPEC \ 39990075Sobrien"%@{posix: -D_POSIX_SOURCE @} \ 400132718Skan%@{mcall-sysv: -D_CALL_SYSV @} \ 401132718Skan%@{!mcall-sysv: %(cpp_sysv_default) @} \ 40290075Sobrien%@{msoft-float: -D_SOFT_FLOAT@} %@{mcpu=403: -D_SOFT_FLOAT@}" 40390075Sobrien 40490075Sobrien#undef CPP_SYSV_DEFAULT 40590075Sobrien#define CPP_SYSV_DEFAULT "-D_CALL_SYSV" 40690075Sobrien@end smallexample 40790075Sobrien 40890075Sobrienwhile the @file{config/rs6000/eabiaix.h} target file defines 40990075Sobrien@code{CPP_SYSV_DEFAULT} as: 41090075Sobrien 41190075Sobrien@smallexample 41290075Sobrien#undef CPP_SYSV_DEFAULT 41390075Sobrien#define CPP_SYSV_DEFAULT "-D_CALL_AIX" 41490075Sobrien@end smallexample 415132718Skan@end defmac 41690075Sobrien 417132718Skan@defmac LINK_LIBGCC_SPECIAL_1 41890075SobrienDefine this macro if the driver program should find the library 41990075Sobrien@file{libgcc.a}. If you do not define this macro, the driver program will pass 42090075Sobrienthe argument @option{-lgcc} to tell the linker to do the search. 421132718Skan@end defmac 42290075Sobrien 423132718Skan@defmac LINK_GCC_C_SEQUENCE_SPEC 42496263SobrienThe sequence in which libgcc and libc are specified to the linker. 42596263SobrienBy default this is @code{%G %L %G}. 426132718Skan@end defmac 42796263Sobrien 428132718Skan@defmac LINK_COMMAND_SPEC 42990075SobrienA C string constant giving the complete command line need to execute the 43090075Sobrienlinker. When you do this, you will need to update your port each time a 43190075Sobrienchange is made to the link command line within @file{gcc.c}. Therefore, 43290075Sobriendefine this macro only if you need to completely redefine the command 43390075Sobrienline for invoking the linker and there is no other way to accomplish 43496263Sobrienthe effect you need. Overriding this macro may be avoidable by overriding 43596263Sobrien@code{LINK_GCC_C_SEQUENCE_SPEC} instead. 436132718Skan@end defmac 43790075Sobrien 438132718Skan@defmac LINK_ELIMINATE_DUPLICATE_LDIRECTORIES 43990075SobrienA nonzero value causes @command{collect2} to remove duplicate @option{-L@var{directory}} search 44090075Sobriendirectories from linking commands. Do not give it a nonzero value if 44190075Sobrienremoving duplicate search directories changes the linker's semantics. 442132718Skan@end defmac 44390075Sobrien 444132718Skan@defmac MULTILIB_DEFAULTS 44590075SobrienDefine this macro as a C expression for the initializer of an array of 44690075Sobrienstring to tell the driver program which options are defaults for this 44790075Sobrientarget and thus do not need to be handled specially when using 44890075Sobrien@code{MULTILIB_OPTIONS}. 44990075Sobrien 45090075SobrienDo not define this macro if @code{MULTILIB_OPTIONS} is not defined in 45190075Sobrienthe target makefile fragment or if none of the options listed in 45290075Sobrien@code{MULTILIB_OPTIONS} are set by default. 45390075Sobrien@xref{Target Fragment}. 454132718Skan@end defmac 45590075Sobrien 456132718Skan@defmac RELATIVE_PREFIX_NOT_LINKDIR 457117395SkanDefine this macro to tell @command{gcc} that it should only translate 45890075Sobriena @option{-B} prefix into a @option{-L} linker option if the prefix 45990075Sobrienindicates an absolute file name. 460132718Skan@end defmac 46190075Sobrien 462132718Skan@defmac MD_EXEC_PREFIX 46390075SobrienIf defined, this macro is an additional prefix to try after 46490075Sobrien@code{STANDARD_EXEC_PREFIX}. @code{MD_EXEC_PREFIX} is not searched 46590075Sobrienwhen the @option{-b} option is used, or the compiler is built as a cross 46690075Sobriencompiler. If you define @code{MD_EXEC_PREFIX}, then be sure to add it 46790075Sobriento the list of directories used to find the assembler in @file{configure.in}. 468132718Skan@end defmac 46990075Sobrien 470132718Skan@defmac STANDARD_STARTFILE_PREFIX 47190075SobrienDefine this macro as a C string constant if you wish to override the 472132718Skanstandard choice of @code{libdir} as the default prefix to 47390075Sobrientry when searching for startup files such as @file{crt0.o}. 474132718Skan@code{STANDARD_STARTFILE_PREFIX} is not searched when the compiler 475132718Skanis built as a cross compiler. 476132718Skan@end defmac 47790075Sobrien 478169689Skan@defmac STANDARD_STARTFILE_PREFIX_1 479169689SkanDefine this macro as a C string constant if you wish to override the 480169689Skanstandard choice of @code{/lib} as a prefix to try after the default prefix 481169689Skanwhen searching for startup files such as @file{crt0.o}. 482169689Skan@code{STANDARD_STARTFILE_PREFIX_1} is not searched when the compiler 483169689Skanis built as a cross compiler. 484169689Skan@end defmac 485169689Skan 486169689Skan@defmac STANDARD_STARTFILE_PREFIX_2 487169689SkanDefine this macro as a C string constant if you wish to override the 488169689Skanstandard choice of @code{/lib} as yet another prefix to try after the 489169689Skandefault prefix when searching for startup files such as @file{crt0.o}. 490169689Skan@code{STANDARD_STARTFILE_PREFIX_2} is not searched when the compiler 491169689Skanis built as a cross compiler. 492169689Skan@end defmac 493169689Skan 494132718Skan@defmac MD_STARTFILE_PREFIX 49590075SobrienIf defined, this macro supplies an additional prefix to try after the 49690075Sobrienstandard prefixes. @code{MD_EXEC_PREFIX} is not searched when the 49790075Sobrien@option{-b} option is used, or when the compiler is built as a cross 49890075Sobriencompiler. 499132718Skan@end defmac 50090075Sobrien 501132718Skan@defmac MD_STARTFILE_PREFIX_1 50290075SobrienIf defined, this macro supplies yet another prefix to try after the 50390075Sobrienstandard prefixes. It is not searched when the @option{-b} option is 50490075Sobrienused, or when the compiler is built as a cross compiler. 505132718Skan@end defmac 50690075Sobrien 507132718Skan@defmac INIT_ENVIRONMENT 50890075SobrienDefine this macro as a C string constant if you wish to set environment 50990075Sobrienvariables for programs called by the driver, such as the assembler and 51090075Sobrienloader. The driver passes the value of this macro to @code{putenv} to 51190075Sobrieninitialize the necessary environment variables. 512132718Skan@end defmac 51390075Sobrien 514132718Skan@defmac LOCAL_INCLUDE_DIR 51590075SobrienDefine this macro as a C string constant if you wish to override the 51690075Sobrienstandard choice of @file{/usr/local/include} as the default prefix to 51790075Sobrientry when searching for local header files. @code{LOCAL_INCLUDE_DIR} 51890075Sobriencomes before @code{SYSTEM_INCLUDE_DIR} in the search order. 51990075Sobrien 52090075SobrienCross compilers do not search either @file{/usr/local/include} or its 52190075Sobrienreplacement. 522132718Skan@end defmac 52390075Sobrien 524132718Skan@defmac MODIFY_TARGET_NAME 525132718SkanDefine this macro if you wish to define command-line switches that 526132718Skanmodify the default target name. 52790075Sobrien 52890075SobrienFor each switch, you can include a string to be appended to the first 52990075Sobrienpart of the configuration name or a string to be deleted from the 53090075Sobrienconfiguration name, if present. The definition should be an initializer 53190075Sobrienfor an array of structures. Each array element should have three 53290075Sobrienelements: the switch name (a string constant, including the initial 53390075Sobriendash), one of the enumeration codes @code{ADD} or @code{DELETE} to 53490075Sobrienindicate whether the string should be inserted or deleted, and the string 53590075Sobriento be inserted or deleted (a string constant). 53690075Sobrien 53790075SobrienFor example, on a machine where @samp{64} at the end of the 53890075Sobrienconfiguration name denotes a 64-bit target and you want the @option{-32} 53990075Sobrienand @option{-64} switches to select between 32- and 64-bit targets, you would 54090075Sobriencode 54190075Sobrien 54290075Sobrien@smallexample 54390075Sobrien#define MODIFY_TARGET_NAME \ 54490075Sobrien @{ @{ "-32", DELETE, "64"@}, \ 54590075Sobrien @{"-64", ADD, "64"@}@} 54690075Sobrien@end smallexample 547132718Skan@end defmac 54890075Sobrien 549132718Skan@defmac SYSTEM_INCLUDE_DIR 55090075SobrienDefine this macro as a C string constant if you wish to specify a 55190075Sobriensystem-specific directory to search for header files before the standard 55290075Sobriendirectory. @code{SYSTEM_INCLUDE_DIR} comes before 55390075Sobrien@code{STANDARD_INCLUDE_DIR} in the search order. 55490075Sobrien 55590075SobrienCross compilers do not use this macro and do not search the directory 55690075Sobrienspecified. 557132718Skan@end defmac 55890075Sobrien 559132718Skan@defmac STANDARD_INCLUDE_DIR 56090075SobrienDefine this macro as a C string constant if you wish to override the 56190075Sobrienstandard choice of @file{/usr/include} as the default prefix to 56290075Sobrientry when searching for header files. 56390075Sobrien 564132718SkanCross compilers ignore this macro and do not search either 56590075Sobrien@file{/usr/include} or its replacement. 566132718Skan@end defmac 56790075Sobrien 568132718Skan@defmac STANDARD_INCLUDE_COMPONENT 56990075SobrienThe ``component'' corresponding to @code{STANDARD_INCLUDE_DIR}. 57090075SobrienSee @code{INCLUDE_DEFAULTS}, below, for the description of components. 57190075SobrienIf you do not define this macro, no component is used. 572132718Skan@end defmac 57390075Sobrien 574132718Skan@defmac INCLUDE_DEFAULTS 57590075SobrienDefine this macro if you wish to override the entire default search path 57690075Sobrienfor include files. For a native compiler, the default search path 57790075Sobrienusually consists of @code{GCC_INCLUDE_DIR}, @code{LOCAL_INCLUDE_DIR}, 57890075Sobrien@code{SYSTEM_INCLUDE_DIR}, @code{GPLUSPLUS_INCLUDE_DIR}, and 57990075Sobrien@code{STANDARD_INCLUDE_DIR}. In addition, @code{GPLUSPLUS_INCLUDE_DIR} 58090075Sobrienand @code{GCC_INCLUDE_DIR} are defined automatically by @file{Makefile}, 58190075Sobrienand specify private search areas for GCC@. The directory 58290075Sobrien@code{GPLUSPLUS_INCLUDE_DIR} is used only for C++ programs. 58390075Sobrien 58490075SobrienThe definition should be an initializer for an array of structures. 58590075SobrienEach array element should have four elements: the directory name (a 58690075Sobrienstring constant), the component name (also a string constant), a flag 58790075Sobrienfor C++-only directories, 58890075Sobrienand a flag showing that the includes in the directory don't need to be 58990075Sobrienwrapped in @code{extern @samp{C}} when compiling C++. Mark the end of 59090075Sobrienthe array with a null element. 59190075Sobrien 59290075SobrienThe component name denotes what GNU package the include file is part of, 593132718Skanif any, in all uppercase letters. For example, it might be @samp{GCC} 59490075Sobrienor @samp{BINUTILS}. If the package is part of a vendor-supplied 59590075Sobrienoperating system, code the component name as @samp{0}. 59690075Sobrien 59790075SobrienFor example, here is the definition used for VAX/VMS: 59890075Sobrien 599132718Skan@smallexample 60090075Sobrien#define INCLUDE_DEFAULTS \ 60190075Sobrien@{ \ 60290075Sobrien @{ "GNU_GXX_INCLUDE:", "G++", 1, 1@}, \ 60390075Sobrien @{ "GNU_CC_INCLUDE:", "GCC", 0, 0@}, \ 60490075Sobrien @{ "SYS$SYSROOT:[SYSLIB.]", 0, 0, 0@}, \ 60590075Sobrien @{ ".", 0, 0, 0@}, \ 60690075Sobrien @{ 0, 0, 0, 0@} \ 60790075Sobrien@} 608132718Skan@end smallexample 609132718Skan@end defmac 61090075Sobrien 61190075SobrienHere is the order of prefixes tried for exec files: 61290075Sobrien 61390075Sobrien@enumerate 61490075Sobrien@item 61590075SobrienAny prefixes specified by the user with @option{-B}. 61690075Sobrien 61790075Sobrien@item 61890075SobrienThe environment variable @code{GCC_EXEC_PREFIX}, if any. 61990075Sobrien 62090075Sobrien@item 62190075SobrienThe directories specified by the environment variable @code{COMPILER_PATH}. 62290075Sobrien 62390075Sobrien@item 62490075SobrienThe macro @code{STANDARD_EXEC_PREFIX}. 62590075Sobrien 62690075Sobrien@item 62790075Sobrien@file{/usr/lib/gcc/}. 62890075Sobrien 62990075Sobrien@item 63090075SobrienThe macro @code{MD_EXEC_PREFIX}, if any. 63190075Sobrien@end enumerate 63290075Sobrien 63390075SobrienHere is the order of prefixes tried for startfiles: 63490075Sobrien 63590075Sobrien@enumerate 63690075Sobrien@item 63790075SobrienAny prefixes specified by the user with @option{-B}. 63890075Sobrien 63990075Sobrien@item 64090075SobrienThe environment variable @code{GCC_EXEC_PREFIX}, if any. 64190075Sobrien 64290075Sobrien@item 64390075SobrienThe directories specified by the environment variable @code{LIBRARY_PATH} 64490075Sobrien(or port-specific name; native only, cross compilers do not use this). 64590075Sobrien 64690075Sobrien@item 64790075SobrienThe macro @code{STANDARD_EXEC_PREFIX}. 64890075Sobrien 64990075Sobrien@item 65090075Sobrien@file{/usr/lib/gcc/}. 65190075Sobrien 65290075Sobrien@item 65390075SobrienThe macro @code{MD_EXEC_PREFIX}, if any. 65490075Sobrien 65590075Sobrien@item 65690075SobrienThe macro @code{MD_STARTFILE_PREFIX}, if any. 65790075Sobrien 65890075Sobrien@item 65990075SobrienThe macro @code{STANDARD_STARTFILE_PREFIX}. 66090075Sobrien 66190075Sobrien@item 66290075Sobrien@file{/lib/}. 66390075Sobrien 66490075Sobrien@item 66590075Sobrien@file{/usr/lib/}. 66690075Sobrien@end enumerate 66790075Sobrien 66890075Sobrien@node Run-time Target 66990075Sobrien@section Run-time Target Specification 67090075Sobrien@cindex run-time target specification 67190075Sobrien@cindex predefined macros 67290075Sobrien@cindex target specifications 67390075Sobrien 67490075Sobrien@c prevent bad page break with this line 67590075SobrienHere are run-time target specifications. 67690075Sobrien 677132718Skan@defmac TARGET_CPU_CPP_BUILTINS () 678117395SkanThis function-like macro expands to a block of code that defines 679117395Skanbuilt-in preprocessor macros and assertions for the target cpu, using 680117395Skanthe functions @code{builtin_define}, @code{builtin_define_std} and 681132718Skan@code{builtin_assert}. When the front end 682117395Skancalls this macro it provides a trailing semicolon, and since it has 683117395Skanfinished command line option processing your code can use those 684117395Skanresults freely. 685117395Skan 686117395Skan@code{builtin_assert} takes a string in the form you pass to the 687117395Skancommand-line option @option{-A}, such as @code{cpu=mips}, and creates 688117395Skanthe assertion. @code{builtin_define} takes a string in the form 689117395Skanaccepted by option @option{-D} and unconditionally defines the macro. 690117395Skan 691117395Skan@code{builtin_define_std} takes a string representing the name of an 692117395Skanobject-like macro. If it doesn't lie in the user's namespace, 693117395Skan@code{builtin_define_std} defines it unconditionally. Otherwise, it 694117395Skandefines a version with two leading underscores, and another version 695117395Skanwith two leading and trailing underscores, and defines the original 696117395Skanonly if an ISO standard was not requested on the command line. For 697117395Skanexample, passing @code{unix} defines @code{__unix}, @code{__unix__} 698117395Skanand possibly @code{unix}; passing @code{_mips} defines @code{__mips}, 699117395Skan@code{__mips__} and possibly @code{_mips}, and passing @code{_ABI64} 700117395Skandefines only @code{_ABI64}. 701117395Skan 702117395SkanYou can also test for the C dialect being compiled. The variable 703117395Skan@code{c_language} is set to one of @code{clk_c}, @code{clk_cplusplus} 704117395Skanor @code{clk_objective_c}. Note that if we are preprocessing 705117395Skanassembler, this variable will be @code{clk_c} but the function-like 706117395Skanmacro @code{preprocessing_asm_p()} will return true, so you might want 707117395Skanto check for that first. If you need to check for strict ANSI, the 708117395Skanvariable @code{flag_iso} can be used. The function-like macro 709117395Skan@code{preprocessing_trad_p()} can be used to check for traditional 710117395Skanpreprocessing. 711132718Skan@end defmac 712117395Skan 713132718Skan@defmac TARGET_OS_CPP_BUILTINS () 714117395SkanSimilarly to @code{TARGET_CPU_CPP_BUILTINS} but this macro is optional 715117395Skanand is used for the target operating system instead. 716132718Skan@end defmac 717117395Skan 718132718Skan@defmac TARGET_OBJFMT_CPP_BUILTINS () 719132718SkanSimilarly to @code{TARGET_CPU_CPP_BUILTINS} but this macro is optional 720132718Skanand is used for the target object format. @file{elfos.h} uses this 721132718Skanmacro to define @code{__ELF__}, so you probably do not need to define 722132718Skanit yourself. 723132718Skan@end defmac 724117395Skan 725132718Skan@deftypevar {extern int} target_flags 726169689SkanThis variable is declared in @file{options.h}, which is included before 727169689Skanany target-specific headers. 728132718Skan@end deftypevar 72990075Sobrien 730169689Skan@deftypevar {Target Hook} int TARGET_DEFAULT_TARGET_FLAGS 731169689SkanThis variable specifies the initial value of @code{target_flags}. 732169689SkanIts default setting is 0. 733169689Skan@end deftypevar 734169689Skan 73590075Sobrien@cindex optional hardware or system features 73690075Sobrien@cindex features, optional, in system conventions 737132718Skan 738169689Skan@deftypefn {Target Hook} bool TARGET_HANDLE_OPTION (size_t @var{code}, const char *@var{arg}, int @var{value}) 739169689SkanThis hook is called whenever the user specifies one of the 740169689Skantarget-specific options described by the @file{.opt} definition files 741169689Skan(@pxref{Options}). It has the opportunity to do some option-specific 742169689Skanprocessing and should return true if the option is valid. The default 743169689Skandefinition does nothing but return true. 74490075Sobrien 745169689Skan@var{code} specifies the @code{OPT_@var{name}} enumeration value 746169689Skanassociated with the selected option; @var{name} is just a rendering of 747169689Skanthe option name in which non-alphanumeric characters are replaced by 748169689Skanunderscores. @var{arg} specifies the string argument and is null if 749169689Skanno argument was given. If the option is flagged as a @code{UInteger} 750169689Skan(@pxref{Option properties}), @var{value} is the numeric value of the 751169689Skanargument. Otherwise @var{value} is 1 if the positive form of the 752169689Skanoption was used and 0 if the ``no-'' form was. 753169689Skan@end deftypefn 75490075Sobrien 755132718Skan@defmac TARGET_VERSION 75690075SobrienThis macro is a C statement to print on @code{stderr} a string 75790075Sobriendescribing the particular machine description choice. Every machine 75890075Sobriendescription should define @code{TARGET_VERSION}. For example: 75990075Sobrien 76090075Sobrien@smallexample 76190075Sobrien#ifdef MOTOROLA 76290075Sobrien#define TARGET_VERSION \ 76390075Sobrien fprintf (stderr, " (68k, Motorola syntax)"); 76490075Sobrien#else 76590075Sobrien#define TARGET_VERSION \ 76690075Sobrien fprintf (stderr, " (68k, MIT syntax)"); 76790075Sobrien#endif 76890075Sobrien@end smallexample 769132718Skan@end defmac 77090075Sobrien 771132718Skan@defmac OVERRIDE_OPTIONS 77290075SobrienSometimes certain combinations of command options do not make sense on 77390075Sobriena particular target machine. You can define a macro 77490075Sobrien@code{OVERRIDE_OPTIONS} to take account of this. This macro, if 77590075Sobriendefined, is executed once just after all the command options have been 77690075Sobrienparsed. 77790075Sobrien 77890075SobrienDon't use this macro to turn on various extra optimizations for 77990075Sobrien@option{-O}. That is what @code{OPTIMIZATION_OPTIONS} is for. 780132718Skan@end defmac 78190075Sobrien 782169689Skan@defmac C_COMMON_OVERRIDE_OPTIONS 783169689SkanThis is similar to @code{OVERRIDE_OPTIONS} but is only used in the C 784169689Skanlanguage frontends (C, Objective-C, C++, Objective-C++) and so can be 785169689Skanused to alter option flag variables which only exist in those 786169689Skanfrontends. 787169689Skan@end defmac 788169689Skan 789132718Skan@defmac OPTIMIZATION_OPTIONS (@var{level}, @var{size}) 79090075SobrienSome machines may desire to change what optimizations are performed for 79190075Sobrienvarious optimization levels. This macro, if defined, is executed once 79290075Sobrienjust after the optimization level is determined and before the remainder 79390075Sobrienof the command options have been parsed. Values set in this macro are 79490075Sobrienused as the default values for the other command line options. 79590075Sobrien 79690075Sobrien@var{level} is the optimization level specified; 2 if @option{-O2} is 79790075Sobrienspecified, 1 if @option{-O} is specified, and 0 if neither is specified. 79890075Sobrien 79990075Sobrien@var{size} is nonzero if @option{-Os} is specified and zero otherwise. 80090075Sobrien 80190075SobrienYou should not use this macro to change options that are not 80290075Sobrienmachine-specific. These should uniformly selected by the same 80390075Sobrienoptimization level on all supported machines. Use this macro to enable 80490075Sobrienmachine-specific optimizations. 80590075Sobrien 80690075Sobrien@strong{Do not examine @code{write_symbols} in 80790075Sobrienthis macro!} The debugging options are not supposed to alter the 80890075Sobriengenerated code. 809132718Skan@end defmac 81090075Sobrien 811132718Skan@defmac CAN_DEBUG_WITHOUT_FP 81290075SobrienDefine this macro if debugging can be performed even without a frame 81390075Sobrienpointer. If this macro is defined, GCC will turn on the 81490075Sobrien@option{-fomit-frame-pointer} option whenever @option{-O} is specified. 815132718Skan@end defmac 81690075Sobrien 81790075Sobrien@node Per-Function Data 81890075Sobrien@section Defining data structures for per-function information. 81990075Sobrien@cindex per-function data 82090075Sobrien@cindex data structures 82190075Sobrien 82290075SobrienIf the target needs to store information on a per-function basis, GCC 82390075Sobrienprovides a macro and a couple of variables to allow this. Note, just 82490075Sobrienusing statics to store the information is a bad idea, since GCC supports 82590075Sobriennested functions, so you can be halfway through encoding one function 82690075Sobrienwhen another one comes along. 82790075Sobrien 82890075SobrienGCC defines a data structure called @code{struct function} which 82990075Sobriencontains all of the data specific to an individual function. This 83090075Sobrienstructure contains a field called @code{machine} whose type is 83190075Sobrien@code{struct machine_function *}, which can be used by targets to point 83290075Sobriento their own specific data. 83390075Sobrien 83490075SobrienIf a target needs per-function specific data it should define the type 835117395Skan@code{struct machine_function} and also the macro @code{INIT_EXPANDERS}. 836117395SkanThis macro should be used to initialize the function pointer 837117395Skan@code{init_machine_status}. This pointer is explained below. 83890075Sobrien 83990075SobrienOne typical use of per-function, target specific data is to create an 84090075SobrienRTX to hold the register containing the function's return address. This 84190075SobrienRTX can then be used to implement the @code{__builtin_return_address} 84290075Sobrienfunction, for level 0. 84390075Sobrien 84490075SobrienNote---earlier implementations of GCC used a single data area to hold 84590075Sobrienall of the per-function information. Thus when processing of a nested 84690075Sobrienfunction began the old per-function data had to be pushed onto a 84790075Sobrienstack, and when the processing was finished, it had to be popped off the 84890075Sobrienstack. GCC used to provide function pointers called 84990075Sobrien@code{save_machine_status} and @code{restore_machine_status} to handle 85090075Sobrienthe saving and restoring of the target specific information. Since the 85190075Sobriensingle data area approach is no longer used, these pointers are no 85290075Sobrienlonger supported. 85390075Sobrien 854132718Skan@defmac INIT_EXPANDERS 85590075SobrienMacro called to initialize any target specific information. This macro 85690075Sobrienis called once per function, before generation of any RTL has begun. 85790075SobrienThe intention of this macro is to allow the initialization of the 858132718Skanfunction pointer @code{init_machine_status}. 859132718Skan@end defmac 86090075Sobrien 861132718Skan@deftypevar {void (*)(struct function *)} init_machine_status 862132718SkanIf this function pointer is non-@code{NULL} it will be called once per 863132718Skanfunction, before function compilation starts, in order to allow the 864132718Skantarget to perform any target specific initialization of the 865132718Skan@code{struct function} structure. It is intended that this would be 866132718Skanused to initialize the @code{machine} of that structure. 86790075Sobrien 868169689Skan@code{struct machine_function} structures are expected to be freed by GC@. 869117395SkanGenerally, any memory that they reference must be allocated by using 870117395Skan@code{ggc_alloc}, including the structure itself. 871132718Skan@end deftypevar 87290075Sobrien 87390075Sobrien@node Storage Layout 87490075Sobrien@section Storage Layout 87590075Sobrien@cindex storage layout 87690075Sobrien 87790075SobrienNote that the definitions of the macros in this table which are sizes or 87890075Sobrienalignments measured in bits do not need to be constant. They can be C 87990075Sobrienexpressions that refer to static variables, such as the @code{target_flags}. 88090075Sobrien@xref{Run-time Target}. 88190075Sobrien 882132718Skan@defmac BITS_BIG_ENDIAN 88390075SobrienDefine this macro to have the value 1 if the most significant bit in a 88490075Sobrienbyte has the lowest number; otherwise define it to have the value zero. 88590075SobrienThis means that bit-field instructions count from the most significant 88690075Sobrienbit. If the machine has no bit-field instructions, then this must still 88790075Sobrienbe defined, but it doesn't matter which value it is defined to. This 88890075Sobrienmacro need not be a constant. 88990075Sobrien 89090075SobrienThis macro does not affect the way structure fields are packed into 89190075Sobrienbytes or words; that is controlled by @code{BYTES_BIG_ENDIAN}. 892132718Skan@end defmac 89390075Sobrien 894132718Skan@defmac BYTES_BIG_ENDIAN 89590075SobrienDefine this macro to have the value 1 if the most significant byte in a 89690075Sobrienword has the lowest number. This macro need not be a constant. 897132718Skan@end defmac 89890075Sobrien 899132718Skan@defmac WORDS_BIG_ENDIAN 90090075SobrienDefine this macro to have the value 1 if, in a multiword object, the 90190075Sobrienmost significant word has the lowest number. This applies to both 90290075Sobrienmemory locations and registers; GCC fundamentally assumes that the 90390075Sobrienorder of words in memory is the same as the order in registers. This 90490075Sobrienmacro need not be a constant. 905132718Skan@end defmac 90690075Sobrien 907132718Skan@defmac LIBGCC2_WORDS_BIG_ENDIAN 90890075SobrienDefine this macro if @code{WORDS_BIG_ENDIAN} is not constant. This must be a 90990075Sobrienconstant value with the same meaning as @code{WORDS_BIG_ENDIAN}, which will be 91090075Sobrienused only when compiling @file{libgcc2.c}. Typically the value will be set 91190075Sobrienbased on preprocessor defines. 912132718Skan@end defmac 91390075Sobrien 914132718Skan@defmac FLOAT_WORDS_BIG_ENDIAN 91590075SobrienDefine this macro to have the value 1 if @code{DFmode}, @code{XFmode} or 91690075Sobrien@code{TFmode} floating point numbers are stored in memory with the word 91790075Sobriencontaining the sign bit at the lowest address; otherwise define it to 91890075Sobrienhave the value 0. This macro need not be a constant. 91990075Sobrien 92090075SobrienYou need not define this macro if the ordering is the same as for 92190075Sobrienmulti-word integers. 922132718Skan@end defmac 92390075Sobrien 924132718Skan@defmac BITS_PER_UNIT 92590075SobrienDefine this macro to be the number of bits in an addressable storage 926117395Skanunit (byte). If you do not define this macro the default is 8. 927132718Skan@end defmac 92890075Sobrien 929132718Skan@defmac BITS_PER_WORD 930117395SkanNumber of bits in a word. If you do not define this macro, the default 931117395Skanis @code{BITS_PER_UNIT * UNITS_PER_WORD}. 932132718Skan@end defmac 93390075Sobrien 934132718Skan@defmac MAX_BITS_PER_WORD 93590075SobrienMaximum number of bits in a word. If this is undefined, the default is 93690075Sobrien@code{BITS_PER_WORD}. Otherwise, it is the constant value that is the 93790075Sobrienlargest value that @code{BITS_PER_WORD} can have at run-time. 938132718Skan@end defmac 93990075Sobrien 940132718Skan@defmac UNITS_PER_WORD 941169689SkanNumber of storage units in a word; normally the size of a general-purpose 942169689Skanregister, a power of two from 1 or 8. 943132718Skan@end defmac 94490075Sobrien 945132718Skan@defmac MIN_UNITS_PER_WORD 94690075SobrienMinimum number of units in a word. If this is undefined, the default is 94790075Sobrien@code{UNITS_PER_WORD}. Otherwise, it is the constant value that is the 94890075Sobriensmallest value that @code{UNITS_PER_WORD} can have at run-time. 949132718Skan@end defmac 95090075Sobrien 951169689Skan@defmac UNITS_PER_SIMD_WORD 952169689SkanNumber of units in the vectors that the vectorizer can produce. 953169689SkanThe default is equal to @code{UNITS_PER_WORD}, because the vectorizer 954169689Skancan do some transformations even in absence of specialized @acronym{SIMD} 955169689Skanhardware. 956169689Skan@end defmac 957169689Skan 958132718Skan@defmac POINTER_SIZE 95990075SobrienWidth of a pointer, in bits. You must specify a value no wider than the 96090075Sobrienwidth of @code{Pmode}. If it is not equal to the width of @code{Pmode}, 961117395Skanyou must define @code{POINTERS_EXTEND_UNSIGNED}. If you do not specify 962117395Skana value the default is @code{BITS_PER_WORD}. 963132718Skan@end defmac 96490075Sobrien 965132718Skan@defmac POINTERS_EXTEND_UNSIGNED 96690075SobrienA C expression whose value is greater than zero if pointers that need to be 96790075Sobrienextended from being @code{POINTER_SIZE} bits wide to @code{Pmode} are to 96890075Sobrienbe zero-extended and zero if they are to be sign-extended. If the value 96990075Sobrienis less then zero then there must be an "ptr_extend" instruction that 97090075Sobrienextends a pointer from @code{POINTER_SIZE} to @code{Pmode}. 97190075Sobrien 97290075SobrienYou need not define this macro if the @code{POINTER_SIZE} is equal 97390075Sobriento the width of @code{Pmode}. 974132718Skan@end defmac 97590075Sobrien 976132718Skan@defmac PROMOTE_MODE (@var{m}, @var{unsignedp}, @var{type}) 97790075SobrienA macro to update @var{m} and @var{unsignedp} when an object whose type 97890075Sobrienis @var{type} and which has the specified mode and signedness is to be 97990075Sobrienstored in a register. This macro is only called when @var{type} is a 98090075Sobrienscalar type. 98190075Sobrien 98290075SobrienOn most RISC machines, which only have operations that operate on a full 98390075Sobrienregister, define this macro to set @var{m} to @code{word_mode} if 98490075Sobrien@var{m} is an integer mode narrower than @code{BITS_PER_WORD}. In most 98590075Sobriencases, only integer modes should be widened because wider-precision 98690075Sobrienfloating-point operations are usually more expensive than their narrower 98790075Sobriencounterparts. 98890075Sobrien 98990075SobrienFor most machines, the macro definition does not change @var{unsignedp}. 99090075SobrienHowever, some machines, have instructions that preferentially handle 99190075Sobrieneither signed or unsigned quantities of certain modes. For example, on 99290075Sobrienthe DEC Alpha, 32-bit loads from memory and 32-bit add instructions 99390075Sobriensign-extend the result to 64 bits. On such machines, set 99490075Sobrien@var{unsignedp} according to which kind of extension is more efficient. 99590075Sobrien 99690075SobrienDo not define this macro if it would never modify @var{m}. 997132718Skan@end defmac 99890075Sobrien 999169689Skan@defmac PROMOTE_FUNCTION_MODE 1000169689SkanLike @code{PROMOTE_MODE}, but is applied to outgoing function arguments or 1001169689Skanfunction return values, as specified by @code{TARGET_PROMOTE_FUNCTION_ARGS} 1002169689Skanand @code{TARGET_PROMOTE_FUNCTION_RETURN}, respectively. 1003169689Skan 1004169689SkanThe default is @code{PROMOTE_MODE}. 1005169689Skan@end defmac 1006169689Skan 1007132718Skan@deftypefn {Target Hook} bool TARGET_PROMOTE_FUNCTION_ARGS (tree @var{fntype}) 1008132718SkanThis target hook should return @code{true} if the promotion described by 1009169689Skan@code{PROMOTE_FUNCTION_MODE} should be done for outgoing function 1010169689Skanarguments. 1011132718Skan@end deftypefn 101290075Sobrien 1013132718Skan@deftypefn {Target Hook} bool TARGET_PROMOTE_FUNCTION_RETURN (tree @var{fntype}) 1014132718SkanThis target hook should return @code{true} if the promotion described by 1015169689Skan@code{PROMOTE_FUNCTION_MODE} should be done for the return value of 1016132718Skanfunctions. 101790075Sobrien 1018169689SkanIf this target hook returns @code{true}, @code{TARGET_FUNCTION_VALUE} 1019169689Skanmust perform the same promotions done by @code{PROMOTE_FUNCTION_MODE}. 1020132718Skan@end deftypefn 102190075Sobrien 1022132718Skan@defmac PARM_BOUNDARY 102390075SobrienNormal alignment required for function parameters on the stack, in 102490075Sobrienbits. All stack parameters receive at least this much alignment 102590075Sobrienregardless of data type. On most machines, this is the same as the 102690075Sobriensize of an integer. 1027132718Skan@end defmac 102890075Sobrien 1029132718Skan@defmac STACK_BOUNDARY 103090075SobrienDefine this macro to the minimum alignment enforced by hardware for the 103190075Sobrienstack pointer on this machine. The definition is a C expression for the 103290075Sobriendesired alignment (measured in bits). This value is used as a default 103390075Sobrienif @code{PREFERRED_STACK_BOUNDARY} is not defined. On most machines, 103490075Sobrienthis should be the same as @code{PARM_BOUNDARY}. 1035132718Skan@end defmac 103690075Sobrien 1037132718Skan@defmac PREFERRED_STACK_BOUNDARY 103890075SobrienDefine this macro if you wish to preserve a certain alignment for the 103990075Sobrienstack pointer, greater than what the hardware enforces. The definition 104090075Sobrienis a C expression for the desired alignment (measured in bits). This 104190075Sobrienmacro must evaluate to a value equal to or larger than 104290075Sobrien@code{STACK_BOUNDARY}. 1043132718Skan@end defmac 104490075Sobrien 1045132718Skan@defmac FUNCTION_BOUNDARY 104690075SobrienAlignment required for a function entry point, in bits. 1047132718Skan@end defmac 104890075Sobrien 1049132718Skan@defmac BIGGEST_ALIGNMENT 105090075SobrienBiggest alignment that any data type can require on this machine, in bits. 1051132718Skan@end defmac 105290075Sobrien 1053132718Skan@defmac MINIMUM_ATOMIC_ALIGNMENT 105490075SobrienIf defined, the smallest alignment, in bits, that can be given to an 105590075Sobrienobject that can be referenced in one operation, without disturbing any 105690075Sobriennearby object. Normally, this is @code{BITS_PER_UNIT}, but may be larger 105790075Sobrienon machines that don't have byte or half-word store operations. 1058132718Skan@end defmac 105990075Sobrien 1060132718Skan@defmac BIGGEST_FIELD_ALIGNMENT 106190075SobrienBiggest alignment that any structure or union field can require on this 106290075Sobrienmachine, in bits. If defined, this overrides @code{BIGGEST_ALIGNMENT} for 106390075Sobrienstructure and union fields only, unless the field alignment has been set 106490075Sobrienby the @code{__attribute__ ((aligned (@var{n})))} construct. 1065132718Skan@end defmac 106690075Sobrien 1067132718Skan@defmac ADJUST_FIELD_ALIGN (@var{field}, @var{computed}) 106890075SobrienAn expression for the alignment of a structure field @var{field} if the 1069102780Skanalignment computed in the usual way (including applying of 1070102780Skan@code{BIGGEST_ALIGNMENT} and @code{BIGGEST_FIELD_ALIGNMENT} to the 1071102780Skanalignment) is @var{computed}. It overrides alignment only if the 1072102780Skanfield alignment has not been set by the 1073102780Skan@code{__attribute__ ((aligned (@var{n})))} construct. 1074132718Skan@end defmac 107590075Sobrien 1076132718Skan@defmac MAX_OFILE_ALIGNMENT 107790075SobrienBiggest alignment supported by the object file format of this machine. 107890075SobrienUse this macro to limit the alignment which can be specified using the 107990075Sobrien@code{__attribute__ ((aligned (@var{n})))} construct. If not defined, 108090075Sobrienthe default value is @code{BIGGEST_ALIGNMENT}. 1081132718Skan@end defmac 108290075Sobrien 1083132718Skan@defmac DATA_ALIGNMENT (@var{type}, @var{basic-align}) 108490075SobrienIf defined, a C expression to compute the alignment for a variable in 108590075Sobrienthe static store. @var{type} is the data type, and @var{basic-align} is 108690075Sobrienthe alignment that the object would ordinarily have. The value of this 108790075Sobrienmacro is used instead of that alignment to align the object. 108890075Sobrien 108990075SobrienIf this macro is not defined, then @var{basic-align} is used. 109090075Sobrien 109190075Sobrien@findex strcpy 109290075SobrienOne use of this macro is to increase alignment of medium-size data to 109390075Sobrienmake it all fit in fewer cache lines. Another is to cause character 109490075Sobrienarrays to be word-aligned so that @code{strcpy} calls that copy 109590075Sobrienconstants to character arrays can be done inline. 1096132718Skan@end defmac 109790075Sobrien 1098132718Skan@defmac CONSTANT_ALIGNMENT (@var{constant}, @var{basic-align}) 109990075SobrienIf defined, a C expression to compute the alignment given to a constant 110090075Sobrienthat is being placed in memory. @var{constant} is the constant and 110190075Sobrien@var{basic-align} is the alignment that the object would ordinarily 110290075Sobrienhave. The value of this macro is used instead of that alignment to 110390075Sobrienalign the object. 110490075Sobrien 110590075SobrienIf this macro is not defined, then @var{basic-align} is used. 110690075Sobrien 110790075SobrienThe typical use of this macro is to increase alignment for string 110890075Sobrienconstants to be word aligned so that @code{strcpy} calls that copy 110990075Sobrienconstants can be done inline. 1110132718Skan@end defmac 111190075Sobrien 1112132718Skan@defmac LOCAL_ALIGNMENT (@var{type}, @var{basic-align}) 111390075SobrienIf defined, a C expression to compute the alignment for a variable in 111490075Sobrienthe local store. @var{type} is the data type, and @var{basic-align} is 111590075Sobrienthe alignment that the object would ordinarily have. The value of this 111690075Sobrienmacro is used instead of that alignment to align the object. 111790075Sobrien 111890075SobrienIf this macro is not defined, then @var{basic-align} is used. 111990075Sobrien 112090075SobrienOne use of this macro is to increase alignment of medium-size data to 112190075Sobrienmake it all fit in fewer cache lines. 1122132718Skan@end defmac 112390075Sobrien 1124132718Skan@defmac EMPTY_FIELD_BOUNDARY 112590075SobrienAlignment in bits to be given to a structure bit-field that follows an 112690075Sobrienempty field such as @code{int : 0;}. 112790075Sobrien 1128132718SkanIf @code{PCC_BITFIELD_TYPE_MATTERS} is true, it overrides this macro. 1129132718Skan@end defmac 113090075Sobrien 1131132718Skan@defmac STRUCTURE_SIZE_BOUNDARY 113290075SobrienNumber of bits which any structure or union's size must be a multiple of. 113390075SobrienEach structure or union's size is rounded up to a multiple of this. 113490075Sobrien 113590075SobrienIf you do not define this macro, the default is the same as 113690075Sobrien@code{BITS_PER_UNIT}. 1137132718Skan@end defmac 113890075Sobrien 1139132718Skan@defmac STRICT_ALIGNMENT 114090075SobrienDefine this macro to be the value 1 if instructions will fail to work 114190075Sobrienif given data not on the nominal alignment. If instructions will merely 114290075Sobriengo slower in that case, define this macro as 0. 1143132718Skan@end defmac 114490075Sobrien 1145132718Skan@defmac PCC_BITFIELD_TYPE_MATTERS 114690075SobrienDefine this if you wish to imitate the way many other C compilers handle 114790075Sobrienalignment of bit-fields and the structures that contain them. 114890075Sobrien 1149132718SkanThe behavior is that the type written for a named bit-field (@code{int}, 1150132718Skan@code{short}, or other integer type) imposes an alignment for the entire 1151132718Skanstructure, as if the structure really did contain an ordinary field of 1152132718Skanthat type. In addition, the bit-field is placed within the structure so 1153132718Skanthat it would fit within such a field, not crossing a boundary for it. 115490075Sobrien 1155132718SkanThus, on most machines, a named bit-field whose type is written as 1156132718Skan@code{int} would not cross a four-byte boundary, and would force 1157132718Skanfour-byte alignment for the whole structure. (The alignment used may 1158132718Skannot be four bytes; it is controlled by the other alignment parameters.) 115990075Sobrien 1160132718SkanAn unnamed bit-field will not affect the alignment of the containing 1161132718Skanstructure. 1162132718Skan 116390075SobrienIf the macro is defined, its definition should be a C expression; 116490075Sobriena nonzero value for the expression enables this behavior. 116590075Sobrien 116690075SobrienNote that if this macro is not defined, or its value is zero, some 116790075Sobrienbit-fields may cross more than one alignment boundary. The compiler can 116890075Sobriensupport such references if there are @samp{insv}, @samp{extv}, and 116990075Sobrien@samp{extzv} insns that can directly reference memory. 117090075Sobrien 117190075SobrienThe other known way of making bit-fields work is to define 117290075Sobrien@code{STRUCTURE_SIZE_BOUNDARY} as large as @code{BIGGEST_ALIGNMENT}. 117390075SobrienThen every structure can be accessed with fullwords. 117490075Sobrien 117590075SobrienUnless the machine has bit-field instructions or you define 117690075Sobrien@code{STRUCTURE_SIZE_BOUNDARY} that way, you must define 117790075Sobrien@code{PCC_BITFIELD_TYPE_MATTERS} to have a nonzero value. 117890075Sobrien 117990075SobrienIf your aim is to make GCC use the same conventions for laying out 118090075Sobrienbit-fields as are used by another compiler, here is how to investigate 118190075Sobrienwhat the other compiler does. Compile and run this program: 118290075Sobrien 1183132718Skan@smallexample 118490075Sobrienstruct foo1 118590075Sobrien@{ 118690075Sobrien char x; 118790075Sobrien char :0; 118890075Sobrien char y; 118990075Sobrien@}; 119090075Sobrien 119190075Sobrienstruct foo2 119290075Sobrien@{ 119390075Sobrien char x; 119490075Sobrien int :0; 119590075Sobrien char y; 119690075Sobrien@}; 119790075Sobrien 119890075Sobrienmain () 119990075Sobrien@{ 120090075Sobrien printf ("Size of foo1 is %d\n", 120190075Sobrien sizeof (struct foo1)); 120290075Sobrien printf ("Size of foo2 is %d\n", 120390075Sobrien sizeof (struct foo2)); 120490075Sobrien exit (0); 120590075Sobrien@} 1206132718Skan@end smallexample 120790075Sobrien 120890075SobrienIf this prints 2 and 5, then the compiler's behavior is what you would 120990075Sobrienget from @code{PCC_BITFIELD_TYPE_MATTERS}. 1210132718Skan@end defmac 121190075Sobrien 1212132718Skan@defmac BITFIELD_NBYTES_LIMITED 121396263SobrienLike @code{PCC_BITFIELD_TYPE_MATTERS} except that its effect is limited 121496263Sobriento aligning a bit-field within the structure. 1215132718Skan@end defmac 121690075Sobrien 1217169689Skan@deftypefn {Target Hook} bool TARGET_ALIGN_ANON_BITFIELDS (void) 1218169689SkanWhen @code{PCC_BITFIELD_TYPE_MATTERS} is true this hook will determine 1219169689Skanwhether unnamed bitfields affect the alignment of the containing 1220169689Skanstructure. The hook should return true if the structure should inherit 1221169689Skanthe alignment requirements of an unnamed bitfield's type. 1222169689Skan@end deftypefn 1223169689Skan 1224169689Skan@deftypefn {Target Hook} bool TARGET_NARROW_VOLATILE_BITFIELDS (void) 1225169689SkanThis target hook should return @code{true} if accesses to volatile bitfields 1226169689Skanshould use the narrowest mode possible. It should return @code{false} if 1227169689Skanthese accesses should use the bitfield container type. 1228169689Skan 1229169689SkanThe default is @code{!TARGET_STRICT_ALIGN}. 1230169689Skan@end deftypefn 1231169689Skan 1232132718Skan@defmac MEMBER_TYPE_FORCES_BLK (@var{field}, @var{mode}) 123390075SobrienReturn 1 if a structure or array containing @var{field} should be accessed using 123490075Sobrien@code{BLKMODE}. 123590075Sobrien 1236117395SkanIf @var{field} is the only field in the structure, @var{mode} is its 1237117395Skanmode, otherwise @var{mode} is VOIDmode. @var{mode} is provided in the 1238117395Skancase where structures of one field would require the structure's mode to 1239117395Skanretain the field's mode. 1240117395Skan 124190075SobrienNormally, this is not needed. See the file @file{c4x.h} for an example 124290075Sobrienof how to use this macro to prevent a structure having a floating point 124390075Sobrienfield from being accessed in an integer mode. 1244132718Skan@end defmac 124590075Sobrien 1246132718Skan@defmac ROUND_TYPE_ALIGN (@var{type}, @var{computed}, @var{specified}) 124790075SobrienDefine this macro as an expression for the alignment of a type (given 124890075Sobrienby @var{type} as a tree node) if the alignment computed in the usual 124990075Sobrienway is @var{computed} and the alignment explicitly specified was 125090075Sobrien@var{specified}. 125190075Sobrien 125290075SobrienThe default is to use @var{specified} if it is larger; otherwise, use 125390075Sobrienthe smaller of @var{computed} and @code{BIGGEST_ALIGNMENT} 1254132718Skan@end defmac 125590075Sobrien 1256132718Skan@defmac MAX_FIXED_MODE_SIZE 125790075SobrienAn integer expression for the size in bits of the largest integer 125890075Sobrienmachine mode that should actually be used. All integer machine modes of 125990075Sobrienthis size or smaller can be used for structures and unions with the 126090075Sobrienappropriate sizes. If this macro is undefined, @code{GET_MODE_BITSIZE 126190075Sobrien(DImode)} is assumed. 1262132718Skan@end defmac 126390075Sobrien 1264132718Skan@defmac STACK_SAVEAREA_MODE (@var{save_level}) 126590075SobrienIf defined, an expression of type @code{enum machine_mode} that 126690075Sobrienspecifies the mode of the save area operand of a 126790075Sobrien@code{save_stack_@var{level}} named pattern (@pxref{Standard Names}). 126890075Sobrien@var{save_level} is one of @code{SAVE_BLOCK}, @code{SAVE_FUNCTION}, or 126990075Sobrien@code{SAVE_NONLOCAL} and selects which of the three named patterns is 127090075Sobrienhaving its mode specified. 127190075Sobrien 127290075SobrienYou need not define this macro if it always returns @code{Pmode}. You 127390075Sobrienwould most commonly define this macro if the 127490075Sobrien@code{save_stack_@var{level}} patterns need to support both a 32- and a 127590075Sobrien64-bit mode. 1276132718Skan@end defmac 127790075Sobrien 1278132718Skan@defmac STACK_SIZE_MODE 127990075SobrienIf defined, an expression of type @code{enum machine_mode} that 128090075Sobrienspecifies the mode of the size increment operand of an 128190075Sobrien@code{allocate_stack} named pattern (@pxref{Standard Names}). 128290075Sobrien 128390075SobrienYou need not define this macro if it always returns @code{word_mode}. 128490075SobrienYou would most commonly define this macro if the @code{allocate_stack} 128590075Sobrienpattern needs to support both a 32- and a 64-bit mode. 1286132718Skan@end defmac 128790075Sobrien 1288132718Skan@defmac TARGET_FLOAT_FORMAT 128990075SobrienA code distinguishing the floating point format of the target machine. 1290132718SkanThere are four defined values: 129190075Sobrien 1292132718Skan@ftable @code 129390075Sobrien@item IEEE_FLOAT_FORMAT 129490075SobrienThis code indicates IEEE floating point. It is the default; there is no 1295132718Skanneed to define @code{TARGET_FLOAT_FORMAT} when the format is IEEE@. 129690075Sobrien 129790075Sobrien@item VAX_FLOAT_FORMAT 1298117395SkanThis code indicates the ``F float'' (for @code{float}) and ``D float'' 1299117395Skanor ``G float'' formats (for @code{double}) used on the VAX and PDP-11@. 130090075Sobrien 130190075Sobrien@item IBM_FLOAT_FORMAT 130290075SobrienThis code indicates the format used on the IBM System/370. 130390075Sobrien 130490075Sobrien@item C4X_FLOAT_FORMAT 130590075SobrienThis code indicates the format used on the TMS320C3x/C4x. 1306132718Skan@end ftable 130790075Sobrien 1308132718SkanIf your target uses a floating point format other than these, you must 1309132718Skandefine a new @var{name}_FLOAT_FORMAT code for it, and add support for 1310132718Skanit to @file{real.c}. 131190075Sobrien 131290075SobrienThe ordering of the component words of floating point values stored in 131390075Sobrienmemory is controlled by @code{FLOAT_WORDS_BIG_ENDIAN}. 1314132718Skan@end defmac 131590075Sobrien 1316132718Skan@defmac MODE_HAS_NANS (@var{mode}) 1317117395SkanWhen defined, this macro should be true if @var{mode} has a NaN 1318117395Skanrepresentation. The compiler assumes that NaNs are not equal to 1319117395Skananything (including themselves) and that addition, subtraction, 1320117395Skanmultiplication and division all return NaNs when one operand is 1321117395SkanNaN@. 1322117395Skan 1323117395SkanBy default, this macro is true if @var{mode} is a floating-point 1324117395Skanmode and the target floating-point format is IEEE@. 1325132718Skan@end defmac 1326117395Skan 1327132718Skan@defmac MODE_HAS_INFINITIES (@var{mode}) 1328117395SkanThis macro should be true if @var{mode} can represent infinity. At 1329117395Skanpresent, the compiler uses this macro to decide whether @samp{x - x} 1330117395Skanis always defined. By default, the macro is true when @var{mode} 1331117395Skanis a floating-point mode and the target format is IEEE@. 1332132718Skan@end defmac 1333117395Skan 1334132718Skan@defmac MODE_HAS_SIGNED_ZEROS (@var{mode}) 1335117395SkanTrue if @var{mode} distinguishes between positive and negative zero. 1336117395SkanThe rules are expected to follow the IEEE standard: 1337117395Skan 1338117395Skan@itemize @bullet 1339117395Skan@item 1340117395Skan@samp{x + x} has the same sign as @samp{x}. 1341117395Skan 1342117395Skan@item 1343117395SkanIf the sum of two values with opposite sign is zero, the result is 1344117395Skanpositive for all rounding modes expect towards @minus{}infinity, for 1345117395Skanwhich it is negative. 1346117395Skan 1347117395Skan@item 1348117395SkanThe sign of a product or quotient is negative when exactly one 1349117395Skanof the operands is negative. 1350117395Skan@end itemize 1351117395Skan 1352117395SkanThe default definition is true if @var{mode} is a floating-point 1353117395Skanmode and the target format is IEEE@. 1354132718Skan@end defmac 1355117395Skan 1356132718Skan@defmac MODE_HAS_SIGN_DEPENDENT_ROUNDING (@var{mode}) 1357117395SkanIf defined, this macro should be true for @var{mode} if it has at 1358117395Skanleast one rounding mode in which @samp{x} and @samp{-x} can be 1359117395Skanrounded to numbers of different magnitude. Two such modes are 1360117395Skantowards @minus{}infinity and towards +infinity. 1361117395Skan 1362117395SkanThe default definition of this macro is true if @var{mode} is 1363117395Skana floating-point mode and the target format is IEEE@. 1364132718Skan@end defmac 1365117395Skan 1366132718Skan@defmac ROUND_TOWARDS_ZERO 1367117395SkanIf defined, this macro should be true if the prevailing rounding 1368117395Skanmode is towards zero. A true value has the following effects: 1369117395Skan 1370117395Skan@itemize @bullet 1371117395Skan@item 1372117395Skan@code{MODE_HAS_SIGN_DEPENDENT_ROUNDING} will be false for all modes. 1373117395Skan 1374117395Skan@item 1375117395Skan@file{libgcc.a}'s floating-point emulator will round towards zero 1376117395Skanrather than towards nearest. 1377117395Skan 1378117395Skan@item 1379117395SkanThe compiler's floating-point emulator will round towards zero after 1380117395Skandoing arithmetic, and when converting from the internal float format to 1381117395Skanthe target format. 1382117395Skan@end itemize 1383117395Skan 1384117395SkanThe macro does not affect the parsing of string literals. When the 1385117395Skanprimary rounding mode is towards zero, library functions like 1386117395Skan@code{strtod} might still round towards nearest, and the compiler's 1387117395Skanparser should behave like the target's @code{strtod} where possible. 1388117395Skan 1389117395SkanNot defining this macro is equivalent to returning zero. 1390132718Skan@end defmac 1391117395Skan 1392132718Skan@defmac LARGEST_EXPONENT_IS_NORMAL (@var{size}) 1393117395SkanThis macro should return true if floats with @var{size} 1394117395Skanbits do not have a NaN or infinity representation, but use the largest 1395117395Skanexponent for normal numbers instead. 1396117395Skan 1397117395SkanDefining this macro to true for @var{size} causes @code{MODE_HAS_NANS} 1398117395Skanand @code{MODE_HAS_INFINITIES} to be false for @var{size}-bit modes. 1399117395SkanIt also affects the way @file{libgcc.a} and @file{real.c} emulate 1400117395Skanfloating-point arithmetic. 1401117395Skan 1402117395SkanThe default definition of this macro returns false for all sizes. 1403132718Skan@end defmac 140490075Sobrien 1405132718Skan@deftypefn {Target Hook} bool TARGET_VECTOR_OPAQUE_P (tree @var{type}) 1406132718SkanThis target hook should return @code{true} a vector is opaque. That 1407132718Skanis, if no cast is needed when copying a vector value of type 1408132718Skan@var{type} into another vector lvalue of the same size. Vector opaque 1409132718Skantypes cannot be initialized. The default is that there are no such 1410132718Skantypes. 1411132718Skan@end deftypefn 1412132718Skan 141396263Sobrien@deftypefn {Target Hook} bool TARGET_MS_BITFIELD_LAYOUT_P (tree @var{record_type}) 141496263SobrienThis target hook returns @code{true} if bit-fields in the given 141596263Sobrien@var{record_type} are to be laid out following the rules of Microsoft 141696263SobrienVisual C/C++, namely: (i) a bit-field won't share the same storage 141796263Sobrienunit with the previous bit-field if their underlying types have 141896263Sobriendifferent sizes, and the bit-field will be aligned to the highest 141996263Sobrienalignment of the underlying types of itself and of the previous 142096263Sobrienbit-field; (ii) a zero-sized bit-field will affect the alignment of 142196263Sobrienthe whole enclosing structure, even if it is unnamed; except that 142296263Sobrien(iii) a zero-sized bit-field will be disregarded unless it follows 1423117395Skananother bit-field of nonzero size. If this hook returns @code{true}, 142496263Sobrienother macros that control bit-field layout are ignored. 1425117395Skan 1426117395SkanWhen a bit-field is inserted into a packed record, the whole size 1427117395Skanof the underlying type is used by one or more same-size adjacent 1428117395Skanbit-fields (that is, if its long:3, 32 bits is used in the record, 1429117395Skanand any additional adjacent long bit-fields are packed into the same 1430169689Skanchunk of 32 bits. However, if the size changes, a new field of that 1431169689Skansize is allocated). In an unpacked record, this is the same as using 1432117395Skanalignment, but not equivalent when packing. 1433117395Skan 1434117395SkanIf both MS bit-fields and @samp{__attribute__((packed))} are used, 1435169689Skanthe latter will take precedence. If @samp{__attribute__((packed))} is 1436117395Skanused on a single field when MS bit-fields are in use, it will take 1437117395Skanprecedence for that field, but the alignment of the rest of the structure 1438117395Skanmay affect its placement. 143996263Sobrien@end deftypefn 144096263Sobrien 1441169689Skan@deftypefn {Target Hook} {bool} TARGET_DECIMAL_FLOAT_SUPPORTED_P (void) 1442169689SkanReturns true if the target supports decimal floating point. 1443169689Skan@end deftypefn 1444169689Skan 1445146895Skan@deftypefn {Target Hook} {const char *} TARGET_MANGLE_FUNDAMENTAL_TYPE (tree @var{type}) 1446146895SkanIf your target defines any fundamental types, define this hook to 1447146895Skanreturn the appropriate encoding for these types as part of a C++ 1448146895Skanmangled name. The @var{type} argument is the tree structure 1449146895Skanrepresenting the type to be mangled. The hook may be applied to trees 1450146895Skanwhich are not target-specific fundamental types; it should return 1451146895Skan@code{NULL} for all such types, as well as arguments it does not 1452146895Skanrecognize. If the return value is not @code{NULL}, it must point to 1453146895Skana statically-allocated string constant. 1454146895Skan 1455146895SkanTarget-specific fundamental types might be new fundamental types or 1456146895Skanqualified versions of ordinary fundamental types. Encode new 1457146895Skanfundamental types as @samp{@w{u @var{n} @var{name}}}, where @var{name} 1458146895Skanis the name used for the type in source code, and @var{n} is the 1459146895Skanlength of @var{name} in decimal. Encode qualified versions of 1460146895Skanordinary types as @samp{@w{U @var{n} @var{name} @var{code}}}, where 1461146895Skan@var{name} is the name used for the type qualifier in source code, 1462146895Skan@var{n} is the length of @var{name} as above, and @var{code} is the 1463146895Skancode used to represent the unqualified version of this type. (See 1464146895Skan@code{write_builtin_type} in @file{cp/mangle.c} for the list of 1465146895Skancodes.) In both cases the spaces are for clarity; do not include any 1466146895Skanspaces in your string. 1467146895Skan 1468146895SkanThe default version of this hook always returns @code{NULL}, which is 1469146895Skanappropriate for a target that does not define any new fundamental 1470146895Skantypes. 1471146895Skan@end deftypefn 1472146895Skan 147390075Sobrien@node Type Layout 147490075Sobrien@section Layout of Source Language Data Types 147590075Sobrien 147690075SobrienThese macros define the sizes and other characteristics of the standard 147790075Sobrienbasic data types used in programs being compiled. Unlike the macros in 147890075Sobrienthe previous section, these apply to specific features of C and related 147990075Sobrienlanguages, rather than to fundamental aspects of storage layout. 148090075Sobrien 1481132718Skan@defmac INT_TYPE_SIZE 148290075SobrienA C expression for the size in bits of the type @code{int} on the 148390075Sobrientarget machine. If you don't define this, the default is one word. 1484132718Skan@end defmac 148590075Sobrien 1486132718Skan@defmac SHORT_TYPE_SIZE 148790075SobrienA C expression for the size in bits of the type @code{short} on the 148890075Sobrientarget machine. If you don't define this, the default is half a word. 148990075Sobrien(If this would be less than one storage unit, it is rounded up to one 149090075Sobrienunit.) 1491132718Skan@end defmac 149290075Sobrien 1493132718Skan@defmac LONG_TYPE_SIZE 149490075SobrienA C expression for the size in bits of the type @code{long} on the 149590075Sobrientarget machine. If you don't define this, the default is one word. 1496132718Skan@end defmac 149790075Sobrien 1498132718Skan@defmac ADA_LONG_TYPE_SIZE 149990075SobrienOn some machines, the size used for the Ada equivalent of the type 1500169689Skan@code{long} by a native Ada compiler differs from that used by C@. In 150190075Sobrienthat situation, define this macro to be a C expression to be used for 150290075Sobrienthe size of that type. If you don't define this, the default is the 150390075Sobrienvalue of @code{LONG_TYPE_SIZE}. 1504132718Skan@end defmac 150590075Sobrien 1506132718Skan@defmac LONG_LONG_TYPE_SIZE 150790075SobrienA C expression for the size in bits of the type @code{long long} on the 150890075Sobrientarget machine. If you don't define this, the default is two 150990075Sobrienwords. If you want to support GNU Ada on your machine, the value of this 151090075Sobrienmacro must be at least 64. 1511132718Skan@end defmac 151290075Sobrien 1513132718Skan@defmac CHAR_TYPE_SIZE 151490075SobrienA C expression for the size in bits of the type @code{char} on the 151590075Sobrientarget machine. If you don't define this, the default is 151690075Sobrien@code{BITS_PER_UNIT}. 1517132718Skan@end defmac 151890075Sobrien 1519132718Skan@defmac BOOL_TYPE_SIZE 152096263SobrienA C expression for the size in bits of the C++ type @code{bool} and 152196263SobrienC99 type @code{_Bool} on the target machine. If you don't define 152296263Sobrienthis, and you probably shouldn't, the default is @code{CHAR_TYPE_SIZE}. 1523132718Skan@end defmac 152490075Sobrien 1525132718Skan@defmac FLOAT_TYPE_SIZE 152690075SobrienA C expression for the size in bits of the type @code{float} on the 152790075Sobrientarget machine. If you don't define this, the default is one word. 1528132718Skan@end defmac 152990075Sobrien 1530132718Skan@defmac DOUBLE_TYPE_SIZE 153190075SobrienA C expression for the size in bits of the type @code{double} on the 153290075Sobrientarget machine. If you don't define this, the default is two 153390075Sobrienwords. 1534132718Skan@end defmac 153590075Sobrien 1536132718Skan@defmac LONG_DOUBLE_TYPE_SIZE 153790075SobrienA C expression for the size in bits of the type @code{long double} on 153890075Sobrienthe target machine. If you don't define this, the default is two 153990075Sobrienwords. 1540132718Skan@end defmac 154190075Sobrien 1542169689Skan@defmac LIBGCC2_LONG_DOUBLE_TYPE_SIZE 1543169689SkanDefine this macro if @code{LONG_DOUBLE_TYPE_SIZE} is not constant or 1544169689Skanif you want routines in @file{libgcc2.a} for a size other than 1545169689Skan@code{LONG_DOUBLE_TYPE_SIZE}. If you don't define this, the 1546169689Skandefault is @code{LONG_DOUBLE_TYPE_SIZE}. 1547132718Skan@end defmac 154890075Sobrien 1549169689Skan@defmac LIBGCC2_HAS_DF_MODE 1550169689SkanDefine this macro if neither @code{LIBGCC2_DOUBLE_TYPE_SIZE} nor 1551169689Skan@code{LIBGCC2_LONG_DOUBLE_TYPE_SIZE} is 1552169689Skan@code{DFmode} but you want @code{DFmode} routines in @file{libgcc2.a} 1553169689Skananyway. If you don't define this and either @code{LIBGCC2_DOUBLE_TYPE_SIZE} 1554169689Skanor @code{LIBGCC2_LONG_DOUBLE_TYPE_SIZE} is 64 then the default is 1, 1555169689Skanotherwise it is 0. 1556169689Skan@end defmac 1557169689Skan 1558169689Skan@defmac LIBGCC2_HAS_XF_MODE 1559169689SkanDefine this macro if @code{LIBGCC2_LONG_DOUBLE_TYPE_SIZE} is not 1560169689Skan@code{XFmode} but you want @code{XFmode} routines in @file{libgcc2.a} 1561169689Skananyway. If you don't define this and @code{LIBGCC2_LONG_DOUBLE_TYPE_SIZE} 1562169689Skanis 80 then the default is 1, otherwise it is 0. 1563169689Skan@end defmac 1564169689Skan 1565169689Skan@defmac LIBGCC2_HAS_TF_MODE 1566169689SkanDefine this macro if @code{LIBGCC2_LONG_DOUBLE_TYPE_SIZE} is not 1567169689Skan@code{TFmode} but you want @code{TFmode} routines in @file{libgcc2.a} 1568169689Skananyway. If you don't define this and @code{LIBGCC2_LONG_DOUBLE_TYPE_SIZE} 1569169689Skanis 128 then the default is 1, otherwise it is 0. 1570169689Skan@end defmac 1571169689Skan 1572169689Skan@defmac SF_SIZE 1573169689Skan@defmacx DF_SIZE 1574169689Skan@defmacx XF_SIZE 1575169689Skan@defmacx TF_SIZE 1576169689SkanDefine these macros to be the size in bits of the mantissa of 1577169689Skan@code{SFmode}, @code{DFmode}, @code{XFmode} and @code{TFmode} values, 1578169689Skanif the defaults in @file{libgcc2.h} are inappropriate. By default, 1579169689Skan@code{FLT_MANT_DIG} is used for @code{SF_SIZE}, @code{LDBL_MANT_DIG} 1580169689Skanfor @code{XF_SIZE} and @code{TF_SIZE}, and @code{DBL_MANT_DIG} or 1581169689Skan@code{LDBL_MANT_DIG} for @code{DF_SIZE} according to whether 1582169689Skan@code{LIBGCC2_DOUBLE_TYPE_SIZE} or 1583169689Skan@code{LIBGCC2_LONG_DOUBLE_TYPE_SIZE} is 64. 1584169689Skan@end defmac 1585169689Skan 1586132718Skan@defmac TARGET_FLT_EVAL_METHOD 1587117395SkanA C expression for the value for @code{FLT_EVAL_METHOD} in @file{float.h}, 1588117395Skanassuming, if applicable, that the floating-point control word is in its 1589117395Skandefault state. If you do not define this macro the value of 1590117395Skan@code{FLT_EVAL_METHOD} will be zero. 1591132718Skan@end defmac 159290075Sobrien 1593132718Skan@defmac WIDEST_HARDWARE_FP_SIZE 159490075SobrienA C expression for the size in bits of the widest floating-point format 159590075Sobriensupported by the hardware. If you define this macro, you must specify a 159690075Sobrienvalue less than or equal to the value of @code{LONG_DOUBLE_TYPE_SIZE}. 159790075SobrienIf you do not define this macro, the value of @code{LONG_DOUBLE_TYPE_SIZE} 159890075Sobrienis the default. 1599132718Skan@end defmac 160090075Sobrien 1601132718Skan@defmac DEFAULT_SIGNED_CHAR 160290075SobrienAn expression whose value is 1 or 0, according to whether the type 160390075Sobrien@code{char} should be signed or unsigned by default. The user can 160490075Sobrienalways override this default with the options @option{-fsigned-char} 160590075Sobrienand @option{-funsigned-char}. 1606132718Skan@end defmac 160790075Sobrien 1608169689Skan@deftypefn {Target Hook} bool TARGET_DEFAULT_SHORT_ENUMS (void) 1609169689SkanThis target hook should return true if the compiler should give an 1610169689Skan@code{enum} type only as many bytes as it takes to represent the range 1611169689Skanof possible values of that type. It should return false if all 161290075Sobrien@code{enum} types should be allocated like @code{int}. 161390075Sobrien 1614169689SkanThe default is to return false. 1615169689Skan@end deftypefn 161690075Sobrien 1617132718Skan@defmac SIZE_TYPE 161890075SobrienA C expression for a string describing the name of the data type to use 161990075Sobrienfor size values. The typedef name @code{size_t} is defined using the 162090075Sobriencontents of the string. 162190075Sobrien 162290075SobrienThe string can contain more than one keyword. If so, separate them with 162390075Sobrienspaces, and write first any length keyword, then @code{unsigned} if 162490075Sobrienappropriate, and finally @code{int}. The string must exactly match one 162590075Sobrienof the data type names defined in the function 162690075Sobrien@code{init_decl_processing} in the file @file{c-decl.c}. You may not 162790075Sobrienomit @code{int} or change the order---that would cause the compiler to 162890075Sobriencrash on startup. 162990075Sobrien 163090075SobrienIf you don't define this macro, the default is @code{"long unsigned 163190075Sobrienint"}. 1632132718Skan@end defmac 163390075Sobrien 1634132718Skan@defmac PTRDIFF_TYPE 163590075SobrienA C expression for a string describing the name of the data type to use 163690075Sobrienfor the result of subtracting two pointers. The typedef name 163790075Sobrien@code{ptrdiff_t} is defined using the contents of the string. See 163890075Sobrien@code{SIZE_TYPE} above for more information. 163990075Sobrien 164090075SobrienIf you don't define this macro, the default is @code{"long int"}. 1641132718Skan@end defmac 164290075Sobrien 1643132718Skan@defmac WCHAR_TYPE 164490075SobrienA C expression for a string describing the name of the data type to use 164590075Sobrienfor wide characters. The typedef name @code{wchar_t} is defined using 164690075Sobrienthe contents of the string. See @code{SIZE_TYPE} above for more 164790075Sobrieninformation. 164890075Sobrien 164990075SobrienIf you don't define this macro, the default is @code{"int"}. 1650132718Skan@end defmac 165190075Sobrien 1652132718Skan@defmac WCHAR_TYPE_SIZE 165390075SobrienA C expression for the size in bits of the data type for wide 165490075Sobriencharacters. This is used in @code{cpp}, which cannot make use of 165590075Sobrien@code{WCHAR_TYPE}. 1656132718Skan@end defmac 165790075Sobrien 1658132718Skan@defmac WINT_TYPE 165990075SobrienA C expression for a string describing the name of the data type to 166090075Sobrienuse for wide characters passed to @code{printf} and returned from 166190075Sobrien@code{getwc}. The typedef name @code{wint_t} is defined using the 166290075Sobriencontents of the string. See @code{SIZE_TYPE} above for more 166390075Sobrieninformation. 166490075Sobrien 166590075SobrienIf you don't define this macro, the default is @code{"unsigned int"}. 1666132718Skan@end defmac 166790075Sobrien 1668132718Skan@defmac INTMAX_TYPE 166990075SobrienA C expression for a string describing the name of the data type that 167090075Sobriencan represent any value of any standard or extended signed integer type. 167190075SobrienThe typedef name @code{intmax_t} is defined using the contents of the 167290075Sobrienstring. See @code{SIZE_TYPE} above for more information. 167390075Sobrien 167490075SobrienIf you don't define this macro, the default is the first of 167590075Sobrien@code{"int"}, @code{"long int"}, or @code{"long long int"} that has as 167690075Sobrienmuch precision as @code{long long int}. 1677132718Skan@end defmac 167890075Sobrien 1679132718Skan@defmac UINTMAX_TYPE 168090075SobrienA C expression for a string describing the name of the data type that 168190075Sobriencan represent any value of any standard or extended unsigned integer 168290075Sobrientype. The typedef name @code{uintmax_t} is defined using the contents 168390075Sobrienof the string. See @code{SIZE_TYPE} above for more information. 168490075Sobrien 168590075SobrienIf you don't define this macro, the default is the first of 168690075Sobrien@code{"unsigned int"}, @code{"long unsigned int"}, or @code{"long long 168790075Sobrienunsigned int"} that has as much precision as @code{long long unsigned 168890075Sobrienint}. 1689132718Skan@end defmac 169090075Sobrien 1691132718Skan@defmac TARGET_PTRMEMFUNC_VBIT_LOCATION 169290075SobrienThe C++ compiler represents a pointer-to-member-function with a struct 169390075Sobrienthat looks like: 169490075Sobrien 1695132718Skan@smallexample 169690075Sobrien struct @{ 169790075Sobrien union @{ 169890075Sobrien void (*fn)(); 169990075Sobrien ptrdiff_t vtable_index; 170090075Sobrien @}; 170190075Sobrien ptrdiff_t delta; 170290075Sobrien @}; 1703132718Skan@end smallexample 170490075Sobrien 170590075Sobrien@noindent 170690075SobrienThe C++ compiler must use one bit to indicate whether the function that 170790075Sobrienwill be called through a pointer-to-member-function is virtual. 170890075SobrienNormally, we assume that the low-order bit of a function pointer must 170990075Sobrienalways be zero. Then, by ensuring that the vtable_index is odd, we can 171090075Sobriendistinguish which variant of the union is in use. But, on some 171190075Sobrienplatforms function pointers can be odd, and so this doesn't work. In 171290075Sobrienthat case, we use the low-order bit of the @code{delta} field, and shift 171390075Sobrienthe remainder of the @code{delta} field to the left. 171490075Sobrien 171590075SobrienGCC will automatically make the right selection about where to store 171690075Sobrienthis bit using the @code{FUNCTION_BOUNDARY} setting for your platform. 171790075SobrienHowever, some platforms such as ARM/Thumb have @code{FUNCTION_BOUNDARY} 171890075Sobrienset such that functions always start at even addresses, but the lowest 171990075Sobrienbit of pointers to functions indicate whether the function at that 172090075Sobrienaddress is in ARM or Thumb mode. If this is the case of your 172190075Sobrienarchitecture, you should define this macro to 172290075Sobrien@code{ptrmemfunc_vbit_in_delta}. 172390075Sobrien 172490075SobrienIn general, you should not have to define this macro. On architectures 172590075Sobrienin which function addresses are always even, according to 172690075Sobrien@code{FUNCTION_BOUNDARY}, GCC will automatically define this macro to 172790075Sobrien@code{ptrmemfunc_vbit_in_pfn}. 1728132718Skan@end defmac 172990075Sobrien 1730132718Skan@defmac TARGET_VTABLE_USES_DESCRIPTORS 173190075SobrienNormally, the C++ compiler uses function pointers in vtables. This 173296263Sobrienmacro allows the target to change to use ``function descriptors'' 173390075Sobrieninstead. Function descriptors are found on targets for whom a 173490075Sobrienfunction pointer is actually a small data structure. Normally the 173596263Sobriendata structure consists of the actual code address plus a data 173690075Sobrienpointer to which the function's data is relative. 173790075Sobrien 173890075SobrienIf vtables are used, the value of this macro should be the number 173990075Sobrienof words that the function descriptor occupies. 1740132718Skan@end defmac 1741117395Skan 1742132718Skan@defmac TARGET_VTABLE_ENTRY_ALIGN 1743117395SkanBy default, the vtable entries are void pointers, the so the alignment 1744117395Skanis the same as pointer alignment. The value of this macro specifies 1745117395Skanthe alignment of the vtable entry in bits. It should be defined only 1746117395Skanwhen special alignment is necessary. */ 1747132718Skan@end defmac 1748117395Skan 1749132718Skan@defmac TARGET_VTABLE_DATA_ENTRY_DISTANCE 1750117395SkanThere are a few non-descriptor entries in the vtable at offsets below 1751117395Skanzero. If these entries must be padded (say, to preserve the alignment 1752117395Skanspecified by @code{TARGET_VTABLE_ENTRY_ALIGN}), set this to the number 1753117395Skanof words in each data entry. 1754132718Skan@end defmac 175590075Sobrien 175690075Sobrien@node Registers 175790075Sobrien@section Register Usage 175890075Sobrien@cindex register usage 175990075Sobrien 176090075SobrienThis section explains how to describe what registers the target machine 176190075Sobrienhas, and how (in general) they can be used. 176290075Sobrien 176390075SobrienThe description of which registers a specific instruction can use is 176490075Sobriendone with register classes; see @ref{Register Classes}. For information 176590075Sobrienon using registers to access a stack frame, see @ref{Frame Registers}. 176690075SobrienFor passing values in registers, see @ref{Register Arguments}. 176790075SobrienFor returning values in registers, see @ref{Scalar Return}. 176890075Sobrien 176990075Sobrien@menu 177090075Sobrien* Register Basics:: Number and kinds of registers. 177190075Sobrien* Allocation Order:: Order in which registers are allocated. 177290075Sobrien* Values in Registers:: What kinds of values each reg can hold. 177390075Sobrien* Leaf Functions:: Renumbering registers for leaf functions. 177490075Sobrien* Stack Registers:: Handling a register stack such as 80387. 177590075Sobrien@end menu 177690075Sobrien 177790075Sobrien@node Register Basics 177890075Sobrien@subsection Basic Characteristics of Registers 177990075Sobrien 178090075Sobrien@c prevent bad page break with this line 178190075SobrienRegisters have various characteristics. 178290075Sobrien 1783132718Skan@defmac FIRST_PSEUDO_REGISTER 178490075SobrienNumber of hardware registers known to the compiler. They receive 178590075Sobriennumbers 0 through @code{FIRST_PSEUDO_REGISTER-1}; thus, the first 178690075Sobrienpseudo register's number really is assigned the number 178790075Sobrien@code{FIRST_PSEUDO_REGISTER}. 1788132718Skan@end defmac 178990075Sobrien 1790132718Skan@defmac FIXED_REGISTERS 179190075Sobrien@cindex fixed register 179290075SobrienAn initializer that says which registers are used for fixed purposes 179390075Sobrienall throughout the compiled code and are therefore not available for 179490075Sobriengeneral allocation. These would include the stack pointer, the frame 179590075Sobrienpointer (except on machines where that can be used as a general 179690075Sobrienregister when no frame pointer is needed), the program counter on 179790075Sobrienmachines where that is considered one of the addressable registers, 179890075Sobrienand any other numbered register with a standard use. 179990075Sobrien 180090075SobrienThis information is expressed as a sequence of numbers, separated by 180190075Sobriencommas and surrounded by braces. The @var{n}th number is 1 if 180290075Sobrienregister @var{n} is fixed, 0 otherwise. 180390075Sobrien 180490075SobrienThe table initialized from this macro, and the table initialized by 180590075Sobrienthe following one, may be overridden at run time either automatically, 180690075Sobrienby the actions of the macro @code{CONDITIONAL_REGISTER_USAGE}, or by 180790075Sobrienthe user with the command options @option{-ffixed-@var{reg}}, 180890075Sobrien@option{-fcall-used-@var{reg}} and @option{-fcall-saved-@var{reg}}. 1809132718Skan@end defmac 181090075Sobrien 1811132718Skan@defmac CALL_USED_REGISTERS 181290075Sobrien@cindex call-used register 181390075Sobrien@cindex call-clobbered register 181490075Sobrien@cindex call-saved register 181590075SobrienLike @code{FIXED_REGISTERS} but has 1 for each register that is 181690075Sobrienclobbered (in general) by function calls as well as for fixed 181790075Sobrienregisters. This macro therefore identifies the registers that are not 181890075Sobrienavailable for general allocation of values that must live across 181990075Sobrienfunction calls. 182090075Sobrien 182190075SobrienIf a register has 0 in @code{CALL_USED_REGISTERS}, the compiler 182290075Sobrienautomatically saves it on function entry and restores it on function 182390075Sobrienexit, if the register is used within the function. 1824132718Skan@end defmac 182590075Sobrien 1826132718Skan@defmac CALL_REALLY_USED_REGISTERS 182790075Sobrien@cindex call-used register 182890075Sobrien@cindex call-clobbered register 182990075Sobrien@cindex call-saved register 183096263SobrienLike @code{CALL_USED_REGISTERS} except this macro doesn't require 183196263Sobrienthat the entire set of @code{FIXED_REGISTERS} be included. 183290075Sobrien(@code{CALL_USED_REGISTERS} must be a superset of @code{FIXED_REGISTERS}). 183396263SobrienThis macro is optional. If not specified, it defaults to the value 183490075Sobrienof @code{CALL_USED_REGISTERS}. 1835132718Skan@end defmac 183690075Sobrien 1837132718Skan@defmac HARD_REGNO_CALL_PART_CLOBBERED (@var{regno}, @var{mode}) 183890075Sobrien@cindex call-used register 183990075Sobrien@cindex call-clobbered register 184090075Sobrien@cindex call-saved register 184190075SobrienA C expression that is nonzero if it is not permissible to store a 184290075Sobrienvalue of mode @var{mode} in hard register number @var{regno} across a 184390075Sobriencall without some part of it being clobbered. For most machines this 184490075Sobrienmacro need not be defined. It is only required for machines that do not 184590075Sobrienpreserve the entire contents of a register across a call. 1846132718Skan@end defmac 184790075Sobrien 184890075Sobrien@findex fixed_regs 184990075Sobrien@findex call_used_regs 1850132718Skan@findex global_regs 1851132718Skan@findex reg_names 1852132718Skan@findex reg_class_contents 1853132718Skan@defmac CONDITIONAL_REGISTER_USAGE 185490075SobrienZero or more C statements that may conditionally modify five variables 185590075Sobrien@code{fixed_regs}, @code{call_used_regs}, @code{global_regs}, 185690075Sobrien@code{reg_names}, and @code{reg_class_contents}, to take into account 185790075Sobrienany dependence of these register sets on target flags. The first three 185890075Sobrienof these are of type @code{char []} (interpreted as Boolean vectors). 185990075Sobrien@code{global_regs} is a @code{const char *[]}, and 186090075Sobrien@code{reg_class_contents} is a @code{HARD_REG_SET}. Before the macro is 186190075Sobriencalled, @code{fixed_regs}, @code{call_used_regs}, 186290075Sobrien@code{reg_class_contents}, and @code{reg_names} have been initialized 186390075Sobrienfrom @code{FIXED_REGISTERS}, @code{CALL_USED_REGISTERS}, 186490075Sobrien@code{REG_CLASS_CONTENTS}, and @code{REGISTER_NAMES}, respectively. 186590075Sobrien@code{global_regs} has been cleared, and any @option{-ffixed-@var{reg}}, 186690075Sobrien@option{-fcall-used-@var{reg}} and @option{-fcall-saved-@var{reg}} 186790075Sobriencommand options have been applied. 186890075Sobrien 186990075SobrienYou need not define this macro if it has no work to do. 187090075Sobrien 187190075Sobrien@cindex disabling certain registers 187290075Sobrien@cindex controlling register usage 187390075SobrienIf the usage of an entire class of registers depends on the target 187490075Sobrienflags, you may indicate this to GCC by using this macro to modify 187590075Sobrien@code{fixed_regs} and @code{call_used_regs} to 1 for each of the 187690075Sobrienregisters in the classes which should not be used by GCC@. Also define 1877132718Skanthe macro @code{REG_CLASS_FROM_LETTER} / @code{REG_CLASS_FROM_CONSTRAINT} 1878132718Skanto return @code{NO_REGS} if it 187990075Sobrienis called with a letter for a class that shouldn't be used. 188090075Sobrien 188190075Sobrien(However, if this class is not included in @code{GENERAL_REGS} and all 188290075Sobrienof the insn patterns whose constraints permit this class are 188390075Sobriencontrolled by target switches, then GCC will automatically avoid using 188490075Sobrienthese registers when the target switches are opposed to them.) 1885132718Skan@end defmac 188690075Sobrien 1887132718Skan@defmac INCOMING_REGNO (@var{out}) 188890075SobrienDefine this macro if the target machine has register windows. This C 188990075Sobrienexpression returns the register number as seen by the called function 189090075Sobriencorresponding to the register number @var{out} as seen by the calling 189190075Sobrienfunction. Return @var{out} if register number @var{out} is not an 189290075Sobrienoutbound register. 1893132718Skan@end defmac 189490075Sobrien 1895132718Skan@defmac OUTGOING_REGNO (@var{in}) 189690075SobrienDefine this macro if the target machine has register windows. This C 189790075Sobrienexpression returns the register number as seen by the calling function 189890075Sobriencorresponding to the register number @var{in} as seen by the called 189990075Sobrienfunction. Return @var{in} if register number @var{in} is not an inbound 190090075Sobrienregister. 1901132718Skan@end defmac 190290075Sobrien 1903132718Skan@defmac LOCAL_REGNO (@var{regno}) 190490075SobrienDefine this macro if the target machine has register windows. This C 190590075Sobrienexpression returns true if the register is call-saved but is in the 190690075Sobrienregister window. Unlike most call-saved registers, such registers 190790075Sobrienneed not be explicitly restored on function exit or during non-local 190890075Sobriengotos. 1909132718Skan@end defmac 191090075Sobrien 1911132718Skan@defmac PC_REGNUM 191290075SobrienIf the program counter has a register number, define this as that 191390075Sobrienregister number. Otherwise, do not define it. 1914132718Skan@end defmac 191590075Sobrien 191690075Sobrien@node Allocation Order 191790075Sobrien@subsection Order of Allocation of Registers 191890075Sobrien@cindex order of register allocation 191990075Sobrien@cindex register allocation order 192090075Sobrien 192190075Sobrien@c prevent bad page break with this line 192290075SobrienRegisters are allocated in order. 192390075Sobrien 1924132718Skan@defmac REG_ALLOC_ORDER 192590075SobrienIf defined, an initializer for a vector of integers, containing the 192690075Sobriennumbers of hard registers in the order in which GCC should prefer 192790075Sobriento use them (from most preferred to least). 192890075Sobrien 192990075SobrienIf this macro is not defined, registers are used lowest numbered first 193090075Sobrien(all else being equal). 193190075Sobrien 193290075SobrienOne use of this macro is on machines where the highest numbered 193390075Sobrienregisters must always be saved and the save-multiple-registers 193490075Sobrieninstruction supports only sequences of consecutive registers. On such 193590075Sobrienmachines, define @code{REG_ALLOC_ORDER} to be an initializer that lists 193690075Sobrienthe highest numbered allocable register first. 1937132718Skan@end defmac 193890075Sobrien 1939132718Skan@defmac ORDER_REGS_FOR_LOCAL_ALLOC 194090075SobrienA C statement (sans semicolon) to choose the order in which to allocate 194190075Sobrienhard registers for pseudo-registers local to a basic block. 194290075Sobrien 194390075SobrienStore the desired register order in the array @code{reg_alloc_order}. 194490075SobrienElement 0 should be the register to allocate first; element 1, the next 194590075Sobrienregister; and so on. 194690075Sobrien 194790075SobrienThe macro body should not assume anything about the contents of 194890075Sobrien@code{reg_alloc_order} before execution of the macro. 194990075Sobrien 195090075SobrienOn most machines, it is not necessary to define this macro. 1951132718Skan@end defmac 195290075Sobrien 195390075Sobrien@node Values in Registers 195490075Sobrien@subsection How Values Fit in Registers 195590075Sobrien 195690075SobrienThis section discusses the macros that describe which kinds of values 195790075Sobrien(specifically, which machine modes) each register can hold, and how many 195890075Sobrienconsecutive registers are needed for a given mode. 195990075Sobrien 1960132718Skan@defmac HARD_REGNO_NREGS (@var{regno}, @var{mode}) 196190075SobrienA C expression for the number of consecutive hard registers, starting 196290075Sobrienat register number @var{regno}, required to hold a value of mode 196390075Sobrien@var{mode}. 196490075Sobrien 196590075SobrienOn a machine where all registers are exactly one word, a suitable 196690075Sobriendefinition of this macro is 196790075Sobrien 196890075Sobrien@smallexample 196990075Sobrien#define HARD_REGNO_NREGS(REGNO, MODE) \ 197090075Sobrien ((GET_MODE_SIZE (MODE) + UNITS_PER_WORD - 1) \ 197190075Sobrien / UNITS_PER_WORD) 197290075Sobrien@end smallexample 1973132718Skan@end defmac 197490075Sobrien 1975169689Skan@defmac HARD_REGNO_NREGS_HAS_PADDING (@var{regno}, @var{mode}) 1976169689SkanA C expression that is nonzero if a value of mode @var{mode}, stored 1977169689Skanin memory, ends with padding that causes it to take up more space than 1978169689Skanin registers starting at register number @var{regno} (as determined by 1979169689Skanmultiplying GCC's notion of the size of the register when containing 1980169689Skanthis mode by the number of registers returned by 1981169689Skan@code{HARD_REGNO_NREGS}). By default this is zero. 1982169689Skan 1983169689SkanFor example, if a floating-point value is stored in three 32-bit 1984169689Skanregisters but takes up 128 bits in memory, then this would be 1985169689Skannonzero. 1986169689Skan 1987169689SkanThis macros only needs to be defined if there are cases where 1988169689Skan@code{subreg_regno_offset} and @code{subreg_offset_representable_p} 1989169689Skanwould otherwise wrongly determine that a @code{subreg} can be 1990169689Skanrepresented by an offset to the register number, when in fact such a 1991169689Skan@code{subreg} would contain some of the padding not stored in 1992169689Skanregisters and so not be representable. 1993169689Skan@end defmac 1994169689Skan 1995169689Skan@defmac HARD_REGNO_NREGS_WITH_PADDING (@var{regno}, @var{mode}) 1996169689SkanFor values of @var{regno} and @var{mode} for which 1997169689Skan@code{HARD_REGNO_NREGS_HAS_PADDING} returns nonzero, a C expression 1998169689Skanreturning the greater number of registers required to hold the value 1999169689Skanincluding any padding. In the example above, the value would be four. 2000169689Skan@end defmac 2001169689Skan 2002132718Skan@defmac REGMODE_NATURAL_SIZE (@var{mode}) 2003132718SkanDefine this macro if the natural size of registers that hold values 2004132718Skanof mode @var{mode} is not the word size. It is a C expression that 2005132718Skanshould give the natural size in bytes for the specified mode. It is 2006132718Skanused by the register allocator to try to optimize its results. This 2007132718Skanhappens for example on SPARC 64-bit where the natural size of 2008132718Skanfloating-point registers is still 32-bit. 2009132718Skan@end defmac 2010132718Skan 2011132718Skan@defmac HARD_REGNO_MODE_OK (@var{regno}, @var{mode}) 201290075SobrienA C expression that is nonzero if it is permissible to store a value 201390075Sobrienof mode @var{mode} in hard register number @var{regno} (or in several 201490075Sobrienregisters starting with that one). For a machine where all registers 201590075Sobrienare equivalent, a suitable definition is 201690075Sobrien 201790075Sobrien@smallexample 201890075Sobrien#define HARD_REGNO_MODE_OK(REGNO, MODE) 1 201990075Sobrien@end smallexample 202090075Sobrien 202190075SobrienYou need not include code to check for the numbers of fixed registers, 202290075Sobrienbecause the allocation mechanism considers them to be always occupied. 202390075Sobrien 202490075Sobrien@cindex register pairs 202590075SobrienOn some machines, double-precision values must be kept in even/odd 202690075Sobrienregister pairs. You can implement that by defining this macro to reject 202790075Sobrienodd register numbers for such modes. 202890075Sobrien 202990075SobrienThe minimum requirement for a mode to be OK in a register is that the 203090075Sobrien@samp{mov@var{mode}} instruction pattern support moves between the 203190075Sobrienregister and other hard register in the same class and that moving a 203290075Sobrienvalue into the register and back out not alter it. 203390075Sobrien 203490075SobrienSince the same instruction used to move @code{word_mode} will work for 203590075Sobrienall narrower integer modes, it is not necessary on any machine for 203690075Sobrien@code{HARD_REGNO_MODE_OK} to distinguish between these modes, provided 203790075Sobrienyou define patterns @samp{movhi}, etc., to take advantage of this. This 203890075Sobrienis useful because of the interaction between @code{HARD_REGNO_MODE_OK} 203990075Sobrienand @code{MODES_TIEABLE_P}; it is very desirable for all integer modes 204090075Sobriento be tieable. 204190075Sobrien 204290075SobrienMany machines have special registers for floating point arithmetic. 204390075SobrienOften people assume that floating point machine modes are allowed only 204490075Sobrienin floating point registers. This is not true. Any registers that 204590075Sobriencan hold integers can safely @emph{hold} a floating point machine 204690075Sobrienmode, whether or not floating arithmetic can be done on it in those 204790075Sobrienregisters. Integer move instructions can be used to move the values. 204890075Sobrien 204990075SobrienOn some machines, though, the converse is true: fixed-point machine 205090075Sobrienmodes may not go in floating registers. This is true if the floating 205190075Sobrienregisters normalize any value stored in them, because storing a 205290075Sobriennon-floating value there would garble it. In this case, 205390075Sobrien@code{HARD_REGNO_MODE_OK} should reject fixed-point machine modes in 205490075Sobrienfloating registers. But if the floating registers do not automatically 205590075Sobriennormalize, if you can store any bit pattern in one and retrieve it 205690075Sobrienunchanged without a trap, then any machine mode may go in a floating 205790075Sobrienregister, so you can define this macro to say so. 205890075Sobrien 205990075SobrienThe primary significance of special floating registers is rather that 206090075Sobrienthey are the registers acceptable in floating point arithmetic 206190075Sobrieninstructions. However, this is of no concern to 206290075Sobrien@code{HARD_REGNO_MODE_OK}. You handle it by writing the proper 206390075Sobrienconstraints for those instructions. 206490075Sobrien 206590075SobrienOn some machines, the floating registers are especially slow to access, 206690075Sobrienso that it is better to store a value in a stack frame than in such a 206790075Sobrienregister if floating point arithmetic is not being done. As long as the 206890075Sobrienfloating registers are not in class @code{GENERAL_REGS}, they will not 206990075Sobrienbe used unless some pattern's constraint asks for one. 2070132718Skan@end defmac 207190075Sobrien 2072169689Skan@defmac HARD_REGNO_RENAME_OK (@var{from}, @var{to}) 2073169689SkanA C expression that is nonzero if it is OK to rename a hard register 2074169689Skan@var{from} to another hard register @var{to}. 2075169689Skan 2076169689SkanOne common use of this macro is to prevent renaming of a register to 2077169689Skananother register that is not saved by a prologue in an interrupt 2078169689Skanhandler. 2079169689Skan 2080169689SkanThe default is always nonzero. 2081169689Skan@end defmac 2082169689Skan 2083132718Skan@defmac MODES_TIEABLE_P (@var{mode1}, @var{mode2}) 208490075SobrienA C expression that is nonzero if a value of mode 208590075Sobrien@var{mode1} is accessible in mode @var{mode2} without copying. 208690075Sobrien 208790075SobrienIf @code{HARD_REGNO_MODE_OK (@var{r}, @var{mode1})} and 208890075Sobrien@code{HARD_REGNO_MODE_OK (@var{r}, @var{mode2})} are always the same for 208990075Sobrienany @var{r}, then @code{MODES_TIEABLE_P (@var{mode1}, @var{mode2})} 209090075Sobrienshould be nonzero. If they differ for any @var{r}, you should define 209190075Sobrienthis macro to return zero unless some other mechanism ensures the 209290075Sobrienaccessibility of the value in a narrower mode. 209390075Sobrien 209490075SobrienYou should define this macro to return nonzero in as many cases as 209590075Sobrienpossible since doing so will allow GCC to perform better register 209690075Sobrienallocation. 2097132718Skan@end defmac 209890075Sobrien 2099132718Skan@defmac AVOID_CCMODE_COPIES 210090075SobrienDefine this macro if the compiler should avoid copies to/from @code{CCmode} 210190075Sobrienregisters. You should only define this macro if support for copying to/from 210290075Sobrien@code{CCmode} is incomplete. 2103132718Skan@end defmac 210490075Sobrien 210590075Sobrien@node Leaf Functions 210690075Sobrien@subsection Handling Leaf Functions 210790075Sobrien 210890075Sobrien@cindex leaf functions 210990075Sobrien@cindex functions, leaf 211090075SobrienOn some machines, a leaf function (i.e., one which makes no calls) can run 211190075Sobrienmore efficiently if it does not make its own register window. Often this 211290075Sobrienmeans it is required to receive its arguments in the registers where they 211390075Sobrienare passed by the caller, instead of the registers where they would 211490075Sobriennormally arrive. 211590075Sobrien 211690075SobrienThe special treatment for leaf functions generally applies only when 211790075Sobrienother conditions are met; for example, often they may use only those 211890075Sobrienregisters for its own variables and temporaries. We use the term ``leaf 211990075Sobrienfunction'' to mean a function that is suitable for this special 212090075Sobrienhandling, so that functions with no calls are not necessarily ``leaf 212190075Sobrienfunctions''. 212290075Sobrien 212390075SobrienGCC assigns register numbers before it knows whether the function is 212490075Sobriensuitable for leaf function treatment. So it needs to renumber the 212590075Sobrienregisters in order to output a leaf function. The following macros 212690075Sobrienaccomplish this. 212790075Sobrien 2128132718Skan@defmac LEAF_REGISTERS 212990075SobrienName of a char vector, indexed by hard register number, which 213090075Sobriencontains 1 for a register that is allowable in a candidate for leaf 213190075Sobrienfunction treatment. 213290075Sobrien 213390075SobrienIf leaf function treatment involves renumbering the registers, then the 213490075Sobrienregisters marked here should be the ones before renumbering---those that 213590075SobrienGCC would ordinarily allocate. The registers which will actually be 213690075Sobrienused in the assembler code, after renumbering, should not be marked with 1 213790075Sobrienin this vector. 213890075Sobrien 213990075SobrienDefine this macro only if the target machine offers a way to optimize 214090075Sobrienthe treatment of leaf functions. 2141132718Skan@end defmac 214290075Sobrien 2143132718Skan@defmac LEAF_REG_REMAP (@var{regno}) 214490075SobrienA C expression whose value is the register number to which @var{regno} 214590075Sobrienshould be renumbered, when a function is treated as a leaf function. 214690075Sobrien 214790075SobrienIf @var{regno} is a register number which should not appear in a leaf 214890075Sobrienfunction before renumbering, then the expression should yield @minus{}1, which 214990075Sobrienwill cause the compiler to abort. 215090075Sobrien 215190075SobrienDefine this macro only if the target machine offers a way to optimize the 215290075Sobrientreatment of leaf functions, and registers need to be renumbered to do 215390075Sobrienthis. 2154132718Skan@end defmac 215590075Sobrien 215690075Sobrien@findex current_function_is_leaf 215790075Sobrien@findex current_function_uses_only_leaf_regs 215890075Sobrien@code{TARGET_ASM_FUNCTION_PROLOGUE} and 215990075Sobrien@code{TARGET_ASM_FUNCTION_EPILOGUE} must usually treat leaf functions 216090075Sobrienspecially. They can test the C variable @code{current_function_is_leaf} 216190075Sobrienwhich is nonzero for leaf functions. @code{current_function_is_leaf} is 216290075Sobrienset prior to local register allocation and is valid for the remaining 216390075Sobriencompiler passes. They can also test the C variable 216490075Sobrien@code{current_function_uses_only_leaf_regs} which is nonzero for leaf 216590075Sobrienfunctions which only use leaf registers. 2166169689Skan@code{current_function_uses_only_leaf_regs} is valid after all passes 2167169689Skanthat modify the instructions have been run and is only useful if 2168169689Skan@code{LEAF_REGISTERS} is defined. 216990075Sobrien@c changed this to fix overfull. ALSO: why the "it" at the beginning 217090075Sobrien@c of the next paragraph?! --mew 2feb93 217190075Sobrien 217290075Sobrien@node Stack Registers 217390075Sobrien@subsection Registers That Form a Stack 217490075Sobrien 217590075SobrienThere are special features to handle computers where some of the 2176132718Skan``registers'' form a stack. Stack registers are normally written by 2177132718Skanpushing onto the stack, and are numbered relative to the top of the 2178132718Skanstack. 217990075Sobrien 218090075SobrienCurrently, GCC can only handle one group of stack-like registers, and 2181132718Skanthey must be consecutively numbered. Furthermore, the existing 2182132718Skansupport for stack-like registers is specific to the 80387 floating 2183132718Skanpoint coprocessor. If you have a new architecture that uses 2184132718Skanstack-like registers, you will need to do substantial work on 2185132718Skan@file{reg-stack.c} and write your machine description to cooperate 2186132718Skanwith it, as well as defining these macros. 218790075Sobrien 2188132718Skan@defmac STACK_REGS 218990075SobrienDefine this if the machine has any stack-like registers. 2190132718Skan@end defmac 219190075Sobrien 2192132718Skan@defmac FIRST_STACK_REG 219390075SobrienThe number of the first stack-like register. This one is the top 219490075Sobrienof the stack. 2195132718Skan@end defmac 219690075Sobrien 2197132718Skan@defmac LAST_STACK_REG 219890075SobrienThe number of the last stack-like register. This one is the bottom of 219990075Sobrienthe stack. 2200132718Skan@end defmac 220190075Sobrien 220290075Sobrien@node Register Classes 220390075Sobrien@section Register Classes 220490075Sobrien@cindex register class definitions 220590075Sobrien@cindex class definitions, register 220690075Sobrien 220790075SobrienOn many machines, the numbered registers are not all equivalent. 220890075SobrienFor example, certain registers may not be allowed for indexed addressing; 220990075Sobriencertain registers may not be allowed in some instructions. These machine 221090075Sobrienrestrictions are described to the compiler using @dfn{register classes}. 221190075Sobrien 221290075SobrienYou define a number of register classes, giving each one a name and saying 221390075Sobrienwhich of the registers belong to it. Then you can specify register classes 221490075Sobrienthat are allowed as operands to particular instruction patterns. 221590075Sobrien 221690075Sobrien@findex ALL_REGS 221790075Sobrien@findex NO_REGS 221890075SobrienIn general, each register will belong to several classes. In fact, one 221990075Sobrienclass must be named @code{ALL_REGS} and contain all the registers. Another 222090075Sobrienclass must be named @code{NO_REGS} and contain no registers. Often the 222190075Sobrienunion of two classes will be another class; however, this is not required. 222290075Sobrien 222390075Sobrien@findex GENERAL_REGS 222490075SobrienOne of the classes must be named @code{GENERAL_REGS}. There is nothing 222590075Sobrienterribly special about the name, but the operand constraint letters 222690075Sobrien@samp{r} and @samp{g} specify this class. If @code{GENERAL_REGS} is 222790075Sobrienthe same as @code{ALL_REGS}, just define it as a macro which expands 222890075Sobriento @code{ALL_REGS}. 222990075Sobrien 223090075SobrienOrder the classes so that if class @var{x} is contained in class @var{y} 223190075Sobrienthen @var{x} has a lower class number than @var{y}. 223290075Sobrien 223390075SobrienThe way classes other than @code{GENERAL_REGS} are specified in operand 223490075Sobrienconstraints is through machine-dependent operand constraint letters. 223590075SobrienYou can define such letters to correspond to various classes, then use 223690075Sobrienthem in operand constraints. 223790075Sobrien 223890075SobrienYou should define a class for the union of two classes whenever some 223990075Sobrieninstruction allows both classes. For example, if an instruction allows 224090075Sobrieneither a floating point (coprocessor) register or a general register for a 224190075Sobriencertain operand, you should define a class @code{FLOAT_OR_GENERAL_REGS} 224290075Sobrienwhich includes both of them. Otherwise you will get suboptimal code. 224390075Sobrien 224490075SobrienYou must also specify certain redundant information about the register 224590075Sobrienclasses: for each class, which classes contain it and which ones are 224690075Sobriencontained in it; for each pair of classes, the largest class contained 224790075Sobrienin their union. 224890075Sobrien 224990075SobrienWhen a value occupying several consecutive registers is expected in a 225090075Sobriencertain class, all the registers used must belong to that class. 225190075SobrienTherefore, register classes cannot be used to enforce a requirement for 225290075Sobriena register pair to start with an even-numbered register. The way to 225390075Sobrienspecify this requirement is with @code{HARD_REGNO_MODE_OK}. 225490075Sobrien 225590075SobrienRegister classes used for input-operands of bitwise-and or shift 225690075Sobrieninstructions have a special requirement: each such class must have, for 225790075Sobrieneach fixed-point machine mode, a subclass whose registers can transfer that 225890075Sobrienmode to or from memory. For example, on some machines, the operations for 225990075Sobriensingle-byte values (@code{QImode}) are limited to certain registers. When 226090075Sobrienthis is so, each register class that is used in a bitwise-and or shift 226190075Sobrieninstruction must have a subclass consisting of registers from which 226290075Sobriensingle-byte values can be loaded or stored. This is so that 226390075Sobrien@code{PREFERRED_RELOAD_CLASS} can always have a possible value to return. 226490075Sobrien 2265132718Skan@deftp {Data type} {enum reg_class} 2266132718SkanAn enumerated type that must be defined with all the register class names 2267132718Skanas enumerated values. @code{NO_REGS} must be first. @code{ALL_REGS} 2268132718Skanmust be the last register class, followed by one more enumerated value, 226990075Sobrien@code{LIM_REG_CLASSES}, which is not a register class but rather 227090075Sobrientells how many classes there are. 227190075Sobrien 227290075SobrienEach register class has a number, which is the value of casting 227390075Sobrienthe class name to type @code{int}. The number serves as an index 227490075Sobrienin many of the tables described below. 2275132718Skan@end deftp 227690075Sobrien 2277132718Skan@defmac N_REG_CLASSES 227890075SobrienThe number of distinct register classes, defined as follows: 227990075Sobrien 2280132718Skan@smallexample 228190075Sobrien#define N_REG_CLASSES (int) LIM_REG_CLASSES 2282132718Skan@end smallexample 2283132718Skan@end defmac 228490075Sobrien 2285132718Skan@defmac REG_CLASS_NAMES 228690075SobrienAn initializer containing the names of the register classes as C string 228790075Sobrienconstants. These names are used in writing some of the debugging dumps. 2288132718Skan@end defmac 228990075Sobrien 2290132718Skan@defmac REG_CLASS_CONTENTS 229190075SobrienAn initializer containing the contents of the register classes, as integers 229290075Sobrienwhich are bit masks. The @var{n}th integer specifies the contents of class 229390075Sobrien@var{n}. The way the integer @var{mask} is interpreted is that 229490075Sobrienregister @var{r} is in the class if @code{@var{mask} & (1 << @var{r})} is 1. 229590075Sobrien 229690075SobrienWhen the machine has more than 32 registers, an integer does not suffice. 229790075SobrienThen the integers are replaced by sub-initializers, braced groupings containing 229890075Sobrienseveral integers. Each sub-initializer must be suitable as an initializer 229990075Sobrienfor the type @code{HARD_REG_SET} which is defined in @file{hard-reg-set.h}. 230090075SobrienIn this situation, the first integer in each sub-initializer corresponds to 230190075Sobrienregisters 0 through 31, the second integer to registers 32 through 63, and 230290075Sobrienso on. 2303132718Skan@end defmac 230490075Sobrien 2305132718Skan@defmac REGNO_REG_CLASS (@var{regno}) 230690075SobrienA C expression whose value is a register class containing hard register 230790075Sobrien@var{regno}. In general there is more than one such class; choose a class 230890075Sobrienwhich is @dfn{minimal}, meaning that no smaller class also contains the 230990075Sobrienregister. 2310132718Skan@end defmac 231190075Sobrien 2312132718Skan@defmac BASE_REG_CLASS 231390075SobrienA macro whose definition is the name of the class to which a valid 231490075Sobrienbase register must belong. A base register is one used in an address 231590075Sobrienwhich is the register value plus a displacement. 2316132718Skan@end defmac 231790075Sobrien 2318132718Skan@defmac MODE_BASE_REG_CLASS (@var{mode}) 231990075SobrienThis is a variation of the @code{BASE_REG_CLASS} macro which allows 2320117395Skanthe selection of a base register in a mode dependent manner. If 232190075Sobrien@var{mode} is VOIDmode then it should return the same value as 232290075Sobrien@code{BASE_REG_CLASS}. 2323132718Skan@end defmac 232490075Sobrien 2325169689Skan@defmac MODE_BASE_REG_REG_CLASS (@var{mode}) 2326169689SkanA C expression whose value is the register class to which a valid 2327169689Skanbase register must belong in order to be used in a base plus index 2328169689Skanregister address. You should define this macro if base plus index 2329169689Skanaddresses have different requirements than other base register uses. 2330169689Skan@end defmac 2331169689Skan 2332169689Skan@defmac MODE_CODE_BASE_REG_CLASS (@var{mode}, @var{outer_code}, @var{index_code}) 2333169689SkanA C expression whose value is the register class to which a valid 2334169689Skanbase register must belong. @var{outer_code} and @var{index_code} define the 2335169689Skancontext in which the base register occurs. @var{outer_code} is the code of 2336169689Skanthe immediately enclosing expression (@code{MEM} for the top level of an 2337169689Skanaddress, @code{ADDRESS} for something that occurs in an 2338169689Skan@code{address_operand}). @var{index_code} is the code of the corresponding 2339169689Skanindex expression if @var{outer_code} is @code{PLUS}; @code{SCRATCH} otherwise. 2340169689Skan@end defmac 2341169689Skan 2342132718Skan@defmac INDEX_REG_CLASS 234390075SobrienA macro whose definition is the name of the class to which a valid 234490075Sobrienindex register must belong. An index register is one used in an 234590075Sobrienaddress where its value is either multiplied by a scale factor or 234690075Sobrienadded to another register (as well as added to a displacement). 2347132718Skan@end defmac 234890075Sobrien 2349132718Skan@defmac REGNO_OK_FOR_BASE_P (@var{num}) 235090075SobrienA C expression which is nonzero if register number @var{num} is 235190075Sobriensuitable for use as a base register in operand addresses. It may be 235290075Sobrieneither a suitable hard register or a pseudo register that has been 235390075Sobrienallocated such a hard register. 2354132718Skan@end defmac 235590075Sobrien 2356132718Skan@defmac REGNO_MODE_OK_FOR_BASE_P (@var{num}, @var{mode}) 235790075SobrienA C expression that is just like @code{REGNO_OK_FOR_BASE_P}, except that 235890075Sobrienthat expression may examine the mode of the memory reference in 235990075Sobrien@var{mode}. You should define this macro if the mode of the memory 236090075Sobrienreference affects whether a register may be used as a base register. If 236190075Sobrienyou define this macro, the compiler will use it instead of 2362169689Skan@code{REGNO_OK_FOR_BASE_P}. The mode may be @code{VOIDmode} for addresses 2363169689Skanthat appear outside a @code{MEM}, i.e. as an @code{address_operand}. 2364169689Skan 2365132718Skan@end defmac 236690075Sobrien 2367169689Skan@defmac REGNO_MODE_OK_FOR_REG_BASE_P (@var{num}, @var{mode}) 2368169689SkanA C expression which is nonzero if register number @var{num} is suitable for 2369169689Skanuse as a base register in base plus index operand addresses, accessing 2370169689Skanmemory in mode @var{mode}. It may be either a suitable hard register or a 2371169689Skanpseudo register that has been allocated such a hard register. You should 2372169689Skandefine this macro if base plus index addresses have different requirements 2373169689Skanthan other base register uses. 2374169689Skan 2375169689SkanUse of this macro is deprecated; please use the more general 2376169689Skan@code{REGNO_MODE_CODE_OK_FOR_BASE_P}. 2377169689Skan@end defmac 2378169689Skan 2379169689Skan@defmac REGNO_MODE_CODE_OK_FOR_BASE_P (@var{num}, @var{mode}, @var{outer_code}, @var{index_code}) 2380169689SkanA C expression that is just like @code{REGNO_MODE_OK_FOR_BASE_P}, except that 2381169689Skanthat expression may examine the context in which the register appears in the 2382169689Skanmemory reference. @var{outer_code} is the code of the immediately enclosing 2383169689Skanexpression (@code{MEM} if at the top level of the address, @code{ADDRESS} for 2384169689Skansomething that occurs in an @code{address_operand}). @var{index_code} is the 2385169689Skancode of the corresponding index expression if @var{outer_code} is @code{PLUS}; 2386169689Skan@code{SCRATCH} otherwise. The mode may be @code{VOIDmode} for addresses 2387169689Skanthat appear outside a @code{MEM}, i.e. as an @code{address_operand}. 2388169689Skan@end defmac 2389169689Skan 2390132718Skan@defmac REGNO_OK_FOR_INDEX_P (@var{num}) 239190075SobrienA C expression which is nonzero if register number @var{num} is 239290075Sobriensuitable for use as an index register in operand addresses. It may be 239390075Sobrieneither a suitable hard register or a pseudo register that has been 239490075Sobrienallocated such a hard register. 239590075Sobrien 239690075SobrienThe difference between an index register and a base register is that 239790075Sobrienthe index register may be scaled. If an address involves the sum of 239890075Sobrientwo registers, neither one of them scaled, then either one may be 239990075Sobrienlabeled the ``base'' and the other the ``index''; but whichever 240090075Sobrienlabeling is used must fit the machine's constraints of which registers 240190075Sobrienmay serve in each capacity. The compiler will try both labelings, 240290075Sobrienlooking for one that is valid, and will reload one or both registers 240390075Sobrienonly if neither labeling works. 2404132718Skan@end defmac 240590075Sobrien 2406132718Skan@defmac PREFERRED_RELOAD_CLASS (@var{x}, @var{class}) 240790075SobrienA C expression that places additional restrictions on the register class 240890075Sobriento use when it is necessary to copy value @var{x} into a register in class 240990075Sobrien@var{class}. The value is a register class; perhaps @var{class}, or perhaps 241090075Sobrienanother, smaller class. On many machines, the following definition is 241190075Sobriensafe: 241290075Sobrien 2413132718Skan@smallexample 241490075Sobrien#define PREFERRED_RELOAD_CLASS(X,CLASS) CLASS 2415132718Skan@end smallexample 241690075Sobrien 241790075SobrienSometimes returning a more restrictive class makes better code. For 241890075Sobrienexample, on the 68000, when @var{x} is an integer constant that is in range 241990075Sobrienfor a @samp{moveq} instruction, the value of this macro is always 242090075Sobrien@code{DATA_REGS} as long as @var{class} includes the data registers. 242190075SobrienRequiring a data register guarantees that a @samp{moveq} will be used. 242290075Sobrien 2423132718SkanOne case where @code{PREFERRED_RELOAD_CLASS} must not return 2424132718Skan@var{class} is if @var{x} is a legitimate constant which cannot be 2425132718Skanloaded into some register class. By returning @code{NO_REGS} you can 2426132718Skanforce @var{x} into a memory location. For example, rs6000 can load 2427132718Skanimmediate values into general-purpose registers, but does not have an 2428132718Skaninstruction for loading an immediate value into a floating-point 2429132718Skanregister, so @code{PREFERRED_RELOAD_CLASS} returns @code{NO_REGS} when 2430132718Skan@var{x} is a floating-point constant. If the constant can't be loaded 2431132718Skaninto any kind of register, code generation will be better if 2432132718Skan@code{LEGITIMATE_CONSTANT_P} makes the constant illegitimate instead 2433132718Skanof using @code{PREFERRED_RELOAD_CLASS}. 2434169689Skan 2435169689SkanIf an insn has pseudos in it after register allocation, reload will go 2436169689Skanthrough the alternatives and call repeatedly @code{PREFERRED_RELOAD_CLASS} 2437169689Skanto find the best one. Returning @code{NO_REGS}, in this case, makes 2438169689Skanreload add a @code{!} in front of the constraint: the x86 back-end uses 2439169689Skanthis feature to discourage usage of 387 registers when math is done in 2440169689Skanthe SSE registers (and vice versa). 2441132718Skan@end defmac 244290075Sobrien 2443132718Skan@defmac PREFERRED_OUTPUT_RELOAD_CLASS (@var{x}, @var{class}) 244490075SobrienLike @code{PREFERRED_RELOAD_CLASS}, but for output reloads instead of 244590075Sobrieninput reloads. If you don't define this macro, the default is to use 244690075Sobrien@var{class}, unchanged. 2447169689Skan 2448169689SkanYou can also use @code{PREFERRED_OUTPUT_RELOAD_CLASS} to discourage 2449169689Skanreload from using some alternatives, like @code{PREFERRED_RELOAD_CLASS}. 2450132718Skan@end defmac 245190075Sobrien 2452132718Skan@defmac LIMIT_RELOAD_CLASS (@var{mode}, @var{class}) 245390075SobrienA C expression that places additional restrictions on the register class 245490075Sobriento use when it is necessary to be able to hold a value of mode 245590075Sobrien@var{mode} in a reload register for which class @var{class} would 245690075Sobrienordinarily be used. 245790075Sobrien 245890075SobrienUnlike @code{PREFERRED_RELOAD_CLASS}, this macro should be used when 245990075Sobrienthere are certain modes that simply can't go in certain reload classes. 246090075Sobrien 246190075SobrienThe value is a register class; perhaps @var{class}, or perhaps another, 246290075Sobriensmaller class. 246390075Sobrien 246490075SobrienDon't define this macro unless the target machine has limitations which 246590075Sobrienrequire the macro to do something nontrivial. 2466132718Skan@end defmac 246790075Sobrien 2468169689Skan@deftypefn {Target Hook} enum reg_class TARGET_SECONDARY_RELOAD (bool @var{in_p}, rtx @var{x}, enum reg_class @var{reload_class}, enum machine_mode @var{reload_mode}, secondary_reload_info *@var{sri}) 246990075SobrienMany machines have some registers that cannot be copied directly to or 247090075Sobrienfrom memory or even from other types of registers. An example is the 247190075Sobrien@samp{MQ} register, which on most machines, can only be copied to or 2472169689Skanfrom general registers, but not memory. Below, we shall be using the 2473169689Skanterm 'intermediate register' when a move operation cannot be performed 2474169689Skandirectly, but has to be done by copying the source into the intermediate 2475169689Skanregister first, and then copying the intermediate register to the 2476169689Skandestination. An intermediate register always has the same mode as 2477169689Skansource and destination. Since it holds the actual value being copied, 2478169689Skanreload might apply optimizations to re-use an intermediate register 2479169689Skanand eliding the copy from the source when it can determine that the 2480169689Skanintermediate register still holds the required value. 248190075Sobrien 2482169689SkanAnother kind of secondary reload is required on some machines which 2483169689Skanallow copying all registers to and from memory, but require a scratch 2484169689Skanregister for stores to some memory locations (e.g., those with symbolic 2485169689Skanaddress on the RT, and those with certain symbolic address on the SPARC 2486169689Skanwhen compiling PIC)@. Scratch registers need not have the same mode 2487169689Skanas the value being copied, and usually hold a different value that 2488169689Skanthat being copied. Special patterns in the md file are needed to 2489169689Skandescribe how the copy is performed with the help of the scratch register; 2490169689Skanthese patterns also describe the number, register class(es) and mode(s) 2491169689Skanof the scratch register(s). 2492169689Skan 2493169689SkanIn some cases, both an intermediate and a scratch register are required. 2494169689Skan 2495169689SkanFor input reloads, this target hook is called with nonzero @var{in_p}, 2496169689Skanand @var{x} is an rtx that needs to be copied to a register in of class 2497169689Skan@var{reload_class} in @var{reload_mode}. For output reloads, this target 2498169689Skanhook is called with zero @var{in_p}, and a register of class @var{reload_mode} 2499169689Skanneeds to be copied to rtx @var{x} in @var{reload_mode}. 2500169689Skan 2501169689SkanIf copying a register of @var{reload_class} from/to @var{x} requires 2502169689Skanan intermediate register, the hook @code{secondary_reload} should 2503169689Skanreturn the register class required for this intermediate register. 2504169689SkanIf no intermediate register is required, it should return NO_REGS. 2505169689SkanIf more than one intermediate register is required, describe the one 2506169689Skanthat is closest in the copy chain to the reload register. 2507169689Skan 2508169689SkanIf scratch registers are needed, you also have to describe how to 2509169689Skanperform the copy from/to the reload register to/from this 2510169689Skanclosest intermediate register. Or if no intermediate register is 2511169689Skanrequired, but still a scratch register is needed, describe the 2512169689Skancopy from/to the reload register to/from the reload operand @var{x}. 2513169689Skan 2514169689SkanYou do this by setting @code{sri->icode} to the instruction code of a pattern 2515169689Skanin the md file which performs the move. Operands 0 and 1 are the output 2516169689Skanand input of this copy, respectively. Operands from operand 2 onward are 2517169689Skanfor scratch operands. These scratch operands must have a mode, and a 2518169689Skansingle-register-class 2519169689Skan@c [later: or memory] 2520169689Skanoutput constraint. 2521169689Skan 2522169689SkanWhen an intermediate register is used, the @code{secondary_reload} 2523169689Skanhook will be called again to determine how to copy the intermediate 2524169689Skanregister to/from the reload operand @var{x}, so your hook must also 2525169689Skanhave code to handle the register class of the intermediate operand. 2526169689Skan 2527169689Skan@c [For later: maybe we'll allow multi-alternative reload patterns - 2528169689Skan@c the port maintainer could name a mov<mode> pattern that has clobbers - 2529169689Skan@c and match the constraints of input and output to determine the required 2530169689Skan@c alternative. A restriction would be that constraints used to match 2531169689Skan@c against reloads registers would have to be written as register class 2532169689Skan@c constraints, or we need a new target macro / hook that tells us if an 2533169689Skan@c arbitrary constraint can match an unknown register of a given class. 2534169689Skan@c Such a macro / hook would also be useful in other places.] 2535169689Skan 2536169689Skan 2537169689Skan@var{x} might be a pseudo-register or a @code{subreg} of a 2538169689Skanpseudo-register, which could either be in a hard register or in memory. 2539169689SkanUse @code{true_regnum} to find out; it will return @minus{}1 if the pseudo is 2540169689Skanin memory and the hard register number if it is in a register. 2541169689Skan 2542169689SkanScratch operands in memory (constraint @code{"=m"} / @code{"=&m"}) are 2543169689Skancurrently not supported. For the time being, you will have to continue 2544169689Skanto use @code{SECONDARY_MEMORY_NEEDED} for that purpose. 2545169689Skan 2546169689Skan@code{copy_cost} also uses this target hook to find out how values are 2547169689Skancopied. If you want it to include some extra cost for the need to allocate 2548169689Skan(a) scratch register(s), set @code{sri->extra_cost} to the additional cost. 2549169689SkanOr if two dependent moves are supposed to have a lower cost than the sum 2550169689Skanof the individual moves due to expected fortuitous scheduling and/or special 2551169689Skanforwarding logic, you can set @code{sri->extra_cost} to a negative amount. 2552169689Skan@end deftypefn 2553169689Skan 2554169689Skan@defmac SECONDARY_RELOAD_CLASS (@var{class}, @var{mode}, @var{x}) 2555169689Skan@defmacx SECONDARY_INPUT_RELOAD_CLASS (@var{class}, @var{mode}, @var{x}) 2556169689Skan@defmacx SECONDARY_OUTPUT_RELOAD_CLASS (@var{class}, @var{mode}, @var{x}) 2557169689SkanThese macros are obsolete, new ports should use the target hook 2558169689Skan@code{TARGET_SECONDARY_RELOAD} instead. 2559169689Skan 2560169689SkanThese are obsolete macros, replaced by the @code{TARGET_SECONDARY_RELOAD} 2561169689Skantarget hook. Older ports still define these macros to indicate to the 2562169689Skanreload phase that it may 256390075Sobrienneed to allocate at least one register for a reload in addition to the 256490075Sobrienregister to contain the data. Specifically, if copying @var{x} to a 256590075Sobrienregister @var{class} in @var{mode} requires an intermediate register, 2566169689Skanyou were supposed to define @code{SECONDARY_INPUT_RELOAD_CLASS} to return the 256790075Sobrienlargest register class all of whose registers can be used as 256890075Sobrienintermediate registers or scratch registers. 256990075Sobrien 257090075SobrienIf copying a register @var{class} in @var{mode} to @var{x} requires an 257190075Sobrienintermediate or scratch register, @code{SECONDARY_OUTPUT_RELOAD_CLASS} 2572169689Skanwas supposed to be defined be defined to return the largest register 2573169689Skanclass required. If the 2574169689Skanrequirements for input and output reloads were the same, the macro 2575169689Skan@code{SECONDARY_RELOAD_CLASS} should have been used instead of defining both 257690075Sobrienmacros identically. 257790075Sobrien 257890075SobrienThe values returned by these macros are often @code{GENERAL_REGS}. 257990075SobrienReturn @code{NO_REGS} if no spare register is needed; i.e., if @var{x} 258090075Sobriencan be directly copied to or from a register of @var{class} in 258190075Sobrien@var{mode} without requiring a scratch register. Do not define this 258290075Sobrienmacro if it would always return @code{NO_REGS}. 258390075Sobrien 258490075SobrienIf a scratch register is required (either with or without an 2585169689Skanintermediate register), you were supposed to define patterns for 258690075Sobrien@samp{reload_in@var{m}} or @samp{reload_out@var{m}}, as required 2587169689Skan(@pxref{Standard Names}. These patterns, which were normally 258890075Sobrienimplemented with a @code{define_expand}, should be similar to the 258990075Sobrien@samp{mov@var{m}} patterns, except that operand 2 is the scratch 259090075Sobrienregister. 259190075Sobrien 2592169689SkanThese patterns need constraints for the reload register and scratch 2593169689Skanregister that 259490075Sobriencontain a single register class. If the original reload register (whose 259590075Sobrienclass is @var{class}) can meet the constraint given in the pattern, the 259690075Sobrienvalue returned by these macros is used for the class of the scratch 259790075Sobrienregister. Otherwise, two additional reload registers are required. 259890075SobrienTheir classes are obtained from the constraints in the insn pattern. 259990075Sobrien 260090075Sobrien@var{x} might be a pseudo-register or a @code{subreg} of a 260190075Sobrienpseudo-register, which could either be in a hard register or in memory. 260290075SobrienUse @code{true_regnum} to find out; it will return @minus{}1 if the pseudo is 260390075Sobrienin memory and the hard register number if it is in a register. 260490075Sobrien 260590075SobrienThese macros should not be used in the case where a particular class of 260690075Sobrienregisters can only be copied to memory and not to another class of 260790075Sobrienregisters. In that case, secondary reload registers are not needed and 260890075Sobrienwould not be helpful. Instead, a stack location must be used to perform 260990075Sobrienthe copy and the @code{mov@var{m}} pattern should use memory as an 261090075Sobrienintermediate storage. This case often occurs between floating-point and 261190075Sobriengeneral registers. 2612132718Skan@end defmac 261390075Sobrien 2614132718Skan@defmac SECONDARY_MEMORY_NEEDED (@var{class1}, @var{class2}, @var{m}) 261590075SobrienCertain machines have the property that some registers cannot be copied 261690075Sobriento some other registers without using memory. Define this macro on 261790075Sobrienthose machines to be a C expression that is nonzero if objects of mode 261890075Sobrien@var{m} in registers of @var{class1} can only be copied to registers of 261990075Sobrienclass @var{class2} by storing a register of @var{class1} into memory 262090075Sobrienand loading that memory location into a register of @var{class2}. 262190075Sobrien 262290075SobrienDo not define this macro if its value would always be zero. 2623132718Skan@end defmac 262490075Sobrien 2625132718Skan@defmac SECONDARY_MEMORY_NEEDED_RTX (@var{mode}) 262690075SobrienNormally when @code{SECONDARY_MEMORY_NEEDED} is defined, the compiler 262790075Sobrienallocates a stack slot for a memory location needed for register copies. 262890075SobrienIf this macro is defined, the compiler instead uses the memory location 262990075Sobriendefined by this macro. 263090075Sobrien 263190075SobrienDo not define this macro if you do not define 263290075Sobrien@code{SECONDARY_MEMORY_NEEDED}. 2633132718Skan@end defmac 263490075Sobrien 2635132718Skan@defmac SECONDARY_MEMORY_NEEDED_MODE (@var{mode}) 263690075SobrienWhen the compiler needs a secondary memory location to copy between two 263790075Sobrienregisters of mode @var{mode}, it normally allocates sufficient memory to 263890075Sobrienhold a quantity of @code{BITS_PER_WORD} bits and performs the store and 263990075Sobrienload operations in a mode that many bits wide and whose class is the 264090075Sobriensame as that of @var{mode}. 264190075Sobrien 264290075SobrienThis is right thing to do on most machines because it ensures that all 264390075Sobrienbits of the register are copied and prevents accesses to the registers 264490075Sobrienin a narrower mode, which some machines prohibit for floating-point 264590075Sobrienregisters. 264690075Sobrien 264790075SobrienHowever, this default behavior is not correct on some machines, such as 264890075Sobrienthe DEC Alpha, that store short integers in floating-point registers 264990075Sobriendifferently than in integer registers. On those machines, the default 265090075Sobrienwidening will not work correctly and you must define this macro to 265190075Sobriensuppress that widening in some cases. See the file @file{alpha.h} for 265290075Sobriendetails. 265390075Sobrien 265490075SobrienDo not define this macro if you do not define 265590075Sobrien@code{SECONDARY_MEMORY_NEEDED} or if widening @var{mode} to a mode that 265690075Sobrienis @code{BITS_PER_WORD} bits wide is correct for your machine. 2657132718Skan@end defmac 265890075Sobrien 2659132718Skan@defmac SMALL_REGISTER_CLASSES 266090075SobrienOn some machines, it is risky to let hard registers live across arbitrary 266190075Sobrieninsns. Typically, these machines have instructions that require values 266290075Sobriento be in specific registers (like an accumulator), and reload will fail 266390075Sobrienif the required hard register is used for another purpose across such an 266490075Sobrieninsn. 266590075Sobrien 266690075SobrienDefine @code{SMALL_REGISTER_CLASSES} to be an expression with a nonzero 266790075Sobrienvalue on these machines. When this macro has a nonzero value, the 266890075Sobriencompiler will try to minimize the lifetime of hard registers. 266990075Sobrien 267090075SobrienIt is always safe to define this macro with a nonzero value, but if you 267190075Sobrienunnecessarily define it, you will reduce the amount of optimizations 267290075Sobrienthat can be performed in some cases. If you do not define this macro 267390075Sobrienwith a nonzero value when it is required, the compiler will run out of 267490075Sobrienspill registers and print a fatal error message. For most machines, you 267590075Sobrienshould not define this macro at all. 2676132718Skan@end defmac 267790075Sobrien 2678132718Skan@defmac CLASS_LIKELY_SPILLED_P (@var{class}) 267990075SobrienA C expression whose value is nonzero if pseudos that have been assigned 268090075Sobriento registers of class @var{class} would likely be spilled because 268190075Sobrienregisters of @var{class} are needed for spill registers. 268290075Sobrien 268390075SobrienThe default value of this macro returns 1 if @var{class} has exactly one 268490075Sobrienregister and zero otherwise. On most machines, this default should be 268590075Sobrienused. Only define this macro to some other expression if pseudos 268690075Sobrienallocated by @file{local-alloc.c} end up in memory because their hard 268790075Sobrienregisters were needed for spill registers. If this macro returns nonzero 268890075Sobrienfor those classes, those pseudos will only be allocated by 268990075Sobrien@file{global.c}, which knows how to reallocate the pseudo to another 269090075Sobrienregister. If there would not be another register available for 269190075Sobrienreallocation, you should not change the definition of this macro since 269290075Sobrienthe only effect of such a definition would be to slow down register 269390075Sobrienallocation. 2694132718Skan@end defmac 269590075Sobrien 2696132718Skan@defmac CLASS_MAX_NREGS (@var{class}, @var{mode}) 269790075SobrienA C expression for the maximum number of consecutive registers 269890075Sobrienof class @var{class} needed to hold a value of mode @var{mode}. 269990075Sobrien 270090075SobrienThis is closely related to the macro @code{HARD_REGNO_NREGS}. In fact, 270190075Sobrienthe value of the macro @code{CLASS_MAX_NREGS (@var{class}, @var{mode})} 270290075Sobrienshould be the maximum value of @code{HARD_REGNO_NREGS (@var{regno}, 270390075Sobrien@var{mode})} for all @var{regno} values in the class @var{class}. 270490075Sobrien 270590075SobrienThis macro helps control the handling of multiple-word values 270690075Sobrienin the reload pass. 2707132718Skan@end defmac 270890075Sobrien 2709132718Skan@defmac CANNOT_CHANGE_MODE_CLASS (@var{from}, @var{to}, @var{class}) 2710117395SkanIf defined, a C expression that returns nonzero for a @var{class} for which 2711117395Skana change from mode @var{from} to mode @var{to} is invalid. 271290075Sobrien 271390075SobrienFor the example, loading 32-bit integer or floating-point objects into 2714102780Skanfloating-point registers on the Alpha extends them to 64 bits. 271590075SobrienTherefore loading a 64-bit object and then storing it as a 32-bit object 2716102780Skandoes not store the low-order 32 bits, as would be the case for a normal 2717117395Skanregister. Therefore, @file{alpha.h} defines @code{CANNOT_CHANGE_MODE_CLASS} 2718117395Skanas below: 271990075Sobrien 2720132718Skan@smallexample 2721117395Skan#define CANNOT_CHANGE_MODE_CLASS(FROM, TO, CLASS) \ 2722117395Skan (GET_MODE_SIZE (FROM) != GET_MODE_SIZE (TO) \ 2723117395Skan ? reg_classes_intersect_p (FLOAT_REGS, (CLASS)) : 0) 2724132718Skan@end smallexample 2725132718Skan@end defmac 272690075Sobrien 2727169689Skan@node Old Constraints 2728169689Skan@section Obsolete Macros for Defining Constraints 2729169689Skan@cindex defining constraints, obsolete method 2730169689Skan@cindex constraints, defining, obsolete method 273190075Sobrien 2732169689SkanMachine-specific constraints can be defined with these macros instead 2733169689Skanof the machine description constructs described in @ref{Define 2734169689SkanConstraints}. This mechanism is obsolete. New ports should not use 2735169689Skanit; old ports should convert to the new mechanism. 2736169689Skan 2737169689Skan@defmac CONSTRAINT_LEN (@var{char}, @var{str}) 2738169689SkanFor the constraint at the start of @var{str}, which starts with the letter 2739169689Skan@var{c}, return the length. This allows you to have register class / 2740169689Skanconstant / extra constraints that are longer than a single letter; 2741169689Skanyou don't need to define this macro if you can do with single-letter 2742169689Skanconstraints only. The definition of this macro should use 2743169689SkanDEFAULT_CONSTRAINT_LEN for all the characters that you don't want 2744169689Skanto handle specially. 2745169689SkanThere are some sanity checks in genoutput.c that check the constraint lengths 2746169689Skanfor the md file, so you can also use this macro to help you while you are 2747169689Skantransitioning from a byzantine single-letter-constraint scheme: when you 2748169689Skanreturn a negative length for a constraint you want to re-use, genoutput 2749169689Skanwill complain about every instance where it is used in the md file. 2750169689Skan@end defmac 2751169689Skan 2752169689Skan@defmac REG_CLASS_FROM_LETTER (@var{char}) 2753169689SkanA C expression which defines the machine-dependent operand constraint 2754169689Skanletters for register classes. If @var{char} is such a letter, the 2755169689Skanvalue should be the register class corresponding to it. Otherwise, 2756169689Skanthe value should be @code{NO_REGS}. The register letter @samp{r}, 2757169689Skancorresponding to class @code{GENERAL_REGS}, will not be passed 2758169689Skanto this macro; you do not need to handle it. 2759169689Skan@end defmac 2760169689Skan 2761169689Skan@defmac REG_CLASS_FROM_CONSTRAINT (@var{char}, @var{str}) 2762169689SkanLike @code{REG_CLASS_FROM_LETTER}, but you also get the constraint string 2763169689Skanpassed in @var{str}, so that you can use suffixes to distinguish between 2764169689Skandifferent variants. 2765169689Skan@end defmac 2766169689Skan 2767132718Skan@defmac CONST_OK_FOR_LETTER_P (@var{value}, @var{c}) 276890075SobrienA C expression that defines the machine-dependent operand constraint 276990075Sobrienletters (@samp{I}, @samp{J}, @samp{K}, @dots{} @samp{P}) that specify 277090075Sobrienparticular ranges of integer values. If @var{c} is one of those 277190075Sobrienletters, the expression should check that @var{value}, an integer, is in 277290075Sobrienthe appropriate range and return 1 if so, 0 otherwise. If @var{c} is 277390075Sobriennot one of those letters, the value should be 0 regardless of 277490075Sobrien@var{value}. 2775132718Skan@end defmac 277690075Sobrien 2777132718Skan@defmac CONST_OK_FOR_CONSTRAINT_P (@var{value}, @var{c}, @var{str}) 2778132718SkanLike @code{CONST_OK_FOR_LETTER_P}, but you also get the constraint 2779132718Skanstring passed in @var{str}, so that you can use suffixes to distinguish 2780132718Skanbetween different variants. 2781132718Skan@end defmac 2782132718Skan 2783132718Skan@defmac CONST_DOUBLE_OK_FOR_LETTER_P (@var{value}, @var{c}) 278490075SobrienA C expression that defines the machine-dependent operand constraint 278590075Sobrienletters that specify particular ranges of @code{const_double} values 278690075Sobrien(@samp{G} or @samp{H}). 278790075Sobrien 278890075SobrienIf @var{c} is one of those letters, the expression should check that 278990075Sobrien@var{value}, an RTX of code @code{const_double}, is in the appropriate 279090075Sobrienrange and return 1 if so, 0 otherwise. If @var{c} is not one of those 279190075Sobrienletters, the value should be 0 regardless of @var{value}. 279290075Sobrien 279390075Sobrien@code{const_double} is used for all floating-point constants and for 279490075Sobrien@code{DImode} fixed-point constants. A given letter can accept either 279590075Sobrienor both kinds of values. It can use @code{GET_MODE} to distinguish 279690075Sobrienbetween these kinds. 2797132718Skan@end defmac 279890075Sobrien 2799132718Skan@defmac CONST_DOUBLE_OK_FOR_CONSTRAINT_P (@var{value}, @var{c}, @var{str}) 2800132718SkanLike @code{CONST_DOUBLE_OK_FOR_LETTER_P}, but you also get the constraint 2801132718Skanstring passed in @var{str}, so that you can use suffixes to distinguish 2802132718Skanbetween different variants. 2803132718Skan@end defmac 2804132718Skan 2805132718Skan@defmac EXTRA_CONSTRAINT (@var{value}, @var{c}) 280690075SobrienA C expression that defines the optional machine-dependent constraint 280790075Sobrienletters that can be used to segregate specific types of operands, usually 280890075Sobrienmemory references, for the target machine. Any letter that is not 2809132718Skanelsewhere defined and not matched by @code{REG_CLASS_FROM_LETTER} / 2810132718Skan@code{REG_CLASS_FROM_CONSTRAINT} 281190075Sobrienmay be used. Normally this macro will not be defined. 281290075Sobrien 281390075SobrienIf it is required for a particular target machine, it should return 1 281490075Sobrienif @var{value} corresponds to the operand type represented by the 281590075Sobrienconstraint letter @var{c}. If @var{c} is not defined as an extra 281690075Sobrienconstraint, the value returned should be 0 regardless of @var{value}. 281790075Sobrien 281890075SobrienFor example, on the ROMP, load instructions cannot have their output 281990075Sobrienin r0 if the memory reference contains a symbolic address. Constraint 282090075Sobrienletter @samp{Q} is defined as representing a memory address that does 282190075Sobrien@emph{not} contain a symbolic address. An alternative is specified with 282290075Sobriena @samp{Q} constraint on the input and @samp{r} on the output. The next 282390075Sobrienalternative specifies @samp{m} on the input and a register class that 282490075Sobriendoes not include r0 on the output. 2825132718Skan@end defmac 2826117395Skan 2827132718Skan@defmac EXTRA_CONSTRAINT_STR (@var{value}, @var{c}, @var{str}) 2828132718SkanLike @code{EXTRA_CONSTRAINT}, but you also get the constraint string passed 2829132718Skanin @var{str}, so that you can use suffixes to distinguish between different 2830132718Skanvariants. 2831132718Skan@end defmac 2832132718Skan 2833132718Skan@defmac EXTRA_MEMORY_CONSTRAINT (@var{c}, @var{str}) 2834117395SkanA C expression that defines the optional machine-dependent constraint 2835117395Skanletters, amongst those accepted by @code{EXTRA_CONSTRAINT}, that should 2836117395Skanbe treated like memory constraints by the reload pass. 2837117395Skan 2838132718SkanIt should return 1 if the operand type represented by the constraint 2839132718Skanat the start of @var{str}, the first letter of which is the letter @var{c}, 2840132718Skan comprises a subset of all memory references including 2841132718Skanall those whose address is simply a base register. This allows the reload 2842132718Skanpass to reload an operand, if it does not directly correspond to the operand 2843117395Skantype of @var{c}, by copying its address into a base register. 2844117395Skan 2845117395SkanFor example, on the S/390, some instructions do not accept arbitrary 2846117395Skanmemory references, but only those that do not make use of an index 2847117395Skanregister. The constraint letter @samp{Q} is defined via 2848117395Skan@code{EXTRA_CONSTRAINT} as representing a memory address of this type. 2849117395SkanIf the letter @samp{Q} is marked as @code{EXTRA_MEMORY_CONSTRAINT}, 2850117395Skana @samp{Q} constraint can handle any memory operand, because the 2851117395Skanreload pass knows it can be reloaded by copying the memory address 2852117395Skaninto a base register if required. This is analogous to the way 2853117395Skana @samp{o} constraint can handle any memory operand. 2854132718Skan@end defmac 2855117395Skan 2856132718Skan@defmac EXTRA_ADDRESS_CONSTRAINT (@var{c}, @var{str}) 2857117395SkanA C expression that defines the optional machine-dependent constraint 2858132718Skanletters, amongst those accepted by @code{EXTRA_CONSTRAINT} / 2859132718Skan@code{EXTRA_CONSTRAINT_STR}, that should 2860117395Skanbe treated like address constraints by the reload pass. 2861117395Skan 2862132718SkanIt should return 1 if the operand type represented by the constraint 2863132718Skanat the start of @var{str}, which starts with the letter @var{c}, comprises 2864132718Skana subset of all memory addresses including 2865132718Skanall those that consist of just a base register. This allows the reload 2866132718Skanpass to reload an operand, if it does not directly correspond to the operand 2867132718Skantype of @var{str}, by copying it into a base register. 2868117395Skan 2869117395SkanAny constraint marked as @code{EXTRA_ADDRESS_CONSTRAINT} can only 2870132718Skanbe used with the @code{address_operand} predicate. It is treated 2871117395Skananalogously to the @samp{p} constraint. 2872132718Skan@end defmac 287390075Sobrien 287490075Sobrien@node Stack and Calling 287590075Sobrien@section Stack Layout and Calling Conventions 287690075Sobrien@cindex calling conventions 287790075Sobrien 287890075Sobrien@c prevent bad page break with this line 287990075SobrienThis describes the stack layout and calling conventions. 288090075Sobrien 288190075Sobrien@menu 288290075Sobrien* Frame Layout:: 288390075Sobrien* Exception Handling:: 288490075Sobrien* Stack Checking:: 288590075Sobrien* Frame Registers:: 288690075Sobrien* Elimination:: 288790075Sobrien* Stack Arguments:: 288890075Sobrien* Register Arguments:: 288990075Sobrien* Scalar Return:: 289090075Sobrien* Aggregate Return:: 289190075Sobrien* Caller Saves:: 289290075Sobrien* Function Entry:: 289390075Sobrien* Profiling:: 289490075Sobrien* Tail Calls:: 2895169689Skan* Stack Smashing Protection:: 289690075Sobrien@end menu 289790075Sobrien 289890075Sobrien@node Frame Layout 289990075Sobrien@subsection Basic Stack Layout 290090075Sobrien@cindex stack frame layout 290190075Sobrien@cindex frame layout 290290075Sobrien 290390075Sobrien@c prevent bad page break with this line 290490075SobrienHere is the basic stack layout. 290590075Sobrien 2906132718Skan@defmac STACK_GROWS_DOWNWARD 290790075SobrienDefine this macro if pushing a word onto the stack moves the stack 290890075Sobrienpointer to a smaller address. 290990075Sobrien 2910169689SkanWhen we say, ``define this macro if @dots{}'', it means that the 291190075Sobriencompiler checks this macro only with @code{#ifdef} so the precise 291290075Sobriendefinition used does not matter. 2913132718Skan@end defmac 291490075Sobrien 2915132718Skan@defmac STACK_PUSH_CODE 291690075SobrienThis macro defines the operation used when something is pushed 291790075Sobrienon the stack. In RTL, a push operation will be 2918117395Skan@code{(set (mem (STACK_PUSH_CODE (reg sp))) @dots{})} 291990075Sobrien 292090075SobrienThe choices are @code{PRE_DEC}, @code{POST_DEC}, @code{PRE_INC}, 292190075Sobrienand @code{POST_INC}. Which of these is correct depends on 292290075Sobrienthe stack direction and on whether the stack pointer points 292390075Sobriento the last item on the stack or whether it points to the 292490075Sobrienspace for the next item on the stack. 292590075Sobrien 292690075SobrienThe default is @code{PRE_DEC} when @code{STACK_GROWS_DOWNWARD} is 292790075Sobriendefined, which is almost always right, and @code{PRE_INC} otherwise, 292890075Sobrienwhich is often wrong. 2929132718Skan@end defmac 293090075Sobrien 2931132718Skan@defmac FRAME_GROWS_DOWNWARD 2932169689SkanDefine this macro to nonzero value if the addresses of local variable slots 2933169689Skanare at negative offsets from the frame pointer. 2934132718Skan@end defmac 293590075Sobrien 2936132718Skan@defmac ARGS_GROW_DOWNWARD 293790075SobrienDefine this macro if successive arguments to a function occupy decreasing 293890075Sobrienaddresses on the stack. 2939132718Skan@end defmac 294090075Sobrien 2941132718Skan@defmac STARTING_FRAME_OFFSET 294290075SobrienOffset from the frame pointer to the first local variable slot to be allocated. 294390075Sobrien 294490075SobrienIf @code{FRAME_GROWS_DOWNWARD}, find the next slot's offset by 294590075Sobriensubtracting the first slot's length from @code{STARTING_FRAME_OFFSET}. 294690075SobrienOtherwise, it is found by adding the length of the first slot to the 294790075Sobrienvalue @code{STARTING_FRAME_OFFSET}. 294890075Sobrien@c i'm not sure if the above is still correct.. had to change it to get 294990075Sobrien@c rid of an overfull. --mew 2feb93 2950132718Skan@end defmac 295190075Sobrien 2952132718Skan@defmac STACK_ALIGNMENT_NEEDED 2953132718SkanDefine to zero to disable final alignment of the stack during reload. 2954132718SkanThe nonzero default for this macro is suitable for most ports. 2955132718Skan 2956132718SkanOn ports where @code{STARTING_FRAME_OFFSET} is nonzero or where there 2957132718Skanis a register save block following the local block that doesn't require 2958132718Skanalignment to @code{STACK_BOUNDARY}, it may be beneficial to disable 2959132718Skanstack alignment and do it in the backend. 2960132718Skan@end defmac 2961132718Skan 2962132718Skan@defmac STACK_POINTER_OFFSET 296390075SobrienOffset from the stack pointer register to the first location at which 296490075Sobrienoutgoing arguments are placed. If not specified, the default value of 296590075Sobrienzero is used. This is the proper value for most machines. 296690075Sobrien 296790075SobrienIf @code{ARGS_GROW_DOWNWARD}, this is the offset to the location above 296890075Sobrienthe first location at which outgoing arguments are placed. 2969132718Skan@end defmac 297090075Sobrien 2971132718Skan@defmac FIRST_PARM_OFFSET (@var{fundecl}) 297290075SobrienOffset from the argument pointer register to the first argument's 297390075Sobrienaddress. On some machines it may depend on the data type of the 297490075Sobrienfunction. 297590075Sobrien 297690075SobrienIf @code{ARGS_GROW_DOWNWARD}, this is the offset to the location above 297790075Sobrienthe first argument's address. 2978132718Skan@end defmac 297990075Sobrien 2980132718Skan@defmac STACK_DYNAMIC_OFFSET (@var{fundecl}) 298190075SobrienOffset from the stack pointer register to an item dynamically allocated 298290075Sobrienon the stack, e.g., by @code{alloca}. 298390075Sobrien 298490075SobrienThe default value for this macro is @code{STACK_POINTER_OFFSET} plus the 298590075Sobrienlength of the outgoing arguments. The default is correct for most 298690075Sobrienmachines. See @file{function.c} for details. 2987132718Skan@end defmac 298890075Sobrien 2989169689Skan@defmac INITIAL_FRAME_ADDRESS_RTX 2990169689SkanA C expression whose value is RTL representing the address of the initial 2991169689Skanstack frame. This address is passed to @code{RETURN_ADDR_RTX} and 2992169689Skan@code{DYNAMIC_CHAIN_ADDRESS}. If you don't define this macro, a reasonable 2993169689Skandefault value will be used. Define this macro in order to make frame pointer 2994169689Skanelimination work in the presence of @code{__builtin_frame_address (count)} and 2995169689Skan@code{__builtin_return_address (count)} for @code{count} not equal to zero. 2996169689Skan@end defmac 2997169689Skan 2998132718Skan@defmac DYNAMIC_CHAIN_ADDRESS (@var{frameaddr}) 299990075SobrienA C expression whose value is RTL representing the address in a stack 300090075Sobrienframe where the pointer to the caller's frame is stored. Assume that 300190075Sobrien@var{frameaddr} is an RTL expression for the address of the stack frame 300290075Sobrienitself. 300390075Sobrien 300490075SobrienIf you don't define this macro, the default is to return the value 300590075Sobrienof @var{frameaddr}---that is, the stack frame address is also the 300690075Sobrienaddress of the stack word that points to the previous frame. 3007132718Skan@end defmac 300890075Sobrien 3009132718Skan@defmac SETUP_FRAME_ADDRESSES 301090075SobrienIf defined, a C expression that produces the machine-specific code to 301190075Sobriensetup the stack so that arbitrary frames can be accessed. For example, 3012117395Skanon the SPARC, we must flush all of the register windows to the stack 301390075Sobrienbefore we can access arbitrary stack frames. You will seldom need to 301490075Sobriendefine this macro. 3015132718Skan@end defmac 301690075Sobrien 3017169689Skan@deftypefn {Target Hook} bool TARGET_BUILTIN_SETJMP_FRAME_VALUE () 3018169689SkanThis target hook should return an rtx that is used to store 301990075Sobrienthe address of the current frame into the built in @code{setjmp} buffer. 302090075SobrienThe default value, @code{virtual_stack_vars_rtx}, is correct for most 3021169689Skanmachines. One reason you may need to define this target hook is if 302290075Sobrien@code{hard_frame_pointer_rtx} is the appropriate value on your machine. 3023169689Skan@end deftypefn 3024169689Skan 3025169689Skan@defmac FRAME_ADDR_RTX (@var{frameaddr}) 3026169689SkanA C expression whose value is RTL representing the value of the frame 3027169689Skanaddress for the current frame. @var{frameaddr} is the frame pointer 3028169689Skanof the current frame. This is used for __builtin_frame_address. 3029169689SkanYou need only define this macro if the frame address is not the same 3030169689Skanas the frame pointer. Most machines do not need to define it. 3031132718Skan@end defmac 303290075Sobrien 3033132718Skan@defmac RETURN_ADDR_RTX (@var{count}, @var{frameaddr}) 303490075SobrienA C expression whose value is RTL representing the value of the return 303590075Sobrienaddress for the frame @var{count} steps up from the current frame, after 303690075Sobrienthe prologue. @var{frameaddr} is the frame pointer of the @var{count} 303790075Sobrienframe, or the frame pointer of the @var{count} @minus{} 1 frame if 303890075Sobrien@code{RETURN_ADDR_IN_PREVIOUS_FRAME} is defined. 303990075Sobrien 304090075SobrienThe value of the expression must always be the correct address when 304190075Sobrien@var{count} is zero, but may be @code{NULL_RTX} if there is not way to 304290075Sobriendetermine the return address of other frames. 3043132718Skan@end defmac 304490075Sobrien 3045132718Skan@defmac RETURN_ADDR_IN_PREVIOUS_FRAME 304690075SobrienDefine this if the return address of a particular stack frame is accessed 304790075Sobrienfrom the frame pointer of the previous stack frame. 3048132718Skan@end defmac 304990075Sobrien 3050132718Skan@defmac INCOMING_RETURN_ADDR_RTX 305190075SobrienA C expression whose value is RTL representing the location of the 305290075Sobrienincoming return address at the beginning of any function, before the 305390075Sobrienprologue. This RTL is either a @code{REG}, indicating that the return 305490075Sobrienvalue is saved in @samp{REG}, or a @code{MEM} representing a location in 305590075Sobrienthe stack. 305690075Sobrien 305790075SobrienYou only need to define this macro if you want to support call frame 305890075Sobriendebugging information like that provided by DWARF 2. 305990075Sobrien 306090075SobrienIf this RTL is a @code{REG}, you should also define 306190075Sobrien@code{DWARF_FRAME_RETURN_COLUMN} to @code{DWARF_FRAME_REGNUM (REGNO)}. 3062132718Skan@end defmac 306390075Sobrien 3064132718Skan@defmac DWARF_ALT_FRAME_RETURN_COLUMN 3065132718SkanA C expression whose value is an integer giving a DWARF 2 column 3066132718Skannumber that may be used as an alternate return column. This should 3067132718Skanbe defined only if @code{DWARF_FRAME_RETURN_COLUMN} is set to a 3068132718Skangeneral register, but an alternate column needs to be used for 3069132718Skansignal frames. 3070132718Skan@end defmac 3071132718Skan 3072146895Skan@defmac DWARF_ZERO_REG 3073146895SkanA C expression whose value is an integer giving a DWARF 2 register 3074146895Skannumber that is considered to always have the value zero. This should 3075146895Skanonly be defined if the target has an architected zero register, and 3076146895Skansomeone decided it was a good idea to use that register number to 3077146895Skanterminate the stack backtrace. New ports should avoid this. 3078146895Skan@end defmac 3079146895Skan 3080169689Skan@deftypefn {Target Hook} void TARGET_DWARF_HANDLE_FRAME_UNSPEC (const char *@var{label}, rtx @var{pattern}, int @var{index}) 3081169689SkanThis target hook allows the backend to emit frame-related insns that 3082169689Skancontain UNSPECs or UNSPEC_VOLATILEs. The DWARF 2 call frame debugging 3083169689Skaninfo engine will invoke it on insns of the form 3084169689Skan@smallexample 3085169689Skan(set (reg) (unspec [...] UNSPEC_INDEX)) 3086169689Skan@end smallexample 3087169689Skanand 3088169689Skan@smallexample 3089169689Skan(set (reg) (unspec_volatile [...] UNSPECV_INDEX)). 3090169689Skan@end smallexample 3091169689Skanto let the backend emit the call frame instructions. @var{label} is 3092169689Skanthe CFI label attached to the insn, @var{pattern} is the pattern of 3093169689Skanthe insn and @var{index} is @code{UNSPEC_INDEX} or @code{UNSPECV_INDEX}. 3094169689Skan@end deftypefn 3095169689Skan 3096132718Skan@defmac INCOMING_FRAME_SP_OFFSET 309790075SobrienA C expression whose value is an integer giving the offset, in bytes, 309890075Sobrienfrom the value of the stack pointer register to the top of the stack 309990075Sobrienframe at the beginning of any function, before the prologue. The top of 310090075Sobrienthe frame is defined to be the value of the stack pointer in the 310190075Sobrienprevious frame, just before the call instruction. 310290075Sobrien 310390075SobrienYou only need to define this macro if you want to support call frame 310490075Sobriendebugging information like that provided by DWARF 2. 3105132718Skan@end defmac 310690075Sobrien 3107132718Skan@defmac ARG_POINTER_CFA_OFFSET (@var{fundecl}) 310890075SobrienA C expression whose value is an integer giving the offset, in bytes, 310990075Sobrienfrom the argument pointer to the canonical frame address (cfa). The 311090075Sobrienfinal value should coincide with that calculated by 311190075Sobrien@code{INCOMING_FRAME_SP_OFFSET}. Which is unfortunately not usable 311290075Sobrienduring virtual register instantiation. 311390075Sobrien 311490075SobrienThe default value for this macro is @code{FIRST_PARM_OFFSET (fundecl)}, 311590075Sobrienwhich is correct for most machines; in general, the arguments are found 311690075Sobrienimmediately before the stack frame. Note that this is not the case on 311790075Sobriensome targets that save registers into the caller's frame, such as SPARC 311890075Sobrienand rs6000, and so such targets need to define this macro. 311990075Sobrien 312090075SobrienYou only need to define this macro if the default is incorrect, and you 312190075Sobrienwant to support call frame debugging information like that provided by 312290075SobrienDWARF 2. 3123132718Skan@end defmac 312490075Sobrien 3125169689Skan@defmac FRAME_POINTER_CFA_OFFSET (@var{fundecl}) 3126169689SkanIf defined, a C expression whose value is an integer giving the offset 3127169689Skanin bytes from the frame pointer to the canonical frame address (cfa). 3128169689SkanThe final value should coincide with that calculated by 3129169689Skan@code{INCOMING_FRAME_SP_OFFSET}. 3130169689Skan 3131169689SkanNormally the CFA is calculated as an offset from the argument pointer, 3132169689Skanvia @code{ARG_POINTER_CFA_OFFSET}, but if the argument pointer is 3133169689Skanvariable due to the ABI, this may not be possible. If this macro is 3134169689Skandefined, it implies that the virtual register instantiation should be 3135169689Skanbased on the frame pointer instead of the argument pointer. Only one 3136169689Skanof @code{FRAME_POINTER_CFA_OFFSET} and @code{ARG_POINTER_CFA_OFFSET} 3137169689Skanshould be defined. 3138169689Skan@end defmac 3139169689Skan 3140169689Skan@defmac CFA_FRAME_BASE_OFFSET (@var{fundecl}) 3141169689SkanIf defined, a C expression whose value is an integer giving the offset 3142169689Skanin bytes from the canonical frame address (cfa) to the frame base used 3143169689Skanin DWARF 2 debug information. The default is zero. A different value 3144169689Skanmay reduce the size of debug information on some ports. 3145169689Skan@end defmac 3146169689Skan 314790075Sobrien@node Exception Handling 314890075Sobrien@subsection Exception Handling Support 314990075Sobrien@cindex exception handling 315090075Sobrien 3151132718Skan@defmac EH_RETURN_DATA_REGNO (@var{N}) 315290075SobrienA C expression whose value is the @var{N}th register number used for 315390075Sobriendata by exception handlers, or @code{INVALID_REGNUM} if fewer than 315490075Sobrien@var{N} registers are usable. 315590075Sobrien 315690075SobrienThe exception handling library routines communicate with the exception 315790075Sobrienhandlers via a set of agreed upon registers. Ideally these registers 315890075Sobrienshould be call-clobbered; it is possible to use call-saved registers, 315990075Sobrienbut may negatively impact code size. The target must support at least 316090075Sobrien2 data registers, but should define 4 if there are enough free registers. 316190075Sobrien 316290075SobrienYou must define this macro if you want to support call frame exception 316390075Sobrienhandling like that provided by DWARF 2. 3164132718Skan@end defmac 316590075Sobrien 3166132718Skan@defmac EH_RETURN_STACKADJ_RTX 316790075SobrienA C expression whose value is RTL representing a location in which 316890075Sobriento store a stack adjustment to be applied before function return. 316990075SobrienThis is used to unwind the stack to an exception handler's call frame. 317090075SobrienIt will be assigned zero on code paths that return normally. 317190075Sobrien 317290075SobrienTypically this is a call-clobbered hard register that is otherwise 317390075Sobrienuntouched by the epilogue, but could also be a stack slot. 317490075Sobrien 3175117395SkanDo not define this macro if the stack pointer is saved and restored 3176132718Skanby the regular prolog and epilog code in the call frame itself; in 3177132718Skanthis case, the exception handling library routines will update the 3178132718Skanstack location to be restored in place. Otherwise, you must define 3179132718Skanthis macro if you want to support call frame exception handling like 3180117395Skanthat provided by DWARF 2. 3181132718Skan@end defmac 318290075Sobrien 3183132718Skan@defmac EH_RETURN_HANDLER_RTX 318490075SobrienA C expression whose value is RTL representing a location in which 318590075Sobriento store the address of an exception handler to which we should 318690075Sobrienreturn. It will not be assigned on code paths that return normally. 318790075Sobrien 318890075SobrienTypically this is the location in the call frame at which the normal 318990075Sobrienreturn address is stored. For targets that return by popping an 319090075Sobrienaddress off the stack, this might be a memory address just below 319190075Sobrienthe @emph{target} call frame rather than inside the current call 3192132718Skanframe. If defined, @code{EH_RETURN_STACKADJ_RTX} will have already 3193132718Skanbeen assigned, so it may be used to calculate the location of the 3194117395Skantarget call frame. 319590075Sobrien 319690075SobrienSome targets have more complex requirements than storing to an 319790075Sobrienaddress calculable during initial code generation. In that case 319890075Sobrienthe @code{eh_return} instruction pattern should be used instead. 319990075Sobrien 320090075SobrienIf you want to support call frame exception handling, you must 320190075Sobriendefine either this macro or the @code{eh_return} instruction pattern. 3202132718Skan@end defmac 320390075Sobrien 3204132718Skan@defmac RETURN_ADDR_OFFSET 3205132718SkanIf defined, an integer-valued C expression for which rtl will be generated 3206132718Skanto add it to the exception handler address before it is searched in the 3207132718Skanexception handling tables, and to subtract it again from the address before 3208132718Skanusing it to return to the exception handler. 3209132718Skan@end defmac 3210132718Skan 3211132718Skan@defmac ASM_PREFERRED_EH_DATA_FORMAT (@var{code}, @var{global}) 321290075SobrienThis macro chooses the encoding of pointers embedded in the exception 321390075Sobrienhandling sections. If at all possible, this should be defined such 321490075Sobrienthat the exception handling section will not require dynamic relocations, 321590075Sobrienand so may be read-only. 321690075Sobrien 321790075Sobrien@var{code} is 0 for data, 1 for code labels, 2 for function pointers. 321890075Sobrien@var{global} is true if the symbol may be affected by dynamic relocations. 321990075SobrienThe macro should return a combination of the @code{DW_EH_PE_*} defines 322090075Sobrienas found in @file{dwarf2.h}. 322190075Sobrien 322290075SobrienIf this macro is not defined, pointers will not be encoded but 322390075Sobrienrepresented directly. 3224132718Skan@end defmac 322590075Sobrien 3226132718Skan@defmac ASM_MAYBE_OUTPUT_ENCODED_ADDR_RTX (@var{file}, @var{encoding}, @var{size}, @var{addr}, @var{done}) 322790075SobrienThis macro allows the target to emit whatever special magic is required 322890075Sobriento represent the encoding chosen by @code{ASM_PREFERRED_EH_DATA_FORMAT}. 322990075SobrienGeneric code takes care of pc-relative and indirect encodings; this must 323090075Sobrienbe defined if the target uses text-relative or data-relative encodings. 323190075Sobrien 323290075SobrienThis is a C statement that branches to @var{done} if the format was 323390075Sobrienhandled. @var{encoding} is the format chosen, @var{size} is the number 323490075Sobrienof bytes that the format occupies, @var{addr} is the @code{SYMBOL_REF} 323590075Sobriento be emitted. 3236132718Skan@end defmac 323790075Sobrien 3238169689Skan@defmac MD_UNWIND_SUPPORT 3239169689SkanA string specifying a file to be #include'd in unwind-dw2.c. The file 3240169689Skanso included typically defines @code{MD_FALLBACK_FRAME_STATE_FOR}. 3241169689Skan@end defmac 3242169689Skan 3243169689Skan@defmac MD_FALLBACK_FRAME_STATE_FOR (@var{context}, @var{fs}) 324490075SobrienThis macro allows the target to add cpu and operating system specific 324590075Sobriencode to the call-frame unwinder for use when there is no unwind data 324690075Sobrienavailable. The most common reason to implement this macro is to unwind 324790075Sobrienthrough signal frames. 324890075Sobrien 324990075SobrienThis macro is called from @code{uw_frame_state_for} in @file{unwind-dw2.c} 325090075Sobrienand @file{unwind-ia64.c}. @var{context} is an @code{_Unwind_Context}; 325190075Sobrien@var{fs} is an @code{_Unwind_FrameState}. Examine @code{context->ra} 325290075Sobrienfor the address of the code being executed and @code{context->cfa} for 325390075Sobrienthe stack pointer value. If the frame can be decoded, the register save 3254169689Skanaddresses should be updated in @var{fs} and the macro should evaluate to 3255169689Skan@code{_URC_NO_REASON}. If the frame cannot be decoded, the macro should 3256169689Skanevaluate to @code{_URC_END_OF_STACK}. 325790075Sobrien 3258132718SkanFor proper signal handling in Java this macro is accompanied by 3259132718Skan@code{MAKE_THROW_FRAME}, defined in @file{libjava/include/*-signal.h} headers. 3260132718Skan@end defmac 3261132718Skan 3262132718Skan@defmac MD_HANDLE_UNWABI (@var{context}, @var{fs}) 3263132718SkanThis macro allows the target to add operating system specific code to the 3264132718Skancall-frame unwinder to handle the IA-64 @code{.unwabi} unwinding directive, 3265132718Skanusually used for signal or interrupt frames. 3266132718Skan 3267132718SkanThis macro is called from @code{uw_update_context} in @file{unwind-ia64.c}. 3268132718Skan@var{context} is an @code{_Unwind_Context}; 3269132718Skan@var{fs} is an @code{_Unwind_FrameState}. Examine @code{fs->unwabi} 3270132718Skanfor the abi and context in the @code{.unwabi} directive. If the 3271132718Skan@code{.unwabi} directive can be handled, the register save addresses should 3272132718Skanbe updated in @var{fs}. 3273132718Skan@end defmac 3274132718Skan 3275169689Skan@defmac TARGET_USES_WEAK_UNWIND_INFO 3276169689SkanA C expression that evaluates to true if the target requires unwind 3277169689Skaninfo to be given comdat linkage. Define it to be @code{1} if comdat 3278169689Skanlinkage is necessary. The default is @code{0}. 3279169689Skan@end defmac 3280169689Skan 328190075Sobrien@node Stack Checking 328290075Sobrien@subsection Specifying How Stack Checking is Done 328390075Sobrien 328490075SobrienGCC will check that stack references are within the boundaries of 328590075Sobrienthe stack, if the @option{-fstack-check} is specified, in one of three ways: 328690075Sobrien 328790075Sobrien@enumerate 328890075Sobrien@item 328990075SobrienIf the value of the @code{STACK_CHECK_BUILTIN} macro is nonzero, GCC 329090075Sobrienwill assume that you have arranged for stack checking to be done at 329190075Sobrienappropriate places in the configuration files, e.g., in 329290075Sobrien@code{TARGET_ASM_FUNCTION_PROLOGUE}. GCC will do not other special 329390075Sobrienprocessing. 329490075Sobrien 329590075Sobrien@item 329690075SobrienIf @code{STACK_CHECK_BUILTIN} is zero and you defined a named pattern 329790075Sobriencalled @code{check_stack} in your @file{md} file, GCC will call that 329890075Sobrienpattern with one argument which is the address to compare the stack 329990075Sobrienvalue against. You must arrange for this pattern to report an error if 330090075Sobrienthe stack pointer is out of range. 330190075Sobrien 330290075Sobrien@item 330390075SobrienIf neither of the above are true, GCC will generate code to periodically 330490075Sobrien``probe'' the stack pointer using the values of the macros defined below. 330590075Sobrien@end enumerate 330690075Sobrien 330790075SobrienNormally, you will use the default values of these macros, so GCC 330890075Sobrienwill use the third approach. 330990075Sobrien 3310132718Skan@defmac STACK_CHECK_BUILTIN 331190075SobrienA nonzero value if stack checking is done by the configuration files in a 331290075Sobrienmachine-dependent manner. You should define this macro if stack checking 331390075Sobrienis require by the ABI of your machine or if you would like to have to stack 331490075Sobrienchecking in some more efficient way than GCC's portable approach. 331590075SobrienThe default value of this macro is zero. 3316132718Skan@end defmac 331790075Sobrien 3318132718Skan@defmac STACK_CHECK_PROBE_INTERVAL 331990075SobrienAn integer representing the interval at which GCC must generate stack 332090075Sobrienprobe instructions. You will normally define this macro to be no larger 332190075Sobrienthan the size of the ``guard pages'' at the end of a stack area. The 332290075Sobriendefault value of 4096 is suitable for most systems. 3323132718Skan@end defmac 332490075Sobrien 3325132718Skan@defmac STACK_CHECK_PROBE_LOAD 332690075SobrienA integer which is nonzero if GCC should perform the stack probe 332790075Sobrienas a load instruction and zero if GCC should use a store instruction. 332890075SobrienThe default is zero, which is the most efficient choice on most systems. 3329132718Skan@end defmac 333090075Sobrien 3331132718Skan@defmac STACK_CHECK_PROTECT 333290075SobrienThe number of bytes of stack needed to recover from a stack overflow, 333390075Sobrienfor languages where such a recovery is supported. The default value of 333490075Sobrien75 words should be adequate for most machines. 3335132718Skan@end defmac 333690075Sobrien 3337132718Skan@defmac STACK_CHECK_MAX_FRAME_SIZE 333890075SobrienThe maximum size of a stack frame, in bytes. GCC will generate probe 333990075Sobrieninstructions in non-leaf functions to ensure at least this many bytes of 334090075Sobrienstack are available. If a stack frame is larger than this size, stack 334190075Sobrienchecking will not be reliable and GCC will issue a warning. The 334290075Sobriendefault is chosen so that GCC only generates one instruction on most 334390075Sobriensystems. You should normally not change the default value of this macro. 3344132718Skan@end defmac 334590075Sobrien 3346132718Skan@defmac STACK_CHECK_FIXED_FRAME_SIZE 334790075SobrienGCC uses this value to generate the above warning message. It 334890075Sobrienrepresents the amount of fixed frame used by a function, not including 334990075Sobrienspace for any callee-saved registers, temporaries and user variables. 335090075SobrienYou need only specify an upper bound for this amount and will normally 335190075Sobrienuse the default of four words. 3352132718Skan@end defmac 335390075Sobrien 3354132718Skan@defmac STACK_CHECK_MAX_VAR_SIZE 335590075SobrienThe maximum size, in bytes, of an object that GCC will place in the 335690075Sobrienfixed area of the stack frame when the user specifies 335790075Sobrien@option{-fstack-check}. 335890075SobrienGCC computed the default from the values of the above macros and you will 335990075Sobriennormally not need to override that default. 3360132718Skan@end defmac 336190075Sobrien 336290075Sobrien@need 2000 336390075Sobrien@node Frame Registers 336490075Sobrien@subsection Registers That Address the Stack Frame 336590075Sobrien 336690075Sobrien@c prevent bad page break with this line 336790075SobrienThis discusses registers that address the stack frame. 336890075Sobrien 3369132718Skan@defmac STACK_POINTER_REGNUM 337090075SobrienThe register number of the stack pointer register, which must also be a 337190075Sobrienfixed register according to @code{FIXED_REGISTERS}. On most machines, 337290075Sobrienthe hardware determines which register this is. 3373132718Skan@end defmac 337490075Sobrien 3375132718Skan@defmac FRAME_POINTER_REGNUM 337690075SobrienThe register number of the frame pointer register, which is used to 337790075Sobrienaccess automatic variables in the stack frame. On some machines, the 337890075Sobrienhardware determines which register this is. On other machines, you can 337990075Sobrienchoose any register you wish for this purpose. 3380132718Skan@end defmac 338190075Sobrien 3382132718Skan@defmac HARD_FRAME_POINTER_REGNUM 338390075SobrienOn some machines the offset between the frame pointer and starting 338490075Sobrienoffset of the automatic variables is not known until after register 338590075Sobrienallocation has been done (for example, because the saved registers are 338690075Sobrienbetween these two locations). On those machines, define 338790075Sobrien@code{FRAME_POINTER_REGNUM} the number of a special, fixed register to 338890075Sobrienbe used internally until the offset is known, and define 338990075Sobrien@code{HARD_FRAME_POINTER_REGNUM} to be the actual hard register number 339090075Sobrienused for the frame pointer. 339190075Sobrien 339290075SobrienYou should define this macro only in the very rare circumstances when it 339390075Sobrienis not possible to calculate the offset between the frame pointer and 339490075Sobrienthe automatic variables until after register allocation has been 339590075Sobriencompleted. When this macro is defined, you must also indicate in your 339690075Sobriendefinition of @code{ELIMINABLE_REGS} how to eliminate 339790075Sobrien@code{FRAME_POINTER_REGNUM} into either @code{HARD_FRAME_POINTER_REGNUM} 339890075Sobrienor @code{STACK_POINTER_REGNUM}. 339990075Sobrien 340090075SobrienDo not define this macro if it would be the same as 340190075Sobrien@code{FRAME_POINTER_REGNUM}. 3402132718Skan@end defmac 340390075Sobrien 3404132718Skan@defmac ARG_POINTER_REGNUM 340590075SobrienThe register number of the arg pointer register, which is used to access 340690075Sobrienthe function's argument list. On some machines, this is the same as the 340790075Sobrienframe pointer register. On some machines, the hardware determines which 340890075Sobrienregister this is. On other machines, you can choose any register you 340990075Sobrienwish for this purpose. If this is not the same register as the frame 341090075Sobrienpointer register, then you must mark it as a fixed register according to 341190075Sobrien@code{FIXED_REGISTERS}, or arrange to be able to eliminate it 341290075Sobrien(@pxref{Elimination}). 3413132718Skan@end defmac 341490075Sobrien 3415132718Skan@defmac RETURN_ADDRESS_POINTER_REGNUM 341690075SobrienThe register number of the return address pointer register, which is used to 341790075Sobrienaccess the current function's return address from the stack. On some 341890075Sobrienmachines, the return address is not at a fixed offset from the frame 341990075Sobrienpointer or stack pointer or argument pointer. This register can be defined 342090075Sobriento point to the return address on the stack, and then be converted by 342190075Sobrien@code{ELIMINABLE_REGS} into either the frame pointer or stack pointer. 342290075Sobrien 342390075SobrienDo not define this macro unless there is no other way to get the return 342490075Sobrienaddress from the stack. 3425132718Skan@end defmac 342690075Sobrien 3427132718Skan@defmac STATIC_CHAIN_REGNUM 3428132718Skan@defmacx STATIC_CHAIN_INCOMING_REGNUM 342990075SobrienRegister numbers used for passing a function's static chain pointer. If 343090075Sobrienregister windows are used, the register number as seen by the called 343190075Sobrienfunction is @code{STATIC_CHAIN_INCOMING_REGNUM}, while the register 343290075Sobriennumber as seen by the calling function is @code{STATIC_CHAIN_REGNUM}. If 343390075Sobrienthese registers are the same, @code{STATIC_CHAIN_INCOMING_REGNUM} need 343490075Sobriennot be defined. 343590075Sobrien 343690075SobrienThe static chain register need not be a fixed register. 343790075Sobrien 343890075SobrienIf the static chain is passed in memory, these macros should not be 343990075Sobriendefined; instead, the next two macros should be defined. 3440132718Skan@end defmac 344190075Sobrien 3442132718Skan@defmac STATIC_CHAIN 3443132718Skan@defmacx STATIC_CHAIN_INCOMING 344490075SobrienIf the static chain is passed in memory, these macros provide rtx giving 344590075Sobrien@code{mem} expressions that denote where they are stored. 344690075Sobrien@code{STATIC_CHAIN} and @code{STATIC_CHAIN_INCOMING} give the locations 344790075Sobrienas seen by the calling and called functions, respectively. Often the former 344890075Sobrienwill be at an offset from the stack pointer and the latter at an offset from 344990075Sobrienthe frame pointer. 345090075Sobrien 345190075Sobrien@findex stack_pointer_rtx 345290075Sobrien@findex frame_pointer_rtx 345390075Sobrien@findex arg_pointer_rtx 345490075SobrienThe variables @code{stack_pointer_rtx}, @code{frame_pointer_rtx}, and 345590075Sobrien@code{arg_pointer_rtx} will have been initialized prior to the use of these 345690075Sobrienmacros and should be used to refer to those items. 345790075Sobrien 345890075SobrienIf the static chain is passed in a register, the two previous macros should 345990075Sobrienbe defined instead. 3460132718Skan@end defmac 346190075Sobrien 3462132718Skan@defmac DWARF_FRAME_REGISTERS 346390075SobrienThis macro specifies the maximum number of hard registers that can be 346490075Sobriensaved in a call frame. This is used to size data structures used in 346590075SobrienDWARF2 exception handling. 346690075Sobrien 346790075SobrienPrior to GCC 3.0, this macro was needed in order to establish a stable 346890075Sobrienexception handling ABI in the face of adding new hard registers for ISA 346990075Sobrienextensions. In GCC 3.0 and later, the EH ABI is insulated from changes 347090075Sobrienin the number of hard registers. Nevertheless, this macro can still be 347190075Sobrienused to reduce the runtime memory requirements of the exception handling 347290075Sobrienroutines, which can be substantial if the ISA contains a lot of 347390075Sobrienregisters that are not call-saved. 347490075Sobrien 347590075SobrienIf this macro is not defined, it defaults to 347690075Sobrien@code{FIRST_PSEUDO_REGISTER}. 3477132718Skan@end defmac 347890075Sobrien 3479132718Skan@defmac PRE_GCC3_DWARF_FRAME_REGISTERS 348090075Sobrien 348190075SobrienThis macro is similar to @code{DWARF_FRAME_REGISTERS}, but is provided 348290075Sobrienfor backward compatibility in pre GCC 3.0 compiled code. 348390075Sobrien 348490075SobrienIf this macro is not defined, it defaults to 348590075Sobrien@code{DWARF_FRAME_REGISTERS}. 3486132718Skan@end defmac 348790075Sobrien 3488132718Skan@defmac DWARF_REG_TO_UNWIND_COLUMN (@var{regno}) 348990075Sobrien 3490132718SkanDefine this macro if the target's representation for dwarf registers 3491132718Skanis different than the internal representation for unwind column. 3492132718SkanGiven a dwarf register, this macro should return the internal unwind 3493132718Skancolumn number to use instead. 3494132718Skan 3495132718SkanSee the PowerPC's SPE target for an example. 3496132718Skan@end defmac 3497132718Skan 3498132718Skan@defmac DWARF_FRAME_REGNUM (@var{regno}) 3499132718Skan 3500132718SkanDefine this macro if the target's representation for dwarf registers 3501132718Skanused in .eh_frame or .debug_frame is different from that used in other 3502132718Skandebug info sections. Given a GCC hard register number, this macro 3503132718Skanshould return the .eh_frame register number. The default is 3504132718Skan@code{DBX_REGISTER_NUMBER (@var{regno})}. 3505132718Skan 3506132718Skan@end defmac 3507132718Skan 3508132718Skan@defmac DWARF2_FRAME_REG_OUT (@var{regno}, @var{for_eh}) 3509132718Skan 3510132718SkanDefine this macro to map register numbers held in the call frame info 3511132718Skanthat GCC has collected using @code{DWARF_FRAME_REGNUM} to those that 3512132718Skanshould be output in .debug_frame (@code{@var{for_eh}} is zero) and 3513169689Skan.eh_frame (@code{@var{for_eh}} is nonzero). The default is to 3514132718Skanreturn @code{@var{regno}}. 3515132718Skan 3516132718Skan@end defmac 3517132718Skan 351890075Sobrien@node Elimination 351990075Sobrien@subsection Eliminating Frame Pointer and Arg Pointer 352090075Sobrien 352190075Sobrien@c prevent bad page break with this line 352290075SobrienThis is about eliminating the frame pointer and arg pointer. 352390075Sobrien 3524132718Skan@defmac FRAME_POINTER_REQUIRED 352590075SobrienA C expression which is nonzero if a function must have and use a frame 352690075Sobrienpointer. This expression is evaluated in the reload pass. If its value is 352790075Sobriennonzero the function will have a frame pointer. 352890075Sobrien 352990075SobrienThe expression can in principle examine the current function and decide 353090075Sobrienaccording to the facts, but on most machines the constant 0 or the 353190075Sobrienconstant 1 suffices. Use 0 when the machine allows code to be generated 353290075Sobrienwith no frame pointer, and doing so saves some time or space. Use 1 353390075Sobrienwhen there is no possible advantage to avoiding a frame pointer. 353490075Sobrien 353590075SobrienIn certain cases, the compiler does not know how to produce valid code 353690075Sobrienwithout a frame pointer. The compiler recognizes those cases and 353790075Sobrienautomatically gives the function a frame pointer regardless of what 353890075Sobrien@code{FRAME_POINTER_REQUIRED} says. You don't need to worry about 353990075Sobrienthem. 354090075Sobrien 354190075SobrienIn a function that does not require a frame pointer, the frame pointer 354290075Sobrienregister can be allocated for ordinary usage, unless you mark it as a 354390075Sobrienfixed register. See @code{FIXED_REGISTERS} for more information. 3544132718Skan@end defmac 354590075Sobrien 354690075Sobrien@findex get_frame_size 3547132718Skan@defmac INITIAL_FRAME_POINTER_OFFSET (@var{depth-var}) 354890075SobrienA C statement to store in the variable @var{depth-var} the difference 354990075Sobrienbetween the frame pointer and the stack pointer values immediately after 355090075Sobrienthe function prologue. The value would be computed from information 355190075Sobriensuch as the result of @code{get_frame_size ()} and the tables of 355290075Sobrienregisters @code{regs_ever_live} and @code{call_used_regs}. 355390075Sobrien 355490075SobrienIf @code{ELIMINABLE_REGS} is defined, this macro will be not be used and 355590075Sobrienneed not be defined. Otherwise, it must be defined even if 355690075Sobrien@code{FRAME_POINTER_REQUIRED} is defined to always be true; in that 355790075Sobriencase, you may set @var{depth-var} to anything. 3558132718Skan@end defmac 355990075Sobrien 3560132718Skan@defmac ELIMINABLE_REGS 356190075SobrienIf defined, this macro specifies a table of register pairs used to 356290075Sobrieneliminate unneeded registers that point into the stack frame. If it is not 356390075Sobriendefined, the only elimination attempted by the compiler is to replace 356490075Sobrienreferences to the frame pointer with references to the stack pointer. 356590075Sobrien 356690075SobrienThe definition of this macro is a list of structure initializations, each 356790075Sobrienof which specifies an original and replacement register. 356890075Sobrien 356990075SobrienOn some machines, the position of the argument pointer is not known until 357090075Sobrienthe compilation is completed. In such a case, a separate hard register 357190075Sobrienmust be used for the argument pointer. This register can be eliminated by 357290075Sobrienreplacing it with either the frame pointer or the argument pointer, 357390075Sobriendepending on whether or not the frame pointer has been eliminated. 357490075Sobrien 357590075SobrienIn this case, you might specify: 3576132718Skan@smallexample 357790075Sobrien#define ELIMINABLE_REGS \ 357890075Sobrien@{@{ARG_POINTER_REGNUM, STACK_POINTER_REGNUM@}, \ 357990075Sobrien @{ARG_POINTER_REGNUM, FRAME_POINTER_REGNUM@}, \ 358090075Sobrien @{FRAME_POINTER_REGNUM, STACK_POINTER_REGNUM@}@} 3581132718Skan@end smallexample 358290075Sobrien 358390075SobrienNote that the elimination of the argument pointer with the stack pointer is 358490075Sobrienspecified first since that is the preferred elimination. 3585132718Skan@end defmac 358690075Sobrien 3587132718Skan@defmac CAN_ELIMINATE (@var{from-reg}, @var{to-reg}) 358890075SobrienA C expression that returns nonzero if the compiler is allowed to try 358990075Sobriento replace register number @var{from-reg} with register number 359090075Sobrien@var{to-reg}. This macro need only be defined if @code{ELIMINABLE_REGS} 359190075Sobrienis defined, and will usually be the constant 1, since most of the cases 359290075Sobrienpreventing register elimination are things that the compiler already 359390075Sobrienknows about. 3594132718Skan@end defmac 359590075Sobrien 3596132718Skan@defmac INITIAL_ELIMINATION_OFFSET (@var{from-reg}, @var{to-reg}, @var{offset-var}) 359790075SobrienThis macro is similar to @code{INITIAL_FRAME_POINTER_OFFSET}. It 359890075Sobrienspecifies the initial difference between the specified pair of 359990075Sobrienregisters. This macro must be defined if @code{ELIMINABLE_REGS} is 360090075Sobriendefined. 3601132718Skan@end defmac 360290075Sobrien 360390075Sobrien@node Stack Arguments 360490075Sobrien@subsection Passing Function Arguments on the Stack 360590075Sobrien@cindex arguments on stack 360690075Sobrien@cindex stack arguments 360790075Sobrien 360890075SobrienThe macros in this section control how arguments are passed 360990075Sobrienon the stack. See the following section for other macros that 361090075Sobriencontrol passing certain arguments in registers. 361190075Sobrien 3612132718Skan@deftypefn {Target Hook} bool TARGET_PROMOTE_PROTOTYPES (tree @var{fntype}) 3613132718SkanThis target hook returns @code{true} if an argument declared in a 3614132718Skanprototype as an integral type smaller than @code{int} should actually be 3615132718Skanpassed as an @code{int}. In addition to avoiding errors in certain 3616132718Skancases of mismatch, it also makes for better code on certain machines. 3617132718SkanThe default is to not promote prototypes. 3618132718Skan@end deftypefn 361990075Sobrien 3620132718Skan@defmac PUSH_ARGS 362190075SobrienA C expression. If nonzero, push insns will be used to pass 362290075Sobrienoutgoing arguments. 362390075SobrienIf the target machine does not have a push instruction, set it to zero. 362490075SobrienThat directs GCC to use an alternate strategy: to 362590075Sobrienallocate the entire argument block and then store the arguments into 362690075Sobrienit. When @code{PUSH_ARGS} is nonzero, @code{PUSH_ROUNDING} must be defined too. 3627132718Skan@end defmac 362890075Sobrien 3629132718Skan@defmac PUSH_ARGS_REVERSED 3630132718SkanA C expression. If nonzero, function arguments will be evaluated from 3631132718Skanlast to first, rather than from first to last. If this macro is not 3632132718Skandefined, it defaults to @code{PUSH_ARGS} on targets where the stack 3633132718Skanand args grow in opposite directions, and 0 otherwise. 3634132718Skan@end defmac 3635132718Skan 3636132718Skan@defmac PUSH_ROUNDING (@var{npushed}) 363790075SobrienA C expression that is the number of bytes actually pushed onto the 363890075Sobrienstack when an instruction attempts to push @var{npushed} bytes. 363990075Sobrien 364090075SobrienOn some machines, the definition 364190075Sobrien 3642132718Skan@smallexample 364390075Sobrien#define PUSH_ROUNDING(BYTES) (BYTES) 3644132718Skan@end smallexample 364590075Sobrien 364690075Sobrien@noindent 364790075Sobrienwill suffice. But on other machines, instructions that appear 364890075Sobriento push one byte actually push two bytes in an attempt to maintain 364990075Sobrienalignment. Then the definition should be 365090075Sobrien 3651132718Skan@smallexample 365290075Sobrien#define PUSH_ROUNDING(BYTES) (((BYTES) + 1) & ~1) 3653132718Skan@end smallexample 3654132718Skan@end defmac 365590075Sobrien 365690075Sobrien@findex current_function_outgoing_args_size 3657132718Skan@defmac ACCUMULATE_OUTGOING_ARGS 365890075SobrienA C expression. If nonzero, the maximum amount of space required for outgoing arguments 365990075Sobrienwill be computed and placed into the variable 366090075Sobrien@code{current_function_outgoing_args_size}. No space will be pushed 366190075Sobrienonto the stack for each call; instead, the function prologue should 366290075Sobrienincrease the stack frame size by this amount. 366390075Sobrien 366490075SobrienSetting both @code{PUSH_ARGS} and @code{ACCUMULATE_OUTGOING_ARGS} 366590075Sobrienis not proper. 3666132718Skan@end defmac 366790075Sobrien 3668132718Skan@defmac REG_PARM_STACK_SPACE (@var{fndecl}) 366990075SobrienDefine this macro if functions should assume that stack space has been 367090075Sobrienallocated for arguments even when their values are passed in 367190075Sobrienregisters. 367290075Sobrien 367390075SobrienThe value of this macro is the size, in bytes, of the area reserved for 367490075Sobrienarguments passed in registers for the function represented by @var{fndecl}, 367590075Sobrienwhich can be zero if GCC is calling a library function. 367690075Sobrien 367790075SobrienThis space can be allocated by the caller, or be a part of the 367890075Sobrienmachine-dependent stack frame: @code{OUTGOING_REG_PARM_STACK_SPACE} says 367990075Sobrienwhich. 3680132718Skan@end defmac 368190075Sobrien@c above is overfull. not sure what to do. --mew 5feb93 did 368290075Sobrien@c something, not sure if it looks good. --mew 10feb93 368390075Sobrien 3684132718Skan@defmac OUTGOING_REG_PARM_STACK_SPACE 368590075SobrienDefine this if it is the responsibility of the caller to allocate the area 368690075Sobrienreserved for arguments passed in registers. 368790075Sobrien 368890075SobrienIf @code{ACCUMULATE_OUTGOING_ARGS} is defined, this macro controls 368990075Sobrienwhether the space for these arguments counts in the value of 369090075Sobrien@code{current_function_outgoing_args_size}. 3691132718Skan@end defmac 369290075Sobrien 3693132718Skan@defmac STACK_PARMS_IN_REG_PARM_AREA 369490075SobrienDefine this macro if @code{REG_PARM_STACK_SPACE} is defined, but the 369590075Sobrienstack parameters don't skip the area specified by it. 369690075Sobrien@c i changed this, makes more sens and it should have taken care of the 369790075Sobrien@c overfull.. not as specific, tho. --mew 5feb93 369890075Sobrien 369990075SobrienNormally, when a parameter is not passed in registers, it is placed on the 370090075Sobrienstack beyond the @code{REG_PARM_STACK_SPACE} area. Defining this macro 370190075Sobriensuppresses this behavior and causes the parameter to be passed on the 370290075Sobrienstack in its natural location. 3703132718Skan@end defmac 370490075Sobrien 3705132718Skan@defmac RETURN_POPS_ARGS (@var{fundecl}, @var{funtype}, @var{stack-size}) 370690075SobrienA C expression that should indicate the number of bytes of its own 370790075Sobrienarguments that a function pops on returning, or 0 if the 370890075Sobrienfunction pops no arguments and the caller must therefore pop them all 370990075Sobrienafter the function returns. 371090075Sobrien 371190075Sobrien@var{fundecl} is a C variable whose value is a tree node that describes 371290075Sobrienthe function in question. Normally it is a node of type 371390075Sobrien@code{FUNCTION_DECL} that describes the declaration of the function. 371490075SobrienFrom this you can obtain the @code{DECL_ATTRIBUTES} of the function. 371590075Sobrien 371690075Sobrien@var{funtype} is a C variable whose value is a tree node that 371790075Sobriendescribes the function in question. Normally it is a node of type 371890075Sobrien@code{FUNCTION_TYPE} that describes the data type of the function. 371990075SobrienFrom this it is possible to obtain the data types of the value and 372090075Sobrienarguments (if known). 372190075Sobrien 372290075SobrienWhen a call to a library function is being considered, @var{fundecl} 372390075Sobrienwill contain an identifier node for the library function. Thus, if 372490075Sobrienyou need to distinguish among various library functions, you can do so 372590075Sobrienby their names. Note that ``library function'' in this context means 372690075Sobriena function used to perform arithmetic, whose name is known specially 372790075Sobrienin the compiler and was not mentioned in the C code being compiled. 372890075Sobrien 372990075Sobrien@var{stack-size} is the number of bytes of arguments passed on the 373090075Sobrienstack. If a variable number of bytes is passed, it is zero, and 373190075Sobrienargument popping will always be the responsibility of the calling function. 373290075Sobrien 373390075SobrienOn the VAX, all functions always pop their arguments, so the definition 373490075Sobrienof this macro is @var{stack-size}. On the 68000, using the standard 373590075Sobriencalling convention, no functions pop their arguments, so the value of 373690075Sobrienthe macro is always 0 in this case. But an alternative calling 373790075Sobrienconvention is available in which functions that take a fixed number of 373890075Sobrienarguments pop them but other functions (such as @code{printf}) pop 373990075Sobriennothing (the caller pops all). When this convention is in use, 374090075Sobrien@var{funtype} is examined to determine whether a function takes a fixed 374190075Sobriennumber of arguments. 3742132718Skan@end defmac 374396263Sobrien 3744132718Skan@defmac CALL_POPS_ARGS (@var{cum}) 374596263SobrienA C expression that should indicate the number of bytes a call sequence 374696263Sobrienpops off the stack. It is added to the value of @code{RETURN_POPS_ARGS} 374796263Sobrienwhen compiling a function call. 374896263Sobrien 374996263Sobrien@var{cum} is the variable in which all arguments to the called function 375096263Sobrienhave been accumulated. 375196263Sobrien 375296263SobrienOn certain architectures, such as the SH5, a call trampoline is used 375396263Sobrienthat pops certain registers off the stack, depending on the arguments 375496263Sobrienthat have been passed to the function. Since this is a property of the 375596263Sobriencall site, not of the called function, @code{RETURN_POPS_ARGS} is not 375696263Sobrienappropriate. 3757132718Skan@end defmac 375896263Sobrien 375990075Sobrien@node Register Arguments 376090075Sobrien@subsection Passing Arguments in Registers 376190075Sobrien@cindex arguments in registers 376290075Sobrien@cindex registers arguments 376390075Sobrien 376490075SobrienThis section describes the macros which let you control how various 376590075Sobrientypes of arguments are passed in registers or how they are arranged in 376690075Sobrienthe stack. 376790075Sobrien 3768132718Skan@defmac FUNCTION_ARG (@var{cum}, @var{mode}, @var{type}, @var{named}) 376990075SobrienA C expression that controls whether a function argument is passed 377090075Sobrienin a register, and which register. 377190075Sobrien 377290075SobrienThe arguments are @var{cum}, which summarizes all the previous 377390075Sobrienarguments; @var{mode}, the machine mode of the argument; @var{type}, 377490075Sobrienthe data type of the argument as a tree node or 0 if that is not known 377590075Sobrien(which happens for C support library functions); and @var{named}, 377690075Sobrienwhich is 1 for an ordinary argument and 0 for nameless arguments that 377790075Sobriencorrespond to @samp{@dots{}} in the called function's prototype. 377890075Sobrien@var{type} can be an incomplete type if a syntax error has previously 377990075Sobrienoccurred. 378090075Sobrien 378190075SobrienThe value of the expression is usually either a @code{reg} RTX for the 378290075Sobrienhard register in which to pass the argument, or zero to pass the 378390075Sobrienargument on the stack. 378490075Sobrien 378590075SobrienFor machines like the VAX and 68000, where normally all arguments are 378690075Sobrienpushed, zero suffices as a definition. 378790075Sobrien 378890075SobrienThe value of the expression can also be a @code{parallel} RTX@. This is 378990075Sobrienused when an argument is passed in multiple locations. The mode of the 3790132718Skan@code{parallel} should be the mode of the entire argument. The 379190075Sobrien@code{parallel} holds any number of @code{expr_list} pairs; each one 379290075Sobriendescribes where part of the argument is passed. In each 379390075Sobrien@code{expr_list} the first operand must be a @code{reg} RTX for the hard 379490075Sobrienregister in which to pass this part of the argument, and the mode of the 379590075Sobrienregister RTX indicates how large this part of the argument is. The 379690075Sobriensecond operand of the @code{expr_list} is a @code{const_int} which gives 379790075Sobrienthe offset in bytes into the entire argument of where this part starts. 379890075SobrienAs a special exception the first @code{expr_list} in the @code{parallel} 379990075SobrienRTX may have a first operand of zero. This indicates that the entire 380090075Sobrienargument is also stored on the stack. 380190075Sobrien 380290075SobrienThe last time this macro is called, it is called with @code{MODE == 380390075SobrienVOIDmode}, and its result is passed to the @code{call} or @code{call_value} 380490075Sobrienpattern as operands 2 and 3 respectively. 380590075Sobrien 380690075Sobrien@cindex @file{stdarg.h} and register arguments 380790075SobrienThe usual way to make the ISO library @file{stdarg.h} work on a machine 380890075Sobrienwhere some arguments are usually passed in registers, is to cause 380990075Sobriennameless arguments to be passed on the stack instead. This is done 381090075Sobrienby making @code{FUNCTION_ARG} return 0 whenever @var{named} is 0. 381190075Sobrien 3812169689Skan@cindex @code{TARGET_MUST_PASS_IN_STACK}, and @code{FUNCTION_ARG} 381390075Sobrien@cindex @code{REG_PARM_STACK_SPACE}, and @code{FUNCTION_ARG} 3814169689SkanYou may use the hook @code{targetm.calls.must_pass_in_stack} 381590075Sobrienin the definition of this macro to determine if this argument is of a 381690075Sobrientype that must be passed in the stack. If @code{REG_PARM_STACK_SPACE} 381790075Sobrienis not defined and @code{FUNCTION_ARG} returns nonzero for such an 381890075Sobrienargument, the compiler will abort. If @code{REG_PARM_STACK_SPACE} is 381990075Sobriendefined, the argument will be computed in the stack and then loaded into 382090075Sobriena register. 3821132718Skan@end defmac 382290075Sobrien 3823169689Skan@deftypefn {Target Hook} bool TARGET_MUST_PASS_IN_STACK (enum machine_mode @var{mode}, tree @var{type}) 3824169689SkanThis target hook should return @code{true} if we should not pass @var{type} 3825169689Skansolely in registers. The file @file{expr.h} defines a 382690075Sobriendefinition that is usually appropriate, refer to @file{expr.h} for additional 382790075Sobriendocumentation. 3828169689Skan@end deftypefn 382990075Sobrien 3830132718Skan@defmac FUNCTION_INCOMING_ARG (@var{cum}, @var{mode}, @var{type}, @var{named}) 383190075SobrienDefine this macro if the target machine has ``register windows'', so 383290075Sobrienthat the register in which a function sees an arguments is not 383390075Sobriennecessarily the same as the one in which the caller passed the 383490075Sobrienargument. 383590075Sobrien 383690075SobrienFor such machines, @code{FUNCTION_ARG} computes the register in which 383790075Sobrienthe caller passes the value, and @code{FUNCTION_INCOMING_ARG} should 383890075Sobrienbe defined in a similar fashion to tell the function being called 383990075Sobrienwhere the arguments will arrive. 384090075Sobrien 384190075SobrienIf @code{FUNCTION_INCOMING_ARG} is not defined, @code{FUNCTION_ARG} 384290075Sobrienserves both purposes. 3843132718Skan@end defmac 384490075Sobrien 3845169689Skan@deftypefn {Target Hook} int TARGET_ARG_PARTIAL_BYTES (CUMULATIVE_ARGS *@var{cum}, enum machine_mode @var{mode}, tree @var{type}, bool @var{named}) 3846169689SkanThis target hook returns the number of bytes at the beginning of an 3847169689Skanargument that must be put in registers. The value must be zero for 384890075Sobrienarguments that are passed entirely in registers or that are entirely 384990075Sobrienpushed on the stack. 385090075Sobrien 385190075SobrienOn some machines, certain arguments must be passed partially in 385290075Sobrienregisters and partially in memory. On these machines, typically the 3853169689Skanfirst few words of arguments are passed in registers, and the rest 385490075Sobrienon the stack. If a multi-word argument (a @code{double} or a 385590075Sobrienstructure) crosses that boundary, its first few words must be passed 385690075Sobrienin registers and the rest must be pushed. This macro tells the 3857169689Skancompiler when this occurs, and how many bytes should go in registers. 385890075Sobrien 385990075Sobrien@code{FUNCTION_ARG} for these arguments should return the first 386090075Sobrienregister to be used by the caller for this argument; likewise 386190075Sobrien@code{FUNCTION_INCOMING_ARG}, for the called function. 3862169689Skan@end deftypefn 386390075Sobrien 3864169689Skan@deftypefn {Target Hook} bool TARGET_PASS_BY_REFERENCE (CUMULATIVE_ARGS *@var{cum}, enum machine_mode @var{mode}, tree @var{type}, bool @var{named}) 3865169689SkanThis target hook should return @code{true} if an argument at the 3866169689Skanposition indicated by @var{cum} should be passed by reference. This 3867169689Skanpredicate is queried after target independent reasons for being 3868169689Skanpassed by reference, such as @code{TREE_ADDRESSABLE (type)}. 3869169689Skan 3870169689SkanIf the hook returns true, a copy of that argument is made in memory and a 387190075Sobrienpointer to the argument is passed instead of the argument itself. 387290075SobrienThe pointer is passed in whatever way is appropriate for passing a pointer 387390075Sobriento that type. 3874169689Skan@end deftypefn 387590075Sobrien 3876169689Skan@deftypefn {Target Hook} bool TARGET_CALLEE_COPIES (CUMULATIVE_ARGS *@var{cum}, enum machine_mode @var{mode}, tree @var{type}, bool @var{named}) 3877169689SkanThe function argument described by the parameters to this hook is 3878169689Skanknown to be passed by reference. The hook should return true if the 3879169689Skanfunction argument should be copied by the callee instead of copied 3880169689Skanby the caller. 388190075Sobrien 3882169689SkanFor any argument for which the hook returns true, if it can be 3883169689Skandetermined that the argument is not modified, then a copy need 3884169689Skannot be generated. 388590075Sobrien 3886169689SkanThe default version of this hook always returns false. 3887169689Skan@end deftypefn 3888169689Skan 3889132718Skan@defmac CUMULATIVE_ARGS 389090075SobrienA C type for declaring a variable that is used as the first argument of 389190075Sobrien@code{FUNCTION_ARG} and other related values. For some target machines, 389290075Sobrienthe type @code{int} suffices and can hold the number of bytes of 389390075Sobrienargument so far. 389490075Sobrien 389590075SobrienThere is no need to record in @code{CUMULATIVE_ARGS} anything about the 389690075Sobrienarguments that have been passed on the stack. The compiler has other 389790075Sobrienvariables to keep track of that. For target machines on which all 389890075Sobrienarguments are passed on the stack, there is no need to store anything in 389990075Sobrien@code{CUMULATIVE_ARGS}; however, the data structure must exist and 390090075Sobrienshould not be empty, so use @code{int}. 3901132718Skan@end defmac 390290075Sobrien 3903132718Skan@defmac INIT_CUMULATIVE_ARGS (@var{cum}, @var{fntype}, @var{libname}, @var{fndecl}, @var{n_named_args}) 3904132718SkanA C statement (sans semicolon) for initializing the variable 3905132718Skan@var{cum} for the state at the beginning of the argument list. The 3906132718Skanvariable has type @code{CUMULATIVE_ARGS}. The value of @var{fntype} 3907132718Skanis the tree node for the data type of the function which will receive 3908132718Skanthe args, or 0 if the args are to a compiler support library function. 3909132718SkanFor direct calls that are not libcalls, @var{fndecl} contain the 3910132718Skandeclaration node of the function. @var{fndecl} is also set when 391190075Sobrien@code{INIT_CUMULATIVE_ARGS} is used to find arguments for the function 3912132718Skanbeing compiled. @var{n_named_args} is set to the number of named 3913132718Skanarguments, including a structure return address if it is passed as a 3914132718Skanparameter, when making a call. When processing incoming arguments, 3915169689Skan@var{n_named_args} is set to @minus{}1. 391690075Sobrien 391790075SobrienWhen processing a call to a compiler support library function, 391890075Sobrien@var{libname} identifies which one. It is a @code{symbol_ref} rtx which 391990075Sobriencontains the name of the function, as a string. @var{libname} is 0 when 392090075Sobrienan ordinary C function call is being processed. Thus, each time this 392190075Sobrienmacro is called, either @var{libname} or @var{fntype} is nonzero, but 392290075Sobriennever both of them at once. 3923132718Skan@end defmac 392490075Sobrien 3925132718Skan@defmac INIT_CUMULATIVE_LIBCALL_ARGS (@var{cum}, @var{mode}, @var{libname}) 392690075SobrienLike @code{INIT_CUMULATIVE_ARGS} but only used for outgoing libcalls, 392790075Sobrienit gets a @code{MODE} argument instead of @var{fntype}, that would be 392890075Sobrien@code{NULL}. @var{indirect} would always be zero, too. If this macro 392990075Sobrienis not defined, @code{INIT_CUMULATIVE_ARGS (cum, NULL_RTX, libname, 393090075Sobrien0)} is used instead. 3931132718Skan@end defmac 393290075Sobrien 3933132718Skan@defmac INIT_CUMULATIVE_INCOMING_ARGS (@var{cum}, @var{fntype}, @var{libname}) 393490075SobrienLike @code{INIT_CUMULATIVE_ARGS} but overrides it for the purposes of 393590075Sobrienfinding the arguments for the function being compiled. If this macro is 393690075Sobrienundefined, @code{INIT_CUMULATIVE_ARGS} is used instead. 393790075Sobrien 393890075SobrienThe value passed for @var{libname} is always 0, since library routines 393990075Sobrienwith special calling conventions are never compiled with GCC@. The 394090075Sobrienargument @var{libname} exists for symmetry with 394190075Sobrien@code{INIT_CUMULATIVE_ARGS}. 394290075Sobrien@c could use "this macro" in place of @code{INIT_CUMULATIVE_ARGS}, maybe. 394390075Sobrien@c --mew 5feb93 i switched the order of the sentences. --mew 10feb93 3944132718Skan@end defmac 394590075Sobrien 3946132718Skan@defmac FUNCTION_ARG_ADVANCE (@var{cum}, @var{mode}, @var{type}, @var{named}) 394790075SobrienA C statement (sans semicolon) to update the summarizer variable 394890075Sobrien@var{cum} to advance past an argument in the argument list. The 394990075Sobrienvalues @var{mode}, @var{type} and @var{named} describe that argument. 395090075SobrienOnce this is done, the variable @var{cum} is suitable for analyzing 395190075Sobrienthe @emph{following} argument with @code{FUNCTION_ARG}, etc. 395290075Sobrien 395390075SobrienThis macro need not do anything if the argument in question was passed 395490075Sobrienon the stack. The compiler knows how to track the amount of stack space 395590075Sobrienused for arguments without any special help. 3956132718Skan@end defmac 395790075Sobrien 3958132718Skan@defmac FUNCTION_ARG_PADDING (@var{mode}, @var{type}) 395990075SobrienIf defined, a C expression which determines whether, and in which direction, 396090075Sobriento pad out an argument with extra space. The value should be of type 396190075Sobrien@code{enum direction}: either @code{upward} to pad above the argument, 396290075Sobrien@code{downward} to pad below, or @code{none} to inhibit padding. 396390075Sobrien 396490075SobrienThe @emph{amount} of padding is always just enough to reach the next 396590075Sobrienmultiple of @code{FUNCTION_ARG_BOUNDARY}; this macro does not control 396690075Sobrienit. 396790075Sobrien 396890075SobrienThis macro has a default definition which is right for most systems. 396990075SobrienFor little-endian machines, the default is to pad upward. For 397090075Sobrienbig-endian machines, the default is to pad downward for an argument of 397190075Sobrienconstant size shorter than an @code{int}, and upward otherwise. 3972132718Skan@end defmac 397390075Sobrien 3974132718Skan@defmac PAD_VARARGS_DOWN 397590075SobrienIf defined, a C expression which determines whether the default 397690075Sobrienimplementation of va_arg will attempt to pad down before reading the 397790075Sobriennext argument, if that argument is smaller than its aligned space as 397890075Sobriencontrolled by @code{PARM_BOUNDARY}. If this macro is not defined, all such 397990075Sobrienarguments are padded down if @code{BYTES_BIG_ENDIAN} is true. 3980132718Skan@end defmac 398190075Sobrien 3982132718Skan@defmac BLOCK_REG_PADDING (@var{mode}, @var{type}, @var{first}) 3983132718SkanSpecify padding for the last element of a block move between registers and 3984132718Skanmemory. @var{first} is nonzero if this is the only element. Defining this 3985132718Skanmacro allows better control of register function parameters on big-endian 3986132718Skanmachines, without using @code{PARALLEL} rtl. In particular, 3987132718Skan@code{MUST_PASS_IN_STACK} need not test padding and mode of types in 3988132718Skanregisters, as there is no longer a "wrong" part of a register; For example, 3989132718Skana three byte aggregate may be passed in the high part of a register if so 3990132718Skanrequired. 3991132718Skan@end defmac 3992132718Skan 3993132718Skan@defmac FUNCTION_ARG_BOUNDARY (@var{mode}, @var{type}) 399490075SobrienIf defined, a C expression that gives the alignment boundary, in bits, 399590075Sobrienof an argument with the specified mode and type. If it is not defined, 399690075Sobrien@code{PARM_BOUNDARY} is used for all arguments. 3997132718Skan@end defmac 399890075Sobrien 3999132718Skan@defmac FUNCTION_ARG_REGNO_P (@var{regno}) 400090075SobrienA C expression that is nonzero if @var{regno} is the number of a hard 400190075Sobrienregister in which function arguments are sometimes passed. This does 400290075Sobrien@emph{not} include implicit arguments such as the static chain and 400390075Sobrienthe structure-value address. On many machines, no registers can be 400490075Sobrienused for this purpose since all function arguments are pushed on the 400590075Sobrienstack. 4006132718Skan@end defmac 400790075Sobrien 4008132718Skan@deftypefn {Target Hook} bool TARGET_SPLIT_COMPLEX_ARG (tree @var{type}) 4009132718SkanThis hook should return true if parameter of type @var{type} are passed 4010132718Skanas two scalar parameters. By default, GCC will attempt to pack complex 4011132718Skanarguments into the target's word size. Some ABIs require complex arguments 4012132718Skanto be split and treated as their individual components. For example, on 4013132718SkanAIX64, complex floats should be passed in a pair of floating point 4014132718Skanregisters, even though a complex float would fit in one 64-bit floating 4015132718Skanpoint register. 401690075Sobrien 4017132718SkanThe default value of this hook is @code{NULL}, which is treated as always 4018132718Skanfalse. 4019132718Skan@end deftypefn 402090075Sobrien 4021169689Skan@deftypefn {Target Hook} tree TARGET_BUILD_BUILTIN_VA_LIST (void) 4022169689SkanThis hook returns a type node for @code{va_list} for the target. 4023169689SkanThe default version of the hook returns @code{void*}. 4024169689Skan@end deftypefn 4025169689Skan 4026169689Skan@deftypefn {Target Hook} tree TARGET_GIMPLIFY_VA_ARG_EXPR (tree @var{valist}, tree @var{type}, tree *@var{pre_p}, tree *@var{post_p}) 4027169689SkanThis hook performs target-specific gimplification of 4028169689Skan@code{VA_ARG_EXPR}. The first two parameters correspond to the 4029169689Skanarguments to @code{va_arg}; the latter two are as in 4030169689Skan@code{gimplify.c:gimplify_expr}. 4031169689Skan@end deftypefn 4032169689Skan 4033169689Skan@deftypefn {Target Hook} bool TARGET_VALID_POINTER_MODE (enum machine_mode @var{mode}) 4034169689SkanDefine this to return nonzero if the port can handle pointers 4035169689Skanwith machine mode @var{mode}. The default version of this 4036169689Skanhook returns true for both @code{ptr_mode} and @code{Pmode}. 4037169689Skan@end deftypefn 4038169689Skan 4039169689Skan@deftypefn {Target Hook} bool TARGET_SCALAR_MODE_SUPPORTED_P (enum machine_mode @var{mode}) 4040169689SkanDefine this to return nonzero if the port is prepared to handle 4041169689Skaninsns involving scalar mode @var{mode}. For a scalar mode to be 4042169689Skanconsidered supported, all the basic arithmetic and comparisons 4043169689Skanmust work. 4044169689Skan 4045169689SkanThe default version of this hook returns true for any mode 4046169689Skanrequired to handle the basic C types (as defined by the port). 4047169689SkanIncluded here are the double-word arithmetic supported by the 4048169689Skancode in @file{optabs.c}. 4049169689Skan@end deftypefn 4050169689Skan 4051169689Skan@deftypefn {Target Hook} bool TARGET_VECTOR_MODE_SUPPORTED_P (enum machine_mode @var{mode}) 4052169689SkanDefine this to return nonzero if the port is prepared to handle 4053169689Skaninsns involving vector mode @var{mode}. At the very least, it 4054169689Skanmust have move patterns for this mode. 4055169689Skan@end deftypefn 4056169689Skan 405790075Sobrien@node Scalar Return 405890075Sobrien@subsection How Scalar Function Values Are Returned 405990075Sobrien@cindex return values in registers 406090075Sobrien@cindex values, returned by functions 406190075Sobrien@cindex scalars, returned as values 406290075Sobrien 406390075SobrienThis section discusses the macros that control returning scalars as 406490075Sobrienvalues---values that can fit in registers. 406590075Sobrien 4066169689Skan@deftypefn {Target Hook} rtx TARGET_FUNCTION_VALUE (tree @var{ret_type}, tree @var{fn_decl_or_type}, bool @var{outgoing}) 406790075Sobrien 4068169689SkanDefine this to return an RTX representing the place where a function 4069169689Skanreturns or receives a value of data type @var{ret_type}, a tree node 4070169689Skannode representing a data type. @var{fn_decl_or_type} is a tree node 4071169689Skanrepresenting @code{FUNCTION_DECL} or @code{FUNCTION_TYPE} of a 4072169689Skanfunction being called. If @var{outgoing} is false, the hook should 4073169689Skancompute the register in which the caller will see the return value. 4074169689SkanOtherwise, the hook should return an RTX representing the place where 4075169689Skana function returns a value. 407690075Sobrien 4077169689SkanOn many machines, only @code{TYPE_MODE (@var{ret_type})} is relevant. 4078169689Skan(Actually, on most machines, scalar values are returned in the same 4079169689Skanplace regardless of mode.) The value of the expression is usually a 4080169689Skan@code{reg} RTX for the hard register where the return value is stored. 4081169689SkanThe value can also be a @code{parallel} RTX, if the return value is in 4082169689Skanmultiple places. See @code{FUNCTION_ARG} for an explanation of the 4083169689Skan@code{parallel} form. 408490075Sobrien 4085169689SkanIf @code{TARGET_PROMOTE_FUNCTION_RETURN} returns true, you must apply 4086169689Skanthe same promotion rules specified in @code{PROMOTE_MODE} if 4087169689Skan@var{valtype} is a scalar type. 4088169689Skan 408990075SobrienIf the precise function being called is known, @var{func} is a tree 409090075Sobriennode (@code{FUNCTION_DECL}) for it; otherwise, @var{func} is a null 409190075Sobrienpointer. This makes it possible to use a different value-returning 409290075Sobrienconvention for specific functions when all their calls are 409390075Sobrienknown. 409490075Sobrien 4095169689SkanSome target machines have ``register windows'' so that the register in 4096169689Skanwhich a function returns its value is not the same as the one in which 4097169689Skanthe caller sees the value. For such machines, you should return 4098169689Skandifferent RTX depending on @var{outgoing}. 4099169689Skan 4100169689Skan@code{TARGET_FUNCTION_VALUE} is not used for return values with 4101169689Skanaggregate data types, because these are returned in another way. See 4102132718Skan@code{TARGET_STRUCT_VALUE_RTX} and related macros, below. 4103169689Skan@end deftypefn 4104169689Skan 4105169689Skan@defmac FUNCTION_VALUE (@var{valtype}, @var{func}) 4106169689SkanThis macro has been deprecated. Use @code{TARGET_FUNCTION_VALUE} for 4107169689Skana new target instead. 4108132718Skan@end defmac 410990075Sobrien 4110132718Skan@defmac FUNCTION_OUTGOING_VALUE (@var{valtype}, @var{func}) 4111169689SkanThis macro has been deprecated. Use @code{TARGET_FUNCTION_VALUE} for 4112169689Skana new target instead. 4113132718Skan@end defmac 411490075Sobrien 4115132718Skan@defmac LIBCALL_VALUE (@var{mode}) 411690075SobrienA C expression to create an RTX representing the place where a library 411790075Sobrienfunction returns a value of mode @var{mode}. If the precise function 411890075Sobrienbeing called is known, @var{func} is a tree node 411990075Sobrien(@code{FUNCTION_DECL}) for it; otherwise, @var{func} is a null 412090075Sobrienpointer. This makes it possible to use a different value-returning 412190075Sobrienconvention for specific functions when all their calls are 412290075Sobrienknown. 412390075Sobrien 412490075SobrienNote that ``library function'' in this context means a compiler 412590075Sobriensupport routine, used to perform arithmetic, whose name is known 412690075Sobrienspecially by the compiler and was not mentioned in the C code being 412790075Sobriencompiled. 412890075Sobrien 412990075SobrienThe definition of @code{LIBRARY_VALUE} need not be concerned aggregate 413090075Sobriendata types, because none of the library functions returns such types. 4131132718Skan@end defmac 413290075Sobrien 4133132718Skan@defmac FUNCTION_VALUE_REGNO_P (@var{regno}) 413490075SobrienA C expression that is nonzero if @var{regno} is the number of a hard 413590075Sobrienregister in which the values of called function may come back. 413690075Sobrien 413790075SobrienA register whose use for returning values is limited to serving as the 413890075Sobriensecond of a pair (for a value of type @code{double}, say) need not be 413990075Sobrienrecognized by this macro. So for most machines, this definition 414090075Sobriensuffices: 414190075Sobrien 4142132718Skan@smallexample 414390075Sobrien#define FUNCTION_VALUE_REGNO_P(N) ((N) == 0) 4144132718Skan@end smallexample 414590075Sobrien 414690075SobrienIf the machine has register windows, so that the caller and the called 414790075Sobrienfunction use different registers for the return value, this macro 414890075Sobrienshould recognize only the caller's register numbers. 4149132718Skan@end defmac 415090075Sobrien 4151132718Skan@defmac APPLY_RESULT_SIZE 415290075SobrienDefine this macro if @samp{untyped_call} and @samp{untyped_return} 415390075Sobrienneed more space than is implied by @code{FUNCTION_VALUE_REGNO_P} for 415490075Sobriensaving and restoring an arbitrary return value. 4155132718Skan@end defmac 415690075Sobrien 4157132718Skan@deftypefn {Target Hook} bool TARGET_RETURN_IN_MSB (tree @var{type}) 4158132718SkanThis hook should return true if values of type @var{type} are returned 4159132718Skanat the most significant end of a register (in other words, if they are 4160132718Skanpadded at the least significant end). You can assume that @var{type} 4161132718Skanis returned in a register; the caller is required to check this. 4162132718Skan 4163169689SkanNote that the register provided by @code{TARGET_FUNCTION_VALUE} must 4164169689Skanbe able to hold the complete return value. For example, if a 1-, 2- 4165169689Skanor 3-byte structure is returned at the most significant end of a 4166169689Skan4-byte register, @code{TARGET_FUNCTION_VALUE} should provide an 4167169689Skan@code{SImode} rtx. 4168132718Skan@end deftypefn 4169132718Skan 417090075Sobrien@node Aggregate Return 417190075Sobrien@subsection How Large Values Are Returned 417290075Sobrien@cindex aggregates as return values 417390075Sobrien@cindex large return values 417490075Sobrien@cindex returning aggregate values 417590075Sobrien@cindex structure value address 417690075Sobrien 417790075SobrienWhen a function value's mode is @code{BLKmode} (and in some other 4178169689Skancases), the value is not returned according to 4179169689Skan@code{TARGET_FUNCTION_VALUE} (@pxref{Scalar Return}). Instead, the 4180169689Skancaller passes the address of a block of memory in which the value 4181169689Skanshould be stored. This address is called the @dfn{structure value 4182169689Skanaddress}. 418390075Sobrien 418490075SobrienThis section describes how to control returning structure values in 418590075Sobrienmemory. 418690075Sobrien 4187132718Skan@deftypefn {Target Hook} bool TARGET_RETURN_IN_MEMORY (tree @var{type}, tree @var{fntype}) 4188132718SkanThis target hook should return a nonzero value to say to return the 4189132718Skanfunction value in memory, just as large structures are always returned. 4190132718SkanHere @var{type} will be the data type of the value, and @var{fntype} 4191132718Skanwill be the type of the function doing the returning, or @code{NULL} for 4192132718Skanlibcalls. 419390075Sobrien 419490075SobrienNote that values of mode @code{BLKmode} must be explicitly handled 4195132718Skanby this function. Also, the option @option{-fpcc-struct-return} 419690075Sobrientakes effect regardless of this macro. On most systems, it is 4197132718Skanpossible to leave the hook undefined; this causes a default 419890075Sobriendefinition to be used, whose value is the constant 1 for @code{BLKmode} 419990075Sobrienvalues, and 0 otherwise. 420090075Sobrien 4201132718SkanDo not use this hook to indicate that structures and unions should always 420290075Sobrienbe returned in memory. You should instead use @code{DEFAULT_PCC_STRUCT_RETURN} 420390075Sobriento indicate this. 4204132718Skan@end deftypefn 420590075Sobrien 4206132718Skan@defmac DEFAULT_PCC_STRUCT_RETURN 420790075SobrienDefine this macro to be 1 if all structure and union return values must be 420890075Sobrienin memory. Since this results in slower code, this should be defined 420990075Sobrienonly if needed for compatibility with other compilers or with an ABI@. 421090075SobrienIf you define this macro to be 0, then the conventions used for structure 4211132718Skanand union return values are decided by the @code{TARGET_RETURN_IN_MEMORY} 4212132718Skantarget hook. 421390075Sobrien 421490075SobrienIf not defined, this defaults to the value 1. 4215132718Skan@end defmac 421690075Sobrien 4217132718Skan@deftypefn {Target Hook} rtx TARGET_STRUCT_VALUE_RTX (tree @var{fndecl}, int @var{incoming}) 4218132718SkanThis target hook should return the location of the structure value 4219132718Skanaddress (normally a @code{mem} or @code{reg}), or 0 if the address is 4220132718Skanpassed as an ``invisible'' first argument. Note that @var{fndecl} may 4221169689Skanbe @code{NULL}, for libcalls. You do not need to define this target 4222169689Skanhook if the address is always passed as an ``invisible'' first 4223169689Skanargument. 422490075Sobrien 422590075SobrienOn some architectures the place where the structure value address 422690075Sobrienis found by the called function is not the same place that the 422790075Sobriencaller put it. This can be due to register windows, or it could 422890075Sobrienbe because the function prologue moves it to a different place. 4229169689Skan@var{incoming} is @code{1} or @code{2} when the location is needed in 4230169689Skanthe context of the called function, and @code{0} in the context of 4231132718Skanthe caller. 423290075Sobrien 4233169689SkanIf @var{incoming} is nonzero and the address is to be found on the 4234169689Skanstack, return a @code{mem} which refers to the frame pointer. If 4235169689Skan@var{incoming} is @code{2}, the result is being used to fetch the 4236169689Skanstructure value address at the beginning of a function. If you need 4237169689Skanto emit adjusting code, you should do it at this point. 4238132718Skan@end deftypefn 423990075Sobrien 4240132718Skan@defmac PCC_STATIC_STRUCT_RETURN 424190075SobrienDefine this macro if the usual system convention on the target machine 424290075Sobrienfor returning structures and unions is for the called function to return 424390075Sobrienthe address of a static variable containing the value. 424490075Sobrien 424590075SobrienDo not define this if the usual system convention is for the caller to 424690075Sobrienpass an address to the subroutine. 424790075Sobrien 424890075SobrienThis macro has effect in @option{-fpcc-struct-return} mode, but it does 424990075Sobriennothing when you use @option{-freg-struct-return} mode. 4250132718Skan@end defmac 425190075Sobrien 425290075Sobrien@node Caller Saves 425390075Sobrien@subsection Caller-Saves Register Allocation 425490075Sobrien 425590075SobrienIf you enable it, GCC can save registers around function calls. This 425690075Sobrienmakes it possible to use call-clobbered registers to hold variables that 425790075Sobrienmust live across calls. 425890075Sobrien 4259132718Skan@defmac CALLER_SAVE_PROFITABLE (@var{refs}, @var{calls}) 426090075SobrienA C expression to determine whether it is worthwhile to consider placing 426190075Sobriena pseudo-register in a call-clobbered hard register and saving and 426290075Sobrienrestoring it around each function call. The expression should be 1 when 426390075Sobrienthis is worth doing, and 0 otherwise. 426490075Sobrien 426590075SobrienIf you don't define this macro, a default is used which is good on most 426690075Sobrienmachines: @code{4 * @var{calls} < @var{refs}}. 4267132718Skan@end defmac 426890075Sobrien 4269132718Skan@defmac HARD_REGNO_CALLER_SAVE_MODE (@var{regno}, @var{nregs}) 427090075SobrienA C expression specifying which mode is required for saving @var{nregs} 427190075Sobrienof a pseudo-register in call-clobbered hard register @var{regno}. If 427290075Sobrien@var{regno} is unsuitable for caller save, @code{VOIDmode} should be 427390075Sobrienreturned. For most machines this macro need not be defined since GCC 427490075Sobrienwill select the smallest suitable mode. 4275132718Skan@end defmac 427690075Sobrien 427790075Sobrien@node Function Entry 427890075Sobrien@subsection Function Entry and Exit 427990075Sobrien@cindex function entry and exit 428090075Sobrien@cindex prologue 428190075Sobrien@cindex epilogue 428290075Sobrien 428390075SobrienThis section describes the macros that output function entry 428490075Sobrien(@dfn{prologue}) and exit (@dfn{epilogue}) code. 428590075Sobrien 428690075Sobrien@deftypefn {Target Hook} void TARGET_ASM_FUNCTION_PROLOGUE (FILE *@var{file}, HOST_WIDE_INT @var{size}) 428790075SobrienIf defined, a function that outputs the assembler code for entry to a 428890075Sobrienfunction. The prologue is responsible for setting up the stack frame, 428990075Sobrieninitializing the frame pointer register, saving registers that must be 429090075Sobriensaved, and allocating @var{size} additional bytes of storage for the 429190075Sobrienlocal variables. @var{size} is an integer. @var{file} is a stdio 429290075Sobrienstream to which the assembler code should be output. 429390075Sobrien 429490075SobrienThe label for the beginning of the function need not be output by this 429590075Sobrienmacro. That has already been done when the macro is run. 429690075Sobrien 429790075Sobrien@findex regs_ever_live 429890075SobrienTo determine which registers to save, the macro can refer to the array 429990075Sobrien@code{regs_ever_live}: element @var{r} is nonzero if hard register 430090075Sobrien@var{r} is used anywhere within the function. This implies the function 430190075Sobrienprologue should save register @var{r}, provided it is not one of the 430290075Sobriencall-used registers. (@code{TARGET_ASM_FUNCTION_EPILOGUE} must likewise use 430390075Sobrien@code{regs_ever_live}.) 430490075Sobrien 430590075SobrienOn machines that have ``register windows'', the function entry code does 430690075Sobriennot save on the stack the registers that are in the windows, even if 430790075Sobrienthey are supposed to be preserved by function calls; instead it takes 430890075Sobrienappropriate steps to ``push'' the register stack, if any non-call-used 430990075Sobrienregisters are used in the function. 431090075Sobrien 431190075Sobrien@findex frame_pointer_needed 431290075SobrienOn machines where functions may or may not have frame-pointers, the 431390075Sobrienfunction entry code must vary accordingly; it must set up the frame 431490075Sobrienpointer if one is wanted, and not otherwise. To determine whether a 431590075Sobrienframe pointer is in wanted, the macro can refer to the variable 431690075Sobrien@code{frame_pointer_needed}. The variable's value will be 1 at run 431790075Sobrientime in a function that needs a frame pointer. @xref{Elimination}. 431890075Sobrien 431990075SobrienThe function entry code is responsible for allocating any stack space 432090075Sobrienrequired for the function. This stack space consists of the regions 432190075Sobrienlisted below. In most cases, these regions are allocated in the 432290075Sobrienorder listed, with the last listed region closest to the top of the 432390075Sobrienstack (the lowest address if @code{STACK_GROWS_DOWNWARD} is defined, and 432490075Sobrienthe highest address if it is not defined). You can use a different order 432590075Sobrienfor a machine if doing so is more convenient or required for 432690075Sobriencompatibility reasons. Except in cases where required by standard 432790075Sobrienor by a debugger, there is no reason why the stack layout used by GCC 432890075Sobrienneed agree with that used by other compilers for a machine. 432990075Sobrien@end deftypefn 433090075Sobrien 433190075Sobrien@deftypefn {Target Hook} void TARGET_ASM_FUNCTION_END_PROLOGUE (FILE *@var{file}) 433290075SobrienIf defined, a function that outputs assembler code at the end of a 433390075Sobrienprologue. This should be used when the function prologue is being 433490075Sobrienemitted as RTL, and you have some extra assembler that needs to be 433590075Sobrienemitted. @xref{prologue instruction pattern}. 433690075Sobrien@end deftypefn 433790075Sobrien 433890075Sobrien@deftypefn {Target Hook} void TARGET_ASM_FUNCTION_BEGIN_EPILOGUE (FILE *@var{file}) 433990075SobrienIf defined, a function that outputs assembler code at the start of an 434090075Sobrienepilogue. This should be used when the function epilogue is being 434190075Sobrienemitted as RTL, and you have some extra assembler that needs to be 434290075Sobrienemitted. @xref{epilogue instruction pattern}. 434390075Sobrien@end deftypefn 434490075Sobrien 434590075Sobrien@deftypefn {Target Hook} void TARGET_ASM_FUNCTION_EPILOGUE (FILE *@var{file}, HOST_WIDE_INT @var{size}) 434690075SobrienIf defined, a function that outputs the assembler code for exit from a 434790075Sobrienfunction. The epilogue is responsible for restoring the saved 434890075Sobrienregisters and stack pointer to their values when the function was 434990075Sobriencalled, and returning control to the caller. This macro takes the 435090075Sobriensame arguments as the macro @code{TARGET_ASM_FUNCTION_PROLOGUE}, and the 435190075Sobrienregisters to restore are determined from @code{regs_ever_live} and 435290075Sobrien@code{CALL_USED_REGISTERS} in the same way. 435390075Sobrien 435490075SobrienOn some machines, there is a single instruction that does all the work 435590075Sobrienof returning from the function. On these machines, give that 435690075Sobrieninstruction the name @samp{return} and do not define the macro 435790075Sobrien@code{TARGET_ASM_FUNCTION_EPILOGUE} at all. 435890075Sobrien 435990075SobrienDo not define a pattern named @samp{return} if you want the 436090075Sobrien@code{TARGET_ASM_FUNCTION_EPILOGUE} to be used. If you want the target 436190075Sobrienswitches to control whether return instructions or epilogues are used, 436290075Sobriendefine a @samp{return} pattern with a validity condition that tests the 436390075Sobrientarget switches appropriately. If the @samp{return} pattern's validity 436490075Sobriencondition is false, epilogues will be used. 436590075Sobrien 436690075SobrienOn machines where functions may or may not have frame-pointers, the 436790075Sobrienfunction exit code must vary accordingly. Sometimes the code for these 436890075Sobrientwo cases is completely different. To determine whether a frame pointer 436990075Sobrienis wanted, the macro can refer to the variable 437090075Sobrien@code{frame_pointer_needed}. The variable's value will be 1 when compiling 437190075Sobriena function that needs a frame pointer. 437290075Sobrien 437390075SobrienNormally, @code{TARGET_ASM_FUNCTION_PROLOGUE} and 437490075Sobrien@code{TARGET_ASM_FUNCTION_EPILOGUE} must treat leaf functions specially. 437590075SobrienThe C variable @code{current_function_is_leaf} is nonzero for such a 437690075Sobrienfunction. @xref{Leaf Functions}. 437790075Sobrien 437890075SobrienOn some machines, some functions pop their arguments on exit while 437990075Sobrienothers leave that for the caller to do. For example, the 68020 when 438090075Sobriengiven @option{-mrtd} pops arguments in functions that take a fixed 438190075Sobriennumber of arguments. 438290075Sobrien 438390075Sobrien@findex current_function_pops_args 438490075SobrienYour definition of the macro @code{RETURN_POPS_ARGS} decides which 438590075Sobrienfunctions pop their own arguments. @code{TARGET_ASM_FUNCTION_EPILOGUE} 438690075Sobrienneeds to know what was decided. The variable that is called 438790075Sobrien@code{current_function_pops_args} is the number of bytes of its 438890075Sobrienarguments that a function should pop. @xref{Scalar Return}. 438990075Sobrien@c what is the "its arguments" in the above sentence referring to, pray 439090075Sobrien@c tell? --mew 5feb93 439190075Sobrien@end deftypefn 439290075Sobrien 439390075Sobrien@itemize @bullet 439490075Sobrien@item 439590075Sobrien@findex current_function_pretend_args_size 439690075SobrienA region of @code{current_function_pretend_args_size} bytes of 439790075Sobrienuninitialized space just underneath the first argument arriving on the 439890075Sobrienstack. (This may not be at the very start of the allocated stack region 439990075Sobrienif the calling sequence has pushed anything else since pushing the stack 440090075Sobrienarguments. But usually, on such machines, nothing else has been pushed 440190075Sobrienyet, because the function prologue itself does all the pushing.) This 440290075Sobrienregion is used on machines where an argument may be passed partly in 440390075Sobrienregisters and partly in memory, and, in some cases to support the 4404117395Skanfeatures in @code{<stdarg.h>}. 440590075Sobrien 440690075Sobrien@item 440790075SobrienAn area of memory used to save certain registers used by the function. 440890075SobrienThe size of this area, which may also include space for such things as 440990075Sobrienthe return address and pointers to previous stack frames, is 441090075Sobrienmachine-specific and usually depends on which registers have been used 441190075Sobrienin the function. Machines with register windows often do not require 441290075Sobriena save area. 441390075Sobrien 441490075Sobrien@item 441590075SobrienA region of at least @var{size} bytes, possibly rounded up to an allocation 441690075Sobrienboundary, to contain the local variables of the function. On some machines, 441790075Sobrienthis region and the save area may occur in the opposite order, with the 441890075Sobriensave area closer to the top of the stack. 441990075Sobrien 442090075Sobrien@item 442190075Sobrien@cindex @code{ACCUMULATE_OUTGOING_ARGS} and stack frames 442290075SobrienOptionally, when @code{ACCUMULATE_OUTGOING_ARGS} is defined, a region of 442390075Sobrien@code{current_function_outgoing_args_size} bytes to be used for outgoing 442490075Sobrienargument lists of the function. @xref{Stack Arguments}. 442590075Sobrien@end itemize 442690075Sobrien 4427132718Skan@defmac EXIT_IGNORE_STACK 442890075SobrienDefine this macro as a C expression that is nonzero if the return 442990075Sobrieninstruction or the function epilogue ignores the value of the stack 443090075Sobrienpointer; in other words, if it is safe to delete an instruction to 4431132718Skanadjust the stack pointer before a return from the function. The 4432132718Skandefault is 0. 443390075Sobrien 443490075SobrienNote that this macro's value is relevant only for functions for which 443590075Sobrienframe pointers are maintained. It is never safe to delete a final 443690075Sobrienstack adjustment in a function that has no frame pointer, and the 443790075Sobriencompiler knows this regardless of @code{EXIT_IGNORE_STACK}. 4438132718Skan@end defmac 443990075Sobrien 4440132718Skan@defmac EPILOGUE_USES (@var{regno}) 444190075SobrienDefine this macro as a C expression that is nonzero for registers that are 444290075Sobrienused by the epilogue or the @samp{return} pattern. The stack and frame 4443169689Skanpointer registers are already assumed to be used as needed. 4444132718Skan@end defmac 444590075Sobrien 4446132718Skan@defmac EH_USES (@var{regno}) 444796263SobrienDefine this macro as a C expression that is nonzero for registers that are 444896263Sobrienused by the exception handling mechanism, and so should be considered live 444996263Sobrienon entry to an exception edge. 4450132718Skan@end defmac 445196263Sobrien 4452132718Skan@defmac DELAY_SLOTS_FOR_EPILOGUE 445390075SobrienDefine this macro if the function epilogue contains delay slots to which 445490075Sobrieninstructions from the rest of the function can be ``moved''. The 445590075Sobriendefinition should be a C expression whose value is an integer 445690075Sobrienrepresenting the number of delay slots there. 4457132718Skan@end defmac 445890075Sobrien 4459132718Skan@defmac ELIGIBLE_FOR_EPILOGUE_DELAY (@var{insn}, @var{n}) 446090075SobrienA C expression that returns 1 if @var{insn} can be placed in delay 446190075Sobrienslot number @var{n} of the epilogue. 446290075Sobrien 446390075SobrienThe argument @var{n} is an integer which identifies the delay slot now 446490075Sobrienbeing considered (since different slots may have different rules of 446590075Sobrieneligibility). It is never negative and is always less than the number 446690075Sobrienof epilogue delay slots (what @code{DELAY_SLOTS_FOR_EPILOGUE} returns). 446790075SobrienIf you reject a particular insn for a given delay slot, in principle, it 446890075Sobrienmay be reconsidered for a subsequent delay slot. Also, other insns may 446990075Sobrien(at least in principle) be considered for the so far unfilled delay 447090075Sobrienslot. 447190075Sobrien 447290075Sobrien@findex current_function_epilogue_delay_list 447390075Sobrien@findex final_scan_insn 447490075SobrienThe insns accepted to fill the epilogue delay slots are put in an RTL 447590075Sobrienlist made with @code{insn_list} objects, stored in the variable 447690075Sobrien@code{current_function_epilogue_delay_list}. The insn for the first 447790075Sobriendelay slot comes first in the list. Your definition of the macro 447890075Sobrien@code{TARGET_ASM_FUNCTION_EPILOGUE} should fill the delay slots by 447990075Sobrienoutputting the insns in this list, usually by calling 448090075Sobrien@code{final_scan_insn}. 448190075Sobrien 448290075SobrienYou need not define this macro if you did not define 448390075Sobrien@code{DELAY_SLOTS_FOR_EPILOGUE}. 4484132718Skan@end defmac 448590075Sobrien 4486146895Skan@deftypefn {Target Hook} void TARGET_ASM_OUTPUT_MI_THUNK (FILE *@var{file}, tree @var{thunk_fndecl}, HOST_WIDE_INT @var{delta}, HOST_WIDE_INT @var{vcall_offset}, tree @var{function}) 4487117395SkanA function that outputs the assembler code for a thunk 448890075Sobrienfunction, used to implement C++ virtual function calls with multiple 448990075Sobrieninheritance. The thunk acts as a wrapper around a virtual function, 449090075Sobrienadjusting the implicit object parameter before handing control off to 449190075Sobrienthe real function. 449290075Sobrien 449390075SobrienFirst, emit code to add the integer @var{delta} to the location that 449490075Sobriencontains the incoming first argument. Assume that this argument 449590075Sobriencontains a pointer, and is the one used to pass the @code{this} pointer 449690075Sobrienin C++. This is the incoming argument @emph{before} the function prologue, 449790075Sobriene.g.@: @samp{%o0} on a sparc. The addition must preserve the values of 449890075Sobrienall other incoming arguments. 449990075Sobrien 4500146895SkanThen, if @var{vcall_offset} is nonzero, an additional adjustment should be 4501146895Skanmade after adding @code{delta}. In particular, if @var{p} is the 4502146895Skanadjusted pointer, the following adjustment should be made: 4503146895Skan 4504146895Skan@smallexample 4505146895Skanp += (*((ptrdiff_t **)p))[vcall_offset/sizeof(ptrdiff_t)] 4506146895Skan@end smallexample 4507146895Skan 4508146895SkanAfter the additions, emit code to jump to @var{function}, which is a 450990075Sobrien@code{FUNCTION_DECL}. This is a direct pure jump, not a call, and does 451090075Sobriennot touch the return address. Hence returning from @var{FUNCTION} will 451190075Sobrienreturn to whoever called the current @samp{thunk}. 451290075Sobrien 451390075SobrienThe effect must be as if @var{function} had been called directly with 451490075Sobrienthe adjusted first argument. This macro is responsible for emitting all 451590075Sobrienof the code for a thunk function; @code{TARGET_ASM_FUNCTION_PROLOGUE} 451690075Sobrienand @code{TARGET_ASM_FUNCTION_EPILOGUE} are not invoked. 451790075Sobrien 451890075SobrienThe @var{thunk_fndecl} is redundant. (@var{delta} and @var{function} 451990075Sobrienhave already been extracted from it.) It might possibly be useful on 452090075Sobriensome targets, but probably not. 452190075Sobrien 452290075SobrienIf you do not define this macro, the target-independent code in the C++ 452390075Sobrienfront end will generate a less efficient heavyweight thunk that calls 452490075Sobrien@var{function} instead of jumping to it. The generic approach does 452590075Sobriennot support varargs. 4526117395Skan@end deftypefn 452790075Sobrien 4528146895Skan@deftypefn {Target Hook} bool TARGET_ASM_CAN_OUTPUT_MI_THUNK (tree @var{thunk_fndecl}, HOST_WIDE_INT @var{delta}, HOST_WIDE_INT @var{vcall_offset}, tree @var{function}) 4529146895SkanA function that returns true if TARGET_ASM_OUTPUT_MI_THUNK would be able 4530146895Skanto output the assembler code for the thunk function specified by the 4531146895Skanarguments it is passed, and false otherwise. In the latter case, the 4532146895Skangeneric approach will be used by the C++ front end, with the limitations 4533146895Skanpreviously exposed. 4534117395Skan@end deftypefn 4535117395Skan 453690075Sobrien@node Profiling 453790075Sobrien@subsection Generating Code for Profiling 453890075Sobrien@cindex profiling, code generation 453990075Sobrien 454090075SobrienThese macros will help you generate code for profiling. 454190075Sobrien 4542132718Skan@defmac FUNCTION_PROFILER (@var{file}, @var{labelno}) 454390075SobrienA C statement or compound statement to output to @var{file} some 454490075Sobrienassembler code to call the profiling subroutine @code{mcount}. 454590075Sobrien 454690075Sobrien@findex mcount 454790075SobrienThe details of how @code{mcount} expects to be called are determined by 454890075Sobrienyour operating system environment, not by GCC@. To figure them out, 454990075Sobriencompile a small program for profiling using the system's installed C 455090075Sobriencompiler and look at the assembler code that results. 455190075Sobrien 455290075SobrienOlder implementations of @code{mcount} expect the address of a counter 455390075Sobrienvariable to be loaded into some register. The name of this variable is 455490075Sobrien@samp{LP} followed by the number @var{labelno}, so you would generate 455590075Sobrienthe name using @samp{LP%d} in a @code{fprintf}. 4556132718Skan@end defmac 455790075Sobrien 4558132718Skan@defmac PROFILE_HOOK 455990075SobrienA C statement or compound statement to output to @var{file} some assembly 456090075Sobriencode to call the profiling subroutine @code{mcount} even the target does 456190075Sobriennot support profiling. 4562132718Skan@end defmac 456390075Sobrien 4564132718Skan@defmac NO_PROFILE_COUNTERS 4565169689SkanDefine this macro to be an expression with a nonzero value if the 4566169689Skan@code{mcount} subroutine on your system does not need a counter variable 4567169689Skanallocated for each function. This is true for almost all modern 4568169689Skanimplementations. If you define this macro, you must not use the 4569169689Skan@var{labelno} argument to @code{FUNCTION_PROFILER}. 4570132718Skan@end defmac 457190075Sobrien 4572132718Skan@defmac PROFILE_BEFORE_PROLOGUE 457390075SobrienDefine this macro if the code for function profiling should come before 457490075Sobrienthe function prologue. Normally, the profiling code comes after. 4575132718Skan@end defmac 457690075Sobrien 457790075Sobrien@node Tail Calls 457890075Sobrien@subsection Permitting tail calls 457990075Sobrien@cindex tail calls 458090075Sobrien 4581132718Skan@deftypefn {Target Hook} bool TARGET_FUNCTION_OK_FOR_SIBCALL (tree @var{decl}, tree @var{exp}) 4582132718SkanTrue if it is ok to do sibling call optimization for the specified 4583132718Skancall expression @var{exp}. @var{decl} will be the called function, 4584132718Skanor @code{NULL} if this is an indirect call. 458590075Sobrien 458690075SobrienIt is not uncommon for limitations of calling conventions to prevent 458790075Sobrientail calls to functions outside the current unit of translation, or 4588132718Skanduring PIC compilation. The hook is used to enforce these restrictions, 458990075Sobrienas the @code{sibcall} md pattern can not fail, or fall over to a 4590132718Skan``normal'' call. The criteria for successful sibling call optimization 4591132718Skanmay vary greatly between different architectures. 4592132718Skan@end deftypefn 459390075Sobrien 4594169689Skan@deftypefn {Target Hook} void TARGET_EXTRA_LIVE_ON_ENTRY (bitmap *@var{regs}) 4595169689SkanAdd any hard registers to @var{regs} that are live on entry to the 4596169689Skanfunction. This hook only needs to be defined to provide registers that 4597169689Skancannot be found by examination of FUNCTION_ARG_REGNO_P, the callee saved 4598169689Skanregisters, STATIC_CHAIN_INCOMING_REGNUM, STATIC_CHAIN_REGNUM, 4599169689SkanTARGET_STRUCT_VALUE_RTX, FRAME_POINTER_REGNUM, EH_USES, 4600169689SkanFRAME_POINTER_REGNUM, ARG_POINTER_REGNUM, and the PIC_OFFSET_TABLE_REGNUM. 4601169689Skan@end deftypefn 4602169689Skan 4603169689Skan@node Stack Smashing Protection 4604169689Skan@subsection Stack smashing protection 4605169689Skan@cindex stack smashing protection 4606169689Skan 4607169689Skan@deftypefn {Target Hook} tree TARGET_STACK_PROTECT_GUARD (void) 4608169689SkanThis hook returns a @code{DECL} node for the external variable to use 4609169689Skanfor the stack protection guard. This variable is initialized by the 4610169689Skanruntime to some random value and is used to initialize the guard value 4611169689Skanthat is placed at the top of the local stack frame. The type of this 4612169689Skanvariable must be @code{ptr_type_node}. 4613169689Skan 4614169689SkanThe default version of this hook creates a variable called 4615169689Skan@samp{__stack_chk_guard}, which is normally defined in @file{libgcc2.c}. 4616169689Skan@end deftypefn 4617169689Skan 4618169689Skan@deftypefn {Target Hook} tree TARGET_STACK_PROTECT_FAIL (void) 4619169689SkanThis hook returns a tree expression that alerts the runtime that the 4620169689Skanstack protect guard variable has been modified. This expression should 4621169689Skaninvolve a call to a @code{noreturn} function. 4622169689Skan 4623169689SkanThe default version of this hook invokes a function called 4624169689Skan@samp{__stack_chk_fail}, taking no arguments. This function is 4625169689Skannormally defined in @file{libgcc2.c}. 4626169689Skan@end deftypefn 4627169689Skan 462890075Sobrien@node Varargs 462990075Sobrien@section Implementing the Varargs Macros 463090075Sobrien@cindex varargs implementation 463190075Sobrien 463290075SobrienGCC comes with an implementation of @code{<varargs.h>} and 463390075Sobrien@code{<stdarg.h>} that work without change on machines that pass arguments 463490075Sobrienon the stack. Other machines require their own implementations of 463590075Sobrienvarargs, and the two machine independent header files must have 463690075Sobrienconditionals to include it. 463790075Sobrien 463890075SobrienISO @code{<stdarg.h>} differs from traditional @code{<varargs.h>} mainly in 463990075Sobrienthe calling convention for @code{va_start}. The traditional 464090075Sobrienimplementation takes just one argument, which is the variable in which 464190075Sobriento store the argument pointer. The ISO implementation of 464290075Sobrien@code{va_start} takes an additional second argument. The user is 464390075Sobriensupposed to write the last named argument of the function here. 464490075Sobrien 464590075SobrienHowever, @code{va_start} should not use this argument. The way to find 464690075Sobrienthe end of the named arguments is with the built-in functions described 464790075Sobrienbelow. 464890075Sobrien 4649132718Skan@defmac __builtin_saveregs () 465090075SobrienUse this built-in function to save the argument registers in memory so 465190075Sobrienthat the varargs mechanism can access them. Both ISO and traditional 465290075Sobrienversions of @code{va_start} must use @code{__builtin_saveregs}, unless 4653169689Skanyou use @code{TARGET_SETUP_INCOMING_VARARGS} (see below) instead. 465490075Sobrien 465590075SobrienOn some machines, @code{__builtin_saveregs} is open-coded under the 4656169689Skancontrol of the target hook @code{TARGET_EXPAND_BUILTIN_SAVEREGS}. On 4657169689Skanother machines, it calls a routine written in assembler language, 4658169689Skanfound in @file{libgcc2.c}. 465990075Sobrien 466090075SobrienCode generated for the call to @code{__builtin_saveregs} appears at the 466190075Sobrienbeginning of the function, as opposed to where the call to 466290075Sobrien@code{__builtin_saveregs} is written, regardless of what the code is. 466390075SobrienThis is because the registers must be saved before the function starts 466490075Sobriento use them for its own purposes. 466590075Sobrien@c i rewrote the first sentence above to fix an overfull hbox. --mew 466690075Sobrien@c 10feb93 4667132718Skan@end defmac 466890075Sobrien 4669132718Skan@defmac __builtin_args_info (@var{category}) 467090075SobrienUse this built-in function to find the first anonymous arguments in 467190075Sobrienregisters. 467290075Sobrien 467390075SobrienIn general, a machine may have several categories of registers used for 467490075Sobrienarguments, each for a particular category of data types. (For example, 467590075Sobrienon some machines, floating-point registers are used for floating-point 467690075Sobrienarguments while other arguments are passed in the general registers.) 467790075SobrienTo make non-varargs functions use the proper calling convention, you 467890075Sobrienhave defined the @code{CUMULATIVE_ARGS} data type to record how many 467990075Sobrienregisters in each category have been used so far 468090075Sobrien 468190075Sobrien@code{__builtin_args_info} accesses the same data structure of type 468290075Sobrien@code{CUMULATIVE_ARGS} after the ordinary argument layout is finished 468390075Sobrienwith it, with @var{category} specifying which word to access. Thus, the 468490075Sobrienvalue indicates the first unused register in a given category. 468590075Sobrien 468690075SobrienNormally, you would use @code{__builtin_args_info} in the implementation 468790075Sobrienof @code{va_start}, accessing each category just once and storing the 468890075Sobrienvalue in the @code{va_list} object. This is because @code{va_list} will 468990075Sobrienhave to update the values, and there is no way to alter the 469090075Sobrienvalues accessed by @code{__builtin_args_info}. 4691132718Skan@end defmac 469290075Sobrien 4693132718Skan@defmac __builtin_next_arg (@var{lastarg}) 469490075SobrienThis is the equivalent of @code{__builtin_args_info}, for stack 469590075Sobrienarguments. It returns the address of the first anonymous stack 469690075Sobrienargument, as type @code{void *}. If @code{ARGS_GROW_DOWNWARD}, it 469790075Sobrienreturns the address of the location above the first anonymous stack 469890075Sobrienargument. Use it in @code{va_start} to initialize the pointer for 469990075Sobrienfetching arguments from the stack. Also use it in @code{va_start} to 470090075Sobrienverify that the second parameter @var{lastarg} is the last named argument 470190075Sobrienof the current function. 4702132718Skan@end defmac 470390075Sobrien 4704132718Skan@defmac __builtin_classify_type (@var{object}) 470590075SobrienSince each machine has its own conventions for which data types are 470690075Sobrienpassed in which kind of register, your implementation of @code{va_arg} 470790075Sobrienhas to embody these conventions. The easiest way to categorize the 470890075Sobrienspecified data type is to use @code{__builtin_classify_type} together 470990075Sobrienwith @code{sizeof} and @code{__alignof__}. 471090075Sobrien 471190075Sobrien@code{__builtin_classify_type} ignores the value of @var{object}, 471290075Sobrienconsidering only its data type. It returns an integer describing what 471390075Sobrienkind of type that is---integer, floating, pointer, structure, and so on. 471490075Sobrien 471590075SobrienThe file @file{typeclass.h} defines an enumeration that you can use to 471690075Sobrieninterpret the values of @code{__builtin_classify_type}. 4717132718Skan@end defmac 471890075Sobrien 471990075SobrienThese machine description macros help implement varargs: 472090075Sobrien 4721132718Skan@deftypefn {Target Hook} rtx TARGET_EXPAND_BUILTIN_SAVEREGS (void) 4722132718SkanIf defined, this hook produces the machine-specific code for a call to 4723132718Skan@code{__builtin_saveregs}. This code will be moved to the very 4724132718Skanbeginning of the function, before any parameter access are made. The 4725132718Skanreturn value of this function should be an RTX that contains the value 4726132718Skanto use as the return of @code{__builtin_saveregs}. 4727132718Skan@end deftypefn 472890075Sobrien 4729132718Skan@deftypefn {Target Hook} void TARGET_SETUP_INCOMING_VARARGS (CUMULATIVE_ARGS *@var{args_so_far}, enum machine_mode @var{mode}, tree @var{type}, int *@var{pretend_args_size}, int @var{second_time}) 4730132718SkanThis target hook offers an alternative to using 4731132718Skan@code{__builtin_saveregs} and defining the hook 4732132718Skan@code{TARGET_EXPAND_BUILTIN_SAVEREGS}. Use it to store the anonymous 4733132718Skanregister arguments into the stack so that all the arguments appear to 4734132718Skanhave been passed consecutively on the stack. Once this is done, you can 4735132718Skanuse the standard implementation of varargs that works for machines that 4736132718Skanpass all their arguments on the stack. 473790075Sobrien 4738132718SkanThe argument @var{args_so_far} points to the @code{CUMULATIVE_ARGS} data 473990075Sobrienstructure, containing the values that are obtained after processing the 474090075Sobriennamed arguments. The arguments @var{mode} and @var{type} describe the 474190075Sobrienlast named argument---its machine mode and its data type as a tree node. 474290075Sobrien 4743132718SkanThe target hook should do two things: first, push onto the stack all the 4744132718Skanargument registers @emph{not} used for the named arguments, and second, 4745132718Skanstore the size of the data thus pushed into the @code{int}-valued 4746132718Skanvariable pointed to by @var{pretend_args_size}. The value that you 4747132718Skanstore here will serve as additional offset for setting up the stack 4748132718Skanframe. 474990075Sobrien 475090075SobrienBecause you must generate code to push the anonymous arguments at 475190075Sobriencompile time without knowing their data types, 4752132718Skan@code{TARGET_SETUP_INCOMING_VARARGS} is only useful on machines that 4753132718Skanhave just a single category of argument register and use it uniformly 4754132718Skanfor all data types. 475590075Sobrien 475690075SobrienIf the argument @var{second_time} is nonzero, it means that the 475790075Sobrienarguments of the function are being analyzed for the second time. This 475890075Sobrienhappens for an inline function, which is not actually compiled until the 4759132718Skanend of the source file. The hook @code{TARGET_SETUP_INCOMING_VARARGS} should 476090075Sobriennot generate any instructions in this case. 4761132718Skan@end deftypefn 476290075Sobrien 4763132718Skan@deftypefn {Target Hook} bool TARGET_STRICT_ARGUMENT_NAMING (CUMULATIVE_ARGS *@var{ca}) 4764132718SkanDefine this hook to return @code{true} if the location where a function 476590075Sobrienargument is passed depends on whether or not it is a named argument. 476690075Sobrien 4767132718SkanThis hook controls how the @var{named} argument to @code{FUNCTION_ARG} 4768132718Skanis set for varargs and stdarg functions. If this hook returns 4769132718Skan@code{true}, the @var{named} argument is always true for named 4770132718Skanarguments, and false for unnamed arguments. If it returns @code{false}, 4771169689Skanbut @code{TARGET_PRETEND_OUTGOING_VARARGS_NAMED} returns @code{true}, 4772132718Skanthen all arguments are treated as named. Otherwise, all named arguments 4773132718Skanexcept the last are treated as named. 477490075Sobrien 4775132718SkanYou need not define this hook if it always returns zero. 4776132718Skan@end deftypefn 477790075Sobrien 4778132718Skan@deftypefn {Target Hook} bool TARGET_PRETEND_OUTGOING_VARARGS_NAMED 477990075SobrienIf you need to conditionally change ABIs so that one works with 4780132718Skan@code{TARGET_SETUP_INCOMING_VARARGS}, but the other works like neither 4781132718Skan@code{TARGET_SETUP_INCOMING_VARARGS} nor @code{TARGET_STRICT_ARGUMENT_NAMING} was 4782132718Skandefined, then define this hook to return @code{true} if 4783169689Skan@code{TARGET_SETUP_INCOMING_VARARGS} is used, @code{false} otherwise. 4784132718SkanOtherwise, you should not define this hook. 4785132718Skan@end deftypefn 478690075Sobrien 478790075Sobrien@node Trampolines 478890075Sobrien@section Trampolines for Nested Functions 478990075Sobrien@cindex trampolines for nested functions 479090075Sobrien@cindex nested functions, trampolines for 479190075Sobrien 479290075SobrienA @dfn{trampoline} is a small piece of code that is created at run time 479390075Sobrienwhen the address of a nested function is taken. It normally resides on 479490075Sobrienthe stack, in the stack frame of the containing function. These macros 479590075Sobrientell GCC how to generate code to allocate and initialize a 479690075Sobrientrampoline. 479790075Sobrien 479890075SobrienThe instructions in the trampoline must do two things: load a constant 479990075Sobrienaddress into the static chain register, and jump to the real address of 480090075Sobrienthe nested function. On CISC machines such as the m68k, this requires 480190075Sobrientwo instructions, a move immediate and a jump. Then the two addresses 480290075Sobrienexist in the trampoline as word-long immediate operands. On RISC 480390075Sobrienmachines, it is often necessary to load each address into a register in 480490075Sobrientwo parts. Then pieces of each address form separate immediate 480590075Sobrienoperands. 480690075Sobrien 480790075SobrienThe code generated to initialize the trampoline must store the variable 480890075Sobrienparts---the static chain value and the function address---into the 480990075Sobrienimmediate operands of the instructions. On a CISC machine, this is 481090075Sobriensimply a matter of copying each address to a memory reference at the 481190075Sobrienproper offset from the start of the trampoline. On a RISC machine, it 481290075Sobrienmay be necessary to take out pieces of the address and store them 481390075Sobrienseparately. 481490075Sobrien 4815132718Skan@defmac TRAMPOLINE_TEMPLATE (@var{file}) 481690075SobrienA C statement to output, on the stream @var{file}, assembler code for a 481790075Sobrienblock of data that contains the constant parts of a trampoline. This 481890075Sobriencode should not include a label---the label is taken care of 481990075Sobrienautomatically. 482090075Sobrien 482190075SobrienIf you do not define this macro, it means no template is needed 482290075Sobrienfor the target. Do not define this macro on systems where the block move 482390075Sobriencode to copy the trampoline into place would be larger than the code 482490075Sobriento generate it on the spot. 4825132718Skan@end defmac 482690075Sobrien 4827132718Skan@defmac TRAMPOLINE_SECTION 4828169689SkanReturn the section into which the trampoline template is to be placed 4829169689Skan(@pxref{Sections}). The default value is @code{readonly_data_section}. 4830132718Skan@end defmac 483190075Sobrien 4832132718Skan@defmac TRAMPOLINE_SIZE 483390075SobrienA C expression for the size in bytes of the trampoline, as an integer. 4834132718Skan@end defmac 483590075Sobrien 4836132718Skan@defmac TRAMPOLINE_ALIGNMENT 483790075SobrienAlignment required for trampolines, in bits. 483890075Sobrien 483990075SobrienIf you don't define this macro, the value of @code{BIGGEST_ALIGNMENT} 484090075Sobrienis used for aligning trampolines. 4841132718Skan@end defmac 484290075Sobrien 4843132718Skan@defmac INITIALIZE_TRAMPOLINE (@var{addr}, @var{fnaddr}, @var{static_chain}) 484490075SobrienA C statement to initialize the variable parts of a trampoline. 484590075Sobrien@var{addr} is an RTX for the address of the trampoline; @var{fnaddr} is 484690075Sobrienan RTX for the address of the nested function; @var{static_chain} is an 484790075SobrienRTX for the static chain value that should be passed to the function 484890075Sobrienwhen it is called. 4849132718Skan@end defmac 485090075Sobrien 4851132718Skan@defmac TRAMPOLINE_ADJUST_ADDRESS (@var{addr}) 485290075SobrienA C statement that should perform any machine-specific adjustment in 485390075Sobrienthe address of the trampoline. Its argument contains the address that 485490075Sobrienwas passed to @code{INITIALIZE_TRAMPOLINE}. In case the address to be 485590075Sobrienused for a function call should be different from the address in which 485690075Sobrienthe template was stored, the different address should be assigned to 485790075Sobrien@var{addr}. If this macro is not defined, @var{addr} will be used for 485890075Sobrienfunction calls. 485990075Sobrien 486090075Sobrien@cindex @code{TARGET_ASM_FUNCTION_EPILOGUE} and trampolines 486190075Sobrien@cindex @code{TARGET_ASM_FUNCTION_PROLOGUE} and trampolines 486290075SobrienIf this macro is not defined, by default the trampoline is allocated as 486390075Sobriena stack slot. This default is right for most machines. The exceptions 486490075Sobrienare machines where it is impossible to execute instructions in the stack 486590075Sobrienarea. On such machines, you may have to implement a separate stack, 486690075Sobrienusing this macro in conjunction with @code{TARGET_ASM_FUNCTION_PROLOGUE} 486790075Sobrienand @code{TARGET_ASM_FUNCTION_EPILOGUE}. 486890075Sobrien 486990075Sobrien@var{fp} points to a data structure, a @code{struct function}, which 487090075Sobriendescribes the compilation status of the immediate containing function of 4871132718Skanthe function which the trampoline is for. The stack slot for the 487290075Sobrientrampoline is in the stack frame of this containing function. Other 487390075Sobrienallocation strategies probably must do something analogous with this 487490075Sobrieninformation. 4875132718Skan@end defmac 487690075Sobrien 487790075SobrienImplementing trampolines is difficult on many machines because they have 487890075Sobrienseparate instruction and data caches. Writing into a stack location 487990075Sobrienfails to clear the memory in the instruction cache, so when the program 488090075Sobrienjumps to that location, it executes the old contents. 488190075Sobrien 488290075SobrienHere are two possible solutions. One is to clear the relevant parts of 488390075Sobrienthe instruction cache whenever a trampoline is set up. The other is to 488490075Sobrienmake all trampolines identical, by having them jump to a standard 488590075Sobriensubroutine. The former technique makes trampoline execution faster; the 488690075Sobrienlatter makes initialization faster. 488790075Sobrien 488890075SobrienTo clear the instruction cache when a trampoline is initialized, define 4889132718Skanthe following macro. 489090075Sobrien 4891132718Skan@defmac CLEAR_INSN_CACHE (@var{beg}, @var{end}) 4892132718SkanIf defined, expands to a C expression clearing the @emph{instruction 4893132718Skancache} in the specified interval. The definition of this macro would 4894132718Skantypically be a series of @code{asm} statements. Both @var{beg} and 4895132718Skan@var{end} are both pointer expressions. 4896132718Skan@end defmac 489790075Sobrien 4898132718SkanThe operating system may also require the stack to be made executable 4899132718Skanbefore calling the trampoline. To implement this requirement, define 4900132718Skanthe following macro. 490190075Sobrien 4902132718Skan@defmac ENABLE_EXECUTE_STACK 4903132718SkanDefine this macro if certain operations must be performed before executing 4904132718Skancode located on the stack. The macro should expand to a series of C 4905169689Skanfile-scope constructs (e.g.@: functions) and provide a unique entry point 4906132718Skannamed @code{__enable_execute_stack}. The target is responsible for 4907132718Skanemitting calls to the entry point in the code, for example from the 4908132718Skan@code{INITIALIZE_TRAMPOLINE} macro. 4909132718Skan@end defmac 491090075Sobrien 491190075SobrienTo use a standard subroutine, define the following macro. In addition, 491290075Sobrienyou must make sure that the instructions in a trampoline fill an entire 491390075Sobriencache line with identical instructions, or else ensure that the 491490075Sobrienbeginning of the trampoline code is always aligned at the same point in 491590075Sobrienits cache line. Look in @file{m68k.h} as a guide. 491690075Sobrien 4917132718Skan@defmac TRANSFER_FROM_TRAMPOLINE 491890075SobrienDefine this macro if trampolines need a special subroutine to do their 491990075Sobrienwork. The macro should expand to a series of @code{asm} statements 492090075Sobrienwhich will be compiled with GCC@. They go in a library function named 492190075Sobrien@code{__transfer_from_trampoline}. 492290075Sobrien 492390075SobrienIf you need to avoid executing the ordinary prologue code of a compiled 492490075SobrienC function when you jump to the subroutine, you can do so by placing a 492590075Sobrienspecial label of your own in the assembler code. Use one @code{asm} 492690075Sobrienstatement to generate an assembler label, and another to make the label 492790075Sobrienglobal. Then trampolines can use that label to jump directly to your 492890075Sobrienspecial assembler code. 4929132718Skan@end defmac 493090075Sobrien 493190075Sobrien@node Library Calls 493290075Sobrien@section Implicit Calls to Library Routines 493390075Sobrien@cindex library subroutine names 493490075Sobrien@cindex @file{libgcc.a} 493590075Sobrien 493690075Sobrien@c prevent bad page break with this line 493790075SobrienHere is an explanation of implicit calls to library routines. 493890075Sobrien 4939132718Skan@defmac DECLARE_LIBRARY_RENAMES 4940132718SkanThis macro, if defined, should expand to a piece of C code that will get 4941132718Skanexpanded when compiling functions for libgcc.a. It can be used to 4942132718Skanprovide alternate names for GCC's internal library functions if there 4943132718Skanare ABI-mandated names that the compiler should provide. 4944132718Skan@end defmac 494590075Sobrien 4946132718Skan@findex init_one_libfunc 4947132718Skan@findex set_optab_libfunc 4948132718Skan@deftypefn {Target Hook} void TARGET_INIT_LIBFUNCS (void) 4949132718SkanThis hook should declare additional library routines or rename 4950132718Skanexisting ones, using the functions @code{set_optab_libfunc} and 4951132718Skan@code{init_one_libfunc} defined in @file{optabs.c}. 4952132718Skan@code{init_optabs} calls this macro after initializing all the normal 4953132718Skanlibrary routines. 495490075Sobrien 4955132718SkanThe default is to do nothing. Most ports don't need to define this hook. 4956132718Skan@end deftypefn 495790075Sobrien 4958169689Skan@defmac FLOAT_LIB_COMPARE_RETURNS_BOOL (@var{mode}, @var{comparison}) 4959132718SkanThis macro should return @code{true} if the library routine that 4960132718Skanimplements the floating point comparison operator @var{comparison} in 4961132718Skanmode @var{mode} will return a boolean, and @var{false} if it will 4962132718Skanreturn a tristate. 496390075Sobrien 4964132718SkanGCC's own floating point libraries return tristates from the 4965132718Skancomparison operators, so the default returns false always. Most ports 4966132718Skandon't need to define this macro. 4967132718Skan@end defmac 496890075Sobrien 4969169689Skan@defmac TARGET_LIB_INT_CMP_BIASED 4970169689SkanThis macro should evaluate to @code{true} if the integer comparison 4971169689Skanfunctions (like @code{__cmpdi2}) return 0 to indicate that the first 4972169689Skanoperand is smaller than the second, 1 to indicate that they are equal, 4973169689Skanand 2 to indicate that the first operand is greater than the second. 4974169689SkanIf this macro evaluates to @code{false} the comparison functions return 4975169689Skan@minus{}1, 0, and 1 instead of 0, 1, and 2. If the target uses the routines 4976169689Skanin @file{libgcc.a}, you do not need to define this macro. 4977169689Skan@end defmac 4978169689Skan 4979132718Skan@cindex US Software GOFAST, floating point emulation library 4980132718Skan@cindex floating point emulation library, US Software GOFAST 4981132718Skan@cindex GOFAST, floating point emulation library 4982132718Skan@findex gofast_maybe_init_libfuncs 4983132718Skan@defmac US_SOFTWARE_GOFAST 4984132718SkanDefine this macro if your system C library uses the US Software GOFAST 4985132718Skanlibrary to provide floating point emulation. 498690075Sobrien 4987132718SkanIn addition to defining this macro, your architecture must set 4988132718Skan@code{TARGET_INIT_LIBFUNCS} to @code{gofast_maybe_init_libfuncs}, or 4989132718Skanelse call that function from its version of that hook. It is defined 4990132718Skanin @file{config/gofast.h}, which must be included by your 4991132718Skanarchitecture's @file{@var{cpu}.c} file. See @file{sparc/sparc.c} for 4992132718Skanan example. 499390075Sobrien 4994132718SkanIf this macro is defined, the 4995132718Skan@code{TARGET_FLOAT_LIB_COMPARE_RETURNS_BOOL} target hook must return 4996132718Skanfalse for @code{SFmode} and @code{DFmode} comparisons. 4997132718Skan@end defmac 499890075Sobrien 499990075Sobrien@cindex @code{EDOM}, implicit usage 5000132718Skan@findex matherr 5001132718Skan@defmac TARGET_EDOM 500290075SobrienThe value of @code{EDOM} on the target machine, as a C integer constant 500390075Sobrienexpression. If you don't define this macro, GCC does not attempt to 500490075Sobriendeposit the value of @code{EDOM} into @code{errno} directly. Look in 500590075Sobrien@file{/usr/include/errno.h} to find the value of @code{EDOM} on your 500690075Sobriensystem. 500790075Sobrien 500890075SobrienIf you do not define @code{TARGET_EDOM}, then compiled code reports 500990075Sobriendomain errors by calling the library function and letting it report the 501090075Sobrienerror. If mathematical functions on your system use @code{matherr} when 501190075Sobrienthere is an error, then you should leave @code{TARGET_EDOM} undefined so 501290075Sobrienthat @code{matherr} is used normally. 5013132718Skan@end defmac 501490075Sobrien 501590075Sobrien@cindex @code{errno}, implicit usage 5016132718Skan@defmac GEN_ERRNO_RTX 501790075SobrienDefine this macro as a C expression to create an rtl expression that 501890075Sobrienrefers to the global ``variable'' @code{errno}. (On certain systems, 501990075Sobrien@code{errno} may not actually be a variable.) If you don't define this 502090075Sobrienmacro, a reasonable default is used. 5021132718Skan@end defmac 502290075Sobrien 5023132718Skan@cindex C99 math functions, implicit usage 5024132718Skan@defmac TARGET_C99_FUNCTIONS 5025132718SkanWhen this macro is nonzero, GCC will implicitly optimize @code{sin} calls into 5026132718Skan@code{sinf} and similarly for other functions defined by C99 standard. The 5027132718Skandefault is nonzero that should be proper value for most modern systems, however 5028132718Skannumber of existing systems lacks support for these functions in the runtime so 5029132718Skanthey needs this macro to be redefined to 0. 5030132718Skan@end defmac 503190075Sobrien 5032132718Skan@defmac NEXT_OBJC_RUNTIME 503390075SobrienDefine this macro to generate code for Objective-C message sending using 503490075Sobrienthe calling convention of the NeXT system. This calling convention 503590075Sobrieninvolves passing the object, the selector and the method arguments all 503690075Sobrienat once to the method-lookup library function. 503790075Sobrien 503890075SobrienThe default calling convention passes just the object and the selector 503990075Sobriento the lookup function, which returns a pointer to the method. 5040132718Skan@end defmac 504190075Sobrien 504290075Sobrien@node Addressing Modes 504390075Sobrien@section Addressing Modes 504490075Sobrien@cindex addressing modes 504590075Sobrien 504690075Sobrien@c prevent bad page break with this line 504790075SobrienThis is about addressing modes. 504890075Sobrien 5049132718Skan@defmac HAVE_PRE_INCREMENT 5050132718Skan@defmacx HAVE_PRE_DECREMENT 5051132718Skan@defmacx HAVE_POST_INCREMENT 5052132718Skan@defmacx HAVE_POST_DECREMENT 505390075SobrienA C expression that is nonzero if the machine supports pre-increment, 505490075Sobrienpre-decrement, post-increment, or post-decrement addressing respectively. 5055132718Skan@end defmac 505690075Sobrien 5057132718Skan@defmac HAVE_PRE_MODIFY_DISP 5058132718Skan@defmacx HAVE_POST_MODIFY_DISP 505990075SobrienA C expression that is nonzero if the machine supports pre- or 506090075Sobrienpost-address side-effect generation involving constants other than 506190075Sobrienthe size of the memory operand. 5062132718Skan@end defmac 506390075Sobrien 5064132718Skan@defmac HAVE_PRE_MODIFY_REG 5065132718Skan@defmacx HAVE_POST_MODIFY_REG 506690075SobrienA C expression that is nonzero if the machine supports pre- or 506790075Sobrienpost-address side-effect generation involving a register displacement. 5068132718Skan@end defmac 506990075Sobrien 5070132718Skan@defmac CONSTANT_ADDRESS_P (@var{x}) 507190075SobrienA C expression that is 1 if the RTX @var{x} is a constant which 507290075Sobrienis a valid address. On most machines, this can be defined as 507390075Sobrien@code{CONSTANT_P (@var{x})}, but a few machines are more restrictive 507490075Sobrienin which constant addresses are supported. 5075132718Skan@end defmac 507690075Sobrien 5077132718Skan@defmac CONSTANT_P (@var{x}) 5078132718Skan@code{CONSTANT_P}, which is defined by target-independent code, 5079132718Skanaccepts integer-values expressions whose values are not explicitly 5080132718Skanknown, such as @code{symbol_ref}, @code{label_ref}, and @code{high} 5081132718Skanexpressions and @code{const} arithmetic expressions, in addition to 5082132718Skan@code{const_int} and @code{const_double} expressions. 5083132718Skan@end defmac 508490075Sobrien 5085132718Skan@defmac MAX_REGS_PER_ADDRESS 508690075SobrienA number, the maximum number of registers that can appear in a valid 508790075Sobrienmemory address. Note that it is up to you to specify a value equal to 508890075Sobrienthe maximum number that @code{GO_IF_LEGITIMATE_ADDRESS} would ever 508990075Sobrienaccept. 5090132718Skan@end defmac 509190075Sobrien 5092132718Skan@defmac GO_IF_LEGITIMATE_ADDRESS (@var{mode}, @var{x}, @var{label}) 509390075SobrienA C compound statement with a conditional @code{goto @var{label};} 509490075Sobrienexecuted if @var{x} (an RTX) is a legitimate memory address on the 509590075Sobrientarget machine for a memory operand of mode @var{mode}. 509690075Sobrien 509790075SobrienIt usually pays to define several simpler macros to serve as 509890075Sobriensubroutines for this one. Otherwise it may be too complicated to 509990075Sobrienunderstand. 510090075Sobrien 510190075SobrienThis macro must exist in two variants: a strict variant and a 510290075Sobriennon-strict one. The strict variant is used in the reload pass. It 510390075Sobrienmust be defined so that any pseudo-register that has not been 510490075Sobrienallocated a hard register is considered a memory reference. In 510590075Sobriencontexts where some kind of register is required, a pseudo-register 510690075Sobrienwith no hard register must be rejected. 510790075Sobrien 510890075SobrienThe non-strict variant is used in other passes. It must be defined to 510990075Sobrienaccept all pseudo-registers in every context where some kind of 511090075Sobrienregister is required. 511190075Sobrien 511290075Sobrien@findex REG_OK_STRICT 511390075SobrienCompiler source files that want to use the strict variant of this 511490075Sobrienmacro define the macro @code{REG_OK_STRICT}. You should use an 511590075Sobrien@code{#ifdef REG_OK_STRICT} conditional to define the strict variant 511690075Sobrienin that case and the non-strict variant otherwise. 511790075Sobrien 511890075SobrienSubroutines to check for acceptable registers for various purposes (one 511990075Sobrienfor base registers, one for index registers, and so on) are typically 512090075Sobrienamong the subroutines used to define @code{GO_IF_LEGITIMATE_ADDRESS}. 512190075SobrienThen only these subroutine macros need have two variants; the higher 512290075Sobrienlevels of macros may be the same whether strict or not. 512390075Sobrien 512490075SobrienNormally, constant addresses which are the sum of a @code{symbol_ref} 512590075Sobrienand an integer are stored inside a @code{const} RTX to mark them as 512690075Sobrienconstant. Therefore, there is no need to recognize such sums 512790075Sobrienspecifically as legitimate addresses. Normally you would simply 512890075Sobrienrecognize any @code{const} as legitimate. 512990075Sobrien 513090075SobrienUsually @code{PRINT_OPERAND_ADDRESS} is not prepared to handle constant 513190075Sobriensums that are not marked with @code{const}. It assumes that a naked 513290075Sobrien@code{plus} indicates indexing. If so, then you @emph{must} reject such 513390075Sobriennaked constant sums as illegitimate addresses, so that none of them will 513490075Sobrienbe given to @code{PRINT_OPERAND_ADDRESS}. 513590075Sobrien 5136117395Skan@cindex @code{TARGET_ENCODE_SECTION_INFO} and address validation 513790075SobrienOn some machines, whether a symbolic address is legitimate depends on 513890075Sobrienthe section that the address refers to. On these machines, define the 5139117395Skantarget hook @code{TARGET_ENCODE_SECTION_INFO} to store the information 5140117395Skaninto the @code{symbol_ref}, and then check for it here. When you see a 514190075Sobrien@code{const}, you will have to look inside it to find the 514290075Sobrien@code{symbol_ref} in order to determine the section. @xref{Assembler 514390075SobrienFormat}. 5144132718Skan@end defmac 514590075Sobrien 5146132718Skan@defmac FIND_BASE_TERM (@var{x}) 514790075SobrienA C expression to determine the base term of address @var{x}. 514890075SobrienThis macro is used in only one place: `find_base_term' in alias.c. 514990075Sobrien 515090075SobrienIt is always safe for this macro to not be defined. It exists so 515190075Sobrienthat alias analysis can understand machine-dependent addresses. 515290075Sobrien 515390075SobrienThe typical use of this macro is to handle addresses containing 515490075Sobriena label_ref or symbol_ref within an UNSPEC@. 5155132718Skan@end defmac 515690075Sobrien 5157132718Skan@defmac LEGITIMIZE_ADDRESS (@var{x}, @var{oldx}, @var{mode}, @var{win}) 515890075SobrienA C compound statement that attempts to replace @var{x} with a valid 515990075Sobrienmemory address for an operand of mode @var{mode}. @var{win} will be a 516090075SobrienC statement label elsewhere in the code; the macro definition may use 516190075Sobrien 5162132718Skan@smallexample 516390075SobrienGO_IF_LEGITIMATE_ADDRESS (@var{mode}, @var{x}, @var{win}); 5164132718Skan@end smallexample 516590075Sobrien 516690075Sobrien@noindent 516790075Sobriento avoid further processing if the address has become legitimate. 516890075Sobrien 516990075Sobrien@findex break_out_memory_refs 517090075Sobrien@var{x} will always be the result of a call to @code{break_out_memory_refs}, 517190075Sobrienand @var{oldx} will be the operand that was given to that function to produce 517290075Sobrien@var{x}. 517390075Sobrien 517490075SobrienThe code generated by this macro should not alter the substructure of 517590075Sobrien@var{x}. If it transforms @var{x} into a more legitimate form, it 517690075Sobrienshould assign @var{x} (which will always be a C variable) a new value. 517790075Sobrien 517890075SobrienIt is not necessary for this macro to come up with a legitimate 517990075Sobrienaddress. The compiler has standard ways of doing so in all cases. In 5180169689Skanfact, it is safe to omit this macro. But often a 518190075Sobrienmachine-dependent strategy can generate better code. 5182132718Skan@end defmac 518390075Sobrien 5184132718Skan@defmac LEGITIMIZE_RELOAD_ADDRESS (@var{x}, @var{mode}, @var{opnum}, @var{type}, @var{ind_levels}, @var{win}) 518590075SobrienA C compound statement that attempts to replace @var{x}, which is an address 518690075Sobrienthat needs reloading, with a valid memory address for an operand of mode 518790075Sobrien@var{mode}. @var{win} will be a C statement label elsewhere in the code. 518890075SobrienIt is not necessary to define this macro, but it might be useful for 518990075Sobrienperformance reasons. 519090075Sobrien 519190075SobrienFor example, on the i386, it is sometimes possible to use a single 519290075Sobrienreload register instead of two by reloading a sum of two pseudo 519390075Sobrienregisters into a register. On the other hand, for number of RISC 519490075Sobrienprocessors offsets are limited so that often an intermediate address 519590075Sobrienneeds to be generated in order to address a stack slot. By defining 519690075Sobrien@code{LEGITIMIZE_RELOAD_ADDRESS} appropriately, the intermediate addresses 519790075Sobriengenerated for adjacent some stack slots can be made identical, and thus 519890075Sobrienbe shared. 519990075Sobrien 520090075Sobrien@emph{Note}: This macro should be used with caution. It is necessary 520190075Sobriento know something of how reload works in order to effectively use this, 520290075Sobrienand it is quite easy to produce macros that build in too much knowledge 520390075Sobrienof reload internals. 520490075Sobrien 520590075Sobrien@emph{Note}: This macro must be able to reload an address created by a 520690075Sobrienprevious invocation of this macro. If it fails to handle such addresses 520790075Sobrienthen the compiler may generate incorrect code or abort. 520890075Sobrien 520990075Sobrien@findex push_reload 521090075SobrienThe macro definition should use @code{push_reload} to indicate parts that 521190075Sobrienneed reloading; @var{opnum}, @var{type} and @var{ind_levels} are usually 521290075Sobriensuitable to be passed unaltered to @code{push_reload}. 521390075Sobrien 521490075SobrienThe code generated by this macro must not alter the substructure of 521590075Sobrien@var{x}. If it transforms @var{x} into a more legitimate form, it 521690075Sobrienshould assign @var{x} (which will always be a C variable) a new value. 521790075SobrienThis also applies to parts that you change indirectly by calling 521890075Sobrien@code{push_reload}. 521990075Sobrien 522090075Sobrien@findex strict_memory_address_p 522190075SobrienThe macro definition may use @code{strict_memory_address_p} to test if 522290075Sobrienthe address has become legitimate. 522390075Sobrien 522490075Sobrien@findex copy_rtx 522590075SobrienIf you want to change only a part of @var{x}, one standard way of doing 522690075Sobrienthis is to use @code{copy_rtx}. Note, however, that is unshares only a 522790075Sobriensingle level of rtl. Thus, if the part to be changed is not at the 522890075Sobrientop level, you'll need to replace first the top level. 522990075SobrienIt is not necessary for this macro to come up with a legitimate 523090075Sobrienaddress; but often a machine-dependent strategy can generate better code. 5231132718Skan@end defmac 523290075Sobrien 5233132718Skan@defmac GO_IF_MODE_DEPENDENT_ADDRESS (@var{addr}, @var{label}) 523490075SobrienA C statement or compound statement with a conditional @code{goto 523590075Sobrien@var{label};} executed if memory address @var{x} (an RTX) can have 523690075Sobriendifferent meanings depending on the machine mode of the memory 523790075Sobrienreference it is used for or if the address is valid for some modes 523890075Sobrienbut not others. 523990075Sobrien 524090075SobrienAutoincrement and autodecrement addresses typically have mode-dependent 524190075Sobrieneffects because the amount of the increment or decrement is the size 524290075Sobrienof the operand being addressed. Some machines have other mode-dependent 524390075Sobrienaddresses. Many RISC machines have no mode-dependent addresses. 524490075Sobrien 524590075SobrienYou may assume that @var{addr} is a valid address for the machine. 5246132718Skan@end defmac 524790075Sobrien 5248132718Skan@defmac LEGITIMATE_CONSTANT_P (@var{x}) 524990075SobrienA C expression that is nonzero if @var{x} is a legitimate constant for 525090075Sobrienan immediate operand on the target machine. You can assume that 525190075Sobrien@var{x} satisfies @code{CONSTANT_P}, so you need not check this. In fact, 525290075Sobrien@samp{1} is a suitable definition for this macro on machines where 525390075Sobrienanything @code{CONSTANT_P} is valid. 5254132718Skan@end defmac 525590075Sobrien 5256169689Skan@deftypefn {Target Hook} rtx TARGET_DELEGITIMIZE_ADDRESS (rtx @var{x}) 5257169689SkanThis hook is used to undo the possibly obfuscating effects of the 5258169689Skan@code{LEGITIMIZE_ADDRESS} and @code{LEGITIMIZE_RELOAD_ADDRESS} target 5259169689Skanmacros. Some backend implementations of these macros wrap symbol 5260169689Skanreferences inside an @code{UNSPEC} rtx to represent PIC or similar 5261169689Skanaddressing modes. This target hook allows GCC's optimizers to understand 5262169689Skanthe semantics of these opaque @code{UNSPEC}s by converting them back 5263169689Skaninto their original form. 5264169689Skan@end deftypefn 5265169689Skan 5266169689Skan@deftypefn {Target Hook} bool TARGET_CANNOT_FORCE_CONST_MEM (rtx @var{x}) 5267169689SkanThis hook should return true if @var{x} is of a form that cannot (or 5268169689Skanshould not) be spilled to the constant pool. The default version of 5269169689Skanthis hook returns false. 5270169689Skan 5271169689SkanThe primary reason to define this hook is to prevent reload from 5272169689Skandeciding that a non-legitimate constant would be better reloaded 5273169689Skanfrom the constant pool instead of spilling and reloading a register 5274169689Skanholding the constant. This restriction is often true of addresses 5275169689Skanof TLS symbols for various targets. 5276169689Skan@end deftypefn 5277169689Skan 5278169689Skan@deftypefn {Target Hook} bool TARGET_USE_BLOCKS_FOR_CONSTANT_P (enum machine_mode @var{mode}, rtx @var{x}) 5279169689SkanThis hook should return true if pool entries for constant @var{x} can 5280169689Skanbe placed in an @code{object_block} structure. @var{mode} is the mode 5281169689Skanof @var{x}. 5282169689Skan 5283169689SkanThe default version returns false for all constants. 5284169689Skan@end deftypefn 5285169689Skan 5286169689Skan@deftypefn {Target Hook} tree TARGET_VECTORIZE_BUILTIN_MASK_FOR_LOAD (void) 5287169689SkanThis hook should return the DECL of a function @var{f} that given an 5288169689Skanaddress @var{addr} as an argument returns a mask @var{m} that can be 5289169689Skanused to extract from two vectors the relevant data that resides in 5290169689Skan@var{addr} in case @var{addr} is not properly aligned. 5291169689Skan 5292169689SkanThe autovectrizer, when vectorizing a load operation from an address 5293169689Skan@var{addr} that may be unaligned, will generate two vector loads from 5294169689Skanthe two aligned addresses around @var{addr}. It then generates a 5295169689Skan@code{REALIGN_LOAD} operation to extract the relevant data from the 5296169689Skantwo loaded vectors. The first two arguments to @code{REALIGN_LOAD}, 5297169689Skan@var{v1} and @var{v2}, are the two vectors, each of size @var{VS}, and 5298169689Skanthe third argument, @var{OFF}, defines how the data will be extracted 5299169689Skanfrom these two vectors: if @var{OFF} is 0, then the returned vector is 5300169689Skan@var{v2}; otherwise, the returned vector is composed from the last 5301169689Skan@var{VS}-@var{OFF} elements of @var{v1} concatenated to the first 5302169689Skan@var{OFF} elements of @var{v2}. 5303169689Skan 5304169689SkanIf this hook is defined, the autovectorizer will generate a call 5305169689Skanto @var{f} (using the DECL tree that this hook returns) and will 5306169689Skanuse the return value of @var{f} as the argument @var{OFF} to 5307169689Skan@code{REALIGN_LOAD}. Therefore, the mask @var{m} returned by @var{f} 5308169689Skanshould comply with the semantics expected by @code{REALIGN_LOAD} 5309169689Skandescribed above. 5310169689SkanIf this hook is not defined, then @var{addr} will be used as 5311169689Skanthe argument @var{OFF} to @code{REALIGN_LOAD}, in which case the low 5312169689Skanlog2(@var{VS})-1 bits of @var{addr} will be considered. 5313169689Skan@end deftypefn 5314169689Skan 5315169689Skan@node Anchored Addresses 5316169689Skan@section Anchored Addresses 5317169689Skan@cindex anchored addresses 5318169689Skan@cindex @option{-fsection-anchors} 5319169689Skan 5320169689SkanGCC usually addresses every static object as a separate entity. 5321169689SkanFor example, if we have: 5322169689Skan 5323169689Skan@smallexample 5324169689Skanstatic int a, b, c; 5325169689Skanint foo (void) @{ return a + b + c; @} 5326169689Skan@end smallexample 5327169689Skan 5328169689Skanthe code for @code{foo} will usually calculate three separate symbolic 5329169689Skanaddresses: those of @code{a}, @code{b} and @code{c}. On some targets, 5330169689Skanit would be better to calculate just one symbolic address and access 5331169689Skanthe three variables relative to it. The equivalent pseudocode would 5332169689Skanbe something like: 5333169689Skan 5334169689Skan@smallexample 5335169689Skanint foo (void) 5336169689Skan@{ 5337169689Skan register int *xr = &x; 5338169689Skan return xr[&a - &x] + xr[&b - &x] + xr[&c - &x]; 5339169689Skan@} 5340169689Skan@end smallexample 5341169689Skan 5342169689Skan(which isn't valid C). We refer to shared addresses like @code{x} as 5343169689Skan``section anchors''. Their use is controlled by @option{-fsection-anchors}. 5344169689Skan 5345169689SkanThe hooks below describe the target properties that GCC needs to know 5346169689Skanin order to make effective use of section anchors. It won't use 5347169689Skansection anchors at all unless either @code{TARGET_MIN_ANCHOR_OFFSET} 5348169689Skanor @code{TARGET_MAX_ANCHOR_OFFSET} is set to a nonzero value. 5349169689Skan 5350169689Skan@deftypevar {Target Hook} HOST_WIDE_INT TARGET_MIN_ANCHOR_OFFSET 5351169689SkanThe minimum offset that should be applied to a section anchor. 5352169689SkanOn most targets, it should be the smallest offset that can be 5353169689Skanapplied to a base register while still giving a legitimate address 5354169689Skanfor every mode. The default value is 0. 5355169689Skan@end deftypevar 5356169689Skan 5357169689Skan@deftypevar {Target Hook} HOST_WIDE_INT TARGET_MAX_ANCHOR_OFFSET 5358169689SkanLike @code{TARGET_MIN_ANCHOR_OFFSET}, but the maximum (inclusive) 5359169689Skanoffset that should be applied to section anchors. The default 5360169689Skanvalue is 0. 5361169689Skan@end deftypevar 5362169689Skan 5363169689Skan@deftypefn {Target Hook} void TARGET_ASM_OUTPUT_ANCHOR (rtx @var{x}) 5364169689SkanWrite the assembly code to define section anchor @var{x}, which is a 5365169689Skan@code{SYMBOL_REF} for which @samp{SYMBOL_REF_ANCHOR_P (@var{x})} is true. 5366169689SkanThe hook is called with the assembly output position set to the beginning 5367169689Skanof @code{SYMBOL_REF_BLOCK (@var{x})}. 5368169689Skan 5369169689SkanIf @code{ASM_OUTPUT_DEF} is available, the hook's default definition uses 5370169689Skanit to define the symbol as @samp{. + SYMBOL_REF_BLOCK_OFFSET (@var{x})}. 5371169689SkanIf @code{ASM_OUTPUT_DEF} is not available, the hook's default definition 5372169689Skanis @code{NULL}, which disables the use of section anchors altogether. 5373169689Skan@end deftypefn 5374169689Skan 5375169689Skan@deftypefn {Target Hook} bool TARGET_USE_ANCHORS_FOR_SYMBOL_P (rtx @var{x}) 5376169689SkanReturn true if GCC should attempt to use anchors to access @code{SYMBOL_REF} 5377169689Skan@var{x}. You can assume @samp{SYMBOL_REF_HAS_BLOCK_INFO_P (@var{x})} and 5378169689Skan@samp{!SYMBOL_REF_ANCHOR_P (@var{x})}. 5379169689Skan 5380169689SkanThe default version is correct for most targets, but you might need to 5381169689Skanintercept this hook to handle things like target-specific attributes 5382169689Skanor target-specific sections. 5383169689Skan@end deftypefn 5384169689Skan 538590075Sobrien@node Condition Code 538690075Sobrien@section Condition Code Status 538790075Sobrien@cindex condition code status 538890075Sobrien 538990075Sobrien@c prevent bad page break with this line 539090075SobrienThis describes the condition code status. 539190075Sobrien 539290075Sobrien@findex cc_status 539390075SobrienThe file @file{conditions.h} defines a variable @code{cc_status} to 539490075Sobriendescribe how the condition code was computed (in case the interpretation of 539590075Sobrienthe condition code depends on the instruction that it was set by). This 539690075Sobrienvariable contains the RTL expressions on which the condition code is 539790075Sobriencurrently based, and several standard flags. 539890075Sobrien 539990075SobrienSometimes additional machine-specific flags must be defined in the machine 540090075Sobriendescription header file. It can also add additional machine-specific 540190075Sobrieninformation by defining @code{CC_STATUS_MDEP}. 540290075Sobrien 5403132718Skan@defmac CC_STATUS_MDEP 540490075SobrienC code for a data type which is used for declaring the @code{mdep} 540590075Sobriencomponent of @code{cc_status}. It defaults to @code{int}. 540690075Sobrien 540790075SobrienThis macro is not used on machines that do not use @code{cc0}. 5408132718Skan@end defmac 540990075Sobrien 5410132718Skan@defmac CC_STATUS_MDEP_INIT 541190075SobrienA C expression to initialize the @code{mdep} field to ``empty''. 541290075SobrienThe default definition does nothing, since most machines don't use 541390075Sobrienthe field anyway. If you want to use the field, you should probably 541490075Sobriendefine this macro to initialize it. 541590075Sobrien 541690075SobrienThis macro is not used on machines that do not use @code{cc0}. 5417132718Skan@end defmac 541890075Sobrien 5419132718Skan@defmac NOTICE_UPDATE_CC (@var{exp}, @var{insn}) 542090075SobrienA C compound statement to set the components of @code{cc_status} 542190075Sobrienappropriately for an insn @var{insn} whose body is @var{exp}. It is 542290075Sobrienthis macro's responsibility to recognize insns that set the condition 542390075Sobriencode as a byproduct of other activity as well as those that explicitly 542490075Sobrienset @code{(cc0)}. 542590075Sobrien 542690075SobrienThis macro is not used on machines that do not use @code{cc0}. 542790075Sobrien 542890075SobrienIf there are insns that do not set the condition code but do alter 542990075Sobrienother machine registers, this macro must check to see whether they 543090075Sobrieninvalidate the expressions that the condition code is recorded as 543190075Sobrienreflecting. For example, on the 68000, insns that store in address 543290075Sobrienregisters do not set the condition code, which means that usually 543390075Sobrien@code{NOTICE_UPDATE_CC} can leave @code{cc_status} unaltered for such 543490075Sobrieninsns. But suppose that the previous insn set the condition code 543590075Sobrienbased on location @samp{a4@@(102)} and the current insn stores a new 543690075Sobrienvalue in @samp{a4}. Although the condition code is not changed by 543790075Sobrienthis, it will no longer be true that it reflects the contents of 543890075Sobrien@samp{a4@@(102)}. Therefore, @code{NOTICE_UPDATE_CC} must alter 543990075Sobrien@code{cc_status} in this case to say that nothing is known about the 544090075Sobriencondition code value. 544190075Sobrien 544290075SobrienThe definition of @code{NOTICE_UPDATE_CC} must be prepared to deal 544390075Sobrienwith the results of peephole optimization: insns whose patterns are 544490075Sobrien@code{parallel} RTXs containing various @code{reg}, @code{mem} or 544590075Sobrienconstants which are just the operands. The RTL structure of these 544690075Sobrieninsns is not sufficient to indicate what the insns actually do. What 544790075Sobrien@code{NOTICE_UPDATE_CC} should do when it sees one is just to run 544890075Sobrien@code{CC_STATUS_INIT}. 544990075Sobrien 545090075SobrienA possible definition of @code{NOTICE_UPDATE_CC} is to call a function 545190075Sobrienthat looks at an attribute (@pxref{Insn Attributes}) named, for example, 545290075Sobrien@samp{cc}. This avoids having detailed information about patterns in 545390075Sobrientwo places, the @file{md} file and in @code{NOTICE_UPDATE_CC}. 5454132718Skan@end defmac 545590075Sobrien 5456132718Skan@defmac SELECT_CC_MODE (@var{op}, @var{x}, @var{y}) 545790075SobrienReturns a mode from class @code{MODE_CC} to be used when comparison 545890075Sobrienoperation code @var{op} is applied to rtx @var{x} and @var{y}. For 5459117395Skanexample, on the SPARC, @code{SELECT_CC_MODE} is defined as (see 546090075Sobrien@pxref{Jump Patterns} for a description of the reason for this 546190075Sobriendefinition) 546290075Sobrien 546390075Sobrien@smallexample 546490075Sobrien#define SELECT_CC_MODE(OP,X,Y) \ 546590075Sobrien (GET_MODE_CLASS (GET_MODE (X)) == MODE_FLOAT \ 546690075Sobrien ? ((OP == EQ || OP == NE) ? CCFPmode : CCFPEmode) \ 546790075Sobrien : ((GET_CODE (X) == PLUS || GET_CODE (X) == MINUS \ 546890075Sobrien || GET_CODE (X) == NEG) \ 546990075Sobrien ? CC_NOOVmode : CCmode)) 547090075Sobrien@end smallexample 547190075Sobrien 5472132718SkanYou should define this macro if and only if you define extra CC modes 5473132718Skanin @file{@var{machine}-modes.def}. 5474132718Skan@end defmac 547590075Sobrien 5476132718Skan@defmac CANONICALIZE_COMPARISON (@var{code}, @var{op0}, @var{op1}) 547790075SobrienOn some machines not all possible comparisons are defined, but you can 547890075Sobrienconvert an invalid comparison into a valid one. For example, the Alpha 547990075Sobriendoes not have a @code{GT} comparison, but you can use an @code{LT} 548090075Sobriencomparison instead and swap the order of the operands. 548190075Sobrien 548290075SobrienOn such machines, define this macro to be a C statement to do any 548390075Sobrienrequired conversions. @var{code} is the initial comparison code 548490075Sobrienand @var{op0} and @var{op1} are the left and right operands of the 548590075Sobriencomparison, respectively. You should modify @var{code}, @var{op0}, and 548690075Sobrien@var{op1} as required. 548790075Sobrien 548890075SobrienGCC will not assume that the comparison resulting from this macro is 548990075Sobrienvalid but will see if the resulting insn matches a pattern in the 549090075Sobrien@file{md} file. 549190075Sobrien 549290075SobrienYou need not define this macro if it would never change the comparison 549390075Sobriencode or operands. 5494132718Skan@end defmac 549590075Sobrien 5496132718Skan@defmac REVERSIBLE_CC_MODE (@var{mode}) 549790075SobrienA C expression whose value is one if it is always safe to reverse a 549890075Sobriencomparison whose mode is @var{mode}. If @code{SELECT_CC_MODE} 549990075Sobriencan ever return @var{mode} for a floating-point inequality comparison, 550090075Sobrienthen @code{REVERSIBLE_CC_MODE (@var{mode})} must be zero. 550190075Sobrien 550290075SobrienYou need not define this macro if it would always returns zero or if the 550390075Sobrienfloating-point format is anything other than @code{IEEE_FLOAT_FORMAT}. 5504117395SkanFor example, here is the definition used on the SPARC, where floating-point 550590075Sobrieninequality comparisons are always given @code{CCFPEmode}: 550690075Sobrien 550790075Sobrien@smallexample 550890075Sobrien#define REVERSIBLE_CC_MODE(MODE) ((MODE) != CCFPEmode) 550990075Sobrien@end smallexample 5510132718Skan@end defmac 551190075Sobrien 5512132718Skan@defmac REVERSE_CONDITION (@var{code}, @var{mode}) 551390075SobrienA C expression whose value is reversed condition code of the @var{code} for 551490075Sobriencomparison done in CC_MODE @var{mode}. The macro is used only in case 551590075Sobrien@code{REVERSIBLE_CC_MODE (@var{mode})} is nonzero. Define this macro in case 551690075Sobrienmachine has some non-standard way how to reverse certain conditionals. For 551790075Sobrieninstance in case all floating point conditions are non-trapping, compiler may 551890075Sobrienfreely convert unordered compares to ordered one. Then definition may look 551990075Sobrienlike: 552090075Sobrien 552190075Sobrien@smallexample 552290075Sobrien#define REVERSE_CONDITION(CODE, MODE) \ 552390075Sobrien ((MODE) != CCFPmode ? reverse_condition (CODE) \ 552490075Sobrien : reverse_condition_maybe_unordered (CODE)) 552590075Sobrien@end smallexample 5526132718Skan@end defmac 552790075Sobrien 5528169689Skan@defmac REVERSE_CONDEXEC_PREDICATES_P (@var{op1}, @var{op2}) 552990075SobrienA C expression that returns true if the conditional execution predicate 5530169689Skan@var{op1}, a comparison operation, is the inverse of @var{op2} and vice 5531169689Skanversa. Define this to return 0 if the target has conditional execution 5532169689Skanpredicates that cannot be reversed safely. There is no need to validate 5533169689Skanthat the arguments of op1 and op2 are the same, this is done separately. 5534169689SkanIf no expansion is specified, this macro is defined as follows: 553590075Sobrien 553690075Sobrien@smallexample 553790075Sobrien#define REVERSE_CONDEXEC_PREDICATES_P (x, y) \ 5538169689Skan (GET_CODE ((x)) == reversed_comparison_code ((y), NULL)) 553990075Sobrien@end smallexample 5540132718Skan@end defmac 554190075Sobrien 5542132718Skan@deftypefn {Target Hook} bool TARGET_FIXED_CONDITION_CODE_REGS (unsigned int *, unsigned int *) 5543132718SkanOn targets which do not use @code{(cc0)}, and which use a hard 5544132718Skanregister rather than a pseudo-register to hold condition codes, the 5545132718Skanregular CSE passes are often not able to identify cases in which the 5546132718Skanhard register is set to a common value. Use this hook to enable a 5547132718Skansmall pass which optimizes such cases. This hook should return true 5548132718Skanto enable this pass, and it should set the integers to which its 5549132718Skanarguments point to the hard register numbers used for condition codes. 5550132718SkanWhen there is only one such register, as is true on most systems, the 5551132718Skaninteger pointed to by the second argument should be set to 5552132718Skan@code{INVALID_REGNUM}. 555390075Sobrien 5554132718SkanThe default version of this hook returns false. 5555132718Skan@end deftypefn 5556132718Skan 5557132718Skan@deftypefn {Target Hook} enum machine_mode TARGET_CC_MODES_COMPATIBLE (enum machine_mode, enum machine_mode) 5558132718SkanOn targets which use multiple condition code modes in class 5559132718Skan@code{MODE_CC}, it is sometimes the case that a comparison can be 5560132718Skanvalidly done in more than one mode. On such a system, define this 5561132718Skantarget hook to take two mode arguments and to return a mode in which 5562132718Skanboth comparisons may be validly done. If there is no such mode, 5563132718Skanreturn @code{VOIDmode}. 5564132718Skan 5565132718SkanThe default version of this hook checks whether the modes are the 5566132718Skansame. If they are, it returns that mode. If they are different, it 5567132718Skanreturns @code{VOIDmode}. 5568132718Skan@end deftypefn 5569132718Skan 557090075Sobrien@node Costs 557190075Sobrien@section Describing Relative Costs of Operations 557290075Sobrien@cindex costs of instructions 557390075Sobrien@cindex relative costs 557490075Sobrien@cindex speed of instructions 557590075Sobrien 557690075SobrienThese macros let you describe the relative speed of various operations 557790075Sobrienon the target machine. 557890075Sobrien 5579132718Skan@defmac REGISTER_MOVE_COST (@var{mode}, @var{from}, @var{to}) 558090075SobrienA C expression for the cost of moving data of mode @var{mode} from a 558190075Sobrienregister in class @var{from} to one in class @var{to}. The classes are 558290075Sobrienexpressed using the enumeration values such as @code{GENERAL_REGS}. A 558390075Sobrienvalue of 2 is the default; other values are interpreted relative to 558490075Sobrienthat. 558590075Sobrien 558690075SobrienIt is not required that the cost always equal 2 when @var{from} is the 558790075Sobriensame as @var{to}; on some machines it is expensive to move between 558890075Sobrienregisters if they are not general registers. 558990075Sobrien 559090075SobrienIf reload sees an insn consisting of a single @code{set} between two 559190075Sobrienhard registers, and if @code{REGISTER_MOVE_COST} applied to their 559290075Sobrienclasses returns a value of 2, reload does not check to ensure that the 559390075Sobrienconstraints of the insn are met. Setting a cost of other than 2 will 559490075Sobrienallow reload to verify that the constraints are met. You should do this 559590075Sobrienif the @samp{mov@var{m}} pattern's constraints do not allow such copying. 5596132718Skan@end defmac 559790075Sobrien 5598132718Skan@defmac MEMORY_MOVE_COST (@var{mode}, @var{class}, @var{in}) 559990075SobrienA C expression for the cost of moving data of mode @var{mode} between a 560090075Sobrienregister of class @var{class} and memory; @var{in} is zero if the value 560190075Sobrienis to be written to memory, nonzero if it is to be read in. This cost 560290075Sobrienis relative to those in @code{REGISTER_MOVE_COST}. If moving between 560390075Sobrienregisters and memory is more expensive than between two registers, you 560490075Sobrienshould define this macro to express the relative cost. 560590075Sobrien 560690075SobrienIf you do not define this macro, GCC uses a default cost of 4 plus 560790075Sobrienthe cost of copying via a secondary reload register, if one is 560890075Sobrienneeded. If your machine requires a secondary reload register to copy 560990075Sobrienbetween memory and a register of @var{class} but the reload mechanism is 561090075Sobrienmore complex than copying via an intermediate, define this macro to 561190075Sobrienreflect the actual cost of the move. 561290075Sobrien 561390075SobrienGCC defines the function @code{memory_move_secondary_cost} if 561490075Sobriensecondary reloads are needed. It computes the costs due to copying via 561590075Sobriena secondary register. If your machine copies from memory using a 561690075Sobriensecondary register in the conventional way but the default base value of 561790075Sobrien4 is not correct for your machine, define this macro to add some other 561890075Sobrienvalue to the result of that function. The arguments to that function 561990075Sobrienare the same as to this macro. 5620132718Skan@end defmac 562190075Sobrien 5622132718Skan@defmac BRANCH_COST 562390075SobrienA C expression for the cost of a branch instruction. A value of 1 is 562490075Sobrienthe default; other values are interpreted relative to that. 5625132718Skan@end defmac 562690075Sobrien 562790075SobrienHere are additional macros which do not specify precise relative costs, 562890075Sobrienbut only that certain actions are more expensive than GCC would 562990075Sobrienordinarily expect. 563090075Sobrien 5631132718Skan@defmac SLOW_BYTE_ACCESS 563290075SobrienDefine this macro as a C expression which is nonzero if accessing less 563390075Sobrienthan a word of memory (i.e.@: a @code{char} or a @code{short}) is no 563490075Sobrienfaster than accessing a word of memory, i.e., if such access 563590075Sobrienrequire more than one instruction or if there is no difference in cost 563690075Sobrienbetween byte and (aligned) word loads. 563790075Sobrien 563890075SobrienWhen this macro is not defined, the compiler will access a field by 563990075Sobrienfinding the smallest containing object; when it is defined, a fullword 564090075Sobrienload will be used if alignment permits. Unless bytes accesses are 564190075Sobrienfaster than word accesses, using word accesses is preferable since it 564290075Sobrienmay eliminate subsequent memory access if subsequent accesses occur to 564390075Sobrienother fields in the same word of the structure, but to different bytes. 5644132718Skan@end defmac 564590075Sobrien 5646132718Skan@defmac SLOW_UNALIGNED_ACCESS (@var{mode}, @var{alignment}) 564790075SobrienDefine this macro to be the value 1 if memory accesses described by the 564890075Sobrien@var{mode} and @var{alignment} parameters have a cost many times greater 564990075Sobrienthan aligned accesses, for example if they are emulated in a trap 565090075Sobrienhandler. 565190075Sobrien 565290075SobrienWhen this macro is nonzero, the compiler will act as if 565390075Sobrien@code{STRICT_ALIGNMENT} were nonzero when generating code for block 565490075Sobrienmoves. This can cause significantly more instructions to be produced. 565590075SobrienTherefore, do not set this macro nonzero if unaligned accesses only add a 565690075Sobriencycle or two to the time for a memory access. 565790075Sobrien 565890075SobrienIf the value of this macro is always zero, it need not be defined. If 565990075Sobrienthis macro is defined, it should produce a nonzero value when 566090075Sobrien@code{STRICT_ALIGNMENT} is nonzero. 5661132718Skan@end defmac 566290075Sobrien 5663132718Skan@defmac MOVE_RATIO 566490075SobrienThe threshold of number of scalar memory-to-memory move insns, @emph{below} 566590075Sobrienwhich a sequence of insns should be generated instead of a 566690075Sobrienstring move insn or a library call. Increasing the value will always 566790075Sobrienmake code faster, but eventually incurs high cost in increased code size. 566890075Sobrien 566990075SobrienNote that on machines where the corresponding move insn is a 567090075Sobrien@code{define_expand} that emits a sequence of insns, this macro counts 567190075Sobrienthe number of such sequences. 567290075Sobrien 567390075SobrienIf you don't define this, a reasonable default is used. 5674132718Skan@end defmac 567590075Sobrien 5676132718Skan@defmac MOVE_BY_PIECES_P (@var{size}, @var{alignment}) 567790075SobrienA C expression used to determine whether @code{move_by_pieces} will be used to 567890075Sobriencopy a chunk of memory, or whether some other block move mechanism 567990075Sobrienwill be used. Defaults to 1 if @code{move_by_pieces_ninsns} returns less 568090075Sobrienthan @code{MOVE_RATIO}. 5681132718Skan@end defmac 568290075Sobrien 5683132718Skan@defmac MOVE_MAX_PIECES 568490075SobrienA C expression used by @code{move_by_pieces} to determine the largest unit 568590075Sobriena load or store used to copy memory is. Defaults to @code{MOVE_MAX}. 5686132718Skan@end defmac 568790075Sobrien 5688132718Skan@defmac CLEAR_RATIO 5689117395SkanThe threshold of number of scalar move insns, @emph{below} which a sequence 5690117395Skanof insns should be generated to clear memory instead of a string clear insn 5691117395Skanor a library call. Increasing the value will always make code faster, but 5692117395Skaneventually incurs high cost in increased code size. 5693117395Skan 5694117395SkanIf you don't define this, a reasonable default is used. 5695132718Skan@end defmac 5696117395Skan 5697132718Skan@defmac CLEAR_BY_PIECES_P (@var{size}, @var{alignment}) 5698117395SkanA C expression used to determine whether @code{clear_by_pieces} will be used 5699117395Skanto clear a chunk of memory, or whether some other block clear mechanism 5700117395Skanwill be used. Defaults to 1 if @code{move_by_pieces_ninsns} returns less 5701117395Skanthan @code{CLEAR_RATIO}. 5702132718Skan@end defmac 5703117395Skan 5704132718Skan@defmac STORE_BY_PIECES_P (@var{size}, @var{alignment}) 5705132718SkanA C expression used to determine whether @code{store_by_pieces} will be 5706132718Skanused to set a chunk of memory to a constant value, or whether some other 5707132718Skanmechanism will be used. Used by @code{__builtin_memset} when storing 5708132718Skanvalues other than constant zero and by @code{__builtin_strcpy} when 5709132718Skanwhen called with a constant source string. 5710169689SkanDefaults to 1 if @code{move_by_pieces_ninsns} returns less 5711169689Skanthan @code{MOVE_RATIO}. 5712132718Skan@end defmac 5713132718Skan 5714132718Skan@defmac USE_LOAD_POST_INCREMENT (@var{mode}) 571590075SobrienA C expression used to determine whether a load postincrement is a good 571690075Sobrienthing to use for a given mode. Defaults to the value of 571790075Sobrien@code{HAVE_POST_INCREMENT}. 5718132718Skan@end defmac 571990075Sobrien 5720132718Skan@defmac USE_LOAD_POST_DECREMENT (@var{mode}) 572190075SobrienA C expression used to determine whether a load postdecrement is a good 572290075Sobrienthing to use for a given mode. Defaults to the value of 572390075Sobrien@code{HAVE_POST_DECREMENT}. 5724132718Skan@end defmac 572590075Sobrien 5726132718Skan@defmac USE_LOAD_PRE_INCREMENT (@var{mode}) 572790075SobrienA C expression used to determine whether a load preincrement is a good 572890075Sobrienthing to use for a given mode. Defaults to the value of 572990075Sobrien@code{HAVE_PRE_INCREMENT}. 5730132718Skan@end defmac 573190075Sobrien 5732132718Skan@defmac USE_LOAD_PRE_DECREMENT (@var{mode}) 573390075SobrienA C expression used to determine whether a load predecrement is a good 573490075Sobrienthing to use for a given mode. Defaults to the value of 573590075Sobrien@code{HAVE_PRE_DECREMENT}. 5736132718Skan@end defmac 573790075Sobrien 5738132718Skan@defmac USE_STORE_POST_INCREMENT (@var{mode}) 573990075SobrienA C expression used to determine whether a store postincrement is a good 574090075Sobrienthing to use for a given mode. Defaults to the value of 574190075Sobrien@code{HAVE_POST_INCREMENT}. 5742132718Skan@end defmac 574390075Sobrien 5744132718Skan@defmac USE_STORE_POST_DECREMENT (@var{mode}) 574590075SobrienA C expression used to determine whether a store postdecrement is a good 574690075Sobrienthing to use for a given mode. Defaults to the value of 574790075Sobrien@code{HAVE_POST_DECREMENT}. 5748132718Skan@end defmac 574990075Sobrien 5750132718Skan@defmac USE_STORE_PRE_INCREMENT (@var{mode}) 575190075SobrienThis macro is used to determine whether a store preincrement is a good 575290075Sobrienthing to use for a given mode. Defaults to the value of 575390075Sobrien@code{HAVE_PRE_INCREMENT}. 5754132718Skan@end defmac 575590075Sobrien 5756132718Skan@defmac USE_STORE_PRE_DECREMENT (@var{mode}) 575790075SobrienThis macro is used to determine whether a store predecrement is a good 575890075Sobrienthing to use for a given mode. Defaults to the value of 575990075Sobrien@code{HAVE_PRE_DECREMENT}. 5760132718Skan@end defmac 576190075Sobrien 5762132718Skan@defmac NO_FUNCTION_CSE 576390075SobrienDefine this macro if it is as good or better to call a constant 576490075Sobrienfunction address than to call an address kept in a register. 5765132718Skan@end defmac 576690075Sobrien 5767132718Skan@defmac RANGE_TEST_NON_SHORT_CIRCUIT 5768132718SkanDefine this macro if a non-short-circuit operation produced by 5769132718Skan@samp{fold_range_test ()} is optimal. This macro defaults to true if 5770132718Skan@code{BRANCH_COST} is greater than or equal to the value 2. 5771132718Skan@end defmac 5772132718Skan 5773132718Skan@deftypefn {Target Hook} bool TARGET_RTX_COSTS (rtx @var{x}, int @var{code}, int @var{outer_code}, int *@var{total}) 5774132718SkanThis target hook describes the relative costs of RTL expressions. 5775132718Skan 5776132718SkanThe cost may depend on the precise form of the expression, which is 5777132718Skanavailable for examination in @var{x}, and the rtx code of the expression 5778132718Skanin which it is contained, found in @var{outer_code}. @var{code} is the 5779132718Skanexpression code---redundant, since it can be obtained with 5780132718Skan@code{GET_CODE (@var{x})}. 5781132718Skan 5782132718SkanIn implementing this hook, you can use the construct 5783132718Skan@code{COSTS_N_INSNS (@var{n})} to specify a cost equal to @var{n} fast 5784132718Skaninstructions. 5785132718Skan 5786132718SkanOn entry to the hook, @code{*@var{total}} contains a default estimate 5787132718Skanfor the cost of the expression. The hook should modify this value as 5788169689Skannecessary. Traditionally, the default costs are @code{COSTS_N_INSNS (5)} 5789169689Skanfor multiplications, @code{COSTS_N_INSNS (7)} for division and modulus 5790169689Skanoperations, and @code{COSTS_N_INSNS (1)} for all other operations. 5791132718Skan 5792169689SkanWhen optimizing for code size, i.e.@: when @code{optimize_size} is 5793169689Skannonzero, this target hook should be used to estimate the relative 5794169689Skansize cost of an expression, again relative to @code{COSTS_N_INSNS}. 5795169689Skan 5796132718SkanThe hook returns true when all subexpressions of @var{x} have been 5797132718Skanprocessed, and false when @code{rtx_cost} should recurse. 5798132718Skan@end deftypefn 5799132718Skan 5800132718Skan@deftypefn {Target Hook} int TARGET_ADDRESS_COST (rtx @var{address}) 5801132718SkanThis hook computes the cost of an addressing mode that contains 5802132718Skan@var{address}. If not defined, the cost is computed from 5803132718Skanthe @var{address} expression and the @code{TARGET_RTX_COST} hook. 5804132718Skan 5805132718SkanFor most CISC machines, the default cost is a good approximation of the 5806132718Skantrue cost of the addressing mode. However, on RISC machines, all 5807132718Skaninstructions normally have the same length and execution time. Hence 5808132718Skanall addresses will have equal costs. 5809132718Skan 5810132718SkanIn cases where more than one form of an address is known, the form with 5811132718Skanthe lowest cost will be used. If multiple forms have the same, lowest, 5812132718Skancost, the one that is the most complex will be used. 5813132718Skan 5814132718SkanFor example, suppose an address that is equal to the sum of a register 5815132718Skanand a constant is used twice in the same basic block. When this macro 5816132718Skanis not defined, the address will be computed in a register and memory 5817132718Skanreferences will be indirect through that register. On machines where 5818132718Skanthe cost of the addressing mode containing the sum is no higher than 5819132718Skanthat of a simple indirect reference, this will produce an additional 5820132718Skaninstruction and possibly require an additional register. Proper 5821132718Skanspecification of this macro eliminates this overhead for such machines. 5822132718Skan 5823132718SkanThis hook is never called with an invalid address. 5824132718Skan 5825132718SkanOn machines where an address involving more than one register is as 5826132718Skancheap as an address computation involving only one register, defining 5827132718Skan@code{TARGET_ADDRESS_COST} to reflect this can cause two registers to 5828132718Skanbe live over a region of code where only one would have been if 5829132718Skan@code{TARGET_ADDRESS_COST} were not defined in that manner. This effect 5830132718Skanshould be considered in the definition of this macro. Equivalent costs 5831132718Skanshould probably only be given to addresses with different numbers of 5832132718Skanregisters on machines with lots of registers. 5833132718Skan@end deftypefn 5834132718Skan 583590075Sobrien@node Scheduling 583690075Sobrien@section Adjusting the Instruction Scheduler 583790075Sobrien 583890075SobrienThe instruction scheduler may need a fair amount of machine-specific 583990075Sobrienadjustment in order to produce good code. GCC provides several target 584090075Sobrienhooks for this purpose. It is usually enough to define just a few of 584190075Sobrienthem: try the first ones in this list first. 584290075Sobrien 584390075Sobrien@deftypefn {Target Hook} int TARGET_SCHED_ISSUE_RATE (void) 5844117395SkanThis hook returns the maximum number of instructions that can ever 5845117395Skanissue at the same time on the target machine. The default is one. 5846117395SkanAlthough the insn scheduler can define itself the possibility of issue 5847117395Skanan insn on the same cycle, the value can serve as an additional 5848117395Skanconstraint to issue insns on the same simulated processor cycle (see 5849117395Skanhooks @samp{TARGET_SCHED_REORDER} and @samp{TARGET_SCHED_REORDER2}). 5850117395SkanThis value must be constant over the entire compilation. If you need 5851117395Skanit to vary depending on what the instructions are, you must use 585290075Sobrien@samp{TARGET_SCHED_VARIABLE_ISSUE}. 585390075Sobrien@end deftypefn 585490075Sobrien 585590075Sobrien@deftypefn {Target Hook} int TARGET_SCHED_VARIABLE_ISSUE (FILE *@var{file}, int @var{verbose}, rtx @var{insn}, int @var{more}) 585690075SobrienThis hook is executed by the scheduler after it has scheduled an insn 585790075Sobrienfrom the ready list. It should return the number of insns which can 5858132718Skanstill be issued in the current cycle. The default is 5859132718Skan@samp{@w{@var{more} - 1}} for insns other than @code{CLOBBER} and 5860132718Skan@code{USE}, which normally are not counted against the issue rate. 5861132718SkanYou should define this hook if some insns take more machine resources 5862132718Skanthan others, so that fewer insns can follow them in the same cycle. 5863132718Skan@var{file} is either a null pointer, or a stdio stream to write any 5864132718Skandebug output to. @var{verbose} is the verbose level provided by 5865132718Skan@option{-fsched-verbose-@var{n}}. @var{insn} is the instruction that 5866132718Skanwas scheduled. 586790075Sobrien@end deftypefn 586890075Sobrien 586990075Sobrien@deftypefn {Target Hook} int TARGET_SCHED_ADJUST_COST (rtx @var{insn}, rtx @var{link}, rtx @var{dep_insn}, int @var{cost}) 5870117395SkanThis function corrects the value of @var{cost} based on the 5871117395Skanrelationship between @var{insn} and @var{dep_insn} through the 5872117395Skandependence @var{link}. It should return the new value. The default 5873117395Skanis to make no adjustment to @var{cost}. This can be used for example 5874117395Skanto specify to the scheduler using the traditional pipeline description 587590075Sobrienthat an output- or anti-dependence does not incur the same cost as a 5876117395Skandata-dependence. If the scheduler using the automaton based pipeline 5877117395Skandescription, the cost of anti-dependence is zero and the cost of 5878117395Skanoutput-dependence is maximum of one and the difference of latency 5879117395Skantimes of the first and the second insns. If these values are not 5880117395Skanacceptable, you could use the hook to modify them too. See also 5881169689Skan@pxref{Processor pipeline description}. 588290075Sobrien@end deftypefn 588390075Sobrien 588490075Sobrien@deftypefn {Target Hook} int TARGET_SCHED_ADJUST_PRIORITY (rtx @var{insn}, int @var{priority}) 588590075SobrienThis hook adjusts the integer scheduling priority @var{priority} of 5886169689Skan@var{insn}. It should return the new priority. Increase the priority to 5887169689Skanexecute @var{insn} earlier, reduce the priority to execute @var{insn} 588890075Sobrienlater. Do not define this hook if you do not need to adjust the 588990075Sobrienscheduling priorities of insns. 589090075Sobrien@end deftypefn 589190075Sobrien 589290075Sobrien@deftypefn {Target Hook} int TARGET_SCHED_REORDER (FILE *@var{file}, int @var{verbose}, rtx *@var{ready}, int *@var{n_readyp}, int @var{clock}) 589390075SobrienThis hook is executed by the scheduler after it has scheduled the ready 589490075Sobrienlist, to allow the machine description to reorder it (for example to 589590075Sobriencombine two small instructions together on @samp{VLIW} machines). 589690075Sobrien@var{file} is either a null pointer, or a stdio stream to write any 589790075Sobriendebug output to. @var{verbose} is the verbose level provided by 589890075Sobrien@option{-fsched-verbose-@var{n}}. @var{ready} is a pointer to the ready 589990075Sobrienlist of instructions that are ready to be scheduled. @var{n_readyp} is 590090075Sobriena pointer to the number of elements in the ready list. The scheduler 590190075Sobrienreads the ready list in reverse order, starting with 590290075Sobrien@var{ready}[@var{*n_readyp}-1] and going to @var{ready}[0]. @var{clock} 590390075Sobrienis the timer tick of the scheduler. You may modify the ready list and 590490075Sobrienthe number of ready insns. The return value is the number of insns that 590590075Sobriencan issue this cycle; normally this is just @code{issue_rate}. See also 590690075Sobrien@samp{TARGET_SCHED_REORDER2}. 590790075Sobrien@end deftypefn 590890075Sobrien 590990075Sobrien@deftypefn {Target Hook} int TARGET_SCHED_REORDER2 (FILE *@var{file}, int @var{verbose}, rtx *@var{ready}, int *@var{n_ready}, @var{clock}) 591090075SobrienLike @samp{TARGET_SCHED_REORDER}, but called at a different time. That 591190075Sobrienfunction is called whenever the scheduler starts a new cycle. This one 591290075Sobrienis called once per iteration over a cycle, immediately after 591390075Sobrien@samp{TARGET_SCHED_VARIABLE_ISSUE}; it can reorder the ready list and 591490075Sobrienreturn the number of insns to be scheduled in the same cycle. Defining 591590075Sobrienthis hook can be useful if there are frequent situations where 591690075Sobrienscheduling one insn causes other insns to become ready in the same 591790075Sobriencycle. These other insns can then be taken into account properly. 591890075Sobrien@end deftypefn 591990075Sobrien 5920132718Skan@deftypefn {Target Hook} void TARGET_SCHED_DEPENDENCIES_EVALUATION_HOOK (rtx @var{head}, rtx @var{tail}) 5921132718SkanThis hook is called after evaluation forward dependencies of insns in 5922132718Skanchain given by two parameter values (@var{head} and @var{tail} 5923132718Skancorrespondingly) but before insns scheduling of the insn chain. For 5924132718Skanexample, it can be used for better insn classification if it requires 5925132718Skananalysis of dependencies. This hook can use backward and forward 5926132718Skandependencies of the insn scheduler because they are already 5927132718Skancalculated. 5928132718Skan@end deftypefn 5929132718Skan 593090075Sobrien@deftypefn {Target Hook} void TARGET_SCHED_INIT (FILE *@var{file}, int @var{verbose}, int @var{max_ready}) 593190075SobrienThis hook is executed by the scheduler at the beginning of each block of 593290075Sobrieninstructions that are to be scheduled. @var{file} is either a null 593390075Sobrienpointer, or a stdio stream to write any debug output to. @var{verbose} 593490075Sobrienis the verbose level provided by @option{-fsched-verbose-@var{n}}. 593590075Sobrien@var{max_ready} is the maximum number of insns in the current scheduling 593690075Sobrienregion that can be live at the same time. This can be used to allocate 5937169689Skanscratch space if it is needed, e.g.@: by @samp{TARGET_SCHED_REORDER}. 593890075Sobrien@end deftypefn 593990075Sobrien 594090075Sobrien@deftypefn {Target Hook} void TARGET_SCHED_FINISH (FILE *@var{file}, int @var{verbose}) 594190075SobrienThis hook is executed by the scheduler at the end of each block of 594290075Sobrieninstructions that are to be scheduled. It can be used to perform 594390075Sobriencleanup of any actions done by the other scheduling hooks. @var{file} 594490075Sobrienis either a null pointer, or a stdio stream to write any debug output 594590075Sobriento. @var{verbose} is the verbose level provided by 594690075Sobrien@option{-fsched-verbose-@var{n}}. 594790075Sobrien@end deftypefn 594890075Sobrien 5949169689Skan@deftypefn {Target Hook} void TARGET_SCHED_INIT_GLOBAL (FILE *@var{file}, int @var{verbose}, int @var{old_max_uid}) 5950169689SkanThis hook is executed by the scheduler after function level initializations. 5951169689Skan@var{file} is either a null pointer, or a stdio stream to write any debug output to. 5952169689Skan@var{verbose} is the verbose level provided by @option{-fsched-verbose-@var{n}}. 5953169689Skan@var{old_max_uid} is the maximum insn uid when scheduling begins. 5954169689Skan@end deftypefn 5955117395Skan 5956169689Skan@deftypefn {Target Hook} void TARGET_SCHED_FINISH_GLOBAL (FILE *@var{file}, int @var{verbose}) 5957169689SkanThis is the cleanup hook corresponding to @code{TARGET_SCHED_INIT_GLOBAL}. 5958169689Skan@var{file} is either a null pointer, or a stdio stream to write any debug output to. 5959169689Skan@var{verbose} is the verbose level provided by @option{-fsched-verbose-@var{n}}. 596090075Sobrien@end deftypefn 596190075Sobrien 5962117395Skan@deftypefn {Target Hook} int TARGET_SCHED_DFA_PRE_CYCLE_INSN (void) 5963117395SkanThe hook returns an RTL insn. The automaton state used in the 5964117395Skanpipeline hazard recognizer is changed as if the insn were scheduled 5965117395Skanwhen the new simulated processor cycle starts. Usage of the hook may 5966117395Skansimplify the automaton pipeline description for some @acronym{VLIW} 5967117395Skanprocessors. If the hook is defined, it is used only for the automaton 5968117395Skanbased pipeline description. The default is not to change the state 5969117395Skanwhen the new simulated processor cycle starts. 5970117395Skan@end deftypefn 5971117395Skan 5972117395Skan@deftypefn {Target Hook} void TARGET_SCHED_INIT_DFA_PRE_CYCLE_INSN (void) 5973117395SkanThe hook can be used to initialize data used by the previous hook. 5974117395Skan@end deftypefn 5975117395Skan 5976117395Skan@deftypefn {Target Hook} int TARGET_SCHED_DFA_POST_CYCLE_INSN (void) 5977117395SkanThe hook is analogous to @samp{TARGET_SCHED_DFA_PRE_CYCLE_INSN} but used 5978117395Skanto changed the state as if the insn were scheduled when the new 5979117395Skansimulated processor cycle finishes. 5980117395Skan@end deftypefn 5981117395Skan 5982117395Skan@deftypefn {Target Hook} void TARGET_SCHED_INIT_DFA_POST_CYCLE_INSN (void) 5983117395SkanThe hook is analogous to @samp{TARGET_SCHED_INIT_DFA_PRE_CYCLE_INSN} but 5984117395Skanused to initialize data used by the previous hook. 5985117395Skan@end deftypefn 5986117395Skan 5987117395Skan@deftypefn {Target Hook} int TARGET_SCHED_FIRST_CYCLE_MULTIPASS_DFA_LOOKAHEAD (void) 5988117395SkanThis hook controls better choosing an insn from the ready insn queue 5989117395Skanfor the @acronym{DFA}-based insn scheduler. Usually the scheduler 5990117395Skanchooses the first insn from the queue. If the hook returns a positive 5991117395Skanvalue, an additional scheduler code tries all permutations of 5992117395Skan@samp{TARGET_SCHED_FIRST_CYCLE_MULTIPASS_DFA_LOOKAHEAD ()} 5993117395Skansubsequent ready insns to choose an insn whose issue will result in 5994117395Skanmaximal number of issued insns on the same cycle. For the 5995117395Skan@acronym{VLIW} processor, the code could actually solve the problem of 5996117395Skanpacking simple insns into the @acronym{VLIW} insn. Of course, if the 5997117395Skanrules of @acronym{VLIW} packing are described in the automaton. 5998117395Skan 5999117395SkanThis code also could be used for superscalar @acronym{RISC} 6000117395Skanprocessors. Let us consider a superscalar @acronym{RISC} processor 6001117395Skanwith 3 pipelines. Some insns can be executed in pipelines @var{A} or 6002117395Skan@var{B}, some insns can be executed only in pipelines @var{B} or 6003117395Skan@var{C}, and one insn can be executed in pipeline @var{B}. The 6004117395Skanprocessor may issue the 1st insn into @var{A} and the 2nd one into 6005117395Skan@var{B}. In this case, the 3rd insn will wait for freeing @var{B} 6006117395Skanuntil the next cycle. If the scheduler issues the 3rd insn the first, 6007117395Skanthe processor could issue all 3 insns per cycle. 6008117395Skan 6009117395SkanActually this code demonstrates advantages of the automaton based 6010117395Skanpipeline hazard recognizer. We try quickly and easy many insn 6011117395Skanschedules to choose the best one. 6012117395Skan 6013117395SkanThe default is no multipass scheduling. 6014117395Skan@end deftypefn 6015117395Skan 6016132718Skan@deftypefn {Target Hook} int TARGET_SCHED_FIRST_CYCLE_MULTIPASS_DFA_LOOKAHEAD_GUARD (rtx) 6017132718Skan 6018132718SkanThis hook controls what insns from the ready insn queue will be 6019132718Skanconsidered for the multipass insn scheduling. If the hook returns 6020132718Skanzero for insn passed as the parameter, the insn will be not chosen to 6021132718Skanbe issued. 6022132718Skan 6023132718SkanThe default is that any ready insns can be chosen to be issued. 6024132718Skan@end deftypefn 6025132718Skan 6026132718Skan@deftypefn {Target Hook} int TARGET_SCHED_DFA_NEW_CYCLE (FILE *, int, rtx, int, int, int *) 6027132718Skan 6028132718SkanThis hook is called by the insn scheduler before issuing insn passed 6029132718Skanas the third parameter on given cycle. If the hook returns nonzero, 6030132718Skanthe insn is not issued on given processors cycle. Instead of that, 6031132718Skanthe processor cycle is advanced. If the value passed through the last 6032132718Skanparameter is zero, the insn ready queue is not sorted on the new cycle 6033132718Skanstart as usually. The first parameter passes file for debugging 6034132718Skanoutput. The second one passes the scheduler verbose level of the 6035132718Skandebugging output. The forth and the fifth parameter values are 6036132718Skancorrespondingly processor cycle on which the previous insn has been 6037132718Skanissued and the current processor cycle. 6038132718Skan@end deftypefn 6039132718Skan 6040169689Skan@deftypefn {Target Hook} bool TARGET_SCHED_IS_COSTLY_DEPENDENCE (rtx @var{insn1}, rtx @var{insn2}, rtx @var{dep_link}, int @var{dep_cost}, int @var{distance}) 6041132718SkanThis hook is used to define which dependences are considered costly by 6042132718Skanthe target, so costly that it is not advisable to schedule the insns that 6043132718Skanare involved in the dependence too close to one another. The parameters 6044132718Skanto this hook are as follows: The second parameter @var{insn2} is dependent 6045132718Skanupon the first parameter @var{insn1}. The dependence between @var{insn1} 6046132718Skanand @var{insn2} is represented by the third parameter @var{dep_link}. The 6047132718Skanfourth parameter @var{cost} is the cost of the dependence, and the fifth 6048132718Skanparameter @var{distance} is the distance in cycles between the two insns. 6049132718SkanThe hook returns @code{true} if considering the distance between the two 6050132718Skaninsns the dependence between them is considered costly by the target, 6051132718Skanand @code{false} otherwise. 6052132718Skan 6053132718SkanDefining this hook can be useful in multiple-issue out-of-order machines, 6054132718Skanwhere (a) it's practically hopeless to predict the actual data/resource 6055132718Skandelays, however: (b) there's a better chance to predict the actual grouping 6056132718Skanthat will be formed, and (c) correctly emulating the grouping can be very 6057132718Skanimportant. In such targets one may want to allow issuing dependent insns 6058169689Skancloser to one another---i.e., closer than the dependence distance; however, 6059132718Skannot in cases of "costly dependences", which this hooks allows to define. 6060132718Skan@end deftypefn 6061132718Skan 6062169689Skan@deftypefn {Target Hook} int TARGET_SCHED_ADJUST_COST_2 (rtx @var{insn}, int @var{dep_type}, rtx @var{dep_insn}, int @var{cost}) 6063169689SkanThis hook is a modified version of @samp{TARGET_SCHED_ADJUST_COST}. Instead 6064169689Skanof passing dependence as a second parameter, it passes a type of that 6065169689Skandependence. This is useful to calculate cost of dependence between insns 6066169689Skannot having the corresponding link. If @samp{TARGET_SCHED_ADJUST_COST_2} is 6067169689Skandefined it is used instead of @samp{TARGET_SCHED_ADJUST_COST}. 6068169689Skan@end deftypefn 6069117395Skan 6070169689Skan@deftypefn {Target Hook} void TARGET_SCHED_H_I_D_EXTENDED (void) 6071169689SkanThis hook is called by the insn scheduler after emitting a new instruction to 6072169689Skanthe instruction stream. The hook notifies a target backend to extend its 6073169689Skanper instruction data structures. 6074169689Skan@end deftypefn 6075117395Skan 6076169689Skan@deftypefn {Target Hook} int TARGET_SCHED_SPECULATE_INSN (rtx @var{insn}, int @var{request}, rtx *@var{new_pat}) 6077169689SkanThis hook is called by the insn scheduler when @var{insn} has only 6078169689Skanspeculative dependencies and therefore can be scheduled speculatively. 6079169689SkanThe hook is used to check if the pattern of @var{insn} has a speculative 6080169689Skanversion and, in case of successful check, to generate that speculative 6081169689Skanpattern. The hook should return 1, if the instruction has a speculative form, 6082169689Skanor -1, if it doesn't. @var{request} describes the type of requested 6083169689Skanspeculation. If the return value equals 1 then @var{new_pat} is assigned 6084169689Skanthe generated speculative pattern. 6085169689Skan@end deftypefn 6086117395Skan 6087169689Skan@deftypefn {Target Hook} int TARGET_SCHED_NEEDS_BLOCK_P (rtx @var{insn}) 6088169689SkanThis hook is called by the insn scheduler during generation of recovery code 6089169689Skanfor @var{insn}. It should return nonzero, if the corresponding check 6090169689Skaninstruction should branch to recovery code, or zero otherwise. 6091169689Skan@end deftypefn 6092117395Skan 6093169689Skan@deftypefn {Target Hook} rtx TARGET_SCHED_GEN_CHECK (rtx @var{insn}, rtx @var{label}, int @var{mutate_p}) 6094169689SkanThis hook is called by the insn scheduler to generate a pattern for recovery 6095169689Skancheck instruction. If @var{mutate_p} is zero, then @var{insn} is a 6096169689Skanspeculative instruction for which the check should be generated. 6097169689Skan@var{label} is either a label of a basic block, where recovery code should 6098169689Skanbe emitted, or a null pointer, when requested check doesn't branch to 6099169689Skanrecovery code (a simple check). If @var{mutate_p} is nonzero, then 6100169689Skana pattern for a branchy check corresponding to a simple check denoted by 6101169689Skan@var{insn} should be generated. In this case @var{label} can't be null. 6102169689Skan@end deftypefn 6103169689Skan 6104169689Skan@deftypefn {Target Hook} int TARGET_SCHED_FIRST_CYCLE_MULTIPASS_DFA_LOOKAHEAD_GUARD_SPEC (rtx @var{insn}) 6105169689SkanThis hook is used as a workaround for 6106169689Skan@samp{TARGET_SCHED_FIRST_CYCLE_MULTIPASS_DFA_LOOKAHEAD_GUARD} not being 6107169689Skancalled on the first instruction of the ready list. The hook is used to 6108169689Skandiscard speculative instruction that stand first in the ready list from 6109169689Skanbeing scheduled on the current cycle. For non-speculative instructions, 6110169689Skanthe hook should always return nonzero. For example, in the ia64 backend 6111169689Skanthe hook is used to cancel data speculative insns when the ALAT table 6112169689Skanis nearly full. 6113169689Skan@end deftypefn 6114169689Skan 6115169689Skan@deftypefn {Target Hook} void TARGET_SCHED_SET_SCHED_FLAGS (unsigned int *@var{flags}, spec_info_t @var{spec_info}) 6116169689SkanThis hook is used by the insn scheduler to find out what features should be 6117169689Skanenabled/used. @var{flags} initially may have either the SCHED_RGN or SCHED_EBB 6118169689Skanbit set. This denotes the scheduler pass for which the data should be 6119169689Skanprovided. The target backend should modify @var{flags} by modifying 6120169689Skanthe bits corresponding to the following features: USE_DEPS_LIST, USE_GLAT, 6121169689SkanDETACH_LIFE_INFO, and DO_SPECULATION. For the DO_SPECULATION feature 6122169689Skanan additional structure @var{spec_info} should be filled by the target. 6123169689SkanThe structure describes speculation types that can be used in the scheduler. 6124169689Skan@end deftypefn 6125169689Skan 612690075Sobrien@node Sections 612790075Sobrien@section Dividing the Output into Sections (Texts, Data, @dots{}) 612890075Sobrien@c the above section title is WAY too long. maybe cut the part between 612990075Sobrien@c the (...)? --mew 10feb93 613090075Sobrien 613190075SobrienAn object file is divided into sections containing different types of 613290075Sobriendata. In the most common case, there are three sections: the @dfn{text 613390075Sobriensection}, which holds instructions and read-only data; the @dfn{data 613490075Sobriensection}, which holds initialized writable data; and the @dfn{bss 613590075Sobriensection}, which holds uninitialized data. Some systems have other kinds 613690075Sobrienof sections. 613790075Sobrien 6138169689Skan@file{varasm.c} provides several well-known sections, such as 6139169689Skan@code{text_section}, @code{data_section} and @code{bss_section}. 6140169689SkanThe normal way of controlling a @code{@var{foo}_section} variable 6141169689Skanis to define the associated @code{@var{FOO}_SECTION_ASM_OP} macro, 6142169689Skanas described below. The macros are only read once, when @file{varasm.c} 6143169689Skaninitializes itself, so their values must be run-time constants. 6144169689SkanThey may however depend on command-line flags. 614590075Sobrien 6146169689Skan@emph{Note:} Some run-time files, such @file{crtstuff.c}, also make 6147169689Skanuse of the @code{@var{FOO}_SECTION_ASM_OP} macros, and expect them 6148169689Skanto be string literals. 6149169689Skan 6150169689SkanSome assemblers require a different string to be written every time a 6151169689Skansection is selected. If your assembler falls into this category, you 6152169689Skanshould define the @code{TARGET_ASM_INIT_SECTIONS} hook and use 6153169689Skan@code{get_unnamed_section} to set up the sections. 6154169689Skan 6155169689SkanYou must always create a @code{text_section}, either by defining 6156169689Skan@code{TEXT_SECTION_ASM_OP} or by initializing @code{text_section} 6157169689Skanin @code{TARGET_ASM_INIT_SECTIONS}. The same is true of 6158169689Skan@code{data_section} and @code{DATA_SECTION_ASM_OP}. If you do not 6159169689Skancreate a distinct @code{readonly_data_section}, the default is to 6160169689Skanreuse @code{text_section}. 6161169689Skan 6162169689SkanAll the other @file{varasm.c} sections are optional, and are null 6163169689Skanif the target does not provide them. 6164169689Skan 6165132718Skan@defmac TEXT_SECTION_ASM_OP 616690075SobrienA C expression whose value is a string, including spacing, containing the 616790075Sobrienassembler operation that should precede instructions and read-only data. 616890075SobrienNormally @code{"\t.text"} is right. 6169132718Skan@end defmac 617090075Sobrien 6171132718Skan@defmac HOT_TEXT_SECTION_NAME 6172117395SkanIf defined, a C string constant for the name of the section containing most 6173117395Skanfrequently executed functions of the program. If not defined, GCC will provide 6174117395Skana default definition if the target supports named sections. 6175132718Skan@end defmac 6176117395Skan 6177132718Skan@defmac UNLIKELY_EXECUTED_TEXT_SECTION_NAME 6178117395SkanIf defined, a C string constant for the name of the section containing unlikely 6179117395Skanexecuted functions in the program. 6180132718Skan@end defmac 6181117395Skan 6182132718Skan@defmac DATA_SECTION_ASM_OP 618390075SobrienA C expression whose value is a string, including spacing, containing the 618490075Sobrienassembler operation to identify the following data as writable initialized 618590075Sobriendata. Normally @code{"\t.data"} is right. 6186132718Skan@end defmac 618790075Sobrien 6188169689Skan@defmac SDATA_SECTION_ASM_OP 6189169689SkanIf defined, a C expression whose value is a string, including spacing, 6190169689Skancontaining the assembler operation to identify the following data as 6191169689Skaninitialized, writable small data. 6192169689Skan@end defmac 6193169689Skan 6194132718Skan@defmac READONLY_DATA_SECTION_ASM_OP 6195117395SkanA C expression whose value is a string, including spacing, containing the 6196117395Skanassembler operation to identify the following data as read-only initialized 6197117395Skandata. 6198132718Skan@end defmac 6199117395Skan 6200132718Skan@defmac BSS_SECTION_ASM_OP 620190075SobrienIf defined, a C expression whose value is a string, including spacing, 620290075Sobriencontaining the assembler operation to identify the following data as 620390075Sobrienuninitialized global data. If not defined, and neither 620490075Sobrien@code{ASM_OUTPUT_BSS} nor @code{ASM_OUTPUT_ALIGNED_BSS} are defined, 620590075Sobrienuninitialized global data will be output in the data section if 620690075Sobrien@option{-fno-common} is passed, otherwise @code{ASM_OUTPUT_COMMON} will be 620790075Sobrienused. 6208132718Skan@end defmac 620990075Sobrien 6210169689Skan@defmac SBSS_SECTION_ASM_OP 6211169689SkanIf defined, a C expression whose value is a string, including spacing, 6212169689Skancontaining the assembler operation to identify the following data as 6213169689Skanuninitialized, writable small data. 6214169689Skan@end defmac 6215169689Skan 6216132718Skan@defmac INIT_SECTION_ASM_OP 621790075SobrienIf defined, a C expression whose value is a string, including spacing, 621890075Sobriencontaining the assembler operation to identify the following data as 621990075Sobrieninitialization code. If not defined, GCC will assume such a section does 6220169689Skannot exist. This section has no corresponding @code{init_section} 6221169689Skanvariable; it is used entirely in runtime code. 6222132718Skan@end defmac 622390075Sobrien 6224132718Skan@defmac FINI_SECTION_ASM_OP 622590075SobrienIf defined, a C expression whose value is a string, including spacing, 622690075Sobriencontaining the assembler operation to identify the following data as 622790075Sobrienfinalization code. If not defined, GCC will assume such a section does 6228169689Skannot exist. This section has no corresponding @code{fini_section} 6229169689Skanvariable; it is used entirely in runtime code. 6230132718Skan@end defmac 623190075Sobrien 6232169689Skan@defmac INIT_ARRAY_SECTION_ASM_OP 6233169689SkanIf defined, a C expression whose value is a string, including spacing, 6234169689Skancontaining the assembler operation to identify the following data as 6235169689Skanpart of the @code{.init_array} (or equivalent) section. If not 6236169689Skandefined, GCC will assume such a section does not exist. Do not define 6237169689Skanboth this macro and @code{INIT_SECTION_ASM_OP}. 6238169689Skan@end defmac 6239169689Skan 6240169689Skan@defmac FINI_ARRAY_SECTION_ASM_OP 6241169689SkanIf defined, a C expression whose value is a string, including spacing, 6242169689Skancontaining the assembler operation to identify the following data as 6243169689Skanpart of the @code{.fini_array} (or equivalent) section. If not 6244169689Skandefined, GCC will assume such a section does not exist. Do not define 6245169689Skanboth this macro and @code{FINI_SECTION_ASM_OP}. 6246169689Skan@end defmac 6247169689Skan 6248132718Skan@defmac CRT_CALL_STATIC_FUNCTION (@var{section_op}, @var{function}) 624990075SobrienIf defined, an ASM statement that switches to a different section 625090075Sobrienvia @var{section_op}, calls @var{function}, and switches back to 625190075Sobrienthe text section. This is used in @file{crtstuff.c} if 625290075Sobrien@code{INIT_SECTION_ASM_OP} or @code{FINI_SECTION_ASM_OP} to calls 625390075Sobriento initialization and finalization functions from the init and fini 625490075Sobriensections. By default, this macro uses a simple function call. Some 625590075Sobrienports need hand-crafted assembly code to avoid dependencies on 625690075Sobrienregisters initialized in the function prologue or to ensure that 625790075Sobrienconstant pools don't end up too far way in the text section. 6258132718Skan@end defmac 625990075Sobrien 6260169689Skan@defmac TARGET_LIBGCC_SDATA_SECTION 6261169689SkanIf defined, a string which names the section into which small 6262169689Skanvariables defined in crtstuff and libgcc should go. This is useful 6263169689Skanwhen the target has options for optimizing access to small data, and 6264169689Skanyou want the crtstuff and libgcc routines to be conservative in what 6265169689Skanthey expect of your application yet liberal in what your application 6266169689Skanexpects. For example, for targets with a @code{.sdata} section (like 6267169689SkanMIPS), you could compile crtstuff with @code{-G 0} so that it doesn't 6268169689Skanrequire small data support from your application, but use this macro 6269169689Skanto put small data into @code{.sdata} so that your application can 6270169689Skanaccess these variables whether it uses small data or not. 6271169689Skan@end defmac 6272169689Skan 6273132718Skan@defmac FORCE_CODE_SECTION_ALIGN 627490075SobrienIf defined, an ASM statement that aligns a code section to some 627590075Sobrienarbitrary boundary. This is used to force all fragments of the 627690075Sobrien@code{.init} and @code{.fini} sections to have to same alignment 627790075Sobrienand thus prevent the linker from having to add any padding. 6278132718Skan@end defmac 627990075Sobrien 6280132718Skan@defmac JUMP_TABLES_IN_TEXT_SECTION 628190075SobrienDefine this macro to be an expression with a nonzero value if jump 628290075Sobrientables (for @code{tablejump} insns) should be output in the text 628390075Sobriensection, along with the assembler instructions. Otherwise, the 628490075Sobrienreadonly data section is used. 628590075Sobrien 628690075SobrienThis macro is irrelevant if there is no separate readonly data section. 6287132718Skan@end defmac 628890075Sobrien 6289169689Skan@deftypefn {Target Hook} void TARGET_ASM_INIT_SECTIONS (void) 6290169689SkanDefine this hook if you need to do something special to set up the 6291169689Skan@file{varasm.c} sections, or if your target has some special sections 6292169689Skanof its own that you need to create. 6293169689Skan 6294169689SkanGCC calls this hook after processing the command line, but before writing 6295169689Skanany assembly code, and before calling any of the section-returning hooks 6296169689Skandescribed below. 6297169689Skan@end deftypefn 6298169689Skan 6299169689Skan@deftypefn {Target Hook} TARGET_ASM_RELOC_RW_MASK (void) 6300169689SkanReturn a mask describing how relocations should be treated when 6301169689Skanselecting sections. Bit 1 should be set if global relocations 6302169689Skanshould be placed in a read-write section; bit 0 should be set if 6303169689Skanlocal relocations should be placed in a read-write section. 6304169689Skan 6305169689SkanThe default version of this function returns 3 when @option{-fpic} 6306169689Skanis in effect, and 0 otherwise. The hook is typically redefined 6307169689Skanwhen the target cannot support (some kinds of) dynamic relocations 6308169689Skanin read-only sections even in executables. 6309169689Skan@end deftypefn 6310169689Skan 6311169689Skan@deftypefn {Target Hook} {section *} TARGET_ASM_SELECT_SECTION (tree @var{exp}, int @var{reloc}, unsigned HOST_WIDE_INT @var{align}) 6312169689SkanReturn the section into which @var{exp} should be placed. You can 6313117395Skanassume that @var{exp} is either a @code{VAR_DECL} node or a constant of 6314117395Skansome sort. @var{reloc} indicates whether the initial value of @var{exp} 6315117395Skanrequires link-time relocations. Bit 0 is set when variable contains 6316117395Skanlocal relocations only, while bit 1 is set for global relocations. 6317169689Skan@var{align} is the constant alignment in bits. 6318117395Skan 6319117395SkanThe default version of this function takes care of putting read-only 6320117395Skanvariables in @code{readonly_data_section}. 6321169689Skan 6322169689SkanSee also @var{USE_SELECT_SECTION_FOR_FUNCTIONS}. 6323117395Skan@end deftypefn 6324117395Skan 6325169689Skan@defmac USE_SELECT_SECTION_FOR_FUNCTIONS 6326169689SkanDefine this macro if you wish TARGET_ASM_SELECT_SECTION to be called 6327169689Skanfor @code{FUNCTION_DECL}s as well as for variables and constants. 6328169689Skan 6329169689SkanIn the case of a @code{FUNCTION_DECL}, @var{reloc} will be zero if the 6330169689Skanfunction has been determined to be likely to be called, and nonzero if 6331169689Skanit is unlikely to be called. 6332169689Skan@end defmac 6333169689Skan 6334117395Skan@deftypefn {Target Hook} void TARGET_ASM_UNIQUE_SECTION (tree @var{decl}, int @var{reloc}) 6335117395SkanBuild up a unique section name, expressed as a @code{STRING_CST} node, 6336117395Skanand assign it to @samp{DECL_SECTION_NAME (@var{decl})}. 6337117395SkanAs with @code{TARGET_ASM_SELECT_SECTION}, @var{reloc} indicates whether 6338117395Skanthe initial value of @var{exp} requires link-time relocations. 6339117395Skan 6340117395SkanThe default version of this function appends the symbol name to the 6341117395SkanELF section name that would normally be used for the symbol. For 6342117395Skanexample, the function @code{foo} would be placed in @code{.text.foo}. 6343117395SkanWhatever the actual target object format, this is often good enough. 6344117395Skan@end deftypefn 6345117395Skan 6346169689Skan@deftypefn {Target Hook} {section *} TARGET_ASM_FUNCTION_RODATA_SECTION (tree @var{decl}) 6347169689SkanReturn the readonly data section associated with 6348169689Skan@samp{DECL_SECTION_NAME (@var{decl})}. 6349169689SkanThe default version of this function selects @code{.gnu.linkonce.r.name} if 6350169689Skanthe function's section is @code{.gnu.linkonce.t.name}, @code{.rodata.name} 6351169689Skanif function is in @code{.text.name}, and the normal readonly-data section 6352169689Skanotherwise. 6353169689Skan@end deftypefn 6354169689Skan 6355169689Skan@deftypefn {Target Hook} {section *} TARGET_ASM_SELECT_RTX_SECTION (enum machine_mode @var{mode}, rtx @var{x}, unsigned HOST_WIDE_INT @var{align}) 6356169689SkanReturn the section into which a constant @var{x}, of mode @var{mode}, 6357169689Skanshould be placed. You can assume that @var{x} is some kind of 6358117395Skanconstant in RTL@. The argument @var{mode} is redundant except in the 6359169689Skancase of a @code{const_int} rtx. @var{align} is the constant alignment 6360169689Skanin bits. 6361117395Skan 6362117395SkanThe default version of this function takes care of putting symbolic 6363117395Skanconstants in @code{flag_pic} mode in @code{data_section} and everything 6364117395Skanelse in @code{readonly_data_section}. 6365117395Skan@end deftypefn 6366117395Skan 6367132718Skan@deftypefn {Target Hook} void TARGET_ENCODE_SECTION_INFO (tree @var{decl}, rtx @var{rtl}, int @var{new_decl_p}) 6368117395SkanDefine this hook if references to a symbol or a constant must be 636990075Sobrientreated differently depending on something about the variable or 637090075Sobrienfunction named by the symbol (such as what section it is in). 637190075Sobrien 6372132718SkanThe hook is executed immediately after rtl has been created for 6373132718Skan@var{decl}, which may be a variable or function declaration or 6374132718Skanan entry in the constant pool. In either case, @var{rtl} is the 6375132718Skanrtl in question. Do @emph{not} use @code{DECL_RTL (@var{decl})} 6376132718Skanin this hook; that field may not have been initialized yet. 637790075Sobrien 6378132718SkanIn the case of a constant, it is safe to assume that the rtl is 6379132718Skana @code{mem} whose address is a @code{symbol_ref}. Most decls 6380132718Skanwill also have this form, but that is not guaranteed. Global 6381132718Skanregister variables, for instance, will have a @code{reg} for their 6382132718Skanrtl. (Normally the right thing to do with such unusual rtl is 6383132718Skanleave it alone.) 6384132718Skan 6385117395SkanThe @var{new_decl_p} argument will be true if this is the first time 6386132718Skanthat @code{TARGET_ENCODE_SECTION_INFO} has been invoked on this decl. It will 6387117395Skanbe false for subsequent invocations, which will happen for duplicate 6388117395Skandeclarations. Whether or not anything must be done for the duplicate 6389117395Skandeclaration depends on whether the hook examines @code{DECL_ATTRIBUTES}. 6390132718Skan@var{new_decl_p} is always true when the hook is called for a constant. 6391117395Skan 6392117395Skan@cindex @code{SYMBOL_REF_FLAG}, in @code{TARGET_ENCODE_SECTION_INFO} 6393132718SkanThe usual thing for this hook to do is to record flags in the 6394132718Skan@code{symbol_ref}, using @code{SYMBOL_REF_FLAG} or @code{SYMBOL_REF_FLAGS}. 6395132718SkanHistorically, the name string was modified if it was necessary to 6396132718Skanencode more than one bit of information, but this practice is now 6397132718Skandiscouraged; use @code{SYMBOL_REF_FLAGS}. 6398132718Skan 6399132718SkanThe default definition of this hook, @code{default_encode_section_info} 6400132718Skanin @file{varasm.c}, sets a number of commonly-useful bits in 6401132718Skan@code{SYMBOL_REF_FLAGS}. Check whether the default does what you need 6402132718Skanbefore overriding it. 6403117395Skan@end deftypefn 640490075Sobrien 6405117395Skan@deftypefn {Target Hook} const char *TARGET_STRIP_NAME_ENCODING (const char *name) 6406117395SkanDecode @var{name} and return the real name part, sans 6407117395Skanthe characters that @code{TARGET_ENCODE_SECTION_INFO} 6408117395Skanmay have added. 6409117395Skan@end deftypefn 641090075Sobrien 6411117395Skan@deftypefn {Target Hook} bool TARGET_IN_SMALL_DATA_P (tree @var{exp}) 6412117395SkanReturns true if @var{exp} should be placed into a ``small data'' section. 6413117395SkanThe default version of this hook always returns false. 6414117395Skan@end deftypefn 641590075Sobrien 6416117395Skan@deftypevar {Target Hook} bool TARGET_HAVE_SRODATA_SECTION 6417117395SkanContains the value true if the target places read-only 6418117395Skan``small data'' into a separate section. The default value is false. 6419117395Skan@end deftypevar 6420117395Skan 6421117395Skan@deftypefn {Target Hook} bool TARGET_BINDS_LOCAL_P (tree @var{exp}) 6422117395SkanReturns true if @var{exp} names an object for which name resolution 6423117395Skanrules must resolve to the current ``module'' (dynamic shared library 6424117395Skanor executable image). 6425117395Skan 6426117395SkanThe default version of this hook implements the name resolution rules 6427117395Skanfor ELF, which has a looser model of global name binding than other 6428117395Skancurrently supported object file formats. 6429117395Skan@end deftypefn 6430117395Skan 6431117395Skan@deftypevar {Target Hook} bool TARGET_HAVE_TLS 6432117395SkanContains the value true if the target supports thread-local storage. 6433117395SkanThe default value is false. 6434117395Skan@end deftypevar 6435117395Skan 6436117395Skan 643790075Sobrien@node PIC 643890075Sobrien@section Position Independent Code 643990075Sobrien@cindex position independent code 644090075Sobrien@cindex PIC 644190075Sobrien 644290075SobrienThis section describes macros that help implement generation of position 644390075Sobrienindependent code. Simply defining these macros is not enough to 644490075Sobriengenerate valid PIC; you must also add support to the macros 644590075Sobrien@code{GO_IF_LEGITIMATE_ADDRESS} and @code{PRINT_OPERAND_ADDRESS}, as 644690075Sobrienwell as @code{LEGITIMIZE_ADDRESS}. You must modify the definition of 644790075Sobrien@samp{movsi} to do something appropriate when the source operand 644890075Sobriencontains a symbolic address. You may also need to alter the handling of 644990075Sobrienswitch statements so that they use relative addresses. 645090075Sobrien@c i rearranged the order of the macros above to try to force one of 645190075Sobrien@c them to the next line, to eliminate an overfull hbox. --mew 10feb93 645290075Sobrien 6453132718Skan@defmac PIC_OFFSET_TABLE_REGNUM 645490075SobrienThe register number of the register used to address a table of static 645590075Sobriendata addresses in memory. In some cases this register is defined by a 645690075Sobrienprocessor's ``application binary interface'' (ABI)@. When this macro 645790075Sobrienis defined, RTL is generated for this register once, as with the stack 645890075Sobrienpointer and frame pointer registers. If this macro is not defined, it 645990075Sobrienis up to the machine-dependent files to allocate such a register (if 646090075Sobriennecessary). Note that this register must be fixed when in use (e.g.@: 646190075Sobrienwhen @code{flag_pic} is true). 6462132718Skan@end defmac 646390075Sobrien 6464132718Skan@defmac PIC_OFFSET_TABLE_REG_CALL_CLOBBERED 646590075SobrienDefine this macro if the register defined by 646690075Sobrien@code{PIC_OFFSET_TABLE_REGNUM} is clobbered by calls. Do not define 646790075Sobrienthis macro if @code{PIC_OFFSET_TABLE_REGNUM} is not defined. 6468132718Skan@end defmac 646990075Sobrien 6470132718Skan@defmac LEGITIMATE_PIC_OPERAND_P (@var{x}) 647190075SobrienA C expression that is nonzero if @var{x} is a legitimate immediate 647290075Sobrienoperand on the target machine when generating position independent code. 647390075SobrienYou can assume that @var{x} satisfies @code{CONSTANT_P}, so you need not 647490075Sobriencheck this. You can also assume @var{flag_pic} is true, so you need not 647590075Sobriencheck it either. You need not define this macro if all constants 647690075Sobrien(including @code{SYMBOL_REF}) can be immediate operands when generating 647790075Sobrienposition independent code. 6478132718Skan@end defmac 647990075Sobrien 648090075Sobrien@node Assembler Format 648190075Sobrien@section Defining the Output Assembler Language 648290075Sobrien 648390075SobrienThis section describes macros whose principal purpose is to describe how 648490075Sobriento write instructions in assembler language---rather than what the 648590075Sobrieninstructions do. 648690075Sobrien 648790075Sobrien@menu 648890075Sobrien* File Framework:: Structural information for the assembler file. 648990075Sobrien* Data Output:: Output of constants (numbers, strings, addresses). 649090075Sobrien* Uninitialized Data:: Output of uninitialized variables. 649190075Sobrien* Label Output:: Output and generation of labels. 649290075Sobrien* Initialization:: General principles of initialization 649390075Sobrien and termination routines. 649490075Sobrien* Macros for Initialization:: 649590075Sobrien Specific macros that control the handling of 649690075Sobrien initialization and termination routines. 649790075Sobrien* Instruction Output:: Output of actual instructions. 649890075Sobrien* Dispatch Tables:: Output of jump tables. 649990075Sobrien* Exception Region Output:: Output of exception region code. 650090075Sobrien* Alignment Output:: Pseudo ops for alignment and skipping data. 650190075Sobrien@end menu 650290075Sobrien 650390075Sobrien@node File Framework 650490075Sobrien@subsection The Overall Framework of an Assembler File 650590075Sobrien@cindex assembler format 650690075Sobrien@cindex output of assembler code 650790075Sobrien 650890075Sobrien@c prevent bad page break with this line 6509132718SkanThis describes the overall framework of an assembly file. 651090075Sobrien 6511132718Skan@deftypefn {Target Hook} void TARGET_ASM_FILE_START () 6512132718Skan@findex default_file_start 6513132718SkanOutput to @code{asm_out_file} any text which the assembler expects to 6514132718Skanfind at the beginning of a file. The default behavior is controlled 6515132718Skanby two flags, documented below. Unless your target's assembler is 6516132718Skanquite unusual, if you override the default, you should call 6517132718Skan@code{default_file_start} at some point in your target hook. This 6518132718Skanlets other target files rely on these variables. 6519132718Skan@end deftypefn 652090075Sobrien 6521132718Skan@deftypevr {Target Hook} bool TARGET_ASM_FILE_START_APP_OFF 6522132718SkanIf this flag is true, the text of the macro @code{ASM_APP_OFF} will be 6523132718Skanprinted as the very first line in the assembly file, unless 6524132718Skan@option{-fverbose-asm} is in effect. (If that macro has been defined 6525132718Skanto the empty string, this variable has no effect.) With the normal 6526132718Skandefinition of @code{ASM_APP_OFF}, the effect is to notify the GNU 6527132718Skanassembler that it need not bother stripping comments or extra 6528132718Skanwhitespace from its input. This allows it to work a bit faster. 652990075Sobrien 6530132718SkanThe default is false. You should not set it to true unless you have 6531132718Skanverified that your port does not generate any extra whitespace or 6532132718Skancomments that will cause GAS to issue errors in NO_APP mode. 6533132718Skan@end deftypevr 653490075Sobrien 6535132718Skan@deftypevr {Target Hook} bool TARGET_ASM_FILE_START_FILE_DIRECTIVE 6536132718SkanIf this flag is true, @code{output_file_directive} will be called 6537132718Skanfor the primary source file, immediately after printing 6538132718Skan@code{ASM_APP_OFF} (if that is enabled). Most ELF assemblers expect 6539132718Skanthis to be done. The default is false. 6540132718Skan@end deftypevr 654190075Sobrien 6542132718Skan@deftypefn {Target Hook} void TARGET_ASM_FILE_END () 6543132718SkanOutput to @code{asm_out_file} any text which the assembler expects 6544132718Skanto find at the end of a file. The default is to output nothing. 6545132718Skan@end deftypefn 654690075Sobrien 6547132718Skan@deftypefun void file_end_indicate_exec_stack () 6548132718SkanSome systems use a common convention, the @samp{.note.GNU-stack} 6549132718Skanspecial section, to indicate whether or not an object file relies on 6550132718Skanthe stack being executable. If your system uses this convention, you 6551132718Skanshould define @code{TARGET_ASM_FILE_END} to this function. If you 6552132718Skanneed to do other things in that hook, have your hook function call 6553132718Skanthis function. 6554132718Skan@end deftypefun 655590075Sobrien 6556132718Skan@defmac ASM_COMMENT_START 655790075SobrienA C string constant describing how to begin a comment in the target 655890075Sobrienassembler language. The compiler assumes that the comment will end at 655990075Sobrienthe end of the line. 6560132718Skan@end defmac 656190075Sobrien 6562132718Skan@defmac ASM_APP_ON 656390075SobrienA C string constant for text to be output before each @code{asm} 656490075Sobrienstatement or group of consecutive ones. Normally this is 656590075Sobrien@code{"#APP"}, which is a comment that has no effect on most 656690075Sobrienassemblers but tells the GNU assembler that it must check the lines 656790075Sobrienthat follow for all valid assembler constructs. 6568132718Skan@end defmac 656990075Sobrien 6570132718Skan@defmac ASM_APP_OFF 657190075SobrienA C string constant for text to be output after each @code{asm} 657290075Sobrienstatement or group of consecutive ones. Normally this is 657390075Sobrien@code{"#NO_APP"}, which tells the GNU assembler to resume making the 657490075Sobrientime-saving assumptions that are valid for ordinary compiler output. 6575132718Skan@end defmac 657690075Sobrien 6577132718Skan@defmac ASM_OUTPUT_SOURCE_FILENAME (@var{stream}, @var{name}) 657890075SobrienA C statement to output COFF information or DWARF debugging information 657990075Sobrienwhich indicates that filename @var{name} is the current source file to 658090075Sobrienthe stdio stream @var{stream}. 658190075Sobrien 658290075SobrienThis macro need not be defined if the standard form of output 658390075Sobrienfor the file format in use is appropriate. 6584132718Skan@end defmac 658590075Sobrien 6586132718Skan@defmac OUTPUT_QUOTED_STRING (@var{stream}, @var{string}) 658790075SobrienA C statement to output the string @var{string} to the stdio stream 658890075Sobrien@var{stream}. If you do not call the function @code{output_quoted_string} 658990075Sobrienin your config files, GCC will only call it to output filenames to 659090075Sobrienthe assembler source. So you can use it to canonicalize the format 659190075Sobrienof the filename using this macro. 6592132718Skan@end defmac 659390075Sobrien 6594132718Skan@defmac ASM_OUTPUT_IDENT (@var{stream}, @var{string}) 659590075SobrienA C statement to output something to the assembler file to handle a 659690075Sobrien@samp{#ident} directive containing the text @var{string}. If this 659790075Sobrienmacro is not defined, nothing is output for a @samp{#ident} directive. 6598132718Skan@end defmac 659990075Sobrien 660090075Sobrien@deftypefn {Target Hook} void TARGET_ASM_NAMED_SECTION (const char *@var{name}, unsigned int @var{flags}, unsigned int @var{align}) 660190075SobrienOutput assembly directives to switch to section @var{name}. The section 660290075Sobrienshould have attributes as specified by @var{flags}, which is a bit mask 660390075Sobrienof the @code{SECTION_*} flags defined in @file{output.h}. If @var{align} 660490075Sobrienis nonzero, it contains an alignment in bytes to be used for the section, 660596263Sobrienotherwise some target default should be used. Only targets that must 660690075Sobrienspecify an alignment within the section directive need pay attention to 660790075Sobrien@var{align} -- we will still use @code{ASM_OUTPUT_ALIGN}. 660890075Sobrien@end deftypefn 660990075Sobrien 661090075Sobrien@deftypefn {Target Hook} bool TARGET_HAVE_NAMED_SECTIONS 661190075SobrienThis flag is true if the target supports @code{TARGET_ASM_NAMED_SECTION}. 661290075Sobrien@end deftypefn 661390075Sobrien 6614169689Skan@anchor{TARGET_HAVE_SWITCHABLE_BSS_SECTIONS} 6615169689Skan@deftypefn {Target Hook} bool TARGET_HAVE_SWITCHABLE_BSS_SECTIONS 6616169689SkanThis flag is true if we can create zeroed data by switching to a BSS 6617169689Skansection and then using @code{ASM_OUTPUT_SKIP} to allocate the space. 6618169689SkanThis is true on most ELF targets. 6619169689Skan@end deftypefn 6620169689Skan 662190075Sobrien@deftypefn {Target Hook} {unsigned int} TARGET_SECTION_TYPE_FLAGS (tree @var{decl}, const char *@var{name}, int @var{reloc}) 662290075SobrienChoose a set of section attributes for use by @code{TARGET_ASM_NAMED_SECTION} 662390075Sobrienbased on a variable or function decl, a section name, and whether or not the 662490075Sobriendeclaration's initializer may contain runtime relocations. @var{decl} may be 662590075Sobrien null, in which case read-write data should be assumed. 662690075Sobrien 6627169689SkanThe default version of this function handles choosing code vs data, 662890075Sobrienread-only vs read-write data, and @code{flag_pic}. You should only 662990075Sobrienneed to override this if your target has special flags that might be 663090075Sobrienset via @code{__attribute__}. 663190075Sobrien@end deftypefn 663290075Sobrien 663390075Sobrien@need 2000 663490075Sobrien@node Data Output 663590075Sobrien@subsection Output of Data 663690075Sobrien 663790075Sobrien 663890075Sobrien@deftypevr {Target Hook} {const char *} TARGET_ASM_BYTE_OP 663990075Sobrien@deftypevrx {Target Hook} {const char *} TARGET_ASM_ALIGNED_HI_OP 664090075Sobrien@deftypevrx {Target Hook} {const char *} TARGET_ASM_ALIGNED_SI_OP 664190075Sobrien@deftypevrx {Target Hook} {const char *} TARGET_ASM_ALIGNED_DI_OP 664290075Sobrien@deftypevrx {Target Hook} {const char *} TARGET_ASM_ALIGNED_TI_OP 664390075Sobrien@deftypevrx {Target Hook} {const char *} TARGET_ASM_UNALIGNED_HI_OP 664490075Sobrien@deftypevrx {Target Hook} {const char *} TARGET_ASM_UNALIGNED_SI_OP 664590075Sobrien@deftypevrx {Target Hook} {const char *} TARGET_ASM_UNALIGNED_DI_OP 664690075Sobrien@deftypevrx {Target Hook} {const char *} TARGET_ASM_UNALIGNED_TI_OP 664790075SobrienThese hooks specify assembly directives for creating certain kinds 664890075Sobrienof integer object. The @code{TARGET_ASM_BYTE_OP} directive creates a 664990075Sobrienbyte-sized object, the @code{TARGET_ASM_ALIGNED_HI_OP} one creates an 665090075Sobrienaligned two-byte object, and so on. Any of the hooks may be 665190075Sobrien@code{NULL}, indicating that no suitable directive is available. 665290075Sobrien 665390075SobrienThe compiler will print these strings at the start of a new line, 665490075Sobrienfollowed immediately by the object's initial value. In most cases, 665590075Sobrienthe string should contain a tab, a pseudo-op, and then another tab. 665690075Sobrien@end deftypevr 665790075Sobrien 665890075Sobrien@deftypefn {Target Hook} bool TARGET_ASM_INTEGER (rtx @var{x}, unsigned int @var{size}, int @var{aligned_p}) 665990075SobrienThe @code{assemble_integer} function uses this hook to output an 666090075Sobrieninteger object. @var{x} is the object's value, @var{size} is its size 666190075Sobrienin bytes and @var{aligned_p} indicates whether it is aligned. The 666290075Sobrienfunction should return @code{true} if it was able to output the 666390075Sobrienobject. If it returns false, @code{assemble_integer} will try to 666490075Sobriensplit the object into smaller parts. 666590075Sobrien 666690075SobrienThe default implementation of this hook will use the 666790075Sobrien@code{TARGET_ASM_BYTE_OP} family of strings, returning @code{false} 666890075Sobrienwhen the relevant string is @code{NULL}. 666990075Sobrien@end deftypefn 667090075Sobrien 6671132718Skan@defmac OUTPUT_ADDR_CONST_EXTRA (@var{stream}, @var{x}, @var{fail}) 667290075SobrienA C statement to recognize @var{rtx} patterns that 667390075Sobrien@code{output_addr_const} can't deal with, and output assembly code to 667490075Sobrien@var{stream} corresponding to the pattern @var{x}. This may be used to 667590075Sobrienallow machine-dependent @code{UNSPEC}s to appear within constants. 667690075Sobrien 667790075SobrienIf @code{OUTPUT_ADDR_CONST_EXTRA} fails to recognize a pattern, it must 667890075Sobrien@code{goto fail}, so that a standard error message is printed. If it 667990075Sobrienprints an error message itself, by calling, for example, 668090075Sobrien@code{output_operand_lossage}, it may just complete normally. 6681132718Skan@end defmac 668290075Sobrien 6683132718Skan@defmac ASM_OUTPUT_ASCII (@var{stream}, @var{ptr}, @var{len}) 668490075SobrienA C statement to output to the stdio stream @var{stream} an assembler 668590075Sobrieninstruction to assemble a string constant containing the @var{len} 668690075Sobrienbytes at @var{ptr}. @var{ptr} will be a C expression of type 668790075Sobrien@code{char *} and @var{len} a C expression of type @code{int}. 668890075Sobrien 668990075SobrienIf the assembler has a @code{.ascii} pseudo-op as found in the 669090075SobrienBerkeley Unix assembler, do not define the macro 669190075Sobrien@code{ASM_OUTPUT_ASCII}. 6692132718Skan@end defmac 669390075Sobrien 6694132718Skan@defmac ASM_OUTPUT_FDESC (@var{stream}, @var{decl}, @var{n}) 669590075SobrienA C statement to output word @var{n} of a function descriptor for 669690075Sobrien@var{decl}. This must be defined if @code{TARGET_VTABLE_USES_DESCRIPTORS} 669790075Sobrienis defined, and is otherwise unused. 6698132718Skan@end defmac 669990075Sobrien 6700132718Skan@defmac CONSTANT_POOL_BEFORE_FUNCTION 670190075SobrienYou may define this macro as a C expression. You should define the 670290075Sobrienexpression to have a nonzero value if GCC should output the constant 670390075Sobrienpool for a function before the code for the function, or a zero value if 670490075SobrienGCC should output the constant pool after the function. If you do 670590075Sobriennot define this macro, the usual case, GCC will output the constant 670690075Sobrienpool before the function. 6707132718Skan@end defmac 670890075Sobrien 6709132718Skan@defmac ASM_OUTPUT_POOL_PROLOGUE (@var{file}, @var{funname}, @var{fundecl}, @var{size}) 671090075SobrienA C statement to output assembler commands to define the start of the 671190075Sobrienconstant pool for a function. @var{funname} is a string giving 671290075Sobrienthe name of the function. Should the return type of the function 671390075Sobrienbe required, it can be obtained via @var{fundecl}. @var{size} 671490075Sobrienis the size, in bytes, of the constant pool that will be written 671590075Sobrienimmediately after this call. 671690075Sobrien 671790075SobrienIf no constant-pool prefix is required, the usual case, this macro need 671890075Sobriennot be defined. 6719132718Skan@end defmac 672090075Sobrien 6721132718Skan@defmac ASM_OUTPUT_SPECIAL_POOL_ENTRY (@var{file}, @var{x}, @var{mode}, @var{align}, @var{labelno}, @var{jumpto}) 672290075SobrienA C statement (with or without semicolon) to output a constant in the 672390075Sobrienconstant pool, if it needs special treatment. (This macro need not do 672490075Sobrienanything for RTL expressions that can be output normally.) 672590075Sobrien 672690075SobrienThe argument @var{file} is the standard I/O stream to output the 672790075Sobrienassembler code on. @var{x} is the RTL expression for the constant to 672890075Sobrienoutput, and @var{mode} is the machine mode (in case @var{x} is a 672990075Sobrien@samp{const_int}). @var{align} is the required alignment for the value 673090075Sobrien@var{x}; you should output an assembler directive to force this much 673190075Sobrienalignment. 673290075Sobrien 673390075SobrienThe argument @var{labelno} is a number to use in an internal label for 673490075Sobrienthe address of this pool entry. The definition of this macro is 673590075Sobrienresponsible for outputting the label definition at the proper place. 673690075SobrienHere is how to do this: 673790075Sobrien 6738132718Skan@smallexample 6739132718Skan@code{(*targetm.asm_out.internal_label)} (@var{file}, "LC", @var{labelno}); 6740132718Skan@end smallexample 674190075Sobrien 674290075SobrienWhen you output a pool entry specially, you should end with a 674390075Sobrien@code{goto} to the label @var{jumpto}. This will prevent the same pool 674490075Sobrienentry from being output a second time in the usual manner. 674590075Sobrien 674690075SobrienYou need not define this macro if it would do nothing. 6747132718Skan@end defmac 674890075Sobrien 6749132718Skan@defmac ASM_OUTPUT_POOL_EPILOGUE (@var{file} @var{funname} @var{fundecl} @var{size}) 675090075SobrienA C statement to output assembler commands to at the end of the constant 675190075Sobrienpool for a function. @var{funname} is a string giving the name of the 675290075Sobrienfunction. Should the return type of the function be required, you can 675390075Sobrienobtain it via @var{fundecl}. @var{size} is the size, in bytes, of the 675490075Sobrienconstant pool that GCC wrote immediately before this call. 675590075Sobrien 675690075SobrienIf no constant-pool epilogue is required, the usual case, you need not 675790075Sobriendefine this macro. 6758132718Skan@end defmac 675990075Sobrien 6760132718Skan@defmac IS_ASM_LOGICAL_LINE_SEPARATOR (@var{C}) 676190075SobrienDefine this macro as a C expression which is nonzero if @var{C} is 676290075Sobrienused as a logical line separator by the assembler. 676390075Sobrien 676490075SobrienIf you do not define this macro, the default is that only 676590075Sobrienthe character @samp{;} is treated as a logical line separator. 6766132718Skan@end defmac 676790075Sobrien 676890075Sobrien@deftypevr {Target Hook} {const char *} TARGET_ASM_OPEN_PAREN 676990075Sobrien@deftypevrx {Target Hook} {const char *} TARGET_ASM_CLOSE_PAREN 677090075SobrienThese target hooks are C string constants, describing the syntax in the 677190075Sobrienassembler for grouping arithmetic expressions. If not overridden, they 677290075Sobriendefault to normal parentheses, which is correct for most assemblers. 677390075Sobrien@end deftypevr 677490075Sobrien 677590075Sobrien These macros are provided by @file{real.h} for writing the definitions 677690075Sobrienof @code{ASM_OUTPUT_DOUBLE} and the like: 677790075Sobrien 6778132718Skan@defmac REAL_VALUE_TO_TARGET_SINGLE (@var{x}, @var{l}) 6779132718Skan@defmacx REAL_VALUE_TO_TARGET_DOUBLE (@var{x}, @var{l}) 6780132718Skan@defmacx REAL_VALUE_TO_TARGET_LONG_DOUBLE (@var{x}, @var{l}) 6781169689Skan@defmacx REAL_VALUE_TO_TARGET_DECIMAL32 (@var{x}, @var{l}) 6782169689Skan@defmacx REAL_VALUE_TO_TARGET_DECIMAL64 (@var{x}, @var{l}) 6783169689Skan@defmacx REAL_VALUE_TO_TARGET_DECIMAL128 (@var{x}, @var{l}) 6784169689SkanThese translate @var{x}, of type @code{REAL_VALUE_TYPE}, to the 6785169689Skantarget's floating point representation, and store its bit pattern in 6786169689Skanthe variable @var{l}. For @code{REAL_VALUE_TO_TARGET_SINGLE} and 6787169689Skan@code{REAL_VALUE_TO_TARGET_DECIMAL32}, this variable should be a 6788169689Skansimple @code{long int}. For the others, it should be an array of 6789169689Skan@code{long int}. The number of elements in this array is determined 6790169689Skanby the size of the desired target floating point data type: 32 bits of 6791169689Skanit go in each @code{long int} array element. Each array element holds 6792169689Skan32 bits of the result, even if @code{long int} is wider than 32 bits 6793169689Skanon the host machine. 679490075Sobrien 679590075SobrienThe array element values are designed so that you can print them out 679690075Sobrienusing @code{fprintf} in the order they should appear in the target 679790075Sobrienmachine's memory. 6798132718Skan@end defmac 679990075Sobrien 680090075Sobrien@node Uninitialized Data 680190075Sobrien@subsection Output of Uninitialized Variables 680290075Sobrien 680390075SobrienEach of the macros in this section is used to do the whole job of 680490075Sobrienoutputting a single uninitialized variable. 680590075Sobrien 6806132718Skan@defmac ASM_OUTPUT_COMMON (@var{stream}, @var{name}, @var{size}, @var{rounded}) 680790075SobrienA C statement (sans semicolon) to output to the stdio stream 680890075Sobrien@var{stream} the assembler definition of a common-label named 680990075Sobrien@var{name} whose size is @var{size} bytes. The variable @var{rounded} 681090075Sobrienis the size rounded up to whatever alignment the caller wants. 681190075Sobrien 681290075SobrienUse the expression @code{assemble_name (@var{stream}, @var{name})} to 681390075Sobrienoutput the name itself; before and after that, output the additional 681490075Sobrienassembler syntax for defining the name, and a newline. 681590075Sobrien 681690075SobrienThis macro controls how the assembler definitions of uninitialized 681790075Sobriencommon global variables are output. 6818132718Skan@end defmac 681990075Sobrien 6820132718Skan@defmac ASM_OUTPUT_ALIGNED_COMMON (@var{stream}, @var{name}, @var{size}, @var{alignment}) 682190075SobrienLike @code{ASM_OUTPUT_COMMON} except takes the required alignment as a 682290075Sobrienseparate, explicit argument. If you define this macro, it is used in 682390075Sobrienplace of @code{ASM_OUTPUT_COMMON}, and gives you more flexibility in 682490075Sobrienhandling the required alignment of the variable. The alignment is specified 682590075Sobrienas the number of bits. 6826132718Skan@end defmac 682790075Sobrien 6828132718Skan@defmac ASM_OUTPUT_ALIGNED_DECL_COMMON (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{alignment}) 682990075SobrienLike @code{ASM_OUTPUT_ALIGNED_COMMON} except that @var{decl} of the 683090075Sobrienvariable to be output, if there is one, or @code{NULL_TREE} if there 683190075Sobrienis no corresponding variable. If you define this macro, GCC will use it 683290075Sobrienin place of both @code{ASM_OUTPUT_COMMON} and 683390075Sobrien@code{ASM_OUTPUT_ALIGNED_COMMON}. Define this macro when you need to see 683490075Sobrienthe variable's decl in order to chose what to output. 6835132718Skan@end defmac 683690075Sobrien 6837132718Skan@defmac ASM_OUTPUT_BSS (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{rounded}) 683890075SobrienA C statement (sans semicolon) to output to the stdio stream 683990075Sobrien@var{stream} the assembler definition of uninitialized global @var{decl} named 684090075Sobrien@var{name} whose size is @var{size} bytes. The variable @var{rounded} 684190075Sobrienis the size rounded up to whatever alignment the caller wants. 684290075Sobrien 684390075SobrienTry to use function @code{asm_output_bss} defined in @file{varasm.c} when 684490075Sobriendefining this macro. If unable, use the expression 684590075Sobrien@code{assemble_name (@var{stream}, @var{name})} to output the name itself; 684690075Sobrienbefore and after that, output the additional assembler syntax for defining 684790075Sobrienthe name, and a newline. 684890075Sobrien 6849169689SkanThere are two ways of handling global BSS. One is to define either 6850169689Skanthis macro or its aligned counterpart, @code{ASM_OUTPUT_ALIGNED_BSS}. 6851169689SkanThe other is to have @code{TARGET_ASM_SELECT_SECTION} return a 6852169689Skanswitchable BSS section (@pxref{TARGET_HAVE_SWITCHABLE_BSS_SECTIONS}). 6853169689SkanYou do not need to do both. 6854169689Skan 6855169689SkanSome languages do not have @code{common} data, and require a 6856169689Skannon-common form of global BSS in order to handle uninitialized globals 6857169689Skanefficiently. C++ is one example of this. However, if the target does 6858169689Skannot support global BSS, the front end may choose to make globals 6859169689Skancommon in order to save space in the object file. 6860132718Skan@end defmac 686190075Sobrien 6862132718Skan@defmac ASM_OUTPUT_ALIGNED_BSS (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{alignment}) 686390075SobrienLike @code{ASM_OUTPUT_BSS} except takes the required alignment as a 686490075Sobrienseparate, explicit argument. If you define this macro, it is used in 686590075Sobrienplace of @code{ASM_OUTPUT_BSS}, and gives you more flexibility in 686690075Sobrienhandling the required alignment of the variable. The alignment is specified 686790075Sobrienas the number of bits. 686890075Sobrien 686990075SobrienTry to use function @code{asm_output_aligned_bss} defined in file 687090075Sobrien@file{varasm.c} when defining this macro. 6871132718Skan@end defmac 687290075Sobrien 6873132718Skan@defmac ASM_OUTPUT_LOCAL (@var{stream}, @var{name}, @var{size}, @var{rounded}) 687490075SobrienA C statement (sans semicolon) to output to the stdio stream 687590075Sobrien@var{stream} the assembler definition of a local-common-label named 687690075Sobrien@var{name} whose size is @var{size} bytes. The variable @var{rounded} 687790075Sobrienis the size rounded up to whatever alignment the caller wants. 687890075Sobrien 687990075SobrienUse the expression @code{assemble_name (@var{stream}, @var{name})} to 688090075Sobrienoutput the name itself; before and after that, output the additional 688190075Sobrienassembler syntax for defining the name, and a newline. 688290075Sobrien 688390075SobrienThis macro controls how the assembler definitions of uninitialized 688490075Sobrienstatic variables are output. 6885132718Skan@end defmac 688690075Sobrien 6887132718Skan@defmac ASM_OUTPUT_ALIGNED_LOCAL (@var{stream}, @var{name}, @var{size}, @var{alignment}) 688890075SobrienLike @code{ASM_OUTPUT_LOCAL} except takes the required alignment as a 688990075Sobrienseparate, explicit argument. If you define this macro, it is used in 689090075Sobrienplace of @code{ASM_OUTPUT_LOCAL}, and gives you more flexibility in 689190075Sobrienhandling the required alignment of the variable. The alignment is specified 689290075Sobrienas the number of bits. 6893132718Skan@end defmac 689490075Sobrien 6895132718Skan@defmac ASM_OUTPUT_ALIGNED_DECL_LOCAL (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{alignment}) 689690075SobrienLike @code{ASM_OUTPUT_ALIGNED_DECL} except that @var{decl} of the 689790075Sobrienvariable to be output, if there is one, or @code{NULL_TREE} if there 689890075Sobrienis no corresponding variable. If you define this macro, GCC will use it 689990075Sobrienin place of both @code{ASM_OUTPUT_DECL} and 690090075Sobrien@code{ASM_OUTPUT_ALIGNED_DECL}. Define this macro when you need to see 690190075Sobrienthe variable's decl in order to chose what to output. 6902132718Skan@end defmac 690390075Sobrien 690490075Sobrien@node Label Output 690590075Sobrien@subsection Output and Generation of Labels 690690075Sobrien 690790075Sobrien@c prevent bad page break with this line 690890075SobrienThis is about outputting labels. 690990075Sobrien 691090075Sobrien@findex assemble_name 6911132718Skan@defmac ASM_OUTPUT_LABEL (@var{stream}, @var{name}) 691290075SobrienA C statement (sans semicolon) to output to the stdio stream 691390075Sobrien@var{stream} the assembler definition of a label named @var{name}. 691490075SobrienUse the expression @code{assemble_name (@var{stream}, @var{name})} to 691590075Sobrienoutput the name itself; before and after that, output the additional 6916117395Skanassembler syntax for defining the name, and a newline. A default 6917117395Skandefinition of this macro is provided which is correct for most systems. 6918132718Skan@end defmac 691990075Sobrien 6920169689Skan@findex assemble_name_raw 6921169689Skan@defmac ASM_OUTPUT_INTERNAL_LABEL (@var{stream}, @var{name}) 6922169689SkanIdentical to @code{ASM_OUTPUT_LABEL}, except that @var{name} is known 6923169689Skanto refer to a compiler-generated label. The default definition uses 6924169689Skan@code{assemble_name_raw}, which is like @code{assemble_name} except 6925169689Skanthat it is more efficient. 6926169689Skan@end defmac 6927169689Skan 6928132718Skan@defmac SIZE_ASM_OP 6929117395SkanA C string containing the appropriate assembler directive to specify the 6930117395Skansize of a symbol, without any arguments. On systems that use ELF, the 6931117395Skandefault (in @file{config/elfos.h}) is @samp{"\t.size\t"}; on other 6932117395Skansystems, the default is not to define this macro. 6933117395Skan 6934117395SkanDefine this macro only if it is correct to use the default definitions 6935117395Skanof @code{ASM_OUTPUT_SIZE_DIRECTIVE} and @code{ASM_OUTPUT_MEASURED_SIZE} 6936117395Skanfor your system. If you need your own custom definitions of those 6937117395Skanmacros, or if you do not need explicit symbol sizes at all, do not 6938117395Skandefine this macro. 6939132718Skan@end defmac 6940117395Skan 6941132718Skan@defmac ASM_OUTPUT_SIZE_DIRECTIVE (@var{stream}, @var{name}, @var{size}) 6942117395SkanA C statement (sans semicolon) to output to the stdio stream 6943117395Skan@var{stream} a directive telling the assembler that the size of the 6944117395Skansymbol @var{name} is @var{size}. @var{size} is a @code{HOST_WIDE_INT}. 6945117395SkanIf you define @code{SIZE_ASM_OP}, a default definition of this macro is 6946117395Skanprovided. 6947132718Skan@end defmac 6948117395Skan 6949132718Skan@defmac ASM_OUTPUT_MEASURED_SIZE (@var{stream}, @var{name}) 6950117395SkanA C statement (sans semicolon) to output to the stdio stream 6951117395Skan@var{stream} a directive telling the assembler to calculate the size of 6952117395Skanthe symbol @var{name} by subtracting its address from the current 6953132718Skanaddress. 6954117395Skan 6955117395SkanIf you define @code{SIZE_ASM_OP}, a default definition of this macro is 6956117395Skanprovided. The default assumes that the assembler recognizes a special 6957117395Skan@samp{.} symbol as referring to the current address, and can calculate 6958117395Skanthe difference between this and another symbol. If your assembler does 6959117395Skannot recognize @samp{.} or cannot do calculations with it, you will need 6960117395Skanto redefine @code{ASM_OUTPUT_MEASURED_SIZE} to use some other technique. 6961132718Skan@end defmac 6962117395Skan 6963132718Skan@defmac TYPE_ASM_OP 6964117395SkanA C string containing the appropriate assembler directive to specify the 6965117395Skantype of a symbol, without any arguments. On systems that use ELF, the 6966117395Skandefault (in @file{config/elfos.h}) is @samp{"\t.type\t"}; on other 6967117395Skansystems, the default is not to define this macro. 6968117395Skan 6969117395SkanDefine this macro only if it is correct to use the default definition of 6970117395Skan@code{ASM_OUTPUT_TYPE_DIRECTIVE} for your system. If you need your own 6971117395Skancustom definition of this macro, or if you do not need explicit symbol 6972117395Skantypes at all, do not define this macro. 6973132718Skan@end defmac 6974117395Skan 6975132718Skan@defmac TYPE_OPERAND_FMT 6976117395SkanA C string which specifies (using @code{printf} syntax) the format of 6977117395Skanthe second operand to @code{TYPE_ASM_OP}. On systems that use ELF, the 6978117395Skandefault (in @file{config/elfos.h}) is @samp{"@@%s"}; on other systems, 6979117395Skanthe default is not to define this macro. 6980117395Skan 6981117395SkanDefine this macro only if it is correct to use the default definition of 6982117395Skan@code{ASM_OUTPUT_TYPE_DIRECTIVE} for your system. If you need your own 6983117395Skancustom definition of this macro, or if you do not need explicit symbol 6984117395Skantypes at all, do not define this macro. 6985132718Skan@end defmac 6986117395Skan 6987132718Skan@defmac ASM_OUTPUT_TYPE_DIRECTIVE (@var{stream}, @var{type}) 6988117395SkanA C statement (sans semicolon) to output to the stdio stream 6989117395Skan@var{stream} a directive telling the assembler that the type of the 6990117395Skansymbol @var{name} is @var{type}. @var{type} is a C string; currently, 6991117395Skanthat string is always either @samp{"function"} or @samp{"object"}, but 6992117395Skanyou should not count on this. 6993117395Skan 6994117395SkanIf you define @code{TYPE_ASM_OP} and @code{TYPE_OPERAND_FMT}, a default 6995117395Skandefinition of this macro is provided. 6996132718Skan@end defmac 6997117395Skan 6998132718Skan@defmac ASM_DECLARE_FUNCTION_NAME (@var{stream}, @var{name}, @var{decl}) 699990075SobrienA C statement (sans semicolon) to output to the stdio stream 700090075Sobrien@var{stream} any text necessary for declaring the name @var{name} of a 700190075Sobrienfunction which is being defined. This macro is responsible for 700290075Sobrienoutputting the label definition (perhaps using 700390075Sobrien@code{ASM_OUTPUT_LABEL}). The argument @var{decl} is the 700490075Sobrien@code{FUNCTION_DECL} tree node representing the function. 700590075Sobrien 700690075SobrienIf this macro is not defined, then the function name is defined in the 700790075Sobrienusual manner as a label (by means of @code{ASM_OUTPUT_LABEL}). 700890075Sobrien 7009117395SkanYou may wish to use @code{ASM_OUTPUT_TYPE_DIRECTIVE} in the definition 7010117395Skanof this macro. 7011132718Skan@end defmac 7012117395Skan 7013132718Skan@defmac ASM_DECLARE_FUNCTION_SIZE (@var{stream}, @var{name}, @var{decl}) 701490075SobrienA C statement (sans semicolon) to output to the stdio stream 701590075Sobrien@var{stream} any text necessary for declaring the size of a function 701690075Sobrienwhich is being defined. The argument @var{name} is the name of the 701790075Sobrienfunction. The argument @var{decl} is the @code{FUNCTION_DECL} tree node 701890075Sobrienrepresenting the function. 701990075Sobrien 702090075SobrienIf this macro is not defined, then the function size is not defined. 702190075Sobrien 7022117395SkanYou may wish to use @code{ASM_OUTPUT_MEASURED_SIZE} in the definition 7023117395Skanof this macro. 7024132718Skan@end defmac 7025117395Skan 7026132718Skan@defmac ASM_DECLARE_OBJECT_NAME (@var{stream}, @var{name}, @var{decl}) 702790075SobrienA C statement (sans semicolon) to output to the stdio stream 702890075Sobrien@var{stream} any text necessary for declaring the name @var{name} of an 702990075Sobrieninitialized variable which is being defined. This macro must output the 703090075Sobrienlabel definition (perhaps using @code{ASM_OUTPUT_LABEL}). The argument 703190075Sobrien@var{decl} is the @code{VAR_DECL} tree node representing the variable. 703290075Sobrien 703390075SobrienIf this macro is not defined, then the variable name is defined in the 703490075Sobrienusual manner as a label (by means of @code{ASM_OUTPUT_LABEL}). 703590075Sobrien 7036117395SkanYou may wish to use @code{ASM_OUTPUT_TYPE_DIRECTIVE} and/or 7037117395Skan@code{ASM_OUTPUT_SIZE_DIRECTIVE} in the definition of this macro. 7038132718Skan@end defmac 7039117395Skan 7040132718Skan@defmac ASM_DECLARE_CONSTANT_NAME (@var{stream}, @var{name}, @var{exp}, @var{size}) 7041122180SkanA C statement (sans semicolon) to output to the stdio stream 7042122180Skan@var{stream} any text necessary for declaring the name @var{name} of a 7043122180Skanconstant which is being defined. This macro is responsible for 7044122180Skanoutputting the label definition (perhaps using 7045122180Skan@code{ASM_OUTPUT_LABEL}). The argument @var{exp} is the 7046122180Skanvalue of the constant, and @var{size} is the size of the constant 7047122180Skanin bytes. @var{name} will be an internal label. 7048122180Skan 7049122180SkanIf this macro is not defined, then the @var{name} is defined in the 7050122180Skanusual manner as a label (by means of @code{ASM_OUTPUT_LABEL}). 7051122180Skan 7052122180SkanYou may wish to use @code{ASM_OUTPUT_TYPE_DIRECTIVE} in the definition 7053122180Skanof this macro. 7054132718Skan@end defmac 7055122180Skan 7056132718Skan@defmac ASM_DECLARE_REGISTER_GLOBAL (@var{stream}, @var{decl}, @var{regno}, @var{name}) 705790075SobrienA C statement (sans semicolon) to output to the stdio stream 705890075Sobrien@var{stream} any text necessary for claiming a register @var{regno} 705990075Sobrienfor a global variable @var{decl} with name @var{name}. 706090075Sobrien 706190075SobrienIf you don't define this macro, that is equivalent to defining it to do 706290075Sobriennothing. 7063132718Skan@end defmac 706490075Sobrien 7065132718Skan@defmac ASM_FINISH_DECLARE_OBJECT (@var{stream}, @var{decl}, @var{toplevel}, @var{atend}) 706690075SobrienA C statement (sans semicolon) to finish up declaring a variable name 706790075Sobrienonce the compiler has processed its initializer fully and thus has had a 706890075Sobrienchance to determine the size of an array when controlled by an 706990075Sobrieninitializer. This is used on systems where it's necessary to declare 707090075Sobriensomething about the size of the object. 707190075Sobrien 707290075SobrienIf you don't define this macro, that is equivalent to defining it to do 707390075Sobriennothing. 707490075Sobrien 7075117395SkanYou may wish to use @code{ASM_OUTPUT_SIZE_DIRECTIVE} and/or 7076117395Skan@code{ASM_OUTPUT_MEASURED_SIZE} in the definition of this macro. 7077132718Skan@end defmac 7078117395Skan 7079117395Skan@deftypefn {Target Hook} void TARGET_ASM_GLOBALIZE_LABEL (FILE *@var{stream}, const char *@var{name}) 7080117395SkanThis target hook is a function to output to the stdio stream 708190075Sobrien@var{stream} some commands that will make the label @var{name} global; 7082117395Skanthat is, available for reference from other files. 708390075Sobrien 7084117395SkanThe default implementation relies on a proper definition of 7085117395Skan@code{GLOBAL_ASM_OP}. 7086117395Skan@end deftypefn 7087117395Skan 7088132718Skan@defmac ASM_WEAKEN_LABEL (@var{stream}, @var{name}) 708990075SobrienA C statement (sans semicolon) to output to the stdio stream 709090075Sobrien@var{stream} some commands that will make the label @var{name} weak; 709190075Sobrienthat is, available for reference from other files but only used if 709290075Sobrienno other definition is available. Use the expression 709390075Sobrien@code{assemble_name (@var{stream}, @var{name})} to output the name 709490075Sobrienitself; before and after that, output the additional assembler syntax 709590075Sobrienfor making that name weak, and a newline. 709690075Sobrien 709796263SobrienIf you don't define this macro or @code{ASM_WEAKEN_DECL}, GCC will not 709896263Sobriensupport weak symbols and you should not define the @code{SUPPORTS_WEAK} 709996263Sobrienmacro. 7100132718Skan@end defmac 710190075Sobrien 7102132718Skan@defmac ASM_WEAKEN_DECL (@var{stream}, @var{decl}, @var{name}, @var{value}) 710396263SobrienCombines (and replaces) the function of @code{ASM_WEAKEN_LABEL} and 710496263Sobrien@code{ASM_OUTPUT_WEAK_ALIAS}, allowing access to the associated function 710596263Sobrienor variable decl. If @var{value} is not @code{NULL}, this C statement 710696263Sobrienshould output to the stdio stream @var{stream} assembler code which 710796263Sobriendefines (equates) the weak symbol @var{name} to have the value 710896263Sobrien@var{value}. If @var{value} is @code{NULL}, it should output commands 710996263Sobriento make @var{name} weak. 7110132718Skan@end defmac 711196263Sobrien 7112169689Skan@defmac ASM_OUTPUT_WEAKREF (@var{stream}, @var{decl}, @var{name}, @var{value}) 7113169689SkanOutputs a directive that enables @var{name} to be used to refer to 7114169689Skansymbol @var{value} with weak-symbol semantics. @code{decl} is the 7115169689Skandeclaration of @code{name}. 7116169689Skan@end defmac 7117169689Skan 7118132718Skan@defmac SUPPORTS_WEAK 711990075SobrienA C expression which evaluates to true if the target supports weak symbols. 712090075Sobrien 712190075SobrienIf you don't define this macro, @file{defaults.h} provides a default 712296263Sobriendefinition. If either @code{ASM_WEAKEN_LABEL} or @code{ASM_WEAKEN_DECL} 712396263Sobrienis defined, the default definition is @samp{1}; otherwise, it is 712496263Sobrien@samp{0}. Define this macro if you want to control weak symbol support 712596263Sobrienwith a compiler flag such as @option{-melf}. 7126132718Skan@end defmac 712790075Sobrien 7128132718Skan@defmac MAKE_DECL_ONE_ONLY (@var{decl}) 712990075SobrienA C statement (sans semicolon) to mark @var{decl} to be emitted as a 713090075Sobrienpublic symbol such that extra copies in multiple translation units will 713190075Sobrienbe discarded by the linker. Define this macro if your object file 713290075Sobrienformat provides support for this concept, such as the @samp{COMDAT} 713390075Sobriensection flags in the Microsoft Windows PE/COFF format, and this support 713490075Sobrienrequires changes to @var{decl}, such as putting it in a separate section. 7135132718Skan@end defmac 713690075Sobrien 7137132718Skan@defmac SUPPORTS_ONE_ONLY 713890075SobrienA C expression which evaluates to true if the target supports one-only 713990075Sobriensemantics. 714090075Sobrien 714190075SobrienIf you don't define this macro, @file{varasm.c} provides a default 714290075Sobriendefinition. If @code{MAKE_DECL_ONE_ONLY} is defined, the default 714390075Sobriendefinition is @samp{1}; otherwise, it is @samp{0}. Define this macro if 714490075Sobrienyou want to control one-only symbol support with a compiler flag, or if 714590075Sobriensetting the @code{DECL_ONE_ONLY} flag is enough to mark a declaration to 714690075Sobrienbe emitted as one-only. 7147132718Skan@end defmac 714890075Sobrien 7149117395Skan@deftypefn {Target Hook} void TARGET_ASM_ASSEMBLE_VISIBILITY (tree @var{decl}, const char *@var{visibility}) 7150117395SkanThis target hook is a function to output to @var{asm_out_file} some 7151117395Skancommands that will make the symbol(s) associated with @var{decl} have 7152117395Skanhidden, protected or internal visibility as specified by @var{visibility}. 7153117395Skan@end deftypefn 7154117395Skan 7155169689Skan@defmac TARGET_WEAK_NOT_IN_ARCHIVE_TOC 7156169689SkanA C expression that evaluates to true if the target's linker expects 7157169689Skanthat weak symbols do not appear in a static archive's table of contents. 7158169689SkanThe default is @code{0}. 7159169689Skan 7160169689SkanLeaving weak symbols out of an archive's table of contents means that, 7161169689Skanif a symbol will only have a definition in one translation unit and 7162169689Skanwill have undefined references from other translation units, that 7163169689Skansymbol should not be weak. Defining this macro to be nonzero will 7164169689Skanthus have the effect that certain symbols that would normally be weak 7165169689Skan(explicit template instantiations, and vtables for polymorphic classes 7166169689Skanwith noninline key methods) will instead be nonweak. 7167169689Skan 7168169689SkanThe C++ ABI requires this macro to be zero. Define this macro for 7169169689Skantargets where full C++ ABI compliance is impossible and where linker 7170169689Skanrestrictions require weak symbols to be left out of a static archive's 7171169689Skantable of contents. 7172169689Skan@end defmac 7173169689Skan 7174132718Skan@defmac ASM_OUTPUT_EXTERNAL (@var{stream}, @var{decl}, @var{name}) 717590075SobrienA C statement (sans semicolon) to output to the stdio stream 717690075Sobrien@var{stream} any text necessary for declaring the name of an external 717790075Sobriensymbol named @var{name} which is referenced in this compilation but 717890075Sobriennot defined. The value of @var{decl} is the tree node for the 717990075Sobriendeclaration. 718090075Sobrien 718190075SobrienThis macro need not be defined if it does not need to output anything. 718290075SobrienThe GNU assembler and most Unix assemblers don't require anything. 7183132718Skan@end defmac 718490075Sobrien 7185132718Skan@deftypefn {Target Hook} void TARGET_ASM_EXTERNAL_LIBCALL (rtx @var{symref}) 7186132718SkanThis target hook is a function to output to @var{asm_out_file} an assembler 718790075Sobrienpseudo-op to declare a library function name external. The name of the 7188132718Skanlibrary function is given by @var{symref}, which is a @code{symbol_ref}. 7189132718Skan@end deftypefn 719090075Sobrien 7191169689Skan@deftypefn {Target Hook} void TARGET_ASM_MARK_DECL_PRESERVED (tree @var{decl}) 7192169689SkanThis target hook is a function to output to @var{asm_out_file} an assembler 7193169689Skandirective to annotate used symbol. Darwin target use .no_dead_code_strip 7194169689Skandirective. 7195169689Skan@end deftypefn 7196169689Skan 7197132718Skan@defmac ASM_OUTPUT_LABELREF (@var{stream}, @var{name}) 719890075SobrienA C statement (sans semicolon) to output to the stdio stream 719990075Sobrien@var{stream} a reference in assembler syntax to a label named 720090075Sobrien@var{name}. This should add @samp{_} to the front of the name, if that 720190075Sobrienis customary on your operating system, as it is in most Berkeley Unix 720290075Sobriensystems. This macro is used in @code{assemble_name}. 7203132718Skan@end defmac 720490075Sobrien 7205132718Skan@defmac ASM_OUTPUT_SYMBOL_REF (@var{stream}, @var{sym}) 720690075SobrienA C statement (sans semicolon) to output a reference to 720790075Sobrien@code{SYMBOL_REF} @var{sym}. If not defined, @code{assemble_name} 720890075Sobrienwill be used to output the name of the symbol. This macro may be used 720990075Sobriento modify the way a symbol is referenced depending on information 7210117395Skanencoded by @code{TARGET_ENCODE_SECTION_INFO}. 7211132718Skan@end defmac 721290075Sobrien 7213132718Skan@defmac ASM_OUTPUT_LABEL_REF (@var{stream}, @var{buf}) 721490075SobrienA C statement (sans semicolon) to output a reference to @var{buf}, the 7215117395Skanresult of @code{ASM_GENERATE_INTERNAL_LABEL}. If not defined, 721690075Sobrien@code{assemble_name} will be used to output the name of the symbol. 721790075SobrienThis macro is not used by @code{output_asm_label}, or the @code{%l} 721890075Sobrienspecifier that calls it; the intention is that this macro should be set 7219117395Skanwhen it is necessary to output a label differently when its address is 7220117395Skanbeing taken. 7221132718Skan@end defmac 722290075Sobrien 7223132718Skan@deftypefn {Target Hook} void TARGET_ASM_INTERNAL_LABEL (FILE *@var{stream}, const char *@var{prefix}, unsigned long @var{labelno}) 7224132718SkanA function to output to the stdio stream @var{stream} a label whose 7225132718Skanname is made from the string @var{prefix} and the number @var{labelno}. 722690075Sobrien 722790075SobrienIt is absolutely essential that these labels be distinct from the labels 722890075Sobrienused for user-level functions and variables. Otherwise, certain programs 722990075Sobrienwill have name conflicts with internal labels. 723090075Sobrien 723190075SobrienIt is desirable to exclude internal labels from the symbol table of the 723290075Sobrienobject file. Most assemblers have a naming convention for labels that 723390075Sobrienshould be excluded; on many systems, the letter @samp{L} at the 723490075Sobrienbeginning of a label has this effect. You should find out what 723590075Sobrienconvention your system uses, and follow it. 723690075Sobrien 7237169689SkanThe default version of this function utilizes @code{ASM_GENERATE_INTERNAL_LABEL}. 7238132718Skan@end deftypefn 723990075Sobrien 7240132718Skan@defmac ASM_OUTPUT_DEBUG_LABEL (@var{stream}, @var{prefix}, @var{num}) 724190075SobrienA C statement to output to the stdio stream @var{stream} a debug info 724290075Sobrienlabel whose name is made from the string @var{prefix} and the number 724390075Sobrien@var{num}. This is useful for VLIW targets, where debug info labels 724490075Sobrienmay need to be treated differently than branch target labels. On some 724590075Sobriensystems, branch target labels must be at the beginning of instruction 724690075Sobrienbundles, but debug info labels can occur in the middle of instruction 724790075Sobrienbundles. 724890075Sobrien 7249132718SkanIf this macro is not defined, then @code{(*targetm.asm_out.internal_label)} will be 725090075Sobrienused. 7251132718Skan@end defmac 725290075Sobrien 7253132718Skan@defmac ASM_GENERATE_INTERNAL_LABEL (@var{string}, @var{prefix}, @var{num}) 725490075SobrienA C statement to store into the string @var{string} a label whose name 725590075Sobrienis made from the string @var{prefix} and the number @var{num}. 725690075Sobrien 725790075SobrienThis string, when output subsequently by @code{assemble_name}, should 7258132718Skanproduce the output that @code{(*targetm.asm_out.internal_label)} would produce 725990075Sobrienwith the same @var{prefix} and @var{num}. 726090075Sobrien 726190075SobrienIf the string begins with @samp{*}, then @code{assemble_name} will 726290075Sobrienoutput the rest of the string unchanged. It is often convenient for 726390075Sobrien@code{ASM_GENERATE_INTERNAL_LABEL} to use @samp{*} in this way. If the 726490075Sobrienstring doesn't start with @samp{*}, then @code{ASM_OUTPUT_LABELREF} gets 726590075Sobriento output the string, and may change it. (Of course, 726690075Sobrien@code{ASM_OUTPUT_LABELREF} is also part of your machine description, so 726790075Sobrienyou should know what it does on your machine.) 7268132718Skan@end defmac 726990075Sobrien 7270132718Skan@defmac ASM_FORMAT_PRIVATE_NAME (@var{outvar}, @var{name}, @var{number}) 727190075SobrienA C expression to assign to @var{outvar} (which is a variable of type 727290075Sobrien@code{char *}) a newly allocated string made from the string 727390075Sobrien@var{name} and the number @var{number}, with some suitable punctuation 727490075Sobrienadded. Use @code{alloca} to get space for the string. 727590075Sobrien 727690075SobrienThe string will be used as an argument to @code{ASM_OUTPUT_LABELREF} to 727790075Sobrienproduce an assembler label for an internal static variable whose name is 727890075Sobrien@var{name}. Therefore, the string must be such as to result in valid 727990075Sobrienassembler code. The argument @var{number} is different each time this 728090075Sobrienmacro is executed; it prevents conflicts between similarly-named 728190075Sobrieninternal static variables in different scopes. 728290075Sobrien 728390075SobrienIdeally this string should not be a valid C identifier, to prevent any 728490075Sobrienconflict with the user's own symbols. Most assemblers allow periods 728590075Sobrienor percent signs in assembler symbols; putting at least one of these 728690075Sobrienbetween the name and the number will suffice. 728790075Sobrien 7288132718SkanIf this macro is not defined, a default definition will be provided 7289132718Skanwhich is correct for most systems. 7290132718Skan@end defmac 7291132718Skan 7292132718Skan@defmac ASM_OUTPUT_DEF (@var{stream}, @var{name}, @var{value}) 729390075SobrienA C statement to output to the stdio stream @var{stream} assembler code 729490075Sobrienwhich defines (equates) the symbol @var{name} to have the value @var{value}. 729590075Sobrien 729690075Sobrien@findex SET_ASM_OP 729790075SobrienIf @code{SET_ASM_OP} is defined, a default definition is provided which is 729890075Sobriencorrect for most systems. 7299132718Skan@end defmac 730090075Sobrien 7301132718Skan@defmac ASM_OUTPUT_DEF_FROM_DECLS (@var{stream}, @var{decl_of_name}, @var{decl_of_value}) 730290075SobrienA C statement to output to the stdio stream @var{stream} assembler code 730390075Sobrienwhich defines (equates) the symbol whose tree node is @var{decl_of_name} 730490075Sobriento have the value of the tree node @var{decl_of_value}. This macro will 730590075Sobrienbe used in preference to @samp{ASM_OUTPUT_DEF} if it is defined and if 730690075Sobrienthe tree nodes are available. 730790075Sobrien 730890075Sobrien@findex SET_ASM_OP 730990075SobrienIf @code{SET_ASM_OP} is defined, a default definition is provided which is 731090075Sobriencorrect for most systems. 7311132718Skan@end defmac 731290075Sobrien 7313146895Skan@defmac TARGET_DEFERRED_OUTPUT_DEFS (@var{decl_of_name}, @var{decl_of_value}) 7314146895SkanA C statement that evaluates to true if the assembler code which defines 7315146895Skan(equates) the symbol whose tree node is @var{decl_of_name} to have the value 7316146895Skanof the tree node @var{decl_of_value} should be emitted near the end of the 7317146895Skancurrent compilation unit. The default is to not defer output of defines. 7318146895SkanThis macro affects defines output by @samp{ASM_OUTPUT_DEF} and 7319146895Skan@samp{ASM_OUTPUT_DEF_FROM_DECLS}. 7320146895Skan@end defmac 7321146895Skan 7322132718Skan@defmac ASM_OUTPUT_WEAK_ALIAS (@var{stream}, @var{name}, @var{value}) 732390075SobrienA C statement to output to the stdio stream @var{stream} assembler code 732490075Sobrienwhich defines (equates) the weak symbol @var{name} to have the value 732590075Sobrien@var{value}. If @var{value} is @code{NULL}, it defines @var{name} as 732690075Sobrienan undefined weak symbol. 732790075Sobrien 732890075SobrienDefine this macro if the target only supports weak aliases; define 732990075Sobrien@code{ASM_OUTPUT_DEF} instead if possible. 7330132718Skan@end defmac 733190075Sobrien 7332132718Skan@defmac OBJC_GEN_METHOD_LABEL (@var{buf}, @var{is_inst}, @var{class_name}, @var{cat_name}, @var{sel_name}) 733390075SobrienDefine this macro to override the default assembler names used for 733490075SobrienObjective-C methods. 733590075Sobrien 733690075SobrienThe default name is a unique method number followed by the name of the 733790075Sobrienclass (e.g.@: @samp{_1_Foo}). For methods in categories, the name of 733890075Sobrienthe category is also included in the assembler name (e.g.@: 733990075Sobrien@samp{_1_Foo_Bar}). 734090075Sobrien 734190075SobrienThese names are safe on most systems, but make debugging difficult since 734290075Sobrienthe method's selector is not present in the name. Therefore, particular 734390075Sobriensystems define other ways of computing names. 734490075Sobrien 734590075Sobrien@var{buf} is an expression of type @code{char *} which gives you a 734690075Sobrienbuffer in which to store the name; its length is as long as 734790075Sobrien@var{class_name}, @var{cat_name} and @var{sel_name} put together, plus 734890075Sobrien50 characters extra. 734990075Sobrien 735090075SobrienThe argument @var{is_inst} specifies whether the method is an instance 735190075Sobrienmethod or a class method; @var{class_name} is the name of the class; 735290075Sobrien@var{cat_name} is the name of the category (or @code{NULL} if the method is not 735390075Sobrienin a category); and @var{sel_name} is the name of the selector. 735490075Sobrien 735590075SobrienOn systems where the assembler can handle quoted names, you can use this 735690075Sobrienmacro to provide more human-readable names. 7357132718Skan@end defmac 735890075Sobrien 7359132718Skan@defmac ASM_DECLARE_CLASS_REFERENCE (@var{stream}, @var{name}) 736090075SobrienA C statement (sans semicolon) to output to the stdio stream 736190075Sobrien@var{stream} commands to declare that the label @var{name} is an 736290075SobrienObjective-C class reference. This is only needed for targets whose 736390075Sobrienlinkers have special support for NeXT-style runtimes. 7364132718Skan@end defmac 736590075Sobrien 7366132718Skan@defmac ASM_DECLARE_UNRESOLVED_REFERENCE (@var{stream}, @var{name}) 736790075SobrienA C statement (sans semicolon) to output to the stdio stream 736890075Sobrien@var{stream} commands to declare that the label @var{name} is an 736990075Sobrienunresolved Objective-C class reference. This is only needed for targets 737090075Sobrienwhose linkers have special support for NeXT-style runtimes. 7371132718Skan@end defmac 737290075Sobrien 737390075Sobrien@node Initialization 737490075Sobrien@subsection How Initialization Functions Are Handled 737590075Sobrien@cindex initialization routines 737690075Sobrien@cindex termination routines 737790075Sobrien@cindex constructors, output of 737890075Sobrien@cindex destructors, output of 737990075Sobrien 738090075SobrienThe compiled code for certain languages includes @dfn{constructors} 738190075Sobrien(also called @dfn{initialization routines})---functions to initialize 738290075Sobriendata in the program when the program is started. These functions need 738390075Sobriento be called before the program is ``started''---that is to say, before 738490075Sobrien@code{main} is called. 738590075Sobrien 738690075SobrienCompiling some languages generates @dfn{destructors} (also called 738790075Sobrien@dfn{termination routines}) that should be called when the program 738890075Sobrienterminates. 738990075Sobrien 739090075SobrienTo make the initialization and termination functions work, the compiler 739190075Sobrienmust output something in the assembler code to cause those functions to 739290075Sobrienbe called at the appropriate time. When you port the compiler to a new 739390075Sobriensystem, you need to specify how to do this. 739490075Sobrien 739590075SobrienThere are two major ways that GCC currently supports the execution of 739690075Sobrieninitialization and termination functions. Each way has two variants. 739790075SobrienMuch of the structure is common to all four variations. 739890075Sobrien 739990075Sobrien@findex __CTOR_LIST__ 740090075Sobrien@findex __DTOR_LIST__ 740190075SobrienThe linker must build two lists of these functions---a list of 740290075Sobrieninitialization functions, called @code{__CTOR_LIST__}, and a list of 740390075Sobrientermination functions, called @code{__DTOR_LIST__}. 740490075Sobrien 740590075SobrienEach list always begins with an ignored function pointer (which may hold 740690075Sobrien0, @minus{}1, or a count of the function pointers after it, depending on 740790075Sobrienthe environment). This is followed by a series of zero or more function 740890075Sobrienpointers to constructors (or destructors), followed by a function 740990075Sobrienpointer containing zero. 741090075Sobrien 741190075SobrienDepending on the operating system and its executable file format, either 741290075Sobrien@file{crtstuff.c} or @file{libgcc2.c} traverses these lists at startup 741390075Sobrientime and exit time. Constructors are called in reverse order of the 741490075Sobrienlist; destructors in forward order. 741590075Sobrien 741690075SobrienThe best way to handle static constructors works only for object file 741790075Sobrienformats which provide arbitrarily-named sections. A section is set 741890075Sobrienaside for a list of constructors, and another for a list of destructors. 741990075SobrienTraditionally these are called @samp{.ctors} and @samp{.dtors}. Each 742090075Sobrienobject file that defines an initialization function also puts a word in 742190075Sobrienthe constructor section to point to that function. The linker 742290075Sobrienaccumulates all these words into one contiguous @samp{.ctors} section. 742390075SobrienTermination functions are handled similarly. 742490075Sobrien 742590075SobrienThis method will be chosen as the default by @file{target-def.h} if 742690075Sobrien@code{TARGET_ASM_NAMED_SECTION} is defined. A target that does not 742796263Sobriensupport arbitrary sections, but does support special designated 742890075Sobrienconstructor and destructor sections may define @code{CTORS_SECTION_ASM_OP} 742990075Sobrienand @code{DTORS_SECTION_ASM_OP} to achieve the same effect. 743090075Sobrien 743190075SobrienWhen arbitrary sections are available, there are two variants, depending 743290075Sobrienupon how the code in @file{crtstuff.c} is called. On systems that 743390075Sobriensupport a @dfn{.init} section which is executed at program startup, 743490075Sobrienparts of @file{crtstuff.c} are compiled into that section. The 7435117395Skanprogram is linked by the @command{gcc} driver like this: 743690075Sobrien 7437132718Skan@smallexample 743890075Sobrienld -o @var{output_file} crti.o crtbegin.o @dots{} -lgcc crtend.o crtn.o 7439132718Skan@end smallexample 744090075Sobrien 744190075SobrienThe prologue of a function (@code{__init}) appears in the @code{.init} 744290075Sobriensection of @file{crti.o}; the epilogue appears in @file{crtn.o}. Likewise 744390075Sobrienfor the function @code{__fini} in the @dfn{.fini} section. Normally these 744490075Sobrienfiles are provided by the operating system or by the GNU C library, but 744590075Sobrienare provided by GCC for a few targets. 744690075Sobrien 744790075SobrienThe objects @file{crtbegin.o} and @file{crtend.o} are (for most targets) 744890075Sobriencompiled from @file{crtstuff.c}. They contain, among other things, code 744990075Sobrienfragments within the @code{.init} and @code{.fini} sections that branch 745090075Sobriento routines in the @code{.text} section. The linker will pull all parts 745190075Sobrienof a section together, which results in a complete @code{__init} function 745290075Sobrienthat invokes the routines we need at startup. 745390075Sobrien 745490075SobrienTo use this variant, you must define the @code{INIT_SECTION_ASM_OP} 745590075Sobrienmacro properly. 745690075Sobrien 745790075SobrienIf no init section is available, when GCC compiles any function called 745890075Sobrien@code{main} (or more accurately, any function designated as a program 745990075Sobrienentry point by the language front end calling @code{expand_main_function}), 746090075Sobrienit inserts a procedure call to @code{__main} as the first executable code 746190075Sobrienafter the function prologue. The @code{__main} function is defined 746290075Sobrienin @file{libgcc2.c} and runs the global constructors. 746390075Sobrien 746490075SobrienIn file formats that don't support arbitrary sections, there are again 746590075Sobrientwo variants. In the simplest variant, the GNU linker (GNU @code{ld}) 746690075Sobrienand an `a.out' format must be used. In this case, 746790075Sobrien@code{TARGET_ASM_CONSTRUCTOR} is defined to produce a @code{.stabs} 746890075Sobrienentry of type @samp{N_SETT}, referencing the name @code{__CTOR_LIST__}, 746990075Sobrienand with the address of the void function containing the initialization 747090075Sobriencode as its value. The GNU linker recognizes this as a request to add 747190075Sobrienthe value to a @dfn{set}; the values are accumulated, and are eventually 747290075Sobrienplaced in the executable as a vector in the format described above, with 747390075Sobriena leading (ignored) count and a trailing zero element. 747490075Sobrien@code{TARGET_ASM_DESTRUCTOR} is handled similarly. Since no init 747590075Sobriensection is available, the absence of @code{INIT_SECTION_ASM_OP} causes 747690075Sobrienthe compilation of @code{main} to call @code{__main} as above, starting 747790075Sobrienthe initialization process. 747890075Sobrien 747990075SobrienThe last variant uses neither arbitrary sections nor the GNU linker. 748090075SobrienThis is preferable when you want to do dynamic linking and when using 748190075Sobrienfile formats which the GNU linker does not support, such as `ECOFF'@. In 748290075Sobrienthis case, @code{TARGET_HAVE_CTORS_DTORS} is false, initialization and 748390075Sobrientermination functions are recognized simply by their names. This requires 748490075Sobrienan extra program in the linkage step, called @command{collect2}. This program 748590075Sobrienpretends to be the linker, for use with GCC; it does its job by running 748690075Sobrienthe ordinary linker, but also arranges to include the vectors of 748790075Sobrieninitialization and termination functions. These functions are called 748890075Sobrienvia @code{__main} as described above. In order to use this method, 748990075Sobrien@code{use_collect2} must be defined in the target in @file{config.gcc}. 749090075Sobrien 749190075Sobrien@ifinfo 749290075SobrienThe following section describes the specific macros that control and 749390075Sobriencustomize the handling of initialization and termination functions. 749490075Sobrien@end ifinfo 749590075Sobrien 749690075Sobrien@node Macros for Initialization 749790075Sobrien@subsection Macros Controlling Initialization Routines 749890075Sobrien 749990075SobrienHere are the macros that control how the compiler handles initialization 750090075Sobrienand termination functions: 750190075Sobrien 7502132718Skan@defmac INIT_SECTION_ASM_OP 750390075SobrienIf defined, a C string constant, including spacing, for the assembler 750490075Sobrienoperation to identify the following data as initialization code. If not 750590075Sobriendefined, GCC will assume such a section does not exist. When you are 750690075Sobrienusing special sections for initialization and termination functions, this 750790075Sobrienmacro also controls how @file{crtstuff.c} and @file{libgcc2.c} arrange to 750890075Sobrienrun the initialization functions. 7509132718Skan@end defmac 751090075Sobrien 7511132718Skan@defmac HAS_INIT_SECTION 751290075SobrienIf defined, @code{main} will not call @code{__main} as described above. 751390075SobrienThis macro should be defined for systems that control start-up code 751490075Sobrienon a symbol-by-symbol basis, such as OSF/1, and should not 751590075Sobrienbe defined explicitly for systems that support @code{INIT_SECTION_ASM_OP}. 7516132718Skan@end defmac 751790075Sobrien 7518132718Skan@defmac LD_INIT_SWITCH 751990075SobrienIf defined, a C string constant for a switch that tells the linker that 752090075Sobrienthe following symbol is an initialization routine. 7521132718Skan@end defmac 752290075Sobrien 7523132718Skan@defmac LD_FINI_SWITCH 752490075SobrienIf defined, a C string constant for a switch that tells the linker that 752590075Sobrienthe following symbol is a finalization routine. 7526132718Skan@end defmac 752790075Sobrien 7528132718Skan@defmac COLLECT_SHARED_INIT_FUNC (@var{stream}, @var{func}) 752990075SobrienIf defined, a C statement that will write a function that can be 753090075Sobrienautomatically called when a shared library is loaded. The function 753190075Sobrienshould call @var{func}, which takes no arguments. If not defined, and 753290075Sobrienthe object format requires an explicit initialization function, then a 753390075Sobrienfunction called @code{_GLOBAL__DI} will be generated. 753490075Sobrien 753590075SobrienThis function and the following one are used by collect2 when linking a 753696263Sobrienshared library that needs constructors or destructors, or has DWARF2 753790075Sobrienexception tables embedded in the code. 7538132718Skan@end defmac 753990075Sobrien 7540132718Skan@defmac COLLECT_SHARED_FINI_FUNC (@var{stream}, @var{func}) 754190075SobrienIf defined, a C statement that will write a function that can be 754290075Sobrienautomatically called when a shared library is unloaded. The function 754390075Sobrienshould call @var{func}, which takes no arguments. If not defined, and 754490075Sobrienthe object format requires an explicit finalization function, then a 754590075Sobrienfunction called @code{_GLOBAL__DD} will be generated. 7546132718Skan@end defmac 754790075Sobrien 7548132718Skan@defmac INVOKE__main 754990075SobrienIf defined, @code{main} will call @code{__main} despite the presence of 755090075Sobrien@code{INIT_SECTION_ASM_OP}. This macro should be defined for systems 755190075Sobrienwhere the init section is not actually run automatically, but is still 755290075Sobrienuseful for collecting the lists of constructors and destructors. 7553132718Skan@end defmac 755490075Sobrien 7555132718Skan@defmac SUPPORTS_INIT_PRIORITY 755690075SobrienIf nonzero, the C++ @code{init_priority} attribute is supported and the 755790075Sobriencompiler should emit instructions to control the order of initialization 755890075Sobrienof objects. If zero, the compiler will issue an error message upon 755990075Sobrienencountering an @code{init_priority} attribute. 7560132718Skan@end defmac 756190075Sobrien 756290075Sobrien@deftypefn {Target Hook} bool TARGET_HAVE_CTORS_DTORS 756390075SobrienThis value is true if the target supports some ``native'' method of 756490075Sobriencollecting constructors and destructors to be run at startup and exit. 756590075SobrienIt is false if we must use @command{collect2}. 756690075Sobrien@end deftypefn 756790075Sobrien 756890075Sobrien@deftypefn {Target Hook} void TARGET_ASM_CONSTRUCTOR (rtx @var{symbol}, int @var{priority}) 756990075SobrienIf defined, a function that outputs assembler code to arrange to call 757090075Sobrienthe function referenced by @var{symbol} at initialization time. 757190075Sobrien 757290075SobrienAssume that @var{symbol} is a @code{SYMBOL_REF} for a function taking 757390075Sobrienno arguments and with no return value. If the target supports initialization 757490075Sobrienpriorities, @var{priority} is a value between 0 and @code{MAX_INIT_PRIORITY}; 757590075Sobrienotherwise it must be @code{DEFAULT_INIT_PRIORITY}. 757690075Sobrien 757790075SobrienIf this macro is not defined by the target, a suitable default will 757890075Sobrienbe chosen if (1) the target supports arbitrary section names, (2) the 757990075Sobrientarget defines @code{CTORS_SECTION_ASM_OP}, or (3) @code{USE_COLLECT2} 758090075Sobrienis not defined. 758190075Sobrien@end deftypefn 758290075Sobrien 758390075Sobrien@deftypefn {Target Hook} void TARGET_ASM_DESTRUCTOR (rtx @var{symbol}, int @var{priority}) 758490075SobrienThis is like @code{TARGET_ASM_CONSTRUCTOR} but used for termination 758590075Sobrienfunctions rather than initialization functions. 758690075Sobrien@end deftypefn 758790075Sobrien 758890075SobrienIf @code{TARGET_HAVE_CTORS_DTORS} is true, the initialization routine 758990075Sobriengenerated for the generated object file will have static linkage. 759090075Sobrien 759190075SobrienIf your system uses @command{collect2} as the means of processing 759290075Sobrienconstructors, then that program normally uses @command{nm} to scan 759390075Sobrienan object file for constructor functions to be called. 759490075Sobrien 7595132718SkanOn certain kinds of systems, you can define this macro to make 759690075Sobrien@command{collect2} work faster (and, in some cases, make it work at all): 759790075Sobrien 7598132718Skan@defmac OBJECT_FORMAT_COFF 759990075SobrienDefine this macro if the system uses COFF (Common Object File Format) 760090075Sobrienobject files, so that @command{collect2} can assume this format and scan 760190075Sobrienobject files directly for dynamic constructor/destructor functions. 760290075Sobrien 7603132718SkanThis macro is effective only in a native compiler; @command{collect2} as 760490075Sobrienpart of a cross compiler always uses @command{nm} for the target machine. 7605132718Skan@end defmac 760690075Sobrien 7607132718Skan@defmac REAL_NM_FILE_NAME 760890075SobrienDefine this macro as a C string constant containing the file name to use 760990075Sobriento execute @command{nm}. The default is to search the path normally for 761090075Sobrien@command{nm}. 761190075Sobrien 761290075SobrienIf your system supports shared libraries and has a program to list the 761390075Sobriendynamic dependencies of a given library or executable, you can define 761490075Sobrienthese macros to enable support for running initialization and 761590075Sobrientermination functions in shared libraries: 7616132718Skan@end defmac 761790075Sobrien 7618132718Skan@defmac LDD_SUFFIX 761990075SobrienDefine this macro to a C string constant containing the name of the program 762090075Sobrienwhich lists dynamic dependencies, like @command{"ldd"} under SunOS 4. 7621132718Skan@end defmac 762290075Sobrien 7623132718Skan@defmac PARSE_LDD_OUTPUT (@var{ptr}) 762490075SobrienDefine this macro to be C code that extracts filenames from the output 762590075Sobrienof the program denoted by @code{LDD_SUFFIX}. @var{ptr} is a variable 762690075Sobrienof type @code{char *} that points to the beginning of a line of output 762790075Sobrienfrom @code{LDD_SUFFIX}. If the line lists a dynamic dependency, the 762890075Sobriencode must advance @var{ptr} to the beginning of the filename on that 762990075Sobrienline. Otherwise, it must set @var{ptr} to @code{NULL}. 7630132718Skan@end defmac 763190075Sobrien 763290075Sobrien@node Instruction Output 763390075Sobrien@subsection Output of Assembler Instructions 763490075Sobrien 763590075Sobrien@c prevent bad page break with this line 763690075SobrienThis describes assembler instruction output. 763790075Sobrien 7638132718Skan@defmac REGISTER_NAMES 763990075SobrienA C initializer containing the assembler's names for the machine 764090075Sobrienregisters, each one as a C string constant. This is what translates 764190075Sobrienregister numbers in the compiler into assembler language. 7642132718Skan@end defmac 764390075Sobrien 7644132718Skan@defmac ADDITIONAL_REGISTER_NAMES 764590075SobrienIf defined, a C initializer for an array of structures containing a name 764690075Sobrienand a register number. This macro defines additional names for hard 764790075Sobrienregisters, thus allowing the @code{asm} option in declarations to refer 764890075Sobriento registers using alternate names. 7649132718Skan@end defmac 765090075Sobrien 7651132718Skan@defmac ASM_OUTPUT_OPCODE (@var{stream}, @var{ptr}) 765290075SobrienDefine this macro if you are using an unusual assembler that 765390075Sobrienrequires different names for the machine instructions. 765490075Sobrien 765590075SobrienThe definition is a C statement or statements which output an 765690075Sobrienassembler instruction opcode to the stdio stream @var{stream}. The 765790075Sobrienmacro-operand @var{ptr} is a variable of type @code{char *} which 765890075Sobrienpoints to the opcode name in its ``internal'' form---the form that is 765990075Sobrienwritten in the machine description. The definition should output the 766090075Sobrienopcode name to @var{stream}, performing any translation you desire, and 766190075Sobrienincrement the variable @var{ptr} to point at the end of the opcode 766290075Sobrienso that it will not be output twice. 766390075Sobrien 766490075SobrienIn fact, your macro definition may process less than the entire opcode 766590075Sobrienname, or more than the opcode name; but if you want to process text 766690075Sobrienthat includes @samp{%}-sequences to substitute operands, you must take 766790075Sobriencare of the substitution yourself. Just be sure to increment 766890075Sobrien@var{ptr} over whatever text should not be output normally. 766990075Sobrien 767090075Sobrien@findex recog_data.operand 767190075SobrienIf you need to look at the operand values, they can be found as the 767290075Sobrienelements of @code{recog_data.operand}. 767390075Sobrien 767490075SobrienIf the macro definition does nothing, the instruction is output 767590075Sobrienin the usual way. 7676132718Skan@end defmac 767790075Sobrien 7678132718Skan@defmac FINAL_PRESCAN_INSN (@var{insn}, @var{opvec}, @var{noperands}) 767990075SobrienIf defined, a C statement to be executed just prior to the output of 768090075Sobrienassembler code for @var{insn}, to modify the extracted operands so 768190075Sobrienthey will be output differently. 768290075Sobrien 768390075SobrienHere the argument @var{opvec} is the vector containing the operands 768490075Sobrienextracted from @var{insn}, and @var{noperands} is the number of 768590075Sobrienelements of the vector which contain meaningful data for this insn. 768690075SobrienThe contents of this vector are what will be used to convert the insn 768790075Sobrientemplate into assembler code, so you can change the assembler output 768890075Sobrienby changing the contents of the vector. 768990075Sobrien 769090075SobrienThis macro is useful when various assembler syntaxes share a single 769190075Sobrienfile of instruction patterns; by defining this macro differently, you 769290075Sobriencan cause a large class of instructions to be output differently (such 769390075Sobrienas with rearranged operands). Naturally, variations in assembler 769490075Sobriensyntax affecting individual insn patterns ought to be handled by 769590075Sobrienwriting conditional output routines in those patterns. 769690075Sobrien 769790075SobrienIf this macro is not defined, it is equivalent to a null statement. 7698132718Skan@end defmac 769990075Sobrien 7700132718Skan@defmac PRINT_OPERAND (@var{stream}, @var{x}, @var{code}) 770190075SobrienA C compound statement to output to stdio stream @var{stream} the 770290075Sobrienassembler syntax for an instruction operand @var{x}. @var{x} is an 770390075SobrienRTL expression. 770490075Sobrien 770590075Sobrien@var{code} is a value that can be used to specify one of several ways 770690075Sobrienof printing the operand. It is used when identical operands must be 770790075Sobrienprinted differently depending on the context. @var{code} comes from 770890075Sobrienthe @samp{%} specification that was used to request printing of the 770990075Sobrienoperand. If the specification was just @samp{%@var{digit}} then 771090075Sobrien@var{code} is 0; if the specification was @samp{%@var{ltr} 771190075Sobrien@var{digit}} then @var{code} is the ASCII code for @var{ltr}. 771290075Sobrien 771390075Sobrien@findex reg_names 771490075SobrienIf @var{x} is a register, this macro should print the register's name. 771590075SobrienThe names can be found in an array @code{reg_names} whose type is 771690075Sobrien@code{char *[]}. @code{reg_names} is initialized from 771790075Sobrien@code{REGISTER_NAMES}. 771890075Sobrien 771990075SobrienWhen the machine description has a specification @samp{%@var{punct}} 772090075Sobrien(a @samp{%} followed by a punctuation character), this macro is called 772190075Sobrienwith a null pointer for @var{x} and the punctuation character for 772290075Sobrien@var{code}. 7723132718Skan@end defmac 772490075Sobrien 7725132718Skan@defmac PRINT_OPERAND_PUNCT_VALID_P (@var{code}) 772690075SobrienA C expression which evaluates to true if @var{code} is a valid 772790075Sobrienpunctuation character for use in the @code{PRINT_OPERAND} macro. If 772890075Sobrien@code{PRINT_OPERAND_PUNCT_VALID_P} is not defined, it means that no 772990075Sobrienpunctuation characters (except for the standard one, @samp{%}) are used 773090075Sobrienin this way. 7731132718Skan@end defmac 773290075Sobrien 7733132718Skan@defmac PRINT_OPERAND_ADDRESS (@var{stream}, @var{x}) 773490075SobrienA C compound statement to output to stdio stream @var{stream} the 773590075Sobrienassembler syntax for an instruction operand that is a memory reference 773690075Sobrienwhose address is @var{x}. @var{x} is an RTL expression. 773790075Sobrien 7738117395Skan@cindex @code{TARGET_ENCODE_SECTION_INFO} usage 773990075SobrienOn some machines, the syntax for a symbolic address depends on the 7740117395Skansection that the address refers to. On these machines, define the hook 7741117395Skan@code{TARGET_ENCODE_SECTION_INFO} to store the information into the 7742132718Skan@code{symbol_ref}, and then check for it here. @xref{Assembler 7743132718SkanFormat}. 7744132718Skan@end defmac 774590075Sobrien 774690075Sobrien@findex dbr_sequence_length 7747132718Skan@defmac DBR_OUTPUT_SEQEND (@var{file}) 774890075SobrienA C statement, to be executed after all slot-filler instructions have 774990075Sobrienbeen output. If necessary, call @code{dbr_sequence_length} to 775090075Sobriendetermine the number of slots filled in a sequence (zero if not 775190075Sobriencurrently outputting a sequence), to decide how many no-ops to output, 775290075Sobrienor whatever. 775390075Sobrien 775490075SobrienDon't define this macro if it has nothing to do, but it is helpful in 775590075Sobrienreading assembly output if the extent of the delay sequence is made 775690075Sobrienexplicit (e.g.@: with white space). 7757132718Skan@end defmac 775890075Sobrien 775990075Sobrien@findex final_sequence 776090075SobrienNote that output routines for instructions with delay slots must be 776190075Sobrienprepared to deal with not being output as part of a sequence 776290075Sobrien(i.e.@: when the scheduling pass is not run, or when no slot fillers could be 776390075Sobrienfound.) The variable @code{final_sequence} is null when not 776490075Sobrienprocessing a sequence, otherwise it contains the @code{sequence} rtx 776590075Sobrienbeing output. 776690075Sobrien 776790075Sobrien@findex asm_fprintf 7768132718Skan@defmac REGISTER_PREFIX 7769132718Skan@defmacx LOCAL_LABEL_PREFIX 7770132718Skan@defmacx USER_LABEL_PREFIX 7771132718Skan@defmacx IMMEDIATE_PREFIX 777290075SobrienIf defined, C string expressions to be used for the @samp{%R}, @samp{%L}, 777390075Sobrien@samp{%U}, and @samp{%I} options of @code{asm_fprintf} (see 777490075Sobrien@file{final.c}). These are useful when a single @file{md} file must 777590075Sobriensupport multiple assembler formats. In that case, the various @file{tm.h} 777690075Sobrienfiles can define these macros differently. 7777132718Skan@end defmac 777890075Sobrien 7779132718Skan@defmac ASM_FPRINTF_EXTENSIONS (@var{file}, @var{argptr}, @var{format}) 778090075SobrienIf defined this macro should expand to a series of @code{case} 778190075Sobrienstatements which will be parsed inside the @code{switch} statement of 778290075Sobrienthe @code{asm_fprintf} function. This allows targets to define extra 778390075Sobrienprintf formats which may useful when generating their assembler 7784132718Skanstatements. Note that uppercase letters are reserved for future 778590075Sobriengeneric extensions to asm_fprintf, and so are not available to target 778690075Sobrienspecific code. The output file is given by the parameter @var{file}. 778790075SobrienThe varargs input pointer is @var{argptr} and the rest of the format 778890075Sobrienstring, starting the character after the one that is being switched 778990075Sobrienupon, is pointed to by @var{format}. 7790132718Skan@end defmac 779190075Sobrien 7792132718Skan@defmac ASSEMBLER_DIALECT 779390075SobrienIf your target supports multiple dialects of assembler language (such as 779490075Sobriendifferent opcodes), define this macro as a C expression that gives the 779590075Sobriennumeric index of the assembler language dialect to use, with zero as the 779690075Sobrienfirst variant. 779790075Sobrien 779890075SobrienIf this macro is defined, you may use constructs of the form 779990075Sobrien@smallexample 780096263Sobrien@samp{@{option0|option1|option2@dots{}@}} 780190075Sobrien@end smallexample 780290075Sobrien@noindent 780390075Sobrienin the output templates of patterns (@pxref{Output Template}) or in the 780490075Sobrienfirst argument of @code{asm_fprintf}. This construct outputs 780590075Sobrien@samp{option0}, @samp{option1}, @samp{option2}, etc., if the value of 780690075Sobrien@code{ASSEMBLER_DIALECT} is zero, one, two, etc. Any special characters 780790075Sobrienwithin these strings retain their usual meaning. If there are fewer 780890075Sobrienalternatives within the braces than the value of 780990075Sobrien@code{ASSEMBLER_DIALECT}, the construct outputs nothing. 781090075Sobrien 781190075SobrienIf you do not define this macro, the characters @samp{@{}, @samp{|} and 781290075Sobrien@samp{@}} do not have any special meaning when used in templates or 781390075Sobrienoperands to @code{asm_fprintf}. 781490075Sobrien 781590075SobrienDefine the macros @code{REGISTER_PREFIX}, @code{LOCAL_LABEL_PREFIX}, 781690075Sobrien@code{USER_LABEL_PREFIX} and @code{IMMEDIATE_PREFIX} if you can express 781790075Sobrienthe variations in assembler language syntax with that mechanism. Define 781890075Sobrien@code{ASSEMBLER_DIALECT} and use the @samp{@{option0|option1@}} syntax 781990075Sobrienif the syntax variant are larger and involve such things as different 782090075Sobrienopcodes or operand order. 7821132718Skan@end defmac 782290075Sobrien 7823132718Skan@defmac ASM_OUTPUT_REG_PUSH (@var{stream}, @var{regno}) 782490075SobrienA C expression to output to @var{stream} some assembler code 782590075Sobrienwhich will push hard register number @var{regno} onto the stack. 782690075SobrienThe code need not be optimal, since this macro is used only when 782790075Sobrienprofiling. 7828132718Skan@end defmac 782990075Sobrien 7830132718Skan@defmac ASM_OUTPUT_REG_POP (@var{stream}, @var{regno}) 783190075SobrienA C expression to output to @var{stream} some assembler code 783290075Sobrienwhich will pop hard register number @var{regno} off of the stack. 783390075SobrienThe code need not be optimal, since this macro is used only when 783490075Sobrienprofiling. 7835132718Skan@end defmac 783690075Sobrien 783790075Sobrien@node Dispatch Tables 783890075Sobrien@subsection Output of Dispatch Tables 783990075Sobrien 784090075Sobrien@c prevent bad page break with this line 784190075SobrienThis concerns dispatch tables. 784290075Sobrien 784390075Sobrien@cindex dispatch table 7844132718Skan@defmac ASM_OUTPUT_ADDR_DIFF_ELT (@var{stream}, @var{body}, @var{value}, @var{rel}) 784590075SobrienA C statement to output to the stdio stream @var{stream} an assembler 784690075Sobrienpseudo-instruction to generate a difference between two labels. 784790075Sobrien@var{value} and @var{rel} are the numbers of two internal labels. The 784890075Sobriendefinitions of these labels are output using 7849132718Skan@code{(*targetm.asm_out.internal_label)}, and they must be printed in the same 785090075Sobrienway here. For example, 785190075Sobrien 7852132718Skan@smallexample 785390075Sobrienfprintf (@var{stream}, "\t.word L%d-L%d\n", 785490075Sobrien @var{value}, @var{rel}) 7855132718Skan@end smallexample 785690075Sobrien 785790075SobrienYou must provide this macro on machines where the addresses in a 785890075Sobriendispatch table are relative to the table's own address. If defined, GCC 785990075Sobrienwill also use this macro on all machines when producing PIC@. 786090075Sobrien@var{body} is the body of the @code{ADDR_DIFF_VEC}; it is provided so that the 786190075Sobrienmode and flags can be read. 7862132718Skan@end defmac 786390075Sobrien 7864132718Skan@defmac ASM_OUTPUT_ADDR_VEC_ELT (@var{stream}, @var{value}) 786590075SobrienThis macro should be provided on machines where the addresses 786690075Sobrienin a dispatch table are absolute. 786790075Sobrien 786890075SobrienThe definition should be a C statement to output to the stdio stream 786990075Sobrien@var{stream} an assembler pseudo-instruction to generate a reference to 787090075Sobriena label. @var{value} is the number of an internal label whose 7871132718Skandefinition is output using @code{(*targetm.asm_out.internal_label)}. 787290075SobrienFor example, 787390075Sobrien 7874132718Skan@smallexample 787590075Sobrienfprintf (@var{stream}, "\t.word L%d\n", @var{value}) 7876132718Skan@end smallexample 7877132718Skan@end defmac 787890075Sobrien 7879132718Skan@defmac ASM_OUTPUT_CASE_LABEL (@var{stream}, @var{prefix}, @var{num}, @var{table}) 788090075SobrienDefine this if the label before a jump-table needs to be output 788190075Sobrienspecially. The first three arguments are the same as for 7882132718Skan@code{(*targetm.asm_out.internal_label)}; the fourth argument is the 788390075Sobrienjump-table which follows (a @code{jump_insn} containing an 788490075Sobrien@code{addr_vec} or @code{addr_diff_vec}). 788590075Sobrien 788690075SobrienThis feature is used on system V to output a @code{swbeg} statement 788790075Sobrienfor the table. 788890075Sobrien 788990075SobrienIf this macro is not defined, these labels are output with 7890132718Skan@code{(*targetm.asm_out.internal_label)}. 7891132718Skan@end defmac 789290075Sobrien 7893132718Skan@defmac ASM_OUTPUT_CASE_END (@var{stream}, @var{num}, @var{table}) 789490075SobrienDefine this if something special must be output at the end of a 789590075Sobrienjump-table. The definition should be a C statement to be executed 789690075Sobrienafter the assembler code for the table is written. It should write 789790075Sobrienthe appropriate code to stdio stream @var{stream}. The argument 789890075Sobrien@var{table} is the jump-table insn, and @var{num} is the label-number 789990075Sobrienof the preceding label. 790090075Sobrien 790190075SobrienIf this macro is not defined, nothing special is output at the end of 790290075Sobrienthe jump-table. 7903132718Skan@end defmac 790490075Sobrien 7905169689Skan@deftypefn {Target Hook} void TARGET_ASM_EMIT_UNWIND_LABEL (@var{stream}, @var{decl}, @var{for_eh}, @var{empty}) 7906169689SkanThis target hook emits a label at the beginning of each FDE@. It 7907169689Skanshould be defined on targets where FDEs need special labels, and it 7908169689Skanshould write the appropriate label, for the FDE associated with the 7909169689Skanfunction declaration @var{decl}, to the stdio stream @var{stream}. 7910169689SkanThe third argument, @var{for_eh}, is a boolean: true if this is for an 7911169689Skanexception table. The fourth argument, @var{empty}, is a boolean: 7912169689Skantrue if this is a placeholder label for an omitted FDE@. 7913169689Skan 7914169689SkanThe default is that FDEs are not given nonlocal labels. 7915169689Skan@end deftypefn 7916169689Skan 7917169689Skan@deftypefn {Target Hook} void TARGET_ASM_EMIT_EXCEPT_TABLE_LABEL (@var{stream}) 7918169689SkanThis target hook emits a label at the beginning of the exception table. 7919169689SkanIt should be defined on targets where it is desirable for the table 7920169689Skanto be broken up according to function. 7921169689Skan 7922169689SkanThe default is that no label is emitted. 7923169689Skan@end deftypefn 7924169689Skan 7925169689Skan@deftypefn {Target Hook} void TARGET_UNWIND_EMIT (FILE * @var{stream}, rtx @var{insn}) 7926169689SkanThis target hook emits and assembly directives required to unwind the 7927169689Skangiven instruction. This is only used when TARGET_UNWIND_INFO is set. 7928169689Skan@end deftypefn 7929169689Skan 793090075Sobrien@node Exception Region Output 793190075Sobrien@subsection Assembler Commands for Exception Regions 793290075Sobrien 793390075Sobrien@c prevent bad page break with this line 793490075Sobrien 793590075SobrienThis describes commands marking the start and the end of an exception 793690075Sobrienregion. 793790075Sobrien 7938132718Skan@defmac EH_FRAME_SECTION_NAME 793990075SobrienIf defined, a C string constant for the name of the section containing 794090075Sobrienexception handling frame unwind information. If not defined, GCC will 794190075Sobrienprovide a default definition if the target supports named sections. 794290075Sobrien@file{crtstuff.c} uses this macro to switch to the appropriate section. 794390075Sobrien 794490075SobrienYou should define this symbol if your target supports DWARF 2 frame 794590075Sobrienunwind information and the default definition does not work. 7946132718Skan@end defmac 794790075Sobrien 7948132718Skan@defmac EH_FRAME_IN_DATA_SECTION 794990075SobrienIf defined, DWARF 2 frame unwind information will be placed in the 795090075Sobriendata section even though the target supports named sections. This 795190075Sobrienmight be necessary, for instance, if the system linker does garbage 795290075Sobriencollection and sections cannot be marked as not to be collected. 795390075Sobrien 795490075SobrienDo not define this macro unless @code{TARGET_ASM_NAMED_SECTION} is 795590075Sobrienalso defined. 7956132718Skan@end defmac 795790075Sobrien 7958169689Skan@defmac EH_TABLES_CAN_BE_READ_ONLY 7959169689SkanDefine this macro to 1 if your target is such that no frame unwind 7960169689Skaninformation encoding used with non-PIC code will ever require a 7961169689Skanruntime relocation, but the linker may not support merging read-only 7962169689Skanand read-write sections into a single read-write section. 7963169689Skan@end defmac 7964169689Skan 7965132718Skan@defmac MASK_RETURN_ADDR 796690075SobrienAn rtx used to mask the return address found via @code{RETURN_ADDR_RTX}, so 796790075Sobrienthat it does not contain any extraneous set bits in it. 7968132718Skan@end defmac 796990075Sobrien 7970132718Skan@defmac DWARF2_UNWIND_INFO 797190075SobrienDefine this macro to 0 if your target supports DWARF 2 frame unwind 797290075Sobrieninformation, but it does not yet work with exception handling. 797390075SobrienOtherwise, if your target supports this information (if it defines 797490075Sobrien@samp{INCOMING_RETURN_ADDR_RTX} and either @samp{UNALIGNED_INT_ASM_OP} 7975169689Skanor @samp{OBJECT_FORMAT_ELF}), GCC will provide a default definition of 1. 797690075Sobrien 7977169689SkanIf @code{TARGET_UNWIND_INFO} is defined, the target specific unwinder 7978169689Skanwill be used in all cases. Defining this macro will enable the generation 7979169689Skanof DWARF 2 frame debugging information. 7980169689Skan 7981169689SkanIf @code{TARGET_UNWIND_INFO} is not defined, and this macro is defined to 1, 7982169689Skanthe DWARF 2 unwinder will be the default exception handling mechanism; 7983169689Skanotherwise, the @code{setjmp}/@code{longjmp}-based scheme will be used by 798490075Sobriendefault. 7985169689Skan@end defmac 798690075Sobrien 7987169689Skan@defmac TARGET_UNWIND_INFO 7988169689SkanDefine this macro if your target has ABI specified unwind tables. Usually 7989169689Skanthese will be output by @code{TARGET_UNWIND_EMIT}. 7990132718Skan@end defmac 799190075Sobrien 7992169689Skan@deftypevar {Target Hook} bool TARGET_UNWIND_TABLES_DEFAULT 7993169689SkanThis variable should be set to @code{true} if the target ABI requires unwinding 7994169689Skantables even when exceptions are not used. 7995169689Skan@end deftypevar 7996169689Skan 7997132718Skan@defmac MUST_USE_SJLJ_EXCEPTIONS 7998132718SkanThis macro need only be defined if @code{DWARF2_UNWIND_INFO} is 7999132718Skanruntime-variable. In that case, @file{except.h} cannot correctly 8000169689Skandetermine the corresponding definition of @code{MUST_USE_SJLJ_EXCEPTIONS}, 8001169689Skanso the target must provide it directly. 8002132718Skan@end defmac 8003132718Skan 8004169689Skan@defmac DONT_USE_BUILTIN_SETJMP 8005169689SkanDefine this macro to 1 if the @code{setjmp}/@code{longjmp}-based scheme 8006169689Skanshould use the @code{setjmp}/@code{longjmp} functions from the C library 8007169689Skaninstead of the @code{__builtin_setjmp}/@code{__builtin_longjmp} machinery. 8008169689Skan@end defmac 8009169689Skan 8010132718Skan@defmac DWARF_CIE_DATA_ALIGNMENT 801190075SobrienThis macro need only be defined if the target might save registers in the 801290075Sobrienfunction prologue at an offset to the stack pointer that is not aligned to 801390075Sobrien@code{UNITS_PER_WORD}. The definition should be the negative minimum 801490075Sobrienalignment if @code{STACK_GROWS_DOWNWARD} is defined, and the positive 801590075Sobrienminimum alignment otherwise. @xref{SDB and DWARF}. Only applicable if 801690075Sobrienthe target supports DWARF 2 frame unwind information. 8017132718Skan@end defmac 801890075Sobrien 8019117395Skan@deftypevar {Target Hook} bool TARGET_TERMINATE_DW2_EH_FRAME_INFO 8020117395SkanContains the value true if the target should add a zero word onto the 8021117395Skanend of a Dwarf-2 frame info section when used for exception handling. 8022117395SkanDefault value is false if @code{EH_FRAME_SECTION_NAME} is defined, and 8023117395Skantrue otherwise. 8024117395Skan@end deftypevar 8025117395Skan 8026132718Skan@deftypefn {Target Hook} rtx TARGET_DWARF_REGISTER_SPAN (rtx @var{reg}) 8027132718SkanGiven a register, this hook should return a parallel of registers to 8028132718Skanrepresent where to find the register pieces. Define this hook if the 8029132718Skanregister and its mode are represented in Dwarf in non-contiguous 8030132718Skanlocations, or if the register should be represented in more than one 8031132718Skanregister in Dwarf. Otherwise, this hook should return @code{NULL_RTX}. 8032132718SkanIf not defined, the default is to return @code{NULL_RTX}. 8033132718Skan@end deftypefn 8034132718Skan 8035169689Skan@deftypefn {Target Hook} bool TARGET_ASM_TTYPE (rtx @var{sym}) 8036169689SkanThis hook is used to output a reference from a frame unwinding table to 8037169689Skanthe type_info object identified by @var{sym}. It should return @code{true} 8038169689Skanif the reference was output. Returning @code{false} will cause the 8039169689Skanreference to be output using the normal Dwarf2 routines. 8040169689Skan@end deftypefn 8041169689Skan 8042169689Skan@deftypefn {Target Hook} bool TARGET_ARM_EABI_UNWINDER 8043169689SkanThis hook should be set to @code{true} on targets that use an ARM EABI 8044169689Skanbased unwinding library, and @code{false} on other targets. This effects 8045169689Skanthe format of unwinding tables, and how the unwinder in entered after 8046169689Skanrunning a cleanup. The default is @code{false}. 8047169689Skan@end deftypefn 8048169689Skan 804990075Sobrien@node Alignment Output 805090075Sobrien@subsection Assembler Commands for Alignment 805190075Sobrien 805290075Sobrien@c prevent bad page break with this line 805390075SobrienThis describes commands for alignment. 805490075Sobrien 8055132718Skan@defmac JUMP_ALIGN (@var{label}) 805690075SobrienThe alignment (log base 2) to put in front of @var{label}, which is 805790075Sobriena common destination of jumps and has no fallthru incoming edge. 805890075Sobrien 805990075SobrienThis macro need not be defined if you don't want any special alignment 806090075Sobriento be done at such a time. Most machine descriptions do not currently 806190075Sobriendefine the macro. 806290075Sobrien 806390075SobrienUnless it's necessary to inspect the @var{label} parameter, it is better 806490075Sobriento set the variable @var{align_jumps} in the target's 806590075Sobrien@code{OVERRIDE_OPTIONS}. Otherwise, you should try to honor the user's 806690075Sobrienselection in @var{align_jumps} in a @code{JUMP_ALIGN} implementation. 8067132718Skan@end defmac 806890075Sobrien 8069132718Skan@defmac LABEL_ALIGN_AFTER_BARRIER (@var{label}) 807090075SobrienThe alignment (log base 2) to put in front of @var{label}, which follows 807190075Sobriena @code{BARRIER}. 807290075Sobrien 807390075SobrienThis macro need not be defined if you don't want any special alignment 807490075Sobriento be done at such a time. Most machine descriptions do not currently 807590075Sobriendefine the macro. 8076132718Skan@end defmac 807790075Sobrien 8078132718Skan@defmac LABEL_ALIGN_AFTER_BARRIER_MAX_SKIP 807990075SobrienThe maximum number of bytes to skip when applying 808090075Sobrien@code{LABEL_ALIGN_AFTER_BARRIER}. This works only if 808190075Sobrien@code{ASM_OUTPUT_MAX_SKIP_ALIGN} is defined. 8082132718Skan@end defmac 808390075Sobrien 8084132718Skan@defmac LOOP_ALIGN (@var{label}) 808590075SobrienThe alignment (log base 2) to put in front of @var{label}, which follows 808690075Sobriena @code{NOTE_INSN_LOOP_BEG} note. 808790075Sobrien 808890075SobrienThis macro need not be defined if you don't want any special alignment 808990075Sobriento be done at such a time. Most machine descriptions do not currently 809090075Sobriendefine the macro. 809190075Sobrien 809290075SobrienUnless it's necessary to inspect the @var{label} parameter, it is better 809390075Sobriento set the variable @code{align_loops} in the target's 809490075Sobrien@code{OVERRIDE_OPTIONS}. Otherwise, you should try to honor the user's 809590075Sobrienselection in @code{align_loops} in a @code{LOOP_ALIGN} implementation. 8096132718Skan@end defmac 809790075Sobrien 8098132718Skan@defmac LOOP_ALIGN_MAX_SKIP 809990075SobrienThe maximum number of bytes to skip when applying @code{LOOP_ALIGN}. 810090075SobrienThis works only if @code{ASM_OUTPUT_MAX_SKIP_ALIGN} is defined. 8101132718Skan@end defmac 810290075Sobrien 8103132718Skan@defmac LABEL_ALIGN (@var{label}) 810490075SobrienThe alignment (log base 2) to put in front of @var{label}. 810590075SobrienIf @code{LABEL_ALIGN_AFTER_BARRIER} / @code{LOOP_ALIGN} specify a different alignment, 810690075Sobrienthe maximum of the specified values is used. 810790075Sobrien 810890075SobrienUnless it's necessary to inspect the @var{label} parameter, it is better 810990075Sobriento set the variable @code{align_labels} in the target's 811090075Sobrien@code{OVERRIDE_OPTIONS}. Otherwise, you should try to honor the user's 811190075Sobrienselection in @code{align_labels} in a @code{LABEL_ALIGN} implementation. 8112132718Skan@end defmac 811390075Sobrien 8114132718Skan@defmac LABEL_ALIGN_MAX_SKIP 811590075SobrienThe maximum number of bytes to skip when applying @code{LABEL_ALIGN}. 811690075SobrienThis works only if @code{ASM_OUTPUT_MAX_SKIP_ALIGN} is defined. 8117132718Skan@end defmac 811890075Sobrien 8119132718Skan@defmac ASM_OUTPUT_SKIP (@var{stream}, @var{nbytes}) 812090075SobrienA C statement to output to the stdio stream @var{stream} an assembler 812190075Sobrieninstruction to advance the location counter by @var{nbytes} bytes. 812290075SobrienThose bytes should be zero when loaded. @var{nbytes} will be a C 812390075Sobrienexpression of type @code{int}. 8124132718Skan@end defmac 812590075Sobrien 8126132718Skan@defmac ASM_NO_SKIP_IN_TEXT 812790075SobrienDefine this macro if @code{ASM_OUTPUT_SKIP} should not be used in the 812890075Sobrientext section because it fails to put zeros in the bytes that are skipped. 812990075SobrienThis is true on many Unix systems, where the pseudo--op to skip bytes 813090075Sobrienproduces no-op instructions rather than zeros when used in the text 813190075Sobriensection. 8132132718Skan@end defmac 813390075Sobrien 8134132718Skan@defmac ASM_OUTPUT_ALIGN (@var{stream}, @var{power}) 813590075SobrienA C statement to output to the stdio stream @var{stream} an assembler 813690075Sobriencommand to advance the location counter to a multiple of 2 to the 813790075Sobrien@var{power} bytes. @var{power} will be a C expression of type @code{int}. 8138132718Skan@end defmac 813990075Sobrien 8140132718Skan@defmac ASM_OUTPUT_ALIGN_WITH_NOP (@var{stream}, @var{power}) 8141117395SkanLike @code{ASM_OUTPUT_ALIGN}, except that the ``nop'' instruction is used 8142117395Skanfor padding, if necessary. 8143132718Skan@end defmac 8144117395Skan 8145132718Skan@defmac ASM_OUTPUT_MAX_SKIP_ALIGN (@var{stream}, @var{power}, @var{max_skip}) 814690075SobrienA C statement to output to the stdio stream @var{stream} an assembler 814790075Sobriencommand to advance the location counter to a multiple of 2 to the 814890075Sobrien@var{power} bytes, but only if @var{max_skip} or fewer bytes are needed to 814990075Sobriensatisfy the alignment request. @var{power} and @var{max_skip} will be 815090075Sobriena C expression of type @code{int}. 8151132718Skan@end defmac 815290075Sobrien 815390075Sobrien@need 3000 815490075Sobrien@node Debugging Info 815590075Sobrien@section Controlling Debugging Information Format 815690075Sobrien 815790075Sobrien@c prevent bad page break with this line 815890075SobrienThis describes how to specify debugging information. 815990075Sobrien 816090075Sobrien@menu 816190075Sobrien* All Debuggers:: Macros that affect all debugging formats uniformly. 816290075Sobrien* DBX Options:: Macros enabling specific options in DBX format. 816390075Sobrien* DBX Hooks:: Hook macros for varying DBX format. 816490075Sobrien* File Names and DBX:: Macros controlling output of file names in DBX format. 816590075Sobrien* SDB and DWARF:: Macros for SDB (COFF) and DWARF formats. 816690075Sobrien* VMS Debug:: Macros for VMS debug format. 816790075Sobrien@end menu 816890075Sobrien 816990075Sobrien@node All Debuggers 817090075Sobrien@subsection Macros Affecting All Debugging Formats 817190075Sobrien 817290075Sobrien@c prevent bad page break with this line 817390075SobrienThese macros affect all debugging formats. 817490075Sobrien 8175132718Skan@defmac DBX_REGISTER_NUMBER (@var{regno}) 817690075SobrienA C expression that returns the DBX register number for the compiler 817790075Sobrienregister number @var{regno}. In the default macro provided, the value 817890075Sobrienof this expression will be @var{regno} itself. But sometimes there are 817990075Sobriensome registers that the compiler knows about and DBX does not, or vice 818090075Sobrienversa. In such cases, some register may need to have one number in the 818190075Sobriencompiler and another for DBX@. 818290075Sobrien 818390075SobrienIf two registers have consecutive numbers inside GCC, and they can be 818490075Sobrienused as a pair to hold a multiword value, then they @emph{must} have 818590075Sobrienconsecutive numbers after renumbering with @code{DBX_REGISTER_NUMBER}. 818690075SobrienOtherwise, debuggers will be unable to access such a pair, because they 818790075Sobrienexpect register pairs to be consecutive in their own numbering scheme. 818890075Sobrien 818990075SobrienIf you find yourself defining @code{DBX_REGISTER_NUMBER} in way that 819090075Sobriendoes not preserve register pairs, then what you must do instead is 819190075Sobrienredefine the actual register numbering scheme. 8192132718Skan@end defmac 819390075Sobrien 8194132718Skan@defmac DEBUGGER_AUTO_OFFSET (@var{x}) 819590075SobrienA C expression that returns the integer offset value for an automatic 819690075Sobrienvariable having address @var{x} (an RTL expression). The default 819790075Sobriencomputation assumes that @var{x} is based on the frame-pointer and 819890075Sobriengives the offset from the frame-pointer. This is required for targets 819990075Sobrienthat produce debugging output for DBX or COFF-style debugging output 820090075Sobrienfor SDB and allow the frame-pointer to be eliminated when the 820190075Sobrien@option{-g} options is used. 8202132718Skan@end defmac 820390075Sobrien 8204132718Skan@defmac DEBUGGER_ARG_OFFSET (@var{offset}, @var{x}) 820590075SobrienA C expression that returns the integer offset value for an argument 820690075Sobrienhaving address @var{x} (an RTL expression). The nominal offset is 820790075Sobrien@var{offset}. 8208132718Skan@end defmac 820990075Sobrien 8210132718Skan@defmac PREFERRED_DEBUGGING_TYPE 821190075SobrienA C expression that returns the type of debugging output GCC should 821290075Sobrienproduce when the user specifies just @option{-g}. Define 821390075Sobrienthis if you have arranged for GCC to support more than one format of 821490075Sobriendebugging output. Currently, the allowable values are @code{DBX_DEBUG}, 821590075Sobrien@code{SDB_DEBUG}, @code{DWARF_DEBUG}, @code{DWARF2_DEBUG}, 821690075Sobrien@code{XCOFF_DEBUG}, @code{VMS_DEBUG}, and @code{VMS_AND_DWARF2_DEBUG}. 821790075Sobrien 821890075SobrienWhen the user specifies @option{-ggdb}, GCC normally also uses the 821990075Sobrienvalue of this macro to select the debugging output format, but with two 8220132718Skanexceptions. If @code{DWARF2_DEBUGGING_INFO} is defined, GCC uses the 822190075Sobrienvalue @code{DWARF2_DEBUG}. Otherwise, if @code{DBX_DEBUGGING_INFO} is 822290075Sobriendefined, GCC uses @code{DBX_DEBUG}. 822390075Sobrien 822490075SobrienThe value of this macro only affects the default debugging output; the 822590075Sobrienuser can always get a specific type of output by using @option{-gstabs}, 8226132718Skan@option{-gcoff}, @option{-gdwarf-2}, @option{-gxcoff}, or @option{-gvms}. 8227132718Skan@end defmac 822890075Sobrien 822990075Sobrien@node DBX Options 823090075Sobrien@subsection Specific Options for DBX Output 823190075Sobrien 823290075Sobrien@c prevent bad page break with this line 823390075SobrienThese are specific options for DBX output. 823490075Sobrien 8235132718Skan@defmac DBX_DEBUGGING_INFO 823690075SobrienDefine this macro if GCC should produce debugging output for DBX 823790075Sobrienin response to the @option{-g} option. 8238132718Skan@end defmac 823990075Sobrien 8240132718Skan@defmac XCOFF_DEBUGGING_INFO 824190075SobrienDefine this macro if GCC should produce XCOFF format debugging output 824290075Sobrienin response to the @option{-g} option. This is a variant of DBX format. 8243132718Skan@end defmac 824490075Sobrien 8245132718Skan@defmac DEFAULT_GDB_EXTENSIONS 824690075SobrienDefine this macro to control whether GCC should by default generate 824790075SobrienGDB's extended version of DBX debugging information (assuming DBX-format 824890075Sobriendebugging information is enabled at all). If you don't define the 824990075Sobrienmacro, the default is 1: always generate the extended information 825090075Sobrienif there is any occasion to. 8251132718Skan@end defmac 825290075Sobrien 8253132718Skan@defmac DEBUG_SYMS_TEXT 825490075SobrienDefine this macro if all @code{.stabs} commands should be output while 825590075Sobrienin the text section. 8256132718Skan@end defmac 825790075Sobrien 8258132718Skan@defmac ASM_STABS_OP 825990075SobrienA C string constant, including spacing, naming the assembler pseudo op to 826090075Sobrienuse instead of @code{"\t.stabs\t"} to define an ordinary debugging symbol. 826190075SobrienIf you don't define this macro, @code{"\t.stabs\t"} is used. This macro 826290075Sobrienapplies only to DBX debugging information format. 8263132718Skan@end defmac 826490075Sobrien 8265132718Skan@defmac ASM_STABD_OP 826690075SobrienA C string constant, including spacing, naming the assembler pseudo op to 826790075Sobrienuse instead of @code{"\t.stabd\t"} to define a debugging symbol whose 826890075Sobrienvalue is the current location. If you don't define this macro, 826990075Sobrien@code{"\t.stabd\t"} is used. This macro applies only to DBX debugging 827090075Sobrieninformation format. 8271132718Skan@end defmac 827290075Sobrien 8273132718Skan@defmac ASM_STABN_OP 827490075SobrienA C string constant, including spacing, naming the assembler pseudo op to 827590075Sobrienuse instead of @code{"\t.stabn\t"} to define a debugging symbol with no 827690075Sobrienname. If you don't define this macro, @code{"\t.stabn\t"} is used. This 827790075Sobrienmacro applies only to DBX debugging information format. 8278132718Skan@end defmac 827990075Sobrien 8280132718Skan@defmac DBX_NO_XREFS 828190075SobrienDefine this macro if DBX on your system does not support the construct 828290075Sobrien@samp{xs@var{tagname}}. On some systems, this construct is used to 828390075Sobriendescribe a forward reference to a structure named @var{tagname}. 828490075SobrienOn other systems, this construct is not supported at all. 8285132718Skan@end defmac 828690075Sobrien 8287132718Skan@defmac DBX_CONTIN_LENGTH 828890075SobrienA symbol name in DBX-format debugging information is normally 828990075Sobriencontinued (split into two separate @code{.stabs} directives) when it 829090075Sobrienexceeds a certain length (by default, 80 characters). On some 829190075Sobrienoperating systems, DBX requires this splitting; on others, splitting 829290075Sobrienmust not be done. You can inhibit splitting by defining this macro 829390075Sobrienwith the value zero. You can override the default splitting-length by 829490075Sobriendefining this macro as an expression for the length you desire. 8295132718Skan@end defmac 829690075Sobrien 8297132718Skan@defmac DBX_CONTIN_CHAR 829890075SobrienNormally continuation is indicated by adding a @samp{\} character to 829990075Sobrienthe end of a @code{.stabs} string when a continuation follows. To use 830090075Sobriena different character instead, define this macro as a character 830190075Sobrienconstant for the character you want to use. Do not define this macro 830290075Sobrienif backslash is correct for your system. 8303132718Skan@end defmac 830490075Sobrien 8305132718Skan@defmac DBX_STATIC_STAB_DATA_SECTION 830690075SobrienDefine this macro if it is necessary to go to the data section before 830790075Sobrienoutputting the @samp{.stabs} pseudo-op for a non-global static 830890075Sobrienvariable. 8309132718Skan@end defmac 831090075Sobrien 8311132718Skan@defmac DBX_TYPE_DECL_STABS_CODE 831290075SobrienThe value to use in the ``code'' field of the @code{.stabs} directive 831390075Sobrienfor a typedef. The default is @code{N_LSYM}. 8314132718Skan@end defmac 831590075Sobrien 8316132718Skan@defmac DBX_STATIC_CONST_VAR_CODE 831790075SobrienThe value to use in the ``code'' field of the @code{.stabs} directive 831890075Sobrienfor a static variable located in the text section. DBX format does not 831990075Sobrienprovide any ``right'' way to do this. The default is @code{N_FUN}. 8320132718Skan@end defmac 832190075Sobrien 8322132718Skan@defmac DBX_REGPARM_STABS_CODE 832390075SobrienThe value to use in the ``code'' field of the @code{.stabs} directive 832490075Sobrienfor a parameter passed in registers. DBX format does not provide any 832590075Sobrien``right'' way to do this. The default is @code{N_RSYM}. 8326132718Skan@end defmac 832790075Sobrien 8328132718Skan@defmac DBX_REGPARM_STABS_LETTER 832990075SobrienThe letter to use in DBX symbol data to identify a symbol as a parameter 833090075Sobrienpassed in registers. DBX format does not customarily provide any way to 833190075Sobriendo this. The default is @code{'P'}. 8332132718Skan@end defmac 833390075Sobrien 8334132718Skan@defmac DBX_FUNCTION_FIRST 833590075SobrienDefine this macro if the DBX information for a function and its 833690075Sobrienarguments should precede the assembler code for the function. Normally, 833790075Sobrienin DBX format, the debugging information entirely follows the assembler 833890075Sobriencode. 8339132718Skan@end defmac 834090075Sobrien 8341132718Skan@defmac DBX_BLOCKS_FUNCTION_RELATIVE 8342169689SkanDefine this macro, with value 1, if the value of a symbol describing 8343169689Skanthe scope of a block (@code{N_LBRAC} or @code{N_RBRAC}) should be 8344169689Skanrelative to the start of the enclosing function. Normally, GCC uses 8345169689Skanan absolute address. 8346132718Skan@end defmac 834790075Sobrien 8348169689Skan@defmac DBX_LINES_FUNCTION_RELATIVE 8349169689SkanDefine this macro, with value 1, if the value of a symbol indicating 8350169689Skanthe current line number (@code{N_SLINE}) should be relative to the 8351169689Skanstart of the enclosing function. Normally, GCC uses an absolute address. 8352169689Skan@end defmac 8353169689Skan 8354132718Skan@defmac DBX_USE_BINCL 835590075SobrienDefine this macro if GCC should generate @code{N_BINCL} and 835690075Sobrien@code{N_EINCL} stabs for included header files, as on Sun systems. This 835790075Sobrienmacro also directs GCC to output a type number as a pair of a file 835890075Sobriennumber and a type number within the file. Normally, GCC does not 835990075Sobriengenerate @code{N_BINCL} or @code{N_EINCL} stabs, and it outputs a single 836090075Sobriennumber for a type number. 8361132718Skan@end defmac 836290075Sobrien 836390075Sobrien@node DBX Hooks 836490075Sobrien@subsection Open-Ended Hooks for DBX Format 836590075Sobrien 836690075Sobrien@c prevent bad page break with this line 836790075SobrienThese are hooks for DBX format. 836890075Sobrien 8369132718Skan@defmac DBX_OUTPUT_LBRAC (@var{stream}, @var{name}) 837090075SobrienDefine this macro to say how to output to @var{stream} the debugging 837190075Sobrieninformation for the start of a scope level for variable names. The 837290075Sobrienargument @var{name} is the name of an assembler symbol (for use with 837390075Sobrien@code{assemble_name}) whose value is the address where the scope begins. 8374132718Skan@end defmac 837590075Sobrien 8376132718Skan@defmac DBX_OUTPUT_RBRAC (@var{stream}, @var{name}) 837790075SobrienLike @code{DBX_OUTPUT_LBRAC}, but for the end of a scope level. 8378132718Skan@end defmac 837990075Sobrien 8380132718Skan@defmac DBX_OUTPUT_NFUN (@var{stream}, @var{lscope_label}, @var{decl}) 8381103445SkanDefine this macro if the target machine requires special handling to 8382103445Skanoutput an @code{N_FUN} entry for the function @var{decl}. 8383132718Skan@end defmac 8384103445Skan 8385169689Skan@defmac DBX_OUTPUT_SOURCE_LINE (@var{stream}, @var{line}, @var{counter}) 8386169689SkanA C statement to output DBX debugging information before code for line 8387169689Skannumber @var{line} of the current source file to the stdio stream 8388169689Skan@var{stream}. @var{counter} is the number of time the macro was 8389169689Skaninvoked, including the current invocation; it is intended to generate 8390169689Skanunique labels in the assembly output. 839190075Sobrien 8392169689SkanThis macro should not be defined if the default output is correct, or 8393169689Skanif it can be made correct by defining @code{DBX_LINES_FUNCTION_RELATIVE}. 8394132718Skan@end defmac 839590075Sobrien 8396132718Skan@defmac NO_DBX_FUNCTION_END 839790075SobrienSome stabs encapsulation formats (in particular ECOFF), cannot handle the 839890075Sobrien@code{.stabs "",N_FUN,,0,0,Lscope-function-1} gdb dbx extension construct. 839990075SobrienOn those machines, define this macro to turn this feature off without 840090075Sobriendisturbing the rest of the gdb extensions. 8401132718Skan@end defmac 840290075Sobrien 8403169689Skan@defmac NO_DBX_BNSYM_ENSYM 8404169689SkanSome assemblers cannot handle the @code{.stabd BNSYM/ENSYM,0,0} gdb dbx 8405169689Skanextension construct. On those machines, define this macro to turn this 8406169689Skanfeature off without disturbing the rest of the gdb extensions. 8407169689Skan@end defmac 8408169689Skan 840990075Sobrien@node File Names and DBX 841090075Sobrien@subsection File Names in DBX Format 841190075Sobrien 841290075Sobrien@c prevent bad page break with this line 841390075SobrienThis describes file names in DBX format. 841490075Sobrien 8415132718Skan@defmac DBX_OUTPUT_MAIN_SOURCE_FILENAME (@var{stream}, @var{name}) 841690075SobrienA C statement to output DBX debugging information to the stdio stream 8417169689Skan@var{stream}, which indicates that file @var{name} is the main source 841890075Sobrienfile---the file specified as the input file for compilation. 841990075SobrienThis macro is called only once, at the beginning of compilation. 842090075Sobrien 842190075SobrienThis macro need not be defined if the standard form of output 842290075Sobrienfor DBX debugging information is appropriate. 8423169689Skan 8424169689SkanIt may be necessary to refer to a label equal to the beginning of the 8425169689Skantext section. You can use @samp{assemble_name (stream, ltext_label_name)} 8426169689Skanto do so. If you do this, you must also set the variable 8427169689Skan@var{used_ltext_label_name} to @code{true}. 8428132718Skan@end defmac 842990075Sobrien 8430169689Skan@defmac NO_DBX_MAIN_SOURCE_DIRECTORY 8431169689SkanDefine this macro, with value 1, if GCC should not emit an indication 8432169689Skanof the current directory for compilation and current source language at 8433169689Skanthe beginning of the file. 8434169689Skan@end defmac 843590075Sobrien 8436169689Skan@defmac NO_DBX_GCC_MARKER 8437169689SkanDefine this macro, with value 1, if GCC should not emit an indication 8438169689Skanthat this object file was compiled by GCC@. The default is to emit 8439169689Skanan @code{N_OPT} stab at the beginning of every source file, with 8440169689Skan@samp{gcc2_compiled.} for the string and value 0. 8441132718Skan@end defmac 844290075Sobrien 8443132718Skan@defmac DBX_OUTPUT_MAIN_SOURCE_FILE_END (@var{stream}, @var{name}) 844490075SobrienA C statement to output DBX debugging information at the end of 8445169689Skancompilation of the main source file @var{name}. Output should be 8446169689Skanwritten to the stdio stream @var{stream}. 844790075Sobrien 844890075SobrienIf you don't define this macro, nothing special is output at the end 844990075Sobrienof compilation, which is correct for most machines. 8450132718Skan@end defmac 845190075Sobrien 8452169689Skan@defmac DBX_OUTPUT_NULL_N_SO_AT_MAIN_SOURCE_FILE_END 8453169689SkanDefine this macro @emph{instead of} defining 8454169689Skan@code{DBX_OUTPUT_MAIN_SOURCE_FILE_END}, if what needs to be output at 8455169689Skanthe end of compilation is a @code{N_SO} stab with an empty string, 8456169689Skanwhose value is the highest absolute text address in the file. 8457169689Skan@end defmac 8458169689Skan 845990075Sobrien@need 2000 846090075Sobrien@node SDB and DWARF 846190075Sobrien@subsection Macros for SDB and DWARF Output 846290075Sobrien 846390075Sobrien@c prevent bad page break with this line 846490075SobrienHere are macros for SDB and DWARF output. 846590075Sobrien 8466132718Skan@defmac SDB_DEBUGGING_INFO 846790075SobrienDefine this macro if GCC should produce COFF-style debugging output 846890075Sobrienfor SDB in response to the @option{-g} option. 8469132718Skan@end defmac 847090075Sobrien 8471132718Skan@defmac DWARF2_DEBUGGING_INFO 847290075SobrienDefine this macro if GCC should produce dwarf version 2 format 847390075Sobriendebugging output in response to the @option{-g} option. 847490075Sobrien 8475169689Skan@deftypefn {Target Hook} int TARGET_DWARF_CALLING_CONVENTION (tree @var{function}) 8476169689SkanDefine this to enable the dwarf attribute @code{DW_AT_calling_convention} to 8477169689Skanbe emitted for each function. Instead of an integer return the enum 8478169689Skanvalue for the @code{DW_CC_} tag. 8479169689Skan@end deftypefn 8480169689Skan 848190075SobrienTo support optional call frame debugging information, you must also 848290075Sobriendefine @code{INCOMING_RETURN_ADDR_RTX} and either set 848390075Sobrien@code{RTX_FRAME_RELATED_P} on the prologue insns if you use RTL for the 848490075Sobrienprologue, or call @code{dwarf2out_def_cfa} and @code{dwarf2out_reg_save} 848590075Sobrienas appropriate from @code{TARGET_ASM_FUNCTION_PROLOGUE} if you don't. 8486132718Skan@end defmac 848790075Sobrien 8488132718Skan@defmac DWARF2_FRAME_INFO 848990075SobrienDefine this macro to a nonzero value if GCC should always output 849090075SobrienDwarf 2 frame information. If @code{DWARF2_UNWIND_INFO} 849190075Sobrien(@pxref{Exception Region Output} is nonzero, GCC will output this 849290075Sobrieninformation not matter how you define @code{DWARF2_FRAME_INFO}. 8493132718Skan@end defmac 849490075Sobrien 8495132718Skan@defmac DWARF2_ASM_LINE_DEBUG_INFO 849690075SobrienDefine this macro to be a nonzero value if the assembler can generate Dwarf 2 849790075Sobrienline debug info sections. This will result in much more compact line number 849890075Sobrientables, and hence is desirable if it works. 8499132718Skan@end defmac 850090075Sobrien 8501132718Skan@defmac ASM_OUTPUT_DWARF_DELTA (@var{stream}, @var{size}, @var{label1}, @var{label2}) 8502117395SkanA C statement to issue assembly directives that create a difference 8503169689Skan@var{lab1} minus @var{lab2}, using an integer of the given @var{size}. 8504132718Skan@end defmac 8505117395Skan 8506169689Skan@defmac ASM_OUTPUT_DWARF_OFFSET (@var{stream}, @var{size}, @var{label}, @var{section}) 8507117395SkanA C statement to issue assembly directives that create a 8508169689Skansection-relative reference to the given @var{label}, using an integer of the 8509169689Skangiven @var{size}. The label is known to be defined in the given @var{section}. 8510132718Skan@end defmac 8511117395Skan 8512132718Skan@defmac ASM_OUTPUT_DWARF_PCREL (@var{stream}, @var{size}, @var{label}) 8513117395SkanA C statement to issue assembly directives that create a self-relative 8514169689Skanreference to the given @var{label}, using an integer of the given @var{size}. 8515132718Skan@end defmac 8516117395Skan 8517169689Skan@deftypefn {Target Hook} void TARGET_ASM_OUTPUT_DWARF_DTPREL (FILE *@var{FILE}, int @var{size}, rtx @var{x}) 8518169689SkanIf defined, this target hook is a function which outputs a DTP-relative 8519169689Skanreference to the given TLS symbol of the specified size. 8520169689Skan@end deftypefn 8521169689Skan 8522132718Skan@defmac PUT_SDB_@dots{} 852390075SobrienDefine these macros to override the assembler syntax for the special 852490075SobrienSDB assembler directives. See @file{sdbout.c} for a list of these 852590075Sobrienmacros and their arguments. If the standard syntax is used, you need 852690075Sobriennot define them yourself. 8527132718Skan@end defmac 852890075Sobrien 8529132718Skan@defmac SDB_DELIM 853090075SobrienSome assemblers do not support a semicolon as a delimiter, even between 853190075SobrienSDB assembler directives. In that case, define this macro to be the 853290075Sobriendelimiter to use (usually @samp{\n}). It is not necessary to define 853390075Sobriena new set of @code{PUT_SDB_@var{op}} macros if this is the only change 853490075Sobrienrequired. 8535132718Skan@end defmac 853690075Sobrien 8537132718Skan@defmac SDB_ALLOW_UNKNOWN_REFERENCES 853890075SobrienDefine this macro to allow references to unknown structure, 853990075Sobrienunion, or enumeration tags to be emitted. Standard COFF does not 854090075Sobrienallow handling of unknown references, MIPS ECOFF has support for 854190075Sobrienit. 8542132718Skan@end defmac 854390075Sobrien 8544132718Skan@defmac SDB_ALLOW_FORWARD_REFERENCES 854590075SobrienDefine this macro to allow references to structure, union, or 854690075Sobrienenumeration tags that have not yet been seen to be handled. Some 854790075Sobrienassemblers choke if forward tags are used, while some require it. 8548132718Skan@end defmac 854990075Sobrien 8550169689Skan@defmac SDB_OUTPUT_SOURCE_LINE (@var{stream}, @var{line}) 8551169689SkanA C statement to output SDB debugging information before code for line 8552169689Skannumber @var{line} of the current source file to the stdio stream 8553169689Skan@var{stream}. The default is to emit an @code{.ln} directive. 8554169689Skan@end defmac 8555169689Skan 855690075Sobrien@need 2000 855790075Sobrien@node VMS Debug 855890075Sobrien@subsection Macros for VMS Debug Format 855990075Sobrien 856090075Sobrien@c prevent bad page break with this line 856190075SobrienHere are macros for VMS debug format. 856290075Sobrien 8563132718Skan@defmac VMS_DEBUGGING_INFO 856490075SobrienDefine this macro if GCC should produce debugging output for VMS 856590075Sobrienin response to the @option{-g} option. The default behavior for VMS 856690075Sobrienis to generate minimal debug info for a traceback in the absence of 856790075Sobrien@option{-g} unless explicitly overridden with @option{-g0}. This 856890075Sobrienbehavior is controlled by @code{OPTIMIZATION_OPTIONS} and 856990075Sobrien@code{OVERRIDE_OPTIONS}. 8570132718Skan@end defmac 857190075Sobrien 8572117395Skan@node Floating Point 857390075Sobrien@section Cross Compilation and Floating Point 857490075Sobrien@cindex cross compilation and floating point 857590075Sobrien@cindex floating point and cross compilation 857690075Sobrien 8577117395SkanWhile all modern machines use twos-complement representation for integers, 857890075Sobrienthere are a variety of representations for floating point numbers. This 857990075Sobrienmeans that in a cross-compiler the representation of floating point numbers 858090075Sobrienin the compiled program may be different from that used in the machine 858190075Sobriendoing the compilation. 858290075Sobrien 858390075SobrienBecause different representation systems may offer different amounts of 8584117395Skanrange and precision, all floating point constants must be represented in 8585117395Skanthe target machine's format. Therefore, the cross compiler cannot 8586117395Skansafely use the host machine's floating point arithmetic; it must emulate 8587117395Skanthe target's arithmetic. To ensure consistency, GCC always uses 8588117395Skanemulation to work with floating point values, even when the host and 8589117395Skantarget floating point formats are identical. 859090075Sobrien 8591117395SkanThe following macros are provided by @file{real.h} for the compiler to 8592117395Skanuse. All parts of the compiler which generate or optimize 8593117395Skanfloating-point calculations must use these macros. They may evaluate 8594117395Skantheir operands more than once, so operands must not have side effects. 859590075Sobrien 8596117395Skan@defmac REAL_VALUE_TYPE 8597117395SkanThe C data type to be used to hold a floating point value in the target 8598117395Skanmachine's format. Typically this is a @code{struct} containing an 8599117395Skanarray of @code{HOST_WIDE_INT}, but all code should treat it as an opaque 8600117395Skanquantity. 8601117395Skan@end defmac 860290075Sobrien 8603117395Skan@deftypefn Macro int REAL_VALUES_EQUAL (REAL_VALUE_TYPE @var{x}, REAL_VALUE_TYPE @var{y}) 8604117395SkanCompares for equality the two values, @var{x} and @var{y}. If the target 8605117395Skanfloating point format supports negative zeroes and/or NaNs, 8606117395Skan@samp{REAL_VALUES_EQUAL (-0.0, 0.0)} is true, and 8607117395Skan@samp{REAL_VALUES_EQUAL (NaN, NaN)} is false. 8608117395Skan@end deftypefn 860990075Sobrien 8610117395Skan@deftypefn Macro int REAL_VALUES_LESS (REAL_VALUE_TYPE @var{x}, REAL_VALUE_TYPE @var{y}) 8611117395SkanTests whether @var{x} is less than @var{y}. 8612117395Skan@end deftypefn 861390075Sobrien 8614117395Skan@deftypefn Macro HOST_WIDE_INT REAL_VALUE_FIX (REAL_VALUE_TYPE @var{x}) 8615117395SkanTruncates @var{x} to a signed integer, rounding toward zero. 8616117395Skan@end deftypefn 861790075Sobrien 8618117395Skan@deftypefn Macro {unsigned HOST_WIDE_INT} REAL_VALUE_UNSIGNED_FIX (REAL_VALUE_TYPE @var{x}) 8619117395SkanTruncates @var{x} to an unsigned integer, rounding toward zero. If 8620117395Skan@var{x} is negative, returns zero. 8621117395Skan@end deftypefn 862290075Sobrien 8623117395Skan@deftypefn Macro REAL_VALUE_TYPE REAL_VALUE_ATOF (const char *@var{string}, enum machine_mode @var{mode}) 8624117395SkanConverts @var{string} into a floating point number in the target machine's 8625117395Skanrepresentation for mode @var{mode}. This routine can handle both 8626117395Skandecimal and hexadecimal floating point constants, using the syntax 8627117395Skandefined by the C language for both. 8628117395Skan@end deftypefn 862990075Sobrien 8630117395Skan@deftypefn Macro int REAL_VALUE_NEGATIVE (REAL_VALUE_TYPE @var{x}) 8631117395SkanReturns 1 if @var{x} is negative (including negative zero), 0 otherwise. 8632117395Skan@end deftypefn 863390075Sobrien 8634117395Skan@deftypefn Macro int REAL_VALUE_ISINF (REAL_VALUE_TYPE @var{x}) 8635117395SkanDetermines whether @var{x} represents infinity (positive or negative). 8636117395Skan@end deftypefn 863790075Sobrien 8638117395Skan@deftypefn Macro int REAL_VALUE_ISNAN (REAL_VALUE_TYPE @var{x}) 8639117395SkanDetermines whether @var{x} represents a ``NaN'' (not-a-number). 8640117395Skan@end deftypefn 864190075Sobrien 8642117395Skan@deftypefn Macro void REAL_ARITHMETIC (REAL_VALUE_TYPE @var{output}, enum tree_code @var{code}, REAL_VALUE_TYPE @var{x}, REAL_VALUE_TYPE @var{y}) 8643117395SkanCalculates an arithmetic operation on the two floating point values 8644117395Skan@var{x} and @var{y}, storing the result in @var{output} (which must be a 8645117395Skanvariable). 864690075Sobrien 8647117395SkanThe operation to be performed is specified by @var{code}. Only the 8648117395Skanfollowing codes are supported: @code{PLUS_EXPR}, @code{MINUS_EXPR}, 8649117395Skan@code{MULT_EXPR}, @code{RDIV_EXPR}, @code{MAX_EXPR}, @code{MIN_EXPR}. 865090075Sobrien 8651117395SkanIf @code{REAL_ARITHMETIC} is asked to evaluate division by zero and the 8652117395Skantarget's floating point format cannot represent infinity, it will call 8653117395Skan@code{abort}. Callers should check for this situation first, using 8654117395Skan@code{MODE_HAS_INFINITIES}. @xref{Storage Layout}. 8655117395Skan@end deftypefn 865690075Sobrien 8657117395Skan@deftypefn Macro REAL_VALUE_TYPE REAL_VALUE_NEGATE (REAL_VALUE_TYPE @var{x}) 8658117395SkanReturns the negative of the floating point value @var{x}. 8659117395Skan@end deftypefn 866090075Sobrien 8661117395Skan@deftypefn Macro REAL_VALUE_TYPE REAL_VALUE_ABS (REAL_VALUE_TYPE @var{x}) 8662117395SkanReturns the absolute value of @var{x}. 8663117395Skan@end deftypefn 866490075Sobrien 8665117395Skan@deftypefn Macro REAL_VALUE_TYPE REAL_VALUE_TRUNCATE (REAL_VALUE_TYPE @var{mode}, enum machine_mode @var{x}) 8666117395SkanTruncates the floating point value @var{x} to fit in @var{mode}. The 8667117395Skanreturn value is still a full-size @code{REAL_VALUE_TYPE}, but it has an 8668117395Skanappropriate bit pattern to be output asa floating constant whose 8669117395Skanprecision accords with mode @var{mode}. 8670117395Skan@end deftypefn 867190075Sobrien 8672117395Skan@deftypefn Macro void REAL_VALUE_TO_INT (HOST_WIDE_INT @var{low}, HOST_WIDE_INT @var{high}, REAL_VALUE_TYPE @var{x}) 8673117395SkanConverts a floating point value @var{x} into a double-precision integer 8674117395Skanwhich is then stored into @var{low} and @var{high}. If the value is not 8675117395Skanintegral, it is truncated. 8676117395Skan@end deftypefn 867790075Sobrien 8678117395Skan@deftypefn Macro void REAL_VALUE_FROM_INT (REAL_VALUE_TYPE @var{x}, HOST_WIDE_INT @var{low}, HOST_WIDE_INT @var{high}, enum machine_mode @var{mode}) 8679117395SkanConverts a double-precision integer found in @var{low} and @var{high}, 8680117395Skaninto a floating point value which is then stored into @var{x}. The 8681117395Skanvalue is truncated to fit in mode @var{mode}. 8682117395Skan@end deftypefn 868390075Sobrien 868490075Sobrien@node Mode Switching 868590075Sobrien@section Mode Switching Instructions 868690075Sobrien@cindex mode switching 868790075SobrienThe following macros control mode switching optimizations: 868890075Sobrien 8689132718Skan@defmac OPTIMIZE_MODE_SWITCHING (@var{entity}) 869090075SobrienDefine this macro if the port needs extra instructions inserted for mode 869190075Sobrienswitching in an optimizing compilation. 869290075Sobrien 869390075SobrienFor an example, the SH4 can perform both single and double precision 869490075Sobrienfloating point operations, but to perform a single precision operation, 869590075Sobrienthe FPSCR PR bit has to be cleared, while for a double precision 869690075Sobrienoperation, this bit has to be set. Changing the PR bit requires a general 869790075Sobrienpurpose register as a scratch register, hence these FPSCR sets have to 869890075Sobrienbe inserted before reload, i.e.@: you can't put this into instruction emitting 8699132718Skanor @code{TARGET_MACHINE_DEPENDENT_REORG}. 870090075Sobrien 870190075SobrienYou can have multiple entities that are mode-switched, and select at run time 870290075Sobrienwhich entities actually need it. @code{OPTIMIZE_MODE_SWITCHING} should 870390075Sobrienreturn nonzero for any @var{entity} that needs mode-switching. 870490075SobrienIf you define this macro, you also have to define 870590075Sobrien@code{NUM_MODES_FOR_MODE_SWITCHING}, @code{MODE_NEEDED}, 870690075Sobrien@code{MODE_PRIORITY_TO_MODE} and @code{EMIT_MODE_SET}. 8707132718Skan@code{MODE_AFTER}, @code{MODE_ENTRY}, and @code{MODE_EXIT} 8708132718Skanare optional. 8709132718Skan@end defmac 871090075Sobrien 8711132718Skan@defmac NUM_MODES_FOR_MODE_SWITCHING 871290075SobrienIf you define @code{OPTIMIZE_MODE_SWITCHING}, you have to define this as 871390075Sobrieninitializer for an array of integers. Each initializer element 871490075SobrienN refers to an entity that needs mode switching, and specifies the number 871590075Sobrienof different modes that might need to be set for this entity. 8716169689SkanThe position of the initializer in the initializer---starting counting at 8717169689Skanzero---determines the integer that is used to refer to the mode-switched 871890075Sobrienentity in question. 871990075SobrienIn macros that take mode arguments / yield a mode result, modes are 872090075Sobrienrepresented as numbers 0 @dots{} N @minus{} 1. N is used to specify that no mode 872190075Sobrienswitch is needed / supplied. 8722132718Skan@end defmac 872390075Sobrien 8724132718Skan@defmac MODE_NEEDED (@var{entity}, @var{insn}) 872590075Sobrien@var{entity} is an integer specifying a mode-switched entity. If 872690075Sobrien@code{OPTIMIZE_MODE_SWITCHING} is defined, you must define this macro to 872790075Sobrienreturn an integer value not larger than the corresponding element in 872890075Sobrien@code{NUM_MODES_FOR_MODE_SWITCHING}, to denote the mode that @var{entity} must 872990075Sobrienbe switched into prior to the execution of @var{insn}. 8730132718Skan@end defmac 873190075Sobrien 8732132718Skan@defmac MODE_AFTER (@var{mode}, @var{insn}) 8733132718SkanIf this macro is defined, it is evaluated for every @var{insn} during 8734169689Skanmode switching. It determines the mode that an insn results in (if 8735132718Skandifferent from the incoming mode). 8736132718Skan@end defmac 8737132718Skan 8738132718Skan@defmac MODE_ENTRY (@var{entity}) 873990075SobrienIf this macro is defined, it is evaluated for every @var{entity} that needs 8740169689Skanmode switching. It should evaluate to an integer, which is a mode that 8741169689Skan@var{entity} is assumed to be switched to at function entry. If @code{MODE_ENTRY} 8742132718Skanis defined then @code{MODE_EXIT} must be defined. 8743132718Skan@end defmac 874490075Sobrien 8745132718Skan@defmac MODE_EXIT (@var{entity}) 8746132718SkanIf this macro is defined, it is evaluated for every @var{entity} that needs 8747169689Skanmode switching. It should evaluate to an integer, which is a mode that 8748169689Skan@var{entity} is assumed to be switched to at function exit. If @code{MODE_EXIT} 8749132718Skanis defined then @code{MODE_ENTRY} must be defined. 8750132718Skan@end defmac 8751132718Skan 8752132718Skan@defmac MODE_PRIORITY_TO_MODE (@var{entity}, @var{n}) 875390075SobrienThis macro specifies the order in which modes for @var{entity} are processed. 875490075Sobrien0 is the highest priority, @code{NUM_MODES_FOR_MODE_SWITCHING[@var{entity}] - 1} the 875590075Sobrienlowest. The value of the macro should be an integer designating a mode 875690075Sobrienfor @var{entity}. For any fixed @var{entity}, @code{mode_priority_to_mode} 875790075Sobrien(@var{entity}, @var{n}) shall be a bijection in 0 @dots{} 875890075Sobrien@code{num_modes_for_mode_switching[@var{entity}] - 1}. 8759132718Skan@end defmac 876090075Sobrien 8761132718Skan@defmac EMIT_MODE_SET (@var{entity}, @var{mode}, @var{hard_regs_live}) 876290075SobrienGenerate one or more insns to set @var{entity} to @var{mode}. 876390075Sobrien@var{hard_reg_live} is the set of hard registers live at the point where 876490075Sobrienthe insn(s) are to be inserted. 8765132718Skan@end defmac 876690075Sobrien 876790075Sobrien@node Target Attributes 876890075Sobrien@section Defining target-specific uses of @code{__attribute__} 876990075Sobrien@cindex target attributes 877090075Sobrien@cindex machine attributes 877190075Sobrien@cindex attributes, target-specific 877290075Sobrien 877390075SobrienTarget-specific attributes may be defined for functions, data and types. 877490075SobrienThese are described using the following target hooks; they also need to 877590075Sobrienbe documented in @file{extend.texi}. 877690075Sobrien 877790075Sobrien@deftypevr {Target Hook} {const struct attribute_spec *} TARGET_ATTRIBUTE_TABLE 877890075SobrienIf defined, this target hook points to an array of @samp{struct 877990075Sobrienattribute_spec} (defined in @file{tree.h}) specifying the machine 878090075Sobrienspecific attributes for this target and some of the restrictions on the 878190075Sobrienentities to which these attributes are applied and the arguments they 878290075Sobrientake. 878390075Sobrien@end deftypevr 878490075Sobrien 878590075Sobrien@deftypefn {Target Hook} int TARGET_COMP_TYPE_ATTRIBUTES (tree @var{type1}, tree @var{type2}) 878690075SobrienIf defined, this target hook is a function which returns zero if the attributes on 878790075Sobrien@var{type1} and @var{type2} are incompatible, one if they are compatible, 878890075Sobrienand two if they are nearly compatible (which causes a warning to be 878990075Sobriengenerated). If this is not defined, machine-specific attributes are 879090075Sobriensupposed always to be compatible. 879190075Sobrien@end deftypefn 879290075Sobrien 879390075Sobrien@deftypefn {Target Hook} void TARGET_SET_DEFAULT_TYPE_ATTRIBUTES (tree @var{type}) 879490075SobrienIf defined, this target hook is a function which assigns default attributes to 879590075Sobriennewly defined @var{type}. 879690075Sobrien@end deftypefn 879790075Sobrien 879890075Sobrien@deftypefn {Target Hook} tree TARGET_MERGE_TYPE_ATTRIBUTES (tree @var{type1}, tree @var{type2}) 879990075SobrienDefine this target hook if the merging of type attributes needs special 880090075Sobrienhandling. If defined, the result is a list of the combined 880190075Sobrien@code{TYPE_ATTRIBUTES} of @var{type1} and @var{type2}. It is assumed 880290075Sobrienthat @code{comptypes} has already been called and returned 1. This 880390075Sobrienfunction may call @code{merge_attributes} to handle machine-independent 880490075Sobrienmerging. 880590075Sobrien@end deftypefn 880690075Sobrien 880790075Sobrien@deftypefn {Target Hook} tree TARGET_MERGE_DECL_ATTRIBUTES (tree @var{olddecl}, tree @var{newdecl}) 880890075SobrienDefine this target hook if the merging of decl attributes needs special 880990075Sobrienhandling. If defined, the result is a list of the combined 881090075Sobrien@code{DECL_ATTRIBUTES} of @var{olddecl} and @var{newdecl}. 881190075Sobrien@var{newdecl} is a duplicate declaration of @var{olddecl}. Examples of 881290075Sobrienwhen this is needed are when one attribute overrides another, or when an 881390075Sobrienattribute is nullified by a subsequent definition. This function may 881490075Sobriencall @code{merge_attributes} to handle machine-independent merging. 881590075Sobrien 881690075Sobrien@findex TARGET_DLLIMPORT_DECL_ATTRIBUTES 8817169689SkanIf the only target-specific handling you require is @samp{dllimport} 8818169689Skanfor Microsoft Windows targets, you should define the macro 8819169689Skan@code{TARGET_DLLIMPORT_DECL_ATTRIBUTES} to @code{1}. The compiler 8820169689Skanwill then define a function called 8821169689Skan@code{merge_dllimport_decl_attributes} which can then be defined as 8822169689Skanthe expansion of @code{TARGET_MERGE_DECL_ATTRIBUTES}. You can also 8823169689Skanadd @code{handle_dll_attribute} in the attribute table for your port 8824169689Skanto perform initial processing of the @samp{dllimport} and 8825169689Skan@samp{dllexport} attributes. This is done in @file{i386/cygwin.h} and 8826169689Skan@file{i386/i386.c}, for example. 882790075Sobrien@end deftypefn 882890075Sobrien 8829169689Skan@deftypefn {Target Hook} bool TARGET_VALID_DLLIMPORT_ATTRIBUTE_P (tree @var{decl}) 8830169689Skan@var{decl} is a variable or function with @code{__attribute__((dllimport))} 8831169689Skanspecified. Use this hook if the target needs to add extra validation 8832169689Skanchecks to @code{handle_dll_attribute}. 8833169689Skan@end deftypefn 8834169689Skan 8835169689Skan@defmac TARGET_DECLSPEC 8836169689SkanDefine this macro to a nonzero value if you want to treat 8837169689Skan@code{__declspec(X)} as equivalent to @code{__attribute((X))}. By 8838169689Skandefault, this behavior is enabled only for targets that define 8839169689Skan@code{TARGET_DLLIMPORT_DECL_ATTRIBUTES}. The current implementation 8840169689Skanof @code{__declspec} is via a built-in macro, but you should not rely 8841169689Skanon this implementation detail. 8842169689Skan@end defmac 8843169689Skan 884490075Sobrien@deftypefn {Target Hook} void TARGET_INSERT_ATTRIBUTES (tree @var{node}, tree *@var{attr_ptr}) 884590075SobrienDefine this target hook if you want to be able to add attributes to a decl 884690075Sobrienwhen it is being created. This is normally useful for back ends which 884790075Sobrienwish to implement a pragma by using the attributes which correspond to 884890075Sobrienthe pragma's effect. The @var{node} argument is the decl which is being 884990075Sobriencreated. The @var{attr_ptr} argument is a pointer to the attribute list 885090075Sobrienfor this decl. The list itself should not be modified, since it may be 885190075Sobrienshared with other decls, but attributes may be chained on the head of 885290075Sobrienthe list and @code{*@var{attr_ptr}} modified to point to the new 885390075Sobrienattributes, or a copy of the list may be made if further changes are 885490075Sobrienneeded. 885590075Sobrien@end deftypefn 885690075Sobrien 885790075Sobrien@deftypefn {Target Hook} bool TARGET_FUNCTION_ATTRIBUTE_INLINABLE_P (tree @var{fndecl}) 885890075Sobrien@cindex inlining 885990075SobrienThis target hook returns @code{true} if it is ok to inline @var{fndecl} 886090075Sobrieninto the current function, despite its having target-specific 886190075Sobrienattributes, @code{false} otherwise. By default, if a function has a 886290075Sobrientarget specific attribute attached to it, it will not be inlined. 886390075Sobrien@end deftypefn 886490075Sobrien 8865117395Skan@node MIPS Coprocessors 8866117395Skan@section Defining coprocessor specifics for MIPS targets. 8867117395Skan@cindex MIPS coprocessor-definition macros 8868117395Skan 8869117395SkanThe MIPS specification allows MIPS implementations to have as many as 4 8870132718Skancoprocessors, each with as many as 32 private registers. GCC supports 8871117395Skanaccessing these registers and transferring values between the registers 8872117395Skanand memory using asm-ized variables. For example: 8873117395Skan 8874117395Skan@smallexample 8875117395Skan register unsigned int cp0count asm ("c0r1"); 8876117395Skan unsigned int d; 8877117395Skan 8878117395Skan d = cp0count + 3; 8879117395Skan@end smallexample 8880117395Skan 8881117395Skan(``c0r1'' is the default name of register 1 in coprocessor 0; alternate 8882117395Skannames may be added as described below, or the default names may be 8883117395Skanoverridden entirely in @code{SUBTARGET_CONDITIONAL_REGISTER_USAGE}.) 8884117395Skan 8885117395SkanCoprocessor registers are assumed to be epilogue-used; sets to them will 8886117395Skanbe preserved even if it does not appear that the register is used again 8887117395Skanlater in the function. 8888117395Skan 8889117395SkanAnother note: according to the MIPS spec, coprocessor 1 (if present) is 8890169689Skanthe FPU@. One accesses COP1 registers through standard mips 8891117395Skanfloating-point support; they are not included in this mechanism. 8892117395Skan 8893117395SkanThere is one macro used in defining the MIPS coprocessor interface which 8894117395Skanyou may want to override in subtargets; it is described below. 8895117395Skan 8896132718Skan@defmac ALL_COP_ADDITIONAL_REGISTER_NAMES 8897117395SkanA comma-separated list (with leading comma) of pairs describing the 8898117395Skanalternate names of coprocessor registers. The format of each entry should be 8899117395Skan@smallexample 8900117395Skan@{ @var{alternatename}, @var{register_number}@} 8901117395Skan@end smallexample 8902117395SkanDefault: empty. 8903132718Skan@end defmac 8904117395Skan 8905132718Skan@node PCH Target 8906132718Skan@section Parameters for Precompiled Header Validity Checking 8907132718Skan@cindex parameters, precompiled headers 8908117395Skan 8909169689Skan@deftypefn {Target Hook} void *TARGET_GET_PCH_VALIDITY (size_t *@var{sz}) 8910169689SkanThis hook returns the data needed by @code{TARGET_PCH_VALID_P} and sets 8911169689Skan@samp{*@var{sz}} to the size of the data in bytes. 8912132718Skan@end deftypefn 8913132718Skan 8914169689Skan@deftypefn {Target Hook} const char *TARGET_PCH_VALID_P (const void *@var{data}, size_t @var{sz}) 8915169689SkanThis hook checks whether the options used to create a PCH file are 8916169689Skancompatible with the current settings. It returns @code{NULL} 8917169689Skanif so and a suitable error message if not. Error messages will 8918169689Skanbe presented to the user and must be localized using @samp{_(@var{msg})}. 8919169689Skan 8920169689Skan@var{data} is the data that was returned by @code{TARGET_GET_PCH_VALIDITY} 8921169689Skanwhen the PCH file was created and @var{sz} is the size of that data in bytes. 8922169689SkanIt's safe to assume that the data was created by the same version of the 8923169689Skancompiler, so no format checking is needed. 8924169689Skan 8925169689SkanThe default definition of @code{default_pch_valid_p} should be 8926169689Skansuitable for most targets. 8927132718Skan@end deftypefn 8928132718Skan 8929169689Skan@deftypefn {Target Hook} const char *TARGET_CHECK_PCH_TARGET_FLAGS (int @var{pch_flags}) 8930169689SkanIf this hook is nonnull, the default implementation of 8931169689Skan@code{TARGET_PCH_VALID_P} will use it to check for compatible values 8932169689Skanof @code{target_flags}. @var{pch_flags} specifies the value that 8933169689Skan@code{target_flags} had when the PCH file was created. The return 8934169689Skanvalue is the same as for @code{TARGET_PCH_VALID_P}. 8935169689Skan@end deftypefn 8936169689Skan 8937169689Skan@node C++ ABI 8938169689Skan@section C++ ABI parameters 8939169689Skan@cindex parameters, c++ abi 8940169689Skan 8941169689Skan@deftypefn {Target Hook} tree TARGET_CXX_GUARD_TYPE (void) 8942169689SkanDefine this hook to override the integer type used for guard variables. 8943169689SkanThese are used to implement one-time construction of static objects. The 8944169689Skandefault is long_long_integer_type_node. 8945169689Skan@end deftypefn 8946169689Skan 8947169689Skan@deftypefn {Target Hook} bool TARGET_CXX_GUARD_MASK_BIT (void) 8948169689SkanThis hook determines how guard variables are used. It should return 8949169689Skan@code{false} (the default) if first byte should be used. A return value of 8950169689Skan@code{true} indicates the least significant bit should be used. 8951169689Skan@end deftypefn 8952169689Skan 8953169689Skan@deftypefn {Target Hook} tree TARGET_CXX_GET_COOKIE_SIZE (tree @var{type}) 8954169689SkanThis hook returns the size of the cookie to use when allocating an array 8955169689Skanwhose elements have the indicated @var{type}. Assumes that it is already 8956169689Skanknown that a cookie is needed. The default is 8957169689Skan@code{max(sizeof (size_t), alignof(type))}, as defined in section 2.7 of the 8958169689SkanIA64/Generic C++ ABI@. 8959169689Skan@end deftypefn 8960169689Skan 8961169689Skan@deftypefn {Target Hook} bool TARGET_CXX_COOKIE_HAS_SIZE (void) 8962169689SkanThis hook should return @code{true} if the element size should be stored in 8963169689Skanarray cookies. The default is to return @code{false}. 8964169689Skan@end deftypefn 8965169689Skan 8966169689Skan@deftypefn {Target Hook} int TARGET_CXX_IMPORT_EXPORT_CLASS (tree @var{type}, int @var{import_export}) 8967169689SkanIf defined by a backend this hook allows the decision made to export 8968169689Skanclass @var{type} to be overruled. Upon entry @var{import_export} 8969169689Skanwill contain 1 if the class is going to be exported, @minus{}1 if it is going 8970169689Skanto be imported and 0 otherwise. This function should return the 8971169689Skanmodified value and perform any other actions necessary to support the 8972169689Skanbackend's targeted operating system. 8973169689Skan@end deftypefn 8974169689Skan 8975169689Skan@deftypefn {Target Hook} bool TARGET_CXX_CDTOR_RETURNS_THIS (void) 8976169689SkanThis hook should return @code{true} if constructors and destructors return 8977169689Skanthe address of the object created/destroyed. The default is to return 8978169689Skan@code{false}. 8979169689Skan@end deftypefn 8980169689Skan 8981169689Skan@deftypefn {Target Hook} bool TARGET_CXX_KEY_METHOD_MAY_BE_INLINE (void) 8982169689SkanThis hook returns true if the key method for a class (i.e., the method 8983169689Skanwhich, if defined in the current translation unit, causes the virtual 8984169689Skantable to be emitted) may be an inline function. Under the standard 8985169689SkanItanium C++ ABI the key method may be an inline function so long as 8986169689Skanthe function is not declared inline in the class definition. Under 8987169689Skansome variants of the ABI, an inline function can never be the key 8988169689Skanmethod. The default is to return @code{true}. 8989169689Skan@end deftypefn 8990169689Skan 8991169689Skan@deftypefn {Target Hook} void TARGET_CXX_DETERMINE_CLASS_DATA_VISIBILITY (tree @var{decl}) 8992169689Skan@var{decl} is a virtual table, virtual table table, typeinfo object, 8993169689Skanor other similar implicit class data object that will be emitted with 8994169689Skanexternal linkage in this translation unit. No ELF visibility has been 8995169689Skanexplicitly specified. If the target needs to specify a visibility 8996169689Skanother than that of the containing class, use this hook to set 8997169689Skan@code{DECL_VISIBILITY} and @code{DECL_VISIBILITY_SPECIFIED}. 8998169689Skan@end deftypefn 8999169689Skan 9000169689Skan@deftypefn {Target Hook} bool TARGET_CXX_CLASS_DATA_ALWAYS_COMDAT (void) 9001169689SkanThis hook returns true (the default) if virtual tables and other 9002169689Skansimilar implicit class data objects are always COMDAT if they have 9003169689Skanexternal linkage. If this hook returns false, then class data for 9004169689Skanclasses whose virtual table will be emitted in only one translation 9005169689Skanunit will not be COMDAT. 9006169689Skan@end deftypefn 9007169689Skan 9008169689Skan@deftypefn {Target Hook} bool TARGET_CXX_USE_AEABI_ATEXIT (void) 9009169689SkanThis hook returns true if @code{__aeabi_atexit} (as defined by the ARM EABI) 9010169689Skanshould be used to register static destructors when @option{-fuse-cxa-atexit} 9011169689Skanis in effect. The default is to return false to use @code{__cxa_atexit}. 9012169689Skan@end deftypefn 9013169689Skan 9014169689Skan@deftypefn {Target Hook} void TARGET_CXX_ADJUST_CLASS_AT_DEFINITION (tree @var{type}) 9015169689Skan@var{type} is a C++ class (i.e., RECORD_TYPE or UNION_TYPE) that has just been 9016169689Skandefined. Use this hook to make adjustments to the class (eg, tweak 9017169689Skanvisibility or perform any other required target modifications). 9018169689Skan@end deftypefn 9019169689Skan 902090075Sobrien@node Misc 902190075Sobrien@section Miscellaneous Parameters 902290075Sobrien@cindex parameters, miscellaneous 902390075Sobrien 902490075Sobrien@c prevent bad page break with this line 902590075SobrienHere are several miscellaneous parameters. 902690075Sobrien 9027169689Skan@defmac HAS_LONG_COND_BRANCH 9028169689SkanDefine this boolean macro to indicate whether or not your architecture 9029169689Skanhas conditional branches that can span all of memory. It is used in 9030169689Skanconjunction with an optimization that partitions hot and cold basic 9031169689Skanblocks into separate sections of the executable. If this macro is 9032169689Skanset to false, gcc will convert any conditional branches that attempt 9033169689Skanto cross between sections into unconditional branches or indirect jumps. 9034132718Skan@end defmac 903590075Sobrien 9036169689Skan@defmac HAS_LONG_UNCOND_BRANCH 9037169689SkanDefine this boolean macro to indicate whether or not your architecture 9038169689Skanhas unconditional branches that can span all of memory. It is used in 9039169689Skanconjunction with an optimization that partitions hot and cold basic 9040169689Skanblocks into separate sections of the executable. If this macro is 9041169689Skanset to false, gcc will convert any unconditional branches that attempt 9042169689Skanto cross between sections into indirect jumps. 9043132718Skan@end defmac 904490075Sobrien 9045132718Skan@defmac CASE_VECTOR_MODE 904690075SobrienAn alias for a machine mode name. This is the machine mode that 904790075Sobrienelements of a jump-table should have. 9048132718Skan@end defmac 904990075Sobrien 9050132718Skan@defmac CASE_VECTOR_SHORTEN_MODE (@var{min_offset}, @var{max_offset}, @var{body}) 905190075SobrienOptional: return the preferred mode for an @code{addr_diff_vec} 905290075Sobrienwhen the minimum and maximum offset are known. If you define this, 905390075Sobrienit enables extra code in branch shortening to deal with @code{addr_diff_vec}. 9054117395SkanTo make this work, you also have to define @code{INSN_ALIGN} and 905590075Sobrienmake the alignment for @code{addr_diff_vec} explicit. 905690075SobrienThe @var{body} argument is provided so that the offset_unsigned and scale 905790075Sobrienflags can be updated. 9058132718Skan@end defmac 905990075Sobrien 9060132718Skan@defmac CASE_VECTOR_PC_RELATIVE 906190075SobrienDefine this macro to be a C expression to indicate when jump-tables 9062132718Skanshould contain relative addresses. You need not define this macro if 9063132718Skanjump-tables never contain relative addresses, or jump-tables should 9064132718Skancontain relative addresses only when @option{-fPIC} or @option{-fPIC} 9065132718Skanis in effect. 9066132718Skan@end defmac 906790075Sobrien 9068132718Skan@defmac CASE_VALUES_THRESHOLD 906990075SobrienDefine this to be the smallest number of different values for which it 907090075Sobrienis best to use a jump-table instead of a tree of conditional branches. 907190075SobrienThe default is four for machines with a @code{casesi} instruction and 907290075Sobrienfive otherwise. This is best for most machines. 9073132718Skan@end defmac 907490075Sobrien 9075132718Skan@defmac CASE_USE_BIT_TESTS 9076132718SkanDefine this macro to be a C expression to indicate whether C switch 9077132718Skanstatements may be implemented by a sequence of bit tests. This is 9078132718Skanadvantageous on processors that can efficiently implement left shift 9079132718Skanof 1 by the number of bits held in a register, but inappropriate on 9080132718Skantargets that would require a loop. By default, this macro returns 9081132718Skan@code{true} if the target defines an @code{ashlsi3} pattern, and 9082132718Skan@code{false} otherwise. 9083132718Skan@end defmac 9084132718Skan 9085132718Skan@defmac WORD_REGISTER_OPERATIONS 908690075SobrienDefine this macro if operations between registers with integral mode 908790075Sobriensmaller than a word are always performed on the entire register. 908890075SobrienMost RISC machines have this property and most CISC machines do not. 9089132718Skan@end defmac 909090075Sobrien 9091132718Skan@defmac LOAD_EXTEND_OP (@var{mem_mode}) 909290075SobrienDefine this macro to be a C expression indicating when insns that read 9093132718Skanmemory in @var{mem_mode}, an integral mode narrower than a word, set the 9094132718Skanbits outside of @var{mem_mode} to be either the sign-extension or the 909590075Sobrienzero-extension of the data read. Return @code{SIGN_EXTEND} for values 9096132718Skanof @var{mem_mode} for which the 909790075Sobrieninsn sign-extends, @code{ZERO_EXTEND} for which it zero-extends, and 9098169689Skan@code{UNKNOWN} for other modes. 909990075Sobrien 9100132718SkanThis macro is not called with @var{mem_mode} non-integral or with a width 910190075Sobriengreater than or equal to @code{BITS_PER_WORD}, so you may return any 910290075Sobrienvalue in this case. Do not define this macro if it would always return 9103169689Skan@code{UNKNOWN}. On machines where this macro is defined, you will normally 910490075Sobriendefine it as the constant @code{SIGN_EXTEND} or @code{ZERO_EXTEND}. 910590075Sobrien 9106169689SkanYou may return a non-@code{UNKNOWN} value even if for some hard registers 9107132718Skanthe sign extension is not performed, if for the @code{REGNO_REG_CLASS} 9108132718Skanof these hard registers @code{CANNOT_CHANGE_MODE_CLASS} returns nonzero 9109132718Skanwhen the @var{from} mode is @var{mem_mode} and the @var{to} mode is any 9110132718Skanintegral mode larger than this but not larger than @code{word_mode}. 9111132718Skan 9112169689SkanYou must return @code{UNKNOWN} if for some hard registers that allow this 9113132718Skanmode, @code{CANNOT_CHANGE_MODE_CLASS} says that they cannot change to 9114132718Skan@code{word_mode}, but that they can change to another integral mode that 9115132718Skanis larger then @var{mem_mode} but still smaller than @code{word_mode}. 9116132718Skan@end defmac 9117132718Skan 9118132718Skan@defmac SHORT_IMMEDIATES_SIGN_EXTEND 911990075SobrienDefine this macro if loading short immediate values into registers sign 912090075Sobrienextends. 9121132718Skan@end defmac 912290075Sobrien 9123132718Skan@defmac FIXUNS_TRUNC_LIKE_FIX_TRUNC 912490075SobrienDefine this macro if the same instructions that convert a floating 912590075Sobrienpoint number to a signed fixed point number also convert validly to an 912690075Sobrienunsigned one. 9127132718Skan@end defmac 912890075Sobrien 9129169689Skan@deftypefn {Target Hook} int TARGET_MIN_DIVISIONS_FOR_RECIP_MUL (enum machine_mode @var{mode}) 9130169689SkanWhen @option{-ffast-math} is in effect, GCC tries to optimize 9131169689Skandivisions by the same divisor, by turning them into multiplications by 9132169689Skanthe reciprocal. This target hook specifies the minimum number of divisions 9133169689Skanthat should be there for GCC to perform the optimization for a variable 9134169689Skanof mode @var{mode}. The default implementation returns 3 if the machine 9135169689Skanhas an instruction for the division, and 2 if it does not. 9136169689Skan@end deftypefn 9137169689Skan 9138132718Skan@defmac MOVE_MAX 913990075SobrienThe maximum number of bytes that a single instruction can move quickly 914090075Sobrienbetween memory and registers or between two memory locations. 9141132718Skan@end defmac 914290075Sobrien 9143132718Skan@defmac MAX_MOVE_MAX 914490075SobrienThe maximum number of bytes that a single instruction can move quickly 914590075Sobrienbetween memory and registers or between two memory locations. If this 914690075Sobrienis undefined, the default is @code{MOVE_MAX}. Otherwise, it is the 914790075Sobrienconstant value that is the largest value that @code{MOVE_MAX} can have 914890075Sobrienat run-time. 9149132718Skan@end defmac 915090075Sobrien 9151132718Skan@defmac SHIFT_COUNT_TRUNCATED 915290075SobrienA C expression that is nonzero if on this machine the number of bits 915390075Sobrienactually used for the count of a shift operation is equal to the number 915490075Sobrienof bits needed to represent the size of the object being shifted. When 915590075Sobrienthis macro is nonzero, the compiler will assume that it is safe to omit 915690075Sobriena sign-extend, zero-extend, and certain bitwise `and' instructions that 915790075Sobrientruncates the count of a shift operation. On machines that have 915890075Sobrieninstructions that act on bit-fields at variable positions, which may 915990075Sobrieninclude `bit test' instructions, a nonzero @code{SHIFT_COUNT_TRUNCATED} 916090075Sobrienalso enables deletion of truncations of the values that serve as 916190075Sobrienarguments to bit-field instructions. 916290075Sobrien 916390075SobrienIf both types of instructions truncate the count (for shifts) and 916490075Sobrienposition (for bit-field operations), or if no variable-position bit-field 916590075Sobrieninstructions exist, you should define this macro. 916690075Sobrien 916790075SobrienHowever, on some machines, such as the 80386 and the 680x0, truncation 916890075Sobrienonly applies to shift operations and not the (real or pretended) 916990075Sobrienbit-field operations. Define @code{SHIFT_COUNT_TRUNCATED} to be zero on 917090075Sobriensuch machines. Instead, add patterns to the @file{md} file that include 917190075Sobrienthe implied truncation of the shift instructions. 917290075Sobrien 917390075SobrienYou need not define this macro if it would always have the value of zero. 9174132718Skan@end defmac 917590075Sobrien 9176169689Skan@anchor{TARGET_SHIFT_TRUNCATION_MASK} 9177169689Skan@deftypefn {Target Hook} int TARGET_SHIFT_TRUNCATION_MASK (enum machine_mode @var{mode}) 9178169689SkanThis function describes how the standard shift patterns for @var{mode} 9179169689Skandeal with shifts by negative amounts or by more than the width of the mode. 9180169689Skan@xref{shift patterns}. 9181169689Skan 9182169689SkanOn many machines, the shift patterns will apply a mask @var{m} to the 9183169689Skanshift count, meaning that a fixed-width shift of @var{x} by @var{y} is 9184169689Skanequivalent to an arbitrary-width shift of @var{x} by @var{y & m}. If 9185169689Skanthis is true for mode @var{mode}, the function should return @var{m}, 9186169689Skanotherwise it should return 0. A return value of 0 indicates that no 9187169689Skanparticular behavior is guaranteed. 9188169689Skan 9189169689SkanNote that, unlike @code{SHIFT_COUNT_TRUNCATED}, this function does 9190169689Skan@emph{not} apply to general shift rtxes; it applies only to instructions 9191169689Skanthat are generated by the named shift patterns. 9192169689Skan 9193169689SkanThe default implementation of this function returns 9194169689Skan@code{GET_MODE_BITSIZE (@var{mode}) - 1} if @code{SHIFT_COUNT_TRUNCATED} 9195169689Skanand 0 otherwise. This definition is always safe, but if 9196169689Skan@code{SHIFT_COUNT_TRUNCATED} is false, and some shift patterns 9197169689Skannevertheless truncate the shift count, you may get better code 9198169689Skanby overriding it. 9199169689Skan@end deftypefn 9200169689Skan 9201132718Skan@defmac TRULY_NOOP_TRUNCATION (@var{outprec}, @var{inprec}) 920290075SobrienA C expression which is nonzero if on this machine it is safe to 920390075Sobrien``convert'' an integer of @var{inprec} bits to one of @var{outprec} 920490075Sobrienbits (where @var{outprec} is smaller than @var{inprec}) by merely 920590075Sobrienoperating on it as if it had only @var{outprec} bits. 920690075Sobrien 920790075SobrienOn many machines, this expression can be 1. 920890075Sobrien 920990075Sobrien@c rearranged this, removed the phrase "it is reported that". this was 921090075Sobrien@c to fix an overfull hbox. --mew 10feb93 921190075SobrienWhen @code{TRULY_NOOP_TRUNCATION} returns 1 for a pair of sizes for 921290075Sobrienmodes for which @code{MODES_TIEABLE_P} is 0, suboptimal code can result. 921390075SobrienIf this is the case, making @code{TRULY_NOOP_TRUNCATION} return 0 in 921490075Sobriensuch cases may improve things. 9215132718Skan@end defmac 921690075Sobrien 9217169689Skan@deftypefn {Target Hook} int TARGET_MODE_REP_EXTENDED (enum machine_mode @var{mode}, enum machine_mode @var{rep_mode}) 9218169689SkanThe representation of an integral mode can be such that the values 9219169689Skanare always extended to a wider integral mode. Return 9220169689Skan@code{SIGN_EXTEND} if values of @var{mode} are represented in 9221169689Skansign-extended form to @var{rep_mode}. Return @code{UNKNOWN} 9222169689Skanotherwise. (Currently, none of the targets use zero-extended 9223169689Skanrepresentation this way so unlike @code{LOAD_EXTEND_OP}, 9224169689Skan@code{TARGET_MODE_REP_EXTENDED} is expected to return either 9225169689Skan@code{SIGN_EXTEND} or @code{UNKNOWN}. Also no target extends 9226169689Skan@var{mode} to @var{mode_rep} so that @var{mode_rep} is not the next 9227169689Skanwidest integral mode and currently we take advantage of this fact.) 9228169689Skan 9229169689SkanSimilarly to @code{LOAD_EXTEND_OP} you may return a non-@code{UNKNOWN} 9230169689Skanvalue even if the extension is not performed on certain hard registers 9231169689Skanas long as for the @code{REGNO_REG_CLASS} of these hard registers 9232169689Skan@code{CANNOT_CHANGE_MODE_CLASS} returns nonzero. 9233169689Skan 9234169689SkanNote that @code{TARGET_MODE_REP_EXTENDED} and @code{LOAD_EXTEND_OP} 9235169689Skandescribe two related properties. If you define 9236169689Skan@code{TARGET_MODE_REP_EXTENDED (mode, word_mode)} you probably also want 9237169689Skanto define @code{LOAD_EXTEND_OP (mode)} to return the same type of 9238169689Skanextension. 9239169689Skan 9240169689SkanIn order to enforce the representation of @code{mode}, 9241169689Skan@code{TRULY_NOOP_TRUNCATION} should return false when truncating to 9242169689Skan@code{mode}. 9243169689Skan@end deftypefn 9244169689Skan 9245132718Skan@defmac STORE_FLAG_VALUE 924690075SobrienA C expression describing the value returned by a comparison operator 924790075Sobrienwith an integral mode and stored by a store-flag instruction 924890075Sobrien(@samp{s@var{cond}}) when the condition is true. This description must 924990075Sobrienapply to @emph{all} the @samp{s@var{cond}} patterns and all the 925090075Sobriencomparison operators whose results have a @code{MODE_INT} mode. 925190075Sobrien 925290075SobrienA value of 1 or @minus{}1 means that the instruction implementing the 925390075Sobriencomparison operator returns exactly 1 or @minus{}1 when the comparison is true 925490075Sobrienand 0 when the comparison is false. Otherwise, the value indicates 925590075Sobrienwhich bits of the result are guaranteed to be 1 when the comparison is 925690075Sobrientrue. This value is interpreted in the mode of the comparison 925790075Sobrienoperation, which is given by the mode of the first operand in the 925890075Sobrien@samp{s@var{cond}} pattern. Either the low bit or the sign bit of 925990075Sobrien@code{STORE_FLAG_VALUE} be on. Presently, only those bits are used by 926090075Sobrienthe compiler. 926190075Sobrien 926290075SobrienIf @code{STORE_FLAG_VALUE} is neither 1 or @minus{}1, the compiler will 926390075Sobriengenerate code that depends only on the specified bits. It can also 926490075Sobrienreplace comparison operators with equivalent operations if they cause 926590075Sobrienthe required bits to be set, even if the remaining bits are undefined. 926690075SobrienFor example, on a machine whose comparison operators return an 926790075Sobrien@code{SImode} value and where @code{STORE_FLAG_VALUE} is defined as 926890075Sobrien@samp{0x80000000}, saying that just the sign bit is relevant, the 926990075Sobrienexpression 927090075Sobrien 927190075Sobrien@smallexample 927290075Sobrien(ne:SI (and:SI @var{x} (const_int @var{power-of-2})) (const_int 0)) 927390075Sobrien@end smallexample 927490075Sobrien 927590075Sobrien@noindent 927690075Sobriencan be converted to 927790075Sobrien 927890075Sobrien@smallexample 927990075Sobrien(ashift:SI @var{x} (const_int @var{n})) 928090075Sobrien@end smallexample 928190075Sobrien 928290075Sobrien@noindent 928390075Sobrienwhere @var{n} is the appropriate shift count to move the bit being 928490075Sobrientested into the sign bit. 928590075Sobrien 928690075SobrienThere is no way to describe a machine that always sets the low-order bit 928790075Sobrienfor a true value, but does not guarantee the value of any other bits, 928890075Sobrienbut we do not know of any machine that has such an instruction. If you 928990075Sobrienare trying to port GCC to such a machine, include an instruction to 929090075Sobrienperform a logical-and of the result with 1 in the pattern for the 929190075Sobriencomparison operators and let us know at @email{gcc@@gcc.gnu.org}. 929290075Sobrien 929390075SobrienOften, a machine will have multiple instructions that obtain a value 929490075Sobrienfrom a comparison (or the condition codes). Here are rules to guide the 929590075Sobrienchoice of value for @code{STORE_FLAG_VALUE}, and hence the instructions 929690075Sobriento be used: 929790075Sobrien 929890075Sobrien@itemize @bullet 929990075Sobrien@item 930090075SobrienUse the shortest sequence that yields a valid definition for 930190075Sobrien@code{STORE_FLAG_VALUE}. It is more efficient for the compiler to 930290075Sobrien``normalize'' the value (convert it to, e.g., 1 or 0) than for the 930390075Sobriencomparison operators to do so because there may be opportunities to 930490075Sobriencombine the normalization with other operations. 930590075Sobrien 930690075Sobrien@item 930790075SobrienFor equal-length sequences, use a value of 1 or @minus{}1, with @minus{}1 being 930890075Sobrienslightly preferred on machines with expensive jumps and 1 preferred on 930990075Sobrienother machines. 931090075Sobrien 931190075Sobrien@item 931290075SobrienAs a second choice, choose a value of @samp{0x80000001} if instructions 931390075Sobrienexist that set both the sign and low-order bits but do not define the 931490075Sobrienothers. 931590075Sobrien 931690075Sobrien@item 931790075SobrienOtherwise, use a value of @samp{0x80000000}. 931890075Sobrien@end itemize 931990075Sobrien 932090075SobrienMany machines can produce both the value chosen for 932190075Sobrien@code{STORE_FLAG_VALUE} and its negation in the same number of 932290075Sobrieninstructions. On those machines, you should also define a pattern for 932390075Sobrienthose cases, e.g., one matching 932490075Sobrien 932590075Sobrien@smallexample 932690075Sobrien(set @var{A} (neg:@var{m} (ne:@var{m} @var{B} @var{C}))) 932790075Sobrien@end smallexample 932890075Sobrien 932990075SobrienSome machines can also perform @code{and} or @code{plus} operations on 933090075Sobriencondition code values with less instructions than the corresponding 933190075Sobrien@samp{s@var{cond}} insn followed by @code{and} or @code{plus}. On those 933290075Sobrienmachines, define the appropriate patterns. Use the names @code{incscc} 933390075Sobrienand @code{decscc}, respectively, for the patterns which perform 933490075Sobrien@code{plus} or @code{minus} operations on condition code values. See 933590075Sobrien@file{rs6000.md} for some examples. The GNU Superoptizer can be used to 933690075Sobrienfind such instruction sequences on other machines. 933790075Sobrien 9338132718SkanIf this macro is not defined, the default value, 1, is used. You need 9339132718Skannot define @code{STORE_FLAG_VALUE} if the machine has no store-flag 9340132718Skaninstructions, or if the value generated by these instructions is 1. 9341132718Skan@end defmac 934290075Sobrien 9343132718Skan@defmac FLOAT_STORE_FLAG_VALUE (@var{mode}) 934490075SobrienA C expression that gives a nonzero @code{REAL_VALUE_TYPE} value that is 934590075Sobrienreturned when comparison operators with floating-point results are true. 9346169689SkanDefine this macro on machines that have comparison operations that return 934790075Sobrienfloating-point values. If there are no such operations, do not define 934890075Sobrienthis macro. 9349132718Skan@end defmac 935090075Sobrien 9351169689Skan@defmac VECTOR_STORE_FLAG_VALUE (@var{mode}) 9352169689SkanA C expression that gives a rtx representing the nonzero true element 9353169689Skanfor vector comparisons. The returned rtx should be valid for the inner 9354169689Skanmode of @var{mode} which is guaranteed to be a vector mode. Define 9355169689Skanthis macro on machines that have vector comparison operations that 9356169689Skanreturn a vector result. If there are no such operations, do not define 9357169689Skanthis macro. Typically, this macro is defined as @code{const1_rtx} or 9358169689Skan@code{constm1_rtx}. This macro may return @code{NULL_RTX} to prevent 9359169689Skanthe compiler optimizing such vector comparison operations for the 9360169689Skangiven mode. 9361169689Skan@end defmac 9362169689Skan 9363132718Skan@defmac CLZ_DEFINED_VALUE_AT_ZERO (@var{mode}, @var{value}) 9364132718Skan@defmacx CTZ_DEFINED_VALUE_AT_ZERO (@var{mode}, @var{value}) 9365132718SkanA C expression that evaluates to true if the architecture defines a value 9366132718Skanfor @code{clz} or @code{ctz} with a zero operand. If so, @var{value} 9367132718Skanshould be set to this value. If this macro is not defined, the value of 9368132718Skan@code{clz} or @code{ctz} is assumed to be undefined. 9369132718Skan 9370132718SkanThis macro must be defined if the target's expansion for @code{ffs} 9371132718Skanrelies on a particular value to get correct results. Otherwise it 9372132718Skanis not necessary, though it may be used to optimize some corner cases. 9373132718Skan 9374132718SkanNote that regardless of this macro the ``definedness'' of @code{clz} 9375132718Skanand @code{ctz} at zero do @emph{not} extend to the builtin functions 9376132718Skanvisible to the user. Thus one may be free to adjust the value at will 9377132718Skanto match the target expansion of these operations without fear of 9378169689Skanbreaking the API@. 9379132718Skan@end defmac 9380132718Skan 9381132718Skan@defmac Pmode 938290075SobrienAn alias for the machine mode for pointers. On most machines, define 938390075Sobrienthis to be the integer mode corresponding to the width of a hardware 938490075Sobrienpointer; @code{SImode} on 32-bit machine or @code{DImode} on 64-bit machines. 938590075SobrienOn some machines you must define this to be one of the partial integer 938690075Sobrienmodes, such as @code{PSImode}. 938790075Sobrien 938890075SobrienThe width of @code{Pmode} must be at least as large as the value of 938990075Sobrien@code{POINTER_SIZE}. If it is not equal, you must define the macro 939090075Sobrien@code{POINTERS_EXTEND_UNSIGNED} to specify how pointers are extended 939190075Sobriento @code{Pmode}. 9392132718Skan@end defmac 939390075Sobrien 9394132718Skan@defmac FUNCTION_MODE 939590075SobrienAn alias for the machine mode used for memory references to functions 939690075Sobrienbeing called, in @code{call} RTL expressions. On most machines this 939790075Sobrienshould be @code{QImode}. 9398132718Skan@end defmac 939990075Sobrien 9400132718Skan@defmac STDC_0_IN_SYSTEM_HEADERS 940190075SobrienIn normal operation, the preprocessor expands @code{__STDC__} to the 940290075Sobrienconstant 1, to signify that GCC conforms to ISO Standard C@. On some 940390075Sobrienhosts, like Solaris, the system compiler uses a different convention, 940490075Sobrienwhere @code{__STDC__} is normally 0, but is 1 if the user specifies 940590075Sobrienstrict conformance to the C Standard. 940690075Sobrien 940790075SobrienDefining @code{STDC_0_IN_SYSTEM_HEADERS} makes GNU CPP follows the host 940890075Sobrienconvention when processing system header files, but when processing user 940990075Sobrienfiles @code{__STDC__} will always expand to 1. 9410132718Skan@end defmac 941190075Sobrien 9412132718Skan@defmac NO_IMPLICIT_EXTERN_C 941390075SobrienDefine this macro if the system header files support C++ as well as C@. 941490075SobrienThis macro inhibits the usual method of using system header files in 941590075SobrienC++, which is to pretend that the file's contents are enclosed in 941690075Sobrien@samp{extern "C" @{@dots{}@}}. 9417132718Skan@end defmac 941890075Sobrien 941990075Sobrien@findex #pragma 942090075Sobrien@findex pragma 9421132718Skan@defmac REGISTER_TARGET_PRAGMAS () 942290075SobrienDefine this macro if you want to implement any target-specific pragmas. 942390075SobrienIf defined, it is a C expression which makes a series of calls to 9424169689Skan@code{c_register_pragma} or @code{c_register_pragma_with_expansion} 9425169689Skanfor each pragma. The macro may also do any 942690075Sobriensetup required for the pragmas. 942790075Sobrien 942890075SobrienThe primary reason to define this macro is to provide compatibility with 942990075Sobrienother compilers for the same target. In general, we discourage 943090075Sobriendefinition of target-specific pragmas for GCC@. 943190075Sobrien 943290075SobrienIf the pragma can be implemented by attributes then you should consider 943390075Sobriendefining the target hook @samp{TARGET_INSERT_ATTRIBUTES} as well. 943490075Sobrien 943590075SobrienPreprocessor macros that appear on pragma lines are not expanded. All 943690075Sobrien@samp{#pragma} directives that do not match any registered pragma are 943790075Sobriensilently ignored, unless the user specifies @option{-Wunknown-pragmas}. 9438132718Skan@end defmac 943990075Sobrien 9440132718Skan@deftypefun void c_register_pragma (const char *@var{space}, const char *@var{name}, void (*@var{callback}) (struct cpp_reader *)) 9441169689Skan@deftypefunx void c_register_pragma_with_expansion (const char *@var{space}, const char *@var{name}, void (*@var{callback}) (struct cpp_reader *)) 944290075Sobrien 9443169689SkanEach call to @code{c_register_pragma} or 9444169689Skan@code{c_register_pragma_with_expansion} establishes one pragma. The 944590075Sobrien@var{callback} routine will be called when the preprocessor encounters a 944690075Sobrienpragma of the form 944790075Sobrien 944890075Sobrien@smallexample 944990075Sobrien#pragma [@var{space}] @var{name} @dots{} 945090075Sobrien@end smallexample 945190075Sobrien 945290075Sobrien@var{space} is the case-sensitive namespace of the pragma, or 945390075Sobrien@code{NULL} to put the pragma in the global namespace. The callback 945490075Sobrienroutine receives @var{pfile} as its first argument, which can be passed 945590075Sobrienon to cpplib's functions if necessary. You can lex tokens after the 9456169689Skan@var{name} by calling @code{pragma_lex}. Tokens that are not read by the 945790075Sobriencallback will be silently ignored. The end of the line is indicated by 9458169689Skana token of type @code{CPP_EOF}. Macro expansion occurs on the 9459169689Skanarguments of pragmas registered with 9460169689Skan@code{c_register_pragma_with_expansion} but not on the arguments of 9461169689Skanpragmas registered with @code{c_register_pragma}. 946290075Sobrien 946390075SobrienFor an example use of this routine, see @file{c4x.h} and the callback 946490075Sobrienroutines defined in @file{c4x-c.c}. 946590075Sobrien 9466169689SkanNote that the use of @code{pragma_lex} is specific to the C and C++ 946790075Sobriencompilers. It will not work in the Java or Fortran compilers, or any 9468169689Skanother language compilers for that matter. Thus if @code{pragma_lex} is going 946990075Sobriento be called from target-specific code, it must only be done so when 947090075Sobrienbuilding the C and C++ compilers. This can be done by defining the 947190075Sobrienvariables @code{c_target_objs} and @code{cxx_target_objs} in the 947290075Sobrientarget entry in the @file{config.gcc} file. These variables should name 947390075Sobrienthe target-specific, language-specific object file which contains the 9474169689Skancode that uses @code{pragma_lex}. Note it will also be necessary to add a 947590075Sobrienrule to the makefile fragment pointed to by @code{tmake_file} that shows 947690075Sobrienhow to build this object file. 947790075Sobrien@end deftypefun 947890075Sobrien 947990075Sobrien@findex #pragma 948090075Sobrien@findex pragma 9481132718Skan@defmac HANDLE_SYSV_PRAGMA 948290075SobrienDefine this macro (to a value of 1) if you want the System V style 948390075Sobrienpragmas @samp{#pragma pack(<n>)} and @samp{#pragma weak <name> 948490075Sobrien[=<value>]} to be supported by gcc. 948590075Sobrien 948690075SobrienThe pack pragma specifies the maximum alignment (in bytes) of fields 948790075Sobrienwithin a structure, in much the same way as the @samp{__aligned__} and 948890075Sobrien@samp{__packed__} @code{__attribute__}s do. A pack value of zero resets 948990075Sobrienthe behavior to the default. 949090075Sobrien 9491117395SkanA subtlety for Microsoft Visual C/C++ style bit-field packing 9492169689Skan(e.g.@: -mms-bitfields) for targets that support it: 9493117395SkanWhen a bit-field is inserted into a packed record, the whole size 9494117395Skanof the underlying type is used by one or more same-size adjacent 9495117395Skanbit-fields (that is, if its long:3, 32 bits is used in the record, 9496117395Skanand any additional adjacent long bit-fields are packed into the same 9497169689Skanchunk of 32 bits. However, if the size changes, a new field of that 9498117395Skansize is allocated). 9499117395Skan 9500117395SkanIf both MS bit-fields and @samp{__attribute__((packed))} are used, 9501169689Skanthe latter will take precedence. If @samp{__attribute__((packed))} is 9502117395Skanused on a single field when MS bit-fields are in use, it will take 9503117395Skanprecedence for that field, but the alignment of the rest of the structure 9504117395Skanmay affect its placement. 9505117395Skan 950690075SobrienThe weak pragma only works if @code{SUPPORTS_WEAK} and 950790075Sobrien@code{ASM_WEAKEN_LABEL} are defined. If enabled it allows the creation 950890075Sobrienof specifically named weak labels, optionally with a value. 9509132718Skan@end defmac 951090075Sobrien 951190075Sobrien@findex #pragma 951290075Sobrien@findex pragma 9513132718Skan@defmac HANDLE_PRAGMA_PACK_PUSH_POP 951490075SobrienDefine this macro (to a value of 1) if you want to support the Win32 9515169689Skanstyle pragmas @samp{#pragma pack(push[,@var{n}])} and @samp{#pragma 9516169689Skanpack(pop)}. The @samp{pack(push,[@var{n}])} pragma specifies the maximum 9517169689Skanalignment (in bytes) of fields within a structure, in much the same way as 9518169689Skanthe @samp{__aligned__} and @samp{__packed__} @code{__attribute__}s do. A 951990075Sobrienpack value of zero resets the behavior to the default. Successive 952090075Sobrieninvocations of this pragma cause the previous values to be stacked, so 952190075Sobrienthat invocations of @samp{#pragma pack(pop)} will return to the previous 952290075Sobrienvalue. 9523132718Skan@end defmac 952490075Sobrien 9525169689Skan@defmac HANDLE_PRAGMA_PACK_WITH_EXPANSION 9526169689SkanDefine this macro, as well as 9527169689Skan@code{HANDLE_SYSV_PRAGMA}, if macros should be expanded in the 9528169689Skanarguments of @samp{#pragma pack}. 9529169689Skan@end defmac 9530169689Skan 9531169689Skan@defmac TARGET_DEFAULT_PACK_STRUCT 9532169689SkanIf your target requires a structure packing default other than 0 (meaning 9533169689Skanthe machine default), define this macro to the necessary value (in bytes). 9534169689SkanThis must be a value that would also be valid to use with 9535169689Skan@samp{#pragma pack()} (that is, a small power of two). 9536169689Skan@end defmac 9537169689Skan 9538132718Skan@defmac DOLLARS_IN_IDENTIFIERS 9539132718SkanDefine this macro to control use of the character @samp{$} in 9540132718Skanidentifier names for the C family of languages. 0 means @samp{$} is 9541132718Skannot allowed by default; 1 means it is allowed. 1 is the default; 9542132718Skanthere is no need to define this macro in that case. 9543132718Skan@end defmac 954490075Sobrien 9545132718Skan@defmac NO_DOLLAR_IN_LABEL 954690075SobrienDefine this macro if the assembler does not accept the character 954790075Sobrien@samp{$} in label names. By default constructors and destructors in 954890075SobrienG++ have @samp{$} in the identifiers. If this macro is defined, 954990075Sobrien@samp{.} is used instead. 9550132718Skan@end defmac 955190075Sobrien 9552132718Skan@defmac NO_DOT_IN_LABEL 955390075SobrienDefine this macro if the assembler does not accept the character 955490075Sobrien@samp{.} in label names. By default constructors and destructors in G++ 955590075Sobrienhave names that use @samp{.}. If this macro is defined, these names 955690075Sobrienare rewritten to avoid @samp{.}. 9557132718Skan@end defmac 955890075Sobrien 9559132718Skan@defmac INSN_SETS_ARE_DELAYED (@var{insn}) 956090075SobrienDefine this macro as a C expression that is nonzero if it is safe for the 956190075Sobriendelay slot scheduler to place instructions in the delay slot of @var{insn}, 956290075Sobrieneven if they appear to use a resource set or clobbered in @var{insn}. 956390075Sobrien@var{insn} is always a @code{jump_insn} or an @code{insn}; GCC knows that 956490075Sobrienevery @code{call_insn} has this behavior. On machines where some @code{insn} 956590075Sobrienor @code{jump_insn} is really a function call and hence has this behavior, 956690075Sobrienyou should define this macro. 956790075Sobrien 956890075SobrienYou need not define this macro if it would always return zero. 9569132718Skan@end defmac 957090075Sobrien 9571132718Skan@defmac INSN_REFERENCES_ARE_DELAYED (@var{insn}) 957290075SobrienDefine this macro as a C expression that is nonzero if it is safe for the 957390075Sobriendelay slot scheduler to place instructions in the delay slot of @var{insn}, 957490075Sobrieneven if they appear to set or clobber a resource referenced in @var{insn}. 957590075Sobrien@var{insn} is always a @code{jump_insn} or an @code{insn}. On machines where 957690075Sobriensome @code{insn} or @code{jump_insn} is really a function call and its operands 957790075Sobrienare registers whose use is actually in the subroutine it calls, you should 957890075Sobriendefine this macro. Doing so allows the delay slot scheduler to move 957990075Sobrieninstructions which copy arguments into the argument registers into the delay 958090075Sobrienslot of @var{insn}. 958190075Sobrien 958290075SobrienYou need not define this macro if it would always return zero. 9583132718Skan@end defmac 958490075Sobrien 9585132718Skan@defmac MULTIPLE_SYMBOL_SPACES 9586169689SkanDefine this macro as a C expression that is nonzero if, in some cases, 9587169689Skanglobal symbols from one translation unit may not be bound to undefined 9588169689Skansymbols in another translation unit without user intervention. For 9589169689Skaninstance, under Microsoft Windows symbols must be explicitly imported 9590169689Skanfrom shared libraries (DLLs). 959190075Sobrien 9592169689SkanYou need not define this macro if it would always evaluate to zero. 9593132718Skan@end defmac 959490075Sobrien 9595169689Skan@deftypefn {Target Hook} tree TARGET_MD_ASM_CLOBBERS (tree @var{outputs}, tree @var{inputs}, tree @var{clobbers}) 9596169689SkanThis target hook should add to @var{clobbers} @code{STRING_CST} trees for 9597169689Skanany hard regs the port wishes to automatically clobber for an asm. 9598169689SkanIt should return the result of the last @code{tree_cons} used to add a 9599169689Skanclobber. The @var{outputs}, @var{inputs} and @var{clobber} lists are the 9600169689Skancorresponding parameters to the asm and may be inspected to avoid 9601169689Skanclobbering a register that is an input or output of the asm. You can use 9602169689Skan@code{tree_overlaps_hard_reg_set}, declared in @file{tree.h}, to test 9603169689Skanfor overlap with regards to asm-declared registers. 9604169689Skan@end deftypefn 9605169689Skan 9606132718Skan@defmac MATH_LIBRARY 960790075SobrienDefine this macro as a C string constant for the linker argument to link 960890075Sobrienin the system math library, or @samp{""} if the target does not have a 960990075Sobrienseparate math library. 961090075Sobrien 961190075SobrienYou need only define this macro if the default of @samp{"-lm"} is wrong. 9612132718Skan@end defmac 961390075Sobrien 9614132718Skan@defmac LIBRARY_PATH_ENV 961590075SobrienDefine this macro as a C string constant for the environment variable that 961690075Sobrienspecifies where the linker should look for libraries. 961790075Sobrien 961890075SobrienYou need only define this macro if the default of @samp{"LIBRARY_PATH"} 961990075Sobrienis wrong. 9620132718Skan@end defmac 962190075Sobrien 9622169689Skan@defmac TARGET_POSIX_IO 9623169689SkanDefine this macro if the target supports the following POSIX@ file 9624169689Skanfunctions, access, mkdir and file locking with fcntl / F_SETLKW@. 9625169689SkanDefining @code{TARGET_POSIX_IO} will enable the test coverage code 962690075Sobriento use file locking when exiting a program, which avoids race conditions 9627169689Skanif the program has forked. It will also create directories at run-time 9628169689Skanfor cross-profiling. 9629132718Skan@end defmac 963090075Sobrien 9631132718Skan@defmac MAX_CONDITIONAL_EXECUTE 963290075Sobrien 963390075SobrienA C expression for the maximum number of instructions to execute via 963490075Sobrienconditional execution instructions instead of a branch. A value of 963590075Sobrien@code{BRANCH_COST}+1 is the default if the machine does not use cc0, and 963690075Sobrien1 if it does use cc0. 9637132718Skan@end defmac 963890075Sobrien 9639132718Skan@defmac IFCVT_MODIFY_TESTS (@var{ce_info}, @var{true_expr}, @var{false_expr}) 9640117395SkanUsed if the target needs to perform machine-dependent modifications on the 9641117395Skanconditionals used for turning basic blocks into conditionally executed code. 9642117395Skan@var{ce_info} points to a data structure, @code{struct ce_if_block}, which 9643117395Skancontains information about the currently processed blocks. @var{true_expr} 9644117395Skanand @var{false_expr} are the tests that are used for converting the 9645117395Skanthen-block and the else-block, respectively. Set either @var{true_expr} or 9646117395Skan@var{false_expr} to a null pointer if the tests cannot be converted. 9647132718Skan@end defmac 964890075Sobrien 9649132718Skan@defmac IFCVT_MODIFY_MULTIPLE_TESTS (@var{ce_info}, @var{bb}, @var{true_expr}, @var{false_expr}) 9650117395SkanLike @code{IFCVT_MODIFY_TESTS}, but used when converting more complicated 9651117395Skanif-statements into conditions combined by @code{and} and @code{or} operations. 9652117395Skan@var{bb} contains the basic block that contains the test that is currently 9653117395Skanbeing processed and about to be turned into a condition. 9654132718Skan@end defmac 9655117395Skan 9656132718Skan@defmac IFCVT_MODIFY_INSN (@var{ce_info}, @var{pattern}, @var{insn}) 9657117395SkanA C expression to modify the @var{PATTERN} of an @var{INSN} that is to 9658117395Skanbe converted to conditional execution format. @var{ce_info} points to 9659117395Skana data structure, @code{struct ce_if_block}, which contains information 9660117395Skanabout the currently processed blocks. 9661132718Skan@end defmac 966290075Sobrien 9663132718Skan@defmac IFCVT_MODIFY_FINAL (@var{ce_info}) 966490075SobrienA C expression to perform any final machine dependent modifications in 9665117395Skanconverting code to conditional execution. The involved basic blocks 9666117395Skancan be found in the @code{struct ce_if_block} structure that is pointed 9667117395Skanto by @var{ce_info}. 9668132718Skan@end defmac 966990075Sobrien 9670132718Skan@defmac IFCVT_MODIFY_CANCEL (@var{ce_info}) 967190075SobrienA C expression to cancel any machine dependent modifications in 9672117395Skanconverting code to conditional execution. The involved basic blocks 9673117395Skancan be found in the @code{struct ce_if_block} structure that is pointed 9674117395Skanto by @var{ce_info}. 9675132718Skan@end defmac 9676117395Skan 9677132718Skan@defmac IFCVT_INIT_EXTRA_FIELDS (@var{ce_info}) 9678117395SkanA C expression to initialize any extra fields in a @code{struct ce_if_block} 9679117395Skanstructure, which are defined by the @code{IFCVT_EXTRA_FIELDS} macro. 9680132718Skan@end defmac 9681117395Skan 9682132718Skan@defmac IFCVT_EXTRA_FIELDS 9683117395SkanIf defined, it should expand to a set of field declarations that will be 9684117395Skanadded to the @code{struct ce_if_block} structure. These should be initialized 9685117395Skanby the @code{IFCVT_INIT_EXTRA_FIELDS} macro. 9686132718Skan@end defmac 9687117395Skan 9688132718Skan@deftypefn {Target Hook} void TARGET_MACHINE_DEPENDENT_REORG () 9689132718SkanIf non-null, this hook performs a target-specific pass over the 9690132718Skaninstruction stream. The compiler will run it at all optimization levels, 9691132718Skanjust before the point at which it normally does delayed-branch scheduling. 969290075Sobrien 9693132718SkanThe exact purpose of the hook varies from target to target. Some use 9694132718Skanit to do transformations that are necessary for correctness, such as 9695132718Skanlaying out in-function constant pools or avoiding hardware hazards. 9696132718SkanOthers use it as an opportunity to do some machine-dependent optimizations. 9697132718Skan 9698132718SkanYou need not implement the hook if it has nothing to do. The default 9699132718Skandefinition is null. 9700132718Skan@end deftypefn 9701132718Skan 970290075Sobrien@deftypefn {Target Hook} void TARGET_INIT_BUILTINS () 970390075SobrienDefine this hook if you have any machine-specific built-in functions 970490075Sobrienthat need to be defined. It should be a function that performs the 970590075Sobriennecessary setup. 970690075Sobrien 970790075SobrienMachine specific built-in functions can be useful to expand special machine 970890075Sobrieninstructions that would otherwise not normally be generated because 970990075Sobrienthey have no equivalent in the source language (for example, SIMD vector 971090075Sobrieninstructions or prefetch instructions). 971190075Sobrien 9712169689SkanTo create a built-in function, call the function 9713169689Skan@code{lang_hooks.builtin_function} 971490075Sobrienwhich is defined by the language front end. You can use any type nodes set 971590075Sobrienup by @code{build_common_tree_nodes} and @code{build_common_tree_nodes_2}; 971690075Sobrienonly language front ends that use those two functions will call 971790075Sobrien@samp{TARGET_INIT_BUILTINS}. 971890075Sobrien@end deftypefn 971990075Sobrien 972090075Sobrien@deftypefn {Target Hook} rtx TARGET_EXPAND_BUILTIN (tree @var{exp}, rtx @var{target}, rtx @var{subtarget}, enum machine_mode @var{mode}, int @var{ignore}) 972190075Sobrien 972290075SobrienExpand a call to a machine specific built-in function that was set up by 972390075Sobrien@samp{TARGET_INIT_BUILTINS}. @var{exp} is the expression for the 972490075Sobrienfunction call; the result should go to @var{target} if that is 972590075Sobrienconvenient, and have mode @var{mode} if that is convenient. 972690075Sobrien@var{subtarget} may be used as the target for computing one of 972790075Sobrien@var{exp}'s operands. @var{ignore} is nonzero if the value is to be 972890075Sobrienignored. This function should return the result of the call to the 972990075Sobrienbuilt-in function. 973090075Sobrien@end deftypefn 973190075Sobrien 9732169689Skan@deftypefn {Target Hook} tree TARGET_RESOLVE_OVERLOADED_BUILTIN (tree @var{fndecl}, tree @var{arglist}) 9733169689Skan 9734169689SkanSelect a replacement for a machine specific built-in function that 9735169689Skanwas set up by @samp{TARGET_INIT_BUILTINS}. This is done 9736169689Skan@emph{before} regular type checking, and so allows the target to 9737169689Skanimplement a crude form of function overloading. @var{fndecl} is the 9738169689Skandeclaration of the built-in function. @var{arglist} is the list of 9739169689Skanarguments passed to the built-in function. The result is a 9740169689Skancomplete expression that implements the operation, usually 9741169689Skananother @code{CALL_EXPR}. 9742169689Skan@end deftypefn 9743169689Skan 9744169689Skan@deftypefn {Target Hook} tree TARGET_FOLD_BUILTIN (tree @var{fndecl}, tree @var{arglist}, bool @var{ignore}) 9745169689Skan 9746169689SkanFold a call to a machine specific built-in function that was set up by 9747169689Skan@samp{TARGET_INIT_BUILTINS}. @var{fndecl} is the declaration of the 9748169689Skanbuilt-in function. @var{arglist} is the list of arguments passed to 9749169689Skanthe built-in function. The result is another tree containing a 9750169689Skansimplified expression for the call's result. If @var{ignore} is true 9751169689Skanthe value will be ignored. 9752169689Skan@end deftypefn 9753169689Skan 9754169689Skan@deftypefn {Target Hook} const char * TARGET_INVALID_WITHIN_DOLOOP (rtx @var{insn}) 9755169689Skan 9756169689SkanTake an instruction in @var{insn} and return NULL if it is valid within a 9757169689Skanlow-overhead loop, otherwise return a string why doloop could not be applied. 9758169689Skan 9759169689SkanMany targets use special registers for low-overhead looping. For any 9760169689Skaninstruction that clobbers these this function should return a string indicating 9761169689Skanthe reason why the doloop could not be applied. 9762169689SkanBy default, the RTL loop optimizer does not use a present doloop pattern for 9763169689Skanloops containing function calls or branch on table instructions. 9764169689Skan@end deftypefn 9765169689Skan 9766132718Skan@defmac MD_CAN_REDIRECT_BRANCH (@var{branch1}, @var{branch2}) 976790075Sobrien 976890075SobrienTake a branch insn in @var{branch1} and another in @var{branch2}. 976990075SobrienReturn true if redirecting @var{branch1} to the destination of 977090075Sobrien@var{branch2} is possible. 977190075Sobrien 977290075SobrienOn some targets, branches may have a limited range. Optimizing the 977390075Sobrienfilling of delay slots can result in branches being redirected, and this 977490075Sobrienmay in turn cause a branch offset to overflow. 9775132718Skan@end defmac 977690075Sobrien 9777169689Skan@deftypefn {Target Hook} bool TARGET_COMMUTATIVE_P (rtx @var{x}, @var{outer_code}) 9778169689SkanThis target hook returns @code{true} if @var{x} is considered to be commutative. 9779169689SkanUsually, this is just COMMUTATIVE_P (@var{x}), but the HP PA doesn't consider 9780169689SkanPLUS to be commutative inside a MEM. @var{outer_code} is the rtx code 9781169689Skanof the enclosing rtl, if known, otherwise it is UNKNOWN. 9782169689Skan@end deftypefn 978390075Sobrien 9784169689Skan@deftypefn {Target Hook} rtx TARGET_ALLOCATE_INITIAL_VALUE (rtx @var{hard_reg}) 9785169689Skan 978690075SobrienWhen the initial value of a hard register has been copied in a pseudo 978790075Sobrienregister, it is often not necessary to actually allocate another register 978890075Sobriento this pseudo register, because the original hard register or a stack slot 9789169689Skanit has been saved into can be used. @code{TARGET_ALLOCATE_INITIAL_VALUE} 9790169689Skanis called at the start of register allocation once for each hard register 9791169689Skanthat had its initial value copied by using 979290075Sobrien@code{get_func_hard_reg_initial_val} or @code{get_hard_reg_initial_val}. 979390075SobrienPossible values are @code{NULL_RTX}, if you don't want 979490075Sobriento do any special allocation, a @code{REG} rtx---that would typically be 979590075Sobrienthe hard register itself, if it is known not to be clobbered---or a 979690075Sobrien@code{MEM}. 979790075SobrienIf you are returning a @code{MEM}, this is only a hint for the allocator; 979890075Sobrienit might decide to use another register anyways. 9799169689SkanYou may use @code{current_function_leaf_function} in the hook, functions 9800169689Skanthat use @code{REG_N_SETS}, to determine if the hard 980190075Sobrienregister in question will not be clobbered. 9802169689SkanThe default value of this hook is @code{NULL}, which disables any special 9803169689Skanallocation. 9804169689Skan@end deftypefn 980590075Sobrien 9806132718Skan@defmac TARGET_OBJECT_SUFFIX 980790075SobrienDefine this macro to be a C string representing the suffix for object 980890075Sobrienfiles on your target machine. If you do not define this macro, GCC will 980990075Sobrienuse @samp{.o} as the suffix for object files. 9810132718Skan@end defmac 981190075Sobrien 9812132718Skan@defmac TARGET_EXECUTABLE_SUFFIX 981390075SobrienDefine this macro to be a C string representing the suffix to be 981490075Sobrienautomatically added to executable files on your target machine. If you 981590075Sobriendo not define this macro, GCC will use the null string as the suffix for 981690075Sobrienexecutable files. 9817132718Skan@end defmac 981890075Sobrien 9819132718Skan@defmac COLLECT_EXPORT_LIST 982090075SobrienIf defined, @code{collect2} will scan the individual object files 982190075Sobrienspecified on its command line and create an export list for the linker. 982290075SobrienDefine this macro for systems like AIX, where the linker discards 982390075Sobrienobject files that are not referenced from @code{main} and uses export 982490075Sobrienlists. 9825132718Skan@end defmac 982690075Sobrien 9827132718Skan@defmac MODIFY_JNI_METHOD_CALL (@var{mdecl}) 9828117395SkanDefine this macro to a C expression representing a variant of the 9829117395Skanmethod call @var{mdecl}, if Java Native Interface (JNI) methods 9830117395Skanmust be invoked differently from other methods on your target. 9831132718SkanFor example, on 32-bit Microsoft Windows, JNI methods must be invoked using 9832117395Skanthe @code{stdcall} calling convention and this macro is then 9833117395Skandefined as this expression: 9834117395Skan 9835117395Skan@smallexample 9836117395Skanbuild_type_attribute_variant (@var{mdecl}, 9837117395Skan build_tree_list 9838117395Skan (get_identifier ("stdcall"), 9839117395Skan NULL)) 9840117395Skan@end smallexample 9841132718Skan@end defmac 9842117395Skan 984396263Sobrien@deftypefn {Target Hook} bool TARGET_CANNOT_MODIFY_JUMPS_P (void) 984496263SobrienThis target hook returns @code{true} past the point in which new jump 984596263Sobrieninstructions could be created. On machines that require a register for 984696263Sobrienevery jump such as the SHmedia ISA of SH5, this point would typically be 984796263Sobrienreload, so this target hook should be defined to a function such as: 984896263Sobrien 984996263Sobrien@smallexample 985096263Sobrienstatic bool 985196263Sobriencannot_modify_jumps_past_reload_p () 985296263Sobrien@{ 985396263Sobrien return (reload_completed || reload_in_progress); 985496263Sobrien@} 985596263Sobrien@end smallexample 985696263Sobrien@end deftypefn 9857132718Skan 9858132718Skan@deftypefn {Target Hook} int TARGET_BRANCH_TARGET_REGISTER_CLASS (void) 9859132718SkanThis target hook returns a register class for which branch target register 9860132718Skanoptimizations should be applied. All registers in this class should be 9861132718Skanusable interchangeably. After reload, registers in this class will be 9862132718Skanre-allocated and loads will be hoisted out of loops and be subjected 9863132718Skanto inter-block scheduling. 9864132718Skan@end deftypefn 9865132718Skan 9866132718Skan@deftypefn {Target Hook} bool TARGET_BRANCH_TARGET_REGISTER_CALLEE_SAVED (bool @var{after_prologue_epilogue_gen}) 9867132718SkanBranch target register optimization will by default exclude callee-saved 9868132718Skanregisters 9869132718Skanthat are not already live during the current function; if this target hook 9870132718Skanreturns true, they will be included. The target code must than make sure 9871132718Skanthat all target registers in the class returned by 9872132718Skan@samp{TARGET_BRANCH_TARGET_REGISTER_CLASS} that might need saving are 9873132718Skansaved. @var{after_prologue_epilogue_gen} indicates if prologues and 9874132718Skanepilogues have already been generated. Note, even if you only return 9875132718Skantrue when @var{after_prologue_epilogue_gen} is false, you still are likely 9876132718Skanto have to make special provisions in @code{INITIAL_ELIMINATION_OFFSET} 9877132718Skanto reserve space for caller-saved target registers. 9878132718Skan@end deftypefn 9879132718Skan 9880132718Skan@defmac POWI_MAX_MULTS 9881132718SkanIf defined, this macro is interpreted as a signed integer C expression 9882132718Skanthat specifies the maximum number of floating point multiplications 9883132718Skanthat should be emitted when expanding exponentiation by an integer 9884132718Skanconstant inline. When this value is defined, exponentiation requiring 9885132718Skanmore than this number of multiplications is implemented by calling the 9886132718Skansystem library's @code{pow}, @code{powf} or @code{powl} routines. 9887132718SkanThe default value places no upper bound on the multiplication count. 9888132718Skan@end defmac 9889169689Skan 9890169689Skan@deftypefn Macro void TARGET_EXTRA_INCLUDES (const char *@var{sysroot}, const char *@var{iprefix}, int @var{stdinc}) 9891169689SkanThis target hook should register any extra include files for the 9892169689Skantarget. The parameter @var{stdinc} indicates if normal include files 9893169689Skanare present. The parameter @var{sysroot} is the system root directory. 9894169689SkanThe parameter @var{iprefix} is the prefix for the gcc directory. 9895169689Skan@end deftypefn 9896169689Skan 9897169689Skan@deftypefn Macro void TARGET_EXTRA_PRE_INCLUDES (const char *@var{sysroot}, const char *@var{iprefix}, int @var{stdinc}) 9898169689SkanThis target hook should register any extra include files for the 9899169689Skantarget before any standard headers. The parameter @var{stdinc} 9900169689Skanindicates if normal include files are present. The parameter 9901169689Skan@var{sysroot} is the system root directory. The parameter 9902169689Skan@var{iprefix} is the prefix for the gcc directory. 9903169689Skan@end deftypefn 9904169689Skan 9905169689Skan@deftypefn Macro void TARGET_OPTF (char *@var{path}) 9906169689SkanThis target hook should register special include paths for the target. 9907169689SkanThe parameter @var{path} is the include to register. On Darwin 9908169689Skansystems, this is used for Framework includes, which have semantics 9909169689Skanthat are different from @option{-I}. 9910169689Skan@end deftypefn 9911169689Skan 9912169689Skan@deftypefn {Target Hook} bool TARGET_USE_LOCAL_THUNK_ALIAS_P (tree @var{fndecl}) 9913169689SkanThis target hook returns @code{true} if it is safe to use a local alias 9914169689Skanfor a virtual function @var{fndecl} when constructing thunks, 9915169689Skan@code{false} otherwise. By default, the hook returns @code{true} for all 9916169689Skanfunctions, if a target supports aliases (i.e.@: defines 9917169689Skan@code{ASM_OUTPUT_DEF}), @code{false} otherwise, 9918169689Skan@end deftypefn 9919169689Skan 9920169689Skan@defmac TARGET_FORMAT_TYPES 9921169689SkanIf defined, this macro is the name of a global variable containing 9922169689Skantarget-specific format checking information for the @option{-Wformat} 9923169689Skanoption. The default is to have no target-specific format checks. 9924169689Skan@end defmac 9925169689Skan 9926169689Skan@defmac TARGET_N_FORMAT_TYPES 9927169689SkanIf defined, this macro is the number of entries in 9928169689Skan@code{TARGET_FORMAT_TYPES}. 9929169689Skan@end defmac 9930169689Skan 9931169689Skan@deftypefn {Target Hook} bool TARGET_RELAXED_ORDERING 9932169689SkanIf set to @code{true}, means that the target's memory model does not 9933169689Skanguarantee that loads which do not depend on one another will access 9934169689Skanmain memory in the order of the instruction stream; if ordering is 9935169689Skanimportant, an explicit memory barrier must be used. This is true of 9936169689Skanmany recent processors which implement a policy of ``relaxed,'' 9937169689Skan``weak,'' or ``release'' memory consistency, such as Alpha, PowerPC, 9938169689Skanand ia64. The default is @code{false}. 9939169689Skan@end deftypefn 9940169689Skan 9941169689Skan@deftypefn {Target Hook} const char *TARGET_INVALID_ARG_FOR_UNPROTOTYPED_FN (tree @var{typelist}, tree @var{funcdecl}, tree @var{val}) 9942169689SkanIf defined, this macro returns the diagnostic message when it is 9943169689Skanillegal to pass argument @var{val} to function @var{funcdecl} 9944169689Skanwith prototype @var{typelist}. 9945169689Skan@end deftypefn 9946169689Skan 9947169689Skan@deftypefn {Target Hook} {const char *} TARGET_INVALID_CONVERSION (tree @var{fromtype}, tree @var{totype}) 9948169689SkanIf defined, this macro returns the diagnostic message when it is 9949169689Skaninvalid to convert from @var{fromtype} to @var{totype}, or @code{NULL} 9950169689Skanif validity should be determined by the front end. 9951169689Skan@end deftypefn 9952169689Skan 9953169689Skan@deftypefn {Target Hook} {const char *} TARGET_INVALID_UNARY_OP (int @var{op}, tree @var{type}) 9954169689SkanIf defined, this macro returns the diagnostic message when it is 9955169689Skaninvalid to apply operation @var{op} (where unary plus is denoted by 9956169689Skan@code{CONVERT_EXPR}) to an operand of type @var{type}, or @code{NULL} 9957169689Skanif validity should be determined by the front end. 9958169689Skan@end deftypefn 9959169689Skan 9960169689Skan@deftypefn {Target Hook} {const char *} TARGET_INVALID_BINARY_OP (int @var{op}, tree @var{type1}, tree @var{type2}) 9961169689SkanIf defined, this macro returns the diagnostic message when it is 9962169689Skaninvalid to apply operation @var{op} to operands of types @var{type1} 9963169689Skanand @var{type2}, or @code{NULL} if validity should be determined by 9964169689Skanthe front end. 9965169689Skan@end deftypefn 9966169689Skan 9967169689Skan@defmac TARGET_USE_JCR_SECTION 9968169689SkanThis macro determines whether to use the JCR section to register Java 9969169689Skanclasses. By default, TARGET_USE_JCR_SECTION is defined to 1 if both 9970169689SkanSUPPORTS_WEAK and TARGET_HAVE_NAMED_SECTIONS are true, else 0. 9971169689Skan@end defmac 9972169689Skan 9973169689Skan@defmac OBJC_JBLEN 9974169689SkanThis macro determines the size of the objective C jump buffer for the 9975169689SkanNeXT runtime. By default, OBJC_JBLEN is defined to an innocuous value. 9976169689Skan@end defmac 9977