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 703220755Sdim@code{c_language} is set to one of @code{clk_c} or 704220755Sdim@code{clk_cplusplus}. Note that if we are preprocessing assembler, 705220755Sdimthis variable will be @code{clk_c} but the function-like macro 706220755Sdim@code{preprocessing_asm_p()} will return true, so you might want to 707220755Sdimcheck 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 784220755Sdimlanguage frontends (C, C++) and so can be used to alter option flag 785220755Sdimvariables which only exist in those frontends. 786169689Skan@end defmac 787169689Skan 788132718Skan@defmac OPTIMIZATION_OPTIONS (@var{level}, @var{size}) 78990075SobrienSome machines may desire to change what optimizations are performed for 79090075Sobrienvarious optimization levels. This macro, if defined, is executed once 79190075Sobrienjust after the optimization level is determined and before the remainder 79290075Sobrienof the command options have been parsed. Values set in this macro are 79390075Sobrienused as the default values for the other command line options. 79490075Sobrien 79590075Sobrien@var{level} is the optimization level specified; 2 if @option{-O2} is 79690075Sobrienspecified, 1 if @option{-O} is specified, and 0 if neither is specified. 79790075Sobrien 79890075Sobrien@var{size} is nonzero if @option{-Os} is specified and zero otherwise. 79990075Sobrien 80090075SobrienYou should not use this macro to change options that are not 80190075Sobrienmachine-specific. These should uniformly selected by the same 80290075Sobrienoptimization level on all supported machines. Use this macro to enable 80390075Sobrienmachine-specific optimizations. 80490075Sobrien 80590075Sobrien@strong{Do not examine @code{write_symbols} in 80690075Sobrienthis macro!} The debugging options are not supposed to alter the 80790075Sobriengenerated code. 808132718Skan@end defmac 80990075Sobrien 810132718Skan@defmac CAN_DEBUG_WITHOUT_FP 81190075SobrienDefine this macro if debugging can be performed even without a frame 81290075Sobrienpointer. If this macro is defined, GCC will turn on the 81390075Sobrien@option{-fomit-frame-pointer} option whenever @option{-O} is specified. 814132718Skan@end defmac 81590075Sobrien 81690075Sobrien@node Per-Function Data 81790075Sobrien@section Defining data structures for per-function information. 81890075Sobrien@cindex per-function data 81990075Sobrien@cindex data structures 82090075Sobrien 82190075SobrienIf the target needs to store information on a per-function basis, GCC 82290075Sobrienprovides a macro and a couple of variables to allow this. Note, just 82390075Sobrienusing statics to store the information is a bad idea, since GCC supports 82490075Sobriennested functions, so you can be halfway through encoding one function 82590075Sobrienwhen another one comes along. 82690075Sobrien 82790075SobrienGCC defines a data structure called @code{struct function} which 82890075Sobriencontains all of the data specific to an individual function. This 82990075Sobrienstructure contains a field called @code{machine} whose type is 83090075Sobrien@code{struct machine_function *}, which can be used by targets to point 83190075Sobriento their own specific data. 83290075Sobrien 83390075SobrienIf a target needs per-function specific data it should define the type 834117395Skan@code{struct machine_function} and also the macro @code{INIT_EXPANDERS}. 835117395SkanThis macro should be used to initialize the function pointer 836117395Skan@code{init_machine_status}. This pointer is explained below. 83790075Sobrien 83890075SobrienOne typical use of per-function, target specific data is to create an 83990075SobrienRTX to hold the register containing the function's return address. This 84090075SobrienRTX can then be used to implement the @code{__builtin_return_address} 84190075Sobrienfunction, for level 0. 84290075Sobrien 84390075SobrienNote---earlier implementations of GCC used a single data area to hold 84490075Sobrienall of the per-function information. Thus when processing of a nested 84590075Sobrienfunction began the old per-function data had to be pushed onto a 84690075Sobrienstack, and when the processing was finished, it had to be popped off the 84790075Sobrienstack. GCC used to provide function pointers called 84890075Sobrien@code{save_machine_status} and @code{restore_machine_status} to handle 84990075Sobrienthe saving and restoring of the target specific information. Since the 85090075Sobriensingle data area approach is no longer used, these pointers are no 85190075Sobrienlonger supported. 85290075Sobrien 853132718Skan@defmac INIT_EXPANDERS 85490075SobrienMacro called to initialize any target specific information. This macro 85590075Sobrienis called once per function, before generation of any RTL has begun. 85690075SobrienThe intention of this macro is to allow the initialization of the 857132718Skanfunction pointer @code{init_machine_status}. 858132718Skan@end defmac 85990075Sobrien 860132718Skan@deftypevar {void (*)(struct function *)} init_machine_status 861132718SkanIf this function pointer is non-@code{NULL} it will be called once per 862132718Skanfunction, before function compilation starts, in order to allow the 863132718Skantarget to perform any target specific initialization of the 864132718Skan@code{struct function} structure. It is intended that this would be 865132718Skanused to initialize the @code{machine} of that structure. 86690075Sobrien 867169689Skan@code{struct machine_function} structures are expected to be freed by GC@. 868117395SkanGenerally, any memory that they reference must be allocated by using 869117395Skan@code{ggc_alloc}, including the structure itself. 870132718Skan@end deftypevar 87190075Sobrien 87290075Sobrien@node Storage Layout 87390075Sobrien@section Storage Layout 87490075Sobrien@cindex storage layout 87590075Sobrien 87690075SobrienNote that the definitions of the macros in this table which are sizes or 87790075Sobrienalignments measured in bits do not need to be constant. They can be C 87890075Sobrienexpressions that refer to static variables, such as the @code{target_flags}. 87990075Sobrien@xref{Run-time Target}. 88090075Sobrien 881132718Skan@defmac BITS_BIG_ENDIAN 88290075SobrienDefine this macro to have the value 1 if the most significant bit in a 88390075Sobrienbyte has the lowest number; otherwise define it to have the value zero. 88490075SobrienThis means that bit-field instructions count from the most significant 88590075Sobrienbit. If the machine has no bit-field instructions, then this must still 88690075Sobrienbe defined, but it doesn't matter which value it is defined to. This 88790075Sobrienmacro need not be a constant. 88890075Sobrien 88990075SobrienThis macro does not affect the way structure fields are packed into 89090075Sobrienbytes or words; that is controlled by @code{BYTES_BIG_ENDIAN}. 891132718Skan@end defmac 89290075Sobrien 893132718Skan@defmac BYTES_BIG_ENDIAN 89490075SobrienDefine this macro to have the value 1 if the most significant byte in a 89590075Sobrienword has the lowest number. This macro need not be a constant. 896132718Skan@end defmac 89790075Sobrien 898132718Skan@defmac WORDS_BIG_ENDIAN 89990075SobrienDefine this macro to have the value 1 if, in a multiword object, the 90090075Sobrienmost significant word has the lowest number. This applies to both 90190075Sobrienmemory locations and registers; GCC fundamentally assumes that the 90290075Sobrienorder of words in memory is the same as the order in registers. This 90390075Sobrienmacro need not be a constant. 904132718Skan@end defmac 90590075Sobrien 906132718Skan@defmac LIBGCC2_WORDS_BIG_ENDIAN 90790075SobrienDefine this macro if @code{WORDS_BIG_ENDIAN} is not constant. This must be a 90890075Sobrienconstant value with the same meaning as @code{WORDS_BIG_ENDIAN}, which will be 90990075Sobrienused only when compiling @file{libgcc2.c}. Typically the value will be set 91090075Sobrienbased on preprocessor defines. 911132718Skan@end defmac 91290075Sobrien 913132718Skan@defmac FLOAT_WORDS_BIG_ENDIAN 91490075SobrienDefine this macro to have the value 1 if @code{DFmode}, @code{XFmode} or 91590075Sobrien@code{TFmode} floating point numbers are stored in memory with the word 91690075Sobriencontaining the sign bit at the lowest address; otherwise define it to 91790075Sobrienhave the value 0. This macro need not be a constant. 91890075Sobrien 91990075SobrienYou need not define this macro if the ordering is the same as for 92090075Sobrienmulti-word integers. 921132718Skan@end defmac 92290075Sobrien 923132718Skan@defmac BITS_PER_UNIT 92490075SobrienDefine this macro to be the number of bits in an addressable storage 925117395Skanunit (byte). If you do not define this macro the default is 8. 926132718Skan@end defmac 92790075Sobrien 928132718Skan@defmac BITS_PER_WORD 929117395SkanNumber of bits in a word. If you do not define this macro, the default 930117395Skanis @code{BITS_PER_UNIT * UNITS_PER_WORD}. 931132718Skan@end defmac 93290075Sobrien 933132718Skan@defmac MAX_BITS_PER_WORD 93490075SobrienMaximum number of bits in a word. If this is undefined, the default is 93590075Sobrien@code{BITS_PER_WORD}. Otherwise, it is the constant value that is the 93690075Sobrienlargest value that @code{BITS_PER_WORD} can have at run-time. 937132718Skan@end defmac 93890075Sobrien 939132718Skan@defmac UNITS_PER_WORD 940169689SkanNumber of storage units in a word; normally the size of a general-purpose 941169689Skanregister, a power of two from 1 or 8. 942132718Skan@end defmac 94390075Sobrien 944132718Skan@defmac MIN_UNITS_PER_WORD 94590075SobrienMinimum number of units in a word. If this is undefined, the default is 94690075Sobrien@code{UNITS_PER_WORD}. Otherwise, it is the constant value that is the 94790075Sobriensmallest value that @code{UNITS_PER_WORD} can have at run-time. 948132718Skan@end defmac 94990075Sobrien 950169689Skan@defmac UNITS_PER_SIMD_WORD 951169689SkanNumber of units in the vectors that the vectorizer can produce. 952169689SkanThe default is equal to @code{UNITS_PER_WORD}, because the vectorizer 953169689Skancan do some transformations even in absence of specialized @acronym{SIMD} 954169689Skanhardware. 955169689Skan@end defmac 956169689Skan 957132718Skan@defmac POINTER_SIZE 95890075SobrienWidth of a pointer, in bits. You must specify a value no wider than the 95990075Sobrienwidth of @code{Pmode}. If it is not equal to the width of @code{Pmode}, 960117395Skanyou must define @code{POINTERS_EXTEND_UNSIGNED}. If you do not specify 961117395Skana value the default is @code{BITS_PER_WORD}. 962132718Skan@end defmac 96390075Sobrien 964132718Skan@defmac POINTERS_EXTEND_UNSIGNED 96590075SobrienA C expression whose value is greater than zero if pointers that need to be 96690075Sobrienextended from being @code{POINTER_SIZE} bits wide to @code{Pmode} are to 96790075Sobrienbe zero-extended and zero if they are to be sign-extended. If the value 96890075Sobrienis less then zero then there must be an "ptr_extend" instruction that 96990075Sobrienextends a pointer from @code{POINTER_SIZE} to @code{Pmode}. 97090075Sobrien 97190075SobrienYou need not define this macro if the @code{POINTER_SIZE} is equal 97290075Sobriento the width of @code{Pmode}. 973132718Skan@end defmac 97490075Sobrien 975132718Skan@defmac PROMOTE_MODE (@var{m}, @var{unsignedp}, @var{type}) 97690075SobrienA macro to update @var{m} and @var{unsignedp} when an object whose type 97790075Sobrienis @var{type} and which has the specified mode and signedness is to be 97890075Sobrienstored in a register. This macro is only called when @var{type} is a 97990075Sobrienscalar type. 98090075Sobrien 98190075SobrienOn most RISC machines, which only have operations that operate on a full 98290075Sobrienregister, define this macro to set @var{m} to @code{word_mode} if 98390075Sobrien@var{m} is an integer mode narrower than @code{BITS_PER_WORD}. In most 98490075Sobriencases, only integer modes should be widened because wider-precision 98590075Sobrienfloating-point operations are usually more expensive than their narrower 98690075Sobriencounterparts. 98790075Sobrien 98890075SobrienFor most machines, the macro definition does not change @var{unsignedp}. 98990075SobrienHowever, some machines, have instructions that preferentially handle 99090075Sobrieneither signed or unsigned quantities of certain modes. For example, on 99190075Sobrienthe DEC Alpha, 32-bit loads from memory and 32-bit add instructions 99290075Sobriensign-extend the result to 64 bits. On such machines, set 99390075Sobrien@var{unsignedp} according to which kind of extension is more efficient. 99490075Sobrien 99590075SobrienDo not define this macro if it would never modify @var{m}. 996132718Skan@end defmac 99790075Sobrien 998169689Skan@defmac PROMOTE_FUNCTION_MODE 999169689SkanLike @code{PROMOTE_MODE}, but is applied to outgoing function arguments or 1000169689Skanfunction return values, as specified by @code{TARGET_PROMOTE_FUNCTION_ARGS} 1001169689Skanand @code{TARGET_PROMOTE_FUNCTION_RETURN}, respectively. 1002169689Skan 1003169689SkanThe default is @code{PROMOTE_MODE}. 1004169689Skan@end defmac 1005169689Skan 1006132718Skan@deftypefn {Target Hook} bool TARGET_PROMOTE_FUNCTION_ARGS (tree @var{fntype}) 1007132718SkanThis target hook should return @code{true} if the promotion described by 1008169689Skan@code{PROMOTE_FUNCTION_MODE} should be done for outgoing function 1009169689Skanarguments. 1010132718Skan@end deftypefn 101190075Sobrien 1012132718Skan@deftypefn {Target Hook} bool TARGET_PROMOTE_FUNCTION_RETURN (tree @var{fntype}) 1013132718SkanThis target hook should return @code{true} if the promotion described by 1014169689Skan@code{PROMOTE_FUNCTION_MODE} should be done for the return value of 1015132718Skanfunctions. 101690075Sobrien 1017169689SkanIf this target hook returns @code{true}, @code{TARGET_FUNCTION_VALUE} 1018169689Skanmust perform the same promotions done by @code{PROMOTE_FUNCTION_MODE}. 1019132718Skan@end deftypefn 102090075Sobrien 1021132718Skan@defmac PARM_BOUNDARY 102290075SobrienNormal alignment required for function parameters on the stack, in 102390075Sobrienbits. All stack parameters receive at least this much alignment 102490075Sobrienregardless of data type. On most machines, this is the same as the 102590075Sobriensize of an integer. 1026132718Skan@end defmac 102790075Sobrien 1028132718Skan@defmac STACK_BOUNDARY 102990075SobrienDefine this macro to the minimum alignment enforced by hardware for the 103090075Sobrienstack pointer on this machine. The definition is a C expression for the 103190075Sobriendesired alignment (measured in bits). This value is used as a default 103290075Sobrienif @code{PREFERRED_STACK_BOUNDARY} is not defined. On most machines, 103390075Sobrienthis should be the same as @code{PARM_BOUNDARY}. 1034132718Skan@end defmac 103590075Sobrien 1036132718Skan@defmac PREFERRED_STACK_BOUNDARY 103790075SobrienDefine this macro if you wish to preserve a certain alignment for the 103890075Sobrienstack pointer, greater than what the hardware enforces. The definition 103990075Sobrienis a C expression for the desired alignment (measured in bits). This 104090075Sobrienmacro must evaluate to a value equal to or larger than 104190075Sobrien@code{STACK_BOUNDARY}. 1042132718Skan@end defmac 104390075Sobrien 1044132718Skan@defmac FUNCTION_BOUNDARY 104590075SobrienAlignment required for a function entry point, in bits. 1046132718Skan@end defmac 104790075Sobrien 1048132718Skan@defmac BIGGEST_ALIGNMENT 104990075SobrienBiggest alignment that any data type can require on this machine, in bits. 1050132718Skan@end defmac 105190075Sobrien 1052132718Skan@defmac MINIMUM_ATOMIC_ALIGNMENT 105390075SobrienIf defined, the smallest alignment, in bits, that can be given to an 105490075Sobrienobject that can be referenced in one operation, without disturbing any 105590075Sobriennearby object. Normally, this is @code{BITS_PER_UNIT}, but may be larger 105690075Sobrienon machines that don't have byte or half-word store operations. 1057132718Skan@end defmac 105890075Sobrien 1059132718Skan@defmac BIGGEST_FIELD_ALIGNMENT 106090075SobrienBiggest alignment that any structure or union field can require on this 106190075Sobrienmachine, in bits. If defined, this overrides @code{BIGGEST_ALIGNMENT} for 106290075Sobrienstructure and union fields only, unless the field alignment has been set 106390075Sobrienby the @code{__attribute__ ((aligned (@var{n})))} construct. 1064132718Skan@end defmac 106590075Sobrien 1066132718Skan@defmac ADJUST_FIELD_ALIGN (@var{field}, @var{computed}) 106790075SobrienAn expression for the alignment of a structure field @var{field} if the 1068102780Skanalignment computed in the usual way (including applying of 1069102780Skan@code{BIGGEST_ALIGNMENT} and @code{BIGGEST_FIELD_ALIGNMENT} to the 1070102780Skanalignment) is @var{computed}. It overrides alignment only if the 1071102780Skanfield alignment has not been set by the 1072102780Skan@code{__attribute__ ((aligned (@var{n})))} construct. 1073132718Skan@end defmac 107490075Sobrien 1075132718Skan@defmac MAX_OFILE_ALIGNMENT 107690075SobrienBiggest alignment supported by the object file format of this machine. 107790075SobrienUse this macro to limit the alignment which can be specified using the 107890075Sobrien@code{__attribute__ ((aligned (@var{n})))} construct. If not defined, 107990075Sobrienthe default value is @code{BIGGEST_ALIGNMENT}. 1080132718Skan@end defmac 108190075Sobrien 1082132718Skan@defmac DATA_ALIGNMENT (@var{type}, @var{basic-align}) 108390075SobrienIf defined, a C expression to compute the alignment for a variable in 108490075Sobrienthe static store. @var{type} is the data type, and @var{basic-align} is 108590075Sobrienthe alignment that the object would ordinarily have. The value of this 108690075Sobrienmacro is used instead of that alignment to align the object. 108790075Sobrien 108890075SobrienIf this macro is not defined, then @var{basic-align} is used. 108990075Sobrien 109090075Sobrien@findex strcpy 109190075SobrienOne use of this macro is to increase alignment of medium-size data to 109290075Sobrienmake it all fit in fewer cache lines. Another is to cause character 109390075Sobrienarrays to be word-aligned so that @code{strcpy} calls that copy 109490075Sobrienconstants to character arrays can be done inline. 1095132718Skan@end defmac 109690075Sobrien 1097132718Skan@defmac CONSTANT_ALIGNMENT (@var{constant}, @var{basic-align}) 109890075SobrienIf defined, a C expression to compute the alignment given to a constant 109990075Sobrienthat is being placed in memory. @var{constant} is the constant and 110090075Sobrien@var{basic-align} is the alignment that the object would ordinarily 110190075Sobrienhave. The value of this macro is used instead of that alignment to 110290075Sobrienalign the object. 110390075Sobrien 110490075SobrienIf this macro is not defined, then @var{basic-align} is used. 110590075Sobrien 110690075SobrienThe typical use of this macro is to increase alignment for string 110790075Sobrienconstants to be word aligned so that @code{strcpy} calls that copy 110890075Sobrienconstants can be done inline. 1109132718Skan@end defmac 111090075Sobrien 1111132718Skan@defmac LOCAL_ALIGNMENT (@var{type}, @var{basic-align}) 111290075SobrienIf defined, a C expression to compute the alignment for a variable in 111390075Sobrienthe local store. @var{type} is the data type, and @var{basic-align} is 111490075Sobrienthe alignment that the object would ordinarily have. The value of this 111590075Sobrienmacro is used instead of that alignment to align the object. 111690075Sobrien 111790075SobrienIf this macro is not defined, then @var{basic-align} is used. 111890075Sobrien 111990075SobrienOne use of this macro is to increase alignment of medium-size data to 112090075Sobrienmake it all fit in fewer cache lines. 1121132718Skan@end defmac 112290075Sobrien 1123132718Skan@defmac EMPTY_FIELD_BOUNDARY 112490075SobrienAlignment in bits to be given to a structure bit-field that follows an 112590075Sobrienempty field such as @code{int : 0;}. 112690075Sobrien 1127132718SkanIf @code{PCC_BITFIELD_TYPE_MATTERS} is true, it overrides this macro. 1128132718Skan@end defmac 112990075Sobrien 1130132718Skan@defmac STRUCTURE_SIZE_BOUNDARY 113190075SobrienNumber of bits which any structure or union's size must be a multiple of. 113290075SobrienEach structure or union's size is rounded up to a multiple of this. 113390075Sobrien 113490075SobrienIf you do not define this macro, the default is the same as 113590075Sobrien@code{BITS_PER_UNIT}. 1136132718Skan@end defmac 113790075Sobrien 1138132718Skan@defmac STRICT_ALIGNMENT 113990075SobrienDefine this macro to be the value 1 if instructions will fail to work 114090075Sobrienif given data not on the nominal alignment. If instructions will merely 114190075Sobriengo slower in that case, define this macro as 0. 1142132718Skan@end defmac 114390075Sobrien 1144132718Skan@defmac PCC_BITFIELD_TYPE_MATTERS 114590075SobrienDefine this if you wish to imitate the way many other C compilers handle 114690075Sobrienalignment of bit-fields and the structures that contain them. 114790075Sobrien 1148132718SkanThe behavior is that the type written for a named bit-field (@code{int}, 1149132718Skan@code{short}, or other integer type) imposes an alignment for the entire 1150132718Skanstructure, as if the structure really did contain an ordinary field of 1151132718Skanthat type. In addition, the bit-field is placed within the structure so 1152132718Skanthat it would fit within such a field, not crossing a boundary for it. 115390075Sobrien 1154132718SkanThus, on most machines, a named bit-field whose type is written as 1155132718Skan@code{int} would not cross a four-byte boundary, and would force 1156132718Skanfour-byte alignment for the whole structure. (The alignment used may 1157132718Skannot be four bytes; it is controlled by the other alignment parameters.) 115890075Sobrien 1159132718SkanAn unnamed bit-field will not affect the alignment of the containing 1160132718Skanstructure. 1161132718Skan 116290075SobrienIf the macro is defined, its definition should be a C expression; 116390075Sobriena nonzero value for the expression enables this behavior. 116490075Sobrien 116590075SobrienNote that if this macro is not defined, or its value is zero, some 116690075Sobrienbit-fields may cross more than one alignment boundary. The compiler can 116790075Sobriensupport such references if there are @samp{insv}, @samp{extv}, and 116890075Sobrien@samp{extzv} insns that can directly reference memory. 116990075Sobrien 117090075SobrienThe other known way of making bit-fields work is to define 117190075Sobrien@code{STRUCTURE_SIZE_BOUNDARY} as large as @code{BIGGEST_ALIGNMENT}. 117290075SobrienThen every structure can be accessed with fullwords. 117390075Sobrien 117490075SobrienUnless the machine has bit-field instructions or you define 117590075Sobrien@code{STRUCTURE_SIZE_BOUNDARY} that way, you must define 117690075Sobrien@code{PCC_BITFIELD_TYPE_MATTERS} to have a nonzero value. 117790075Sobrien 117890075SobrienIf your aim is to make GCC use the same conventions for laying out 117990075Sobrienbit-fields as are used by another compiler, here is how to investigate 118090075Sobrienwhat the other compiler does. Compile and run this program: 118190075Sobrien 1182132718Skan@smallexample 118390075Sobrienstruct foo1 118490075Sobrien@{ 118590075Sobrien char x; 118690075Sobrien char :0; 118790075Sobrien char y; 118890075Sobrien@}; 118990075Sobrien 119090075Sobrienstruct foo2 119190075Sobrien@{ 119290075Sobrien char x; 119390075Sobrien int :0; 119490075Sobrien char y; 119590075Sobrien@}; 119690075Sobrien 119790075Sobrienmain () 119890075Sobrien@{ 119990075Sobrien printf ("Size of foo1 is %d\n", 120090075Sobrien sizeof (struct foo1)); 120190075Sobrien printf ("Size of foo2 is %d\n", 120290075Sobrien sizeof (struct foo2)); 120390075Sobrien exit (0); 120490075Sobrien@} 1205132718Skan@end smallexample 120690075Sobrien 120790075SobrienIf this prints 2 and 5, then the compiler's behavior is what you would 120890075Sobrienget from @code{PCC_BITFIELD_TYPE_MATTERS}. 1209132718Skan@end defmac 121090075Sobrien 1211132718Skan@defmac BITFIELD_NBYTES_LIMITED 121296263SobrienLike @code{PCC_BITFIELD_TYPE_MATTERS} except that its effect is limited 121396263Sobriento aligning a bit-field within the structure. 1214132718Skan@end defmac 121590075Sobrien 1216169689Skan@deftypefn {Target Hook} bool TARGET_ALIGN_ANON_BITFIELDS (void) 1217169689SkanWhen @code{PCC_BITFIELD_TYPE_MATTERS} is true this hook will determine 1218169689Skanwhether unnamed bitfields affect the alignment of the containing 1219169689Skanstructure. The hook should return true if the structure should inherit 1220169689Skanthe alignment requirements of an unnamed bitfield's type. 1221169689Skan@end deftypefn 1222169689Skan 1223169689Skan@deftypefn {Target Hook} bool TARGET_NARROW_VOLATILE_BITFIELDS (void) 1224169689SkanThis target hook should return @code{true} if accesses to volatile bitfields 1225169689Skanshould use the narrowest mode possible. It should return @code{false} if 1226169689Skanthese accesses should use the bitfield container type. 1227169689Skan 1228169689SkanThe default is @code{!TARGET_STRICT_ALIGN}. 1229169689Skan@end deftypefn 1230169689Skan 1231132718Skan@defmac MEMBER_TYPE_FORCES_BLK (@var{field}, @var{mode}) 123290075SobrienReturn 1 if a structure or array containing @var{field} should be accessed using 123390075Sobrien@code{BLKMODE}. 123490075Sobrien 1235117395SkanIf @var{field} is the only field in the structure, @var{mode} is its 1236117395Skanmode, otherwise @var{mode} is VOIDmode. @var{mode} is provided in the 1237117395Skancase where structures of one field would require the structure's mode to 1238117395Skanretain the field's mode. 1239117395Skan 124090075SobrienNormally, this is not needed. See the file @file{c4x.h} for an example 124190075Sobrienof how to use this macro to prevent a structure having a floating point 124290075Sobrienfield from being accessed in an integer mode. 1243132718Skan@end defmac 124490075Sobrien 1245132718Skan@defmac ROUND_TYPE_ALIGN (@var{type}, @var{computed}, @var{specified}) 124690075SobrienDefine this macro as an expression for the alignment of a type (given 124790075Sobrienby @var{type} as a tree node) if the alignment computed in the usual 124890075Sobrienway is @var{computed} and the alignment explicitly specified was 124990075Sobrien@var{specified}. 125090075Sobrien 125190075SobrienThe default is to use @var{specified} if it is larger; otherwise, use 125290075Sobrienthe smaller of @var{computed} and @code{BIGGEST_ALIGNMENT} 1253132718Skan@end defmac 125490075Sobrien 1255132718Skan@defmac MAX_FIXED_MODE_SIZE 125690075SobrienAn integer expression for the size in bits of the largest integer 125790075Sobrienmachine mode that should actually be used. All integer machine modes of 125890075Sobrienthis size or smaller can be used for structures and unions with the 125990075Sobrienappropriate sizes. If this macro is undefined, @code{GET_MODE_BITSIZE 126090075Sobrien(DImode)} is assumed. 1261132718Skan@end defmac 126290075Sobrien 1263132718Skan@defmac STACK_SAVEAREA_MODE (@var{save_level}) 126490075SobrienIf defined, an expression of type @code{enum machine_mode} that 126590075Sobrienspecifies the mode of the save area operand of a 126690075Sobrien@code{save_stack_@var{level}} named pattern (@pxref{Standard Names}). 126790075Sobrien@var{save_level} is one of @code{SAVE_BLOCK}, @code{SAVE_FUNCTION}, or 126890075Sobrien@code{SAVE_NONLOCAL} and selects which of the three named patterns is 126990075Sobrienhaving its mode specified. 127090075Sobrien 127190075SobrienYou need not define this macro if it always returns @code{Pmode}. You 127290075Sobrienwould most commonly define this macro if the 127390075Sobrien@code{save_stack_@var{level}} patterns need to support both a 32- and a 127490075Sobrien64-bit mode. 1275132718Skan@end defmac 127690075Sobrien 1277132718Skan@defmac STACK_SIZE_MODE 127890075SobrienIf defined, an expression of type @code{enum machine_mode} that 127990075Sobrienspecifies the mode of the size increment operand of an 128090075Sobrien@code{allocate_stack} named pattern (@pxref{Standard Names}). 128190075Sobrien 128290075SobrienYou need not define this macro if it always returns @code{word_mode}. 128390075SobrienYou would most commonly define this macro if the @code{allocate_stack} 128490075Sobrienpattern needs to support both a 32- and a 64-bit mode. 1285132718Skan@end defmac 128690075Sobrien 1287132718Skan@defmac TARGET_FLOAT_FORMAT 128890075SobrienA code distinguishing the floating point format of the target machine. 1289132718SkanThere are four defined values: 129090075Sobrien 1291132718Skan@ftable @code 129290075Sobrien@item IEEE_FLOAT_FORMAT 129390075SobrienThis code indicates IEEE floating point. It is the default; there is no 1294132718Skanneed to define @code{TARGET_FLOAT_FORMAT} when the format is IEEE@. 129590075Sobrien 129690075Sobrien@item VAX_FLOAT_FORMAT 1297117395SkanThis code indicates the ``F float'' (for @code{float}) and ``D float'' 1298117395Skanor ``G float'' formats (for @code{double}) used on the VAX and PDP-11@. 129990075Sobrien 130090075Sobrien@item IBM_FLOAT_FORMAT 130190075SobrienThis code indicates the format used on the IBM System/370. 130290075Sobrien 130390075Sobrien@item C4X_FLOAT_FORMAT 130490075SobrienThis code indicates the format used on the TMS320C3x/C4x. 1305132718Skan@end ftable 130690075Sobrien 1307132718SkanIf your target uses a floating point format other than these, you must 1308132718Skandefine a new @var{name}_FLOAT_FORMAT code for it, and add support for 1309132718Skanit to @file{real.c}. 131090075Sobrien 131190075SobrienThe ordering of the component words of floating point values stored in 131290075Sobrienmemory is controlled by @code{FLOAT_WORDS_BIG_ENDIAN}. 1313132718Skan@end defmac 131490075Sobrien 1315132718Skan@defmac MODE_HAS_NANS (@var{mode}) 1316117395SkanWhen defined, this macro should be true if @var{mode} has a NaN 1317117395Skanrepresentation. The compiler assumes that NaNs are not equal to 1318117395Skananything (including themselves) and that addition, subtraction, 1319117395Skanmultiplication and division all return NaNs when one operand is 1320117395SkanNaN@. 1321117395Skan 1322117395SkanBy default, this macro is true if @var{mode} is a floating-point 1323117395Skanmode and the target floating-point format is IEEE@. 1324132718Skan@end defmac 1325117395Skan 1326132718Skan@defmac MODE_HAS_INFINITIES (@var{mode}) 1327117395SkanThis macro should be true if @var{mode} can represent infinity. At 1328117395Skanpresent, the compiler uses this macro to decide whether @samp{x - x} 1329117395Skanis always defined. By default, the macro is true when @var{mode} 1330117395Skanis a floating-point mode and the target format is IEEE@. 1331132718Skan@end defmac 1332117395Skan 1333132718Skan@defmac MODE_HAS_SIGNED_ZEROS (@var{mode}) 1334117395SkanTrue if @var{mode} distinguishes between positive and negative zero. 1335117395SkanThe rules are expected to follow the IEEE standard: 1336117395Skan 1337117395Skan@itemize @bullet 1338117395Skan@item 1339117395Skan@samp{x + x} has the same sign as @samp{x}. 1340117395Skan 1341117395Skan@item 1342117395SkanIf the sum of two values with opposite sign is zero, the result is 1343117395Skanpositive for all rounding modes expect towards @minus{}infinity, for 1344117395Skanwhich it is negative. 1345117395Skan 1346117395Skan@item 1347117395SkanThe sign of a product or quotient is negative when exactly one 1348117395Skanof the operands is negative. 1349117395Skan@end itemize 1350117395Skan 1351117395SkanThe default definition is true if @var{mode} is a floating-point 1352117395Skanmode and the target format is IEEE@. 1353132718Skan@end defmac 1354117395Skan 1355132718Skan@defmac MODE_HAS_SIGN_DEPENDENT_ROUNDING (@var{mode}) 1356117395SkanIf defined, this macro should be true for @var{mode} if it has at 1357117395Skanleast one rounding mode in which @samp{x} and @samp{-x} can be 1358117395Skanrounded to numbers of different magnitude. Two such modes are 1359117395Skantowards @minus{}infinity and towards +infinity. 1360117395Skan 1361117395SkanThe default definition of this macro is true if @var{mode} is 1362117395Skana floating-point mode and the target format is IEEE@. 1363132718Skan@end defmac 1364117395Skan 1365132718Skan@defmac ROUND_TOWARDS_ZERO 1366117395SkanIf defined, this macro should be true if the prevailing rounding 1367117395Skanmode is towards zero. A true value has the following effects: 1368117395Skan 1369117395Skan@itemize @bullet 1370117395Skan@item 1371117395Skan@code{MODE_HAS_SIGN_DEPENDENT_ROUNDING} will be false for all modes. 1372117395Skan 1373117395Skan@item 1374117395Skan@file{libgcc.a}'s floating-point emulator will round towards zero 1375117395Skanrather than towards nearest. 1376117395Skan 1377117395Skan@item 1378117395SkanThe compiler's floating-point emulator will round towards zero after 1379117395Skandoing arithmetic, and when converting from the internal float format to 1380117395Skanthe target format. 1381117395Skan@end itemize 1382117395Skan 1383117395SkanThe macro does not affect the parsing of string literals. When the 1384117395Skanprimary rounding mode is towards zero, library functions like 1385117395Skan@code{strtod} might still round towards nearest, and the compiler's 1386117395Skanparser should behave like the target's @code{strtod} where possible. 1387117395Skan 1388117395SkanNot defining this macro is equivalent to returning zero. 1389132718Skan@end defmac 1390117395Skan 1391132718Skan@defmac LARGEST_EXPONENT_IS_NORMAL (@var{size}) 1392117395SkanThis macro should return true if floats with @var{size} 1393117395Skanbits do not have a NaN or infinity representation, but use the largest 1394117395Skanexponent for normal numbers instead. 1395117395Skan 1396117395SkanDefining this macro to true for @var{size} causes @code{MODE_HAS_NANS} 1397117395Skanand @code{MODE_HAS_INFINITIES} to be false for @var{size}-bit modes. 1398117395SkanIt also affects the way @file{libgcc.a} and @file{real.c} emulate 1399117395Skanfloating-point arithmetic. 1400117395Skan 1401117395SkanThe default definition of this macro returns false for all sizes. 1402132718Skan@end defmac 140390075Sobrien 1404132718Skan@deftypefn {Target Hook} bool TARGET_VECTOR_OPAQUE_P (tree @var{type}) 1405132718SkanThis target hook should return @code{true} a vector is opaque. That 1406132718Skanis, if no cast is needed when copying a vector value of type 1407132718Skan@var{type} into another vector lvalue of the same size. Vector opaque 1408132718Skantypes cannot be initialized. The default is that there are no such 1409132718Skantypes. 1410132718Skan@end deftypefn 1411132718Skan 141296263Sobrien@deftypefn {Target Hook} bool TARGET_MS_BITFIELD_LAYOUT_P (tree @var{record_type}) 141396263SobrienThis target hook returns @code{true} if bit-fields in the given 141496263Sobrien@var{record_type} are to be laid out following the rules of Microsoft 141596263SobrienVisual C/C++, namely: (i) a bit-field won't share the same storage 141696263Sobrienunit with the previous bit-field if their underlying types have 141796263Sobriendifferent sizes, and the bit-field will be aligned to the highest 141896263Sobrienalignment of the underlying types of itself and of the previous 141996263Sobrienbit-field; (ii) a zero-sized bit-field will affect the alignment of 142096263Sobrienthe whole enclosing structure, even if it is unnamed; except that 142196263Sobrien(iii) a zero-sized bit-field will be disregarded unless it follows 1422117395Skananother bit-field of nonzero size. If this hook returns @code{true}, 142396263Sobrienother macros that control bit-field layout are ignored. 1424117395Skan 1425117395SkanWhen a bit-field is inserted into a packed record, the whole size 1426117395Skanof the underlying type is used by one or more same-size adjacent 1427117395Skanbit-fields (that is, if its long:3, 32 bits is used in the record, 1428117395Skanand any additional adjacent long bit-fields are packed into the same 1429169689Skanchunk of 32 bits. However, if the size changes, a new field of that 1430169689Skansize is allocated). In an unpacked record, this is the same as using 1431117395Skanalignment, but not equivalent when packing. 1432117395Skan 1433117395SkanIf both MS bit-fields and @samp{__attribute__((packed))} are used, 1434169689Skanthe latter will take precedence. If @samp{__attribute__((packed))} is 1435117395Skanused on a single field when MS bit-fields are in use, it will take 1436117395Skanprecedence for that field, but the alignment of the rest of the structure 1437117395Skanmay affect its placement. 143896263Sobrien@end deftypefn 143996263Sobrien 1440169689Skan@deftypefn {Target Hook} {bool} TARGET_DECIMAL_FLOAT_SUPPORTED_P (void) 1441169689SkanReturns true if the target supports decimal floating point. 1442169689Skan@end deftypefn 1443169689Skan 1444146895Skan@deftypefn {Target Hook} {const char *} TARGET_MANGLE_FUNDAMENTAL_TYPE (tree @var{type}) 1445146895SkanIf your target defines any fundamental types, define this hook to 1446146895Skanreturn the appropriate encoding for these types as part of a C++ 1447146895Skanmangled name. The @var{type} argument is the tree structure 1448146895Skanrepresenting the type to be mangled. The hook may be applied to trees 1449146895Skanwhich are not target-specific fundamental types; it should return 1450146895Skan@code{NULL} for all such types, as well as arguments it does not 1451146895Skanrecognize. If the return value is not @code{NULL}, it must point to 1452146895Skana statically-allocated string constant. 1453146895Skan 1454146895SkanTarget-specific fundamental types might be new fundamental types or 1455146895Skanqualified versions of ordinary fundamental types. Encode new 1456146895Skanfundamental types as @samp{@w{u @var{n} @var{name}}}, where @var{name} 1457146895Skanis the name used for the type in source code, and @var{n} is the 1458146895Skanlength of @var{name} in decimal. Encode qualified versions of 1459146895Skanordinary types as @samp{@w{U @var{n} @var{name} @var{code}}}, where 1460146895Skan@var{name} is the name used for the type qualifier in source code, 1461146895Skan@var{n} is the length of @var{name} as above, and @var{code} is the 1462146895Skancode used to represent the unqualified version of this type. (See 1463146895Skan@code{write_builtin_type} in @file{cp/mangle.c} for the list of 1464146895Skancodes.) In both cases the spaces are for clarity; do not include any 1465146895Skanspaces in your string. 1466146895Skan 1467146895SkanThe default version of this hook always returns @code{NULL}, which is 1468146895Skanappropriate for a target that does not define any new fundamental 1469146895Skantypes. 1470146895Skan@end deftypefn 1471146895Skan 147290075Sobrien@node Type Layout 147390075Sobrien@section Layout of Source Language Data Types 147490075Sobrien 147590075SobrienThese macros define the sizes and other characteristics of the standard 147690075Sobrienbasic data types used in programs being compiled. Unlike the macros in 147790075Sobrienthe previous section, these apply to specific features of C and related 147890075Sobrienlanguages, rather than to fundamental aspects of storage layout. 147990075Sobrien 1480132718Skan@defmac INT_TYPE_SIZE 148190075SobrienA C expression for the size in bits of the type @code{int} on the 148290075Sobrientarget machine. If you don't define this, the default is one word. 1483132718Skan@end defmac 148490075Sobrien 1485132718Skan@defmac SHORT_TYPE_SIZE 148690075SobrienA C expression for the size in bits of the type @code{short} on the 148790075Sobrientarget machine. If you don't define this, the default is half a word. 148890075Sobrien(If this would be less than one storage unit, it is rounded up to one 148990075Sobrienunit.) 1490132718Skan@end defmac 149190075Sobrien 1492132718Skan@defmac LONG_TYPE_SIZE 149390075SobrienA C expression for the size in bits of the type @code{long} on the 149490075Sobrientarget machine. If you don't define this, the default is one word. 1495132718Skan@end defmac 149690075Sobrien 1497132718Skan@defmac ADA_LONG_TYPE_SIZE 149890075SobrienOn some machines, the size used for the Ada equivalent of the type 1499169689Skan@code{long} by a native Ada compiler differs from that used by C@. In 150090075Sobrienthat situation, define this macro to be a C expression to be used for 150190075Sobrienthe size of that type. If you don't define this, the default is the 150290075Sobrienvalue of @code{LONG_TYPE_SIZE}. 1503132718Skan@end defmac 150490075Sobrien 1505132718Skan@defmac LONG_LONG_TYPE_SIZE 150690075SobrienA C expression for the size in bits of the type @code{long long} on the 150790075Sobrientarget machine. If you don't define this, the default is two 150890075Sobrienwords. If you want to support GNU Ada on your machine, the value of this 150990075Sobrienmacro must be at least 64. 1510132718Skan@end defmac 151190075Sobrien 1512132718Skan@defmac CHAR_TYPE_SIZE 151390075SobrienA C expression for the size in bits of the type @code{char} on the 151490075Sobrientarget machine. If you don't define this, the default is 151590075Sobrien@code{BITS_PER_UNIT}. 1516132718Skan@end defmac 151790075Sobrien 1518132718Skan@defmac BOOL_TYPE_SIZE 151996263SobrienA C expression for the size in bits of the C++ type @code{bool} and 152096263SobrienC99 type @code{_Bool} on the target machine. If you don't define 152196263Sobrienthis, and you probably shouldn't, the default is @code{CHAR_TYPE_SIZE}. 1522132718Skan@end defmac 152390075Sobrien 1524132718Skan@defmac FLOAT_TYPE_SIZE 152590075SobrienA C expression for the size in bits of the type @code{float} on the 152690075Sobrientarget machine. If you don't define this, the default is one word. 1527132718Skan@end defmac 152890075Sobrien 1529132718Skan@defmac DOUBLE_TYPE_SIZE 153090075SobrienA C expression for the size in bits of the type @code{double} on the 153190075Sobrientarget machine. If you don't define this, the default is two 153290075Sobrienwords. 1533132718Skan@end defmac 153490075Sobrien 1535132718Skan@defmac LONG_DOUBLE_TYPE_SIZE 153690075SobrienA C expression for the size in bits of the type @code{long double} on 153790075Sobrienthe target machine. If you don't define this, the default is two 153890075Sobrienwords. 1539132718Skan@end defmac 154090075Sobrien 1541169689Skan@defmac LIBGCC2_LONG_DOUBLE_TYPE_SIZE 1542169689SkanDefine this macro if @code{LONG_DOUBLE_TYPE_SIZE} is not constant or 1543169689Skanif you want routines in @file{libgcc2.a} for a size other than 1544169689Skan@code{LONG_DOUBLE_TYPE_SIZE}. If you don't define this, the 1545169689Skandefault is @code{LONG_DOUBLE_TYPE_SIZE}. 1546132718Skan@end defmac 154790075Sobrien 1548169689Skan@defmac LIBGCC2_HAS_DF_MODE 1549169689SkanDefine this macro if neither @code{LIBGCC2_DOUBLE_TYPE_SIZE} nor 1550169689Skan@code{LIBGCC2_LONG_DOUBLE_TYPE_SIZE} is 1551169689Skan@code{DFmode} but you want @code{DFmode} routines in @file{libgcc2.a} 1552169689Skananyway. If you don't define this and either @code{LIBGCC2_DOUBLE_TYPE_SIZE} 1553169689Skanor @code{LIBGCC2_LONG_DOUBLE_TYPE_SIZE} is 64 then the default is 1, 1554169689Skanotherwise it is 0. 1555169689Skan@end defmac 1556169689Skan 1557169689Skan@defmac LIBGCC2_HAS_XF_MODE 1558169689SkanDefine this macro if @code{LIBGCC2_LONG_DOUBLE_TYPE_SIZE} is not 1559169689Skan@code{XFmode} but you want @code{XFmode} routines in @file{libgcc2.a} 1560169689Skananyway. If you don't define this and @code{LIBGCC2_LONG_DOUBLE_TYPE_SIZE} 1561169689Skanis 80 then the default is 1, otherwise it is 0. 1562169689Skan@end defmac 1563169689Skan 1564169689Skan@defmac LIBGCC2_HAS_TF_MODE 1565169689SkanDefine this macro if @code{LIBGCC2_LONG_DOUBLE_TYPE_SIZE} is not 1566169689Skan@code{TFmode} but you want @code{TFmode} routines in @file{libgcc2.a} 1567169689Skananyway. If you don't define this and @code{LIBGCC2_LONG_DOUBLE_TYPE_SIZE} 1568169689Skanis 128 then the default is 1, otherwise it is 0. 1569169689Skan@end defmac 1570169689Skan 1571169689Skan@defmac SF_SIZE 1572169689Skan@defmacx DF_SIZE 1573169689Skan@defmacx XF_SIZE 1574169689Skan@defmacx TF_SIZE 1575169689SkanDefine these macros to be the size in bits of the mantissa of 1576169689Skan@code{SFmode}, @code{DFmode}, @code{XFmode} and @code{TFmode} values, 1577169689Skanif the defaults in @file{libgcc2.h} are inappropriate. By default, 1578169689Skan@code{FLT_MANT_DIG} is used for @code{SF_SIZE}, @code{LDBL_MANT_DIG} 1579169689Skanfor @code{XF_SIZE} and @code{TF_SIZE}, and @code{DBL_MANT_DIG} or 1580169689Skan@code{LDBL_MANT_DIG} for @code{DF_SIZE} according to whether 1581169689Skan@code{LIBGCC2_DOUBLE_TYPE_SIZE} or 1582169689Skan@code{LIBGCC2_LONG_DOUBLE_TYPE_SIZE} is 64. 1583169689Skan@end defmac 1584169689Skan 1585132718Skan@defmac TARGET_FLT_EVAL_METHOD 1586117395SkanA C expression for the value for @code{FLT_EVAL_METHOD} in @file{float.h}, 1587117395Skanassuming, if applicable, that the floating-point control word is in its 1588117395Skandefault state. If you do not define this macro the value of 1589117395Skan@code{FLT_EVAL_METHOD} will be zero. 1590132718Skan@end defmac 159190075Sobrien 1592132718Skan@defmac WIDEST_HARDWARE_FP_SIZE 159390075SobrienA C expression for the size in bits of the widest floating-point format 159490075Sobriensupported by the hardware. If you define this macro, you must specify a 159590075Sobrienvalue less than or equal to the value of @code{LONG_DOUBLE_TYPE_SIZE}. 159690075SobrienIf you do not define this macro, the value of @code{LONG_DOUBLE_TYPE_SIZE} 159790075Sobrienis the default. 1598132718Skan@end defmac 159990075Sobrien 1600132718Skan@defmac DEFAULT_SIGNED_CHAR 160190075SobrienAn expression whose value is 1 or 0, according to whether the type 160290075Sobrien@code{char} should be signed or unsigned by default. The user can 160390075Sobrienalways override this default with the options @option{-fsigned-char} 160490075Sobrienand @option{-funsigned-char}. 1605132718Skan@end defmac 160690075Sobrien 1607169689Skan@deftypefn {Target Hook} bool TARGET_DEFAULT_SHORT_ENUMS (void) 1608169689SkanThis target hook should return true if the compiler should give an 1609169689Skan@code{enum} type only as many bytes as it takes to represent the range 1610169689Skanof possible values of that type. It should return false if all 161190075Sobrien@code{enum} types should be allocated like @code{int}. 161290075Sobrien 1613169689SkanThe default is to return false. 1614169689Skan@end deftypefn 161590075Sobrien 1616132718Skan@defmac SIZE_TYPE 161790075SobrienA C expression for a string describing the name of the data type to use 161890075Sobrienfor size values. The typedef name @code{size_t} is defined using the 161990075Sobriencontents of the string. 162090075Sobrien 162190075SobrienThe string can contain more than one keyword. If so, separate them with 162290075Sobrienspaces, and write first any length keyword, then @code{unsigned} if 162390075Sobrienappropriate, and finally @code{int}. The string must exactly match one 162490075Sobrienof the data type names defined in the function 162590075Sobrien@code{init_decl_processing} in the file @file{c-decl.c}. You may not 162690075Sobrienomit @code{int} or change the order---that would cause the compiler to 162790075Sobriencrash on startup. 162890075Sobrien 162990075SobrienIf you don't define this macro, the default is @code{"long unsigned 163090075Sobrienint"}. 1631132718Skan@end defmac 163290075Sobrien 1633132718Skan@defmac PTRDIFF_TYPE 163490075SobrienA C expression for a string describing the name of the data type to use 163590075Sobrienfor the result of subtracting two pointers. The typedef name 163690075Sobrien@code{ptrdiff_t} is defined using the contents of the string. See 163790075Sobrien@code{SIZE_TYPE} above for more information. 163890075Sobrien 163990075SobrienIf you don't define this macro, the default is @code{"long int"}. 1640132718Skan@end defmac 164190075Sobrien 1642132718Skan@defmac WCHAR_TYPE 164390075SobrienA C expression for a string describing the name of the data type to use 164490075Sobrienfor wide characters. The typedef name @code{wchar_t} is defined using 164590075Sobrienthe contents of the string. See @code{SIZE_TYPE} above for more 164690075Sobrieninformation. 164790075Sobrien 164890075SobrienIf you don't define this macro, the default is @code{"int"}. 1649132718Skan@end defmac 165090075Sobrien 1651132718Skan@defmac WCHAR_TYPE_SIZE 165290075SobrienA C expression for the size in bits of the data type for wide 165390075Sobriencharacters. This is used in @code{cpp}, which cannot make use of 165490075Sobrien@code{WCHAR_TYPE}. 1655132718Skan@end defmac 165690075Sobrien 1657132718Skan@defmac WINT_TYPE 165890075SobrienA C expression for a string describing the name of the data type to 165990075Sobrienuse for wide characters passed to @code{printf} and returned from 166090075Sobrien@code{getwc}. The typedef name @code{wint_t} is defined using the 166190075Sobriencontents of the string. See @code{SIZE_TYPE} above for more 166290075Sobrieninformation. 166390075Sobrien 166490075SobrienIf you don't define this macro, the default is @code{"unsigned int"}. 1665132718Skan@end defmac 166690075Sobrien 1667132718Skan@defmac INTMAX_TYPE 166890075SobrienA C expression for a string describing the name of the data type that 166990075Sobriencan represent any value of any standard or extended signed integer type. 167090075SobrienThe typedef name @code{intmax_t} is defined using the contents of the 167190075Sobrienstring. See @code{SIZE_TYPE} above for more information. 167290075Sobrien 167390075SobrienIf you don't define this macro, the default is the first of 167490075Sobrien@code{"int"}, @code{"long int"}, or @code{"long long int"} that has as 167590075Sobrienmuch precision as @code{long long int}. 1676132718Skan@end defmac 167790075Sobrien 1678132718Skan@defmac UINTMAX_TYPE 167990075SobrienA C expression for a string describing the name of the data type that 168090075Sobriencan represent any value of any standard or extended unsigned integer 168190075Sobrientype. The typedef name @code{uintmax_t} is defined using the contents 168290075Sobrienof the string. See @code{SIZE_TYPE} above for more information. 168390075Sobrien 168490075SobrienIf you don't define this macro, the default is the first of 168590075Sobrien@code{"unsigned int"}, @code{"long unsigned int"}, or @code{"long long 168690075Sobrienunsigned int"} that has as much precision as @code{long long unsigned 168790075Sobrienint}. 1688132718Skan@end defmac 168990075Sobrien 1690132718Skan@defmac TARGET_PTRMEMFUNC_VBIT_LOCATION 169190075SobrienThe C++ compiler represents a pointer-to-member-function with a struct 169290075Sobrienthat looks like: 169390075Sobrien 1694132718Skan@smallexample 169590075Sobrien struct @{ 169690075Sobrien union @{ 169790075Sobrien void (*fn)(); 169890075Sobrien ptrdiff_t vtable_index; 169990075Sobrien @}; 170090075Sobrien ptrdiff_t delta; 170190075Sobrien @}; 1702132718Skan@end smallexample 170390075Sobrien 170490075Sobrien@noindent 170590075SobrienThe C++ compiler must use one bit to indicate whether the function that 170690075Sobrienwill be called through a pointer-to-member-function is virtual. 170790075SobrienNormally, we assume that the low-order bit of a function pointer must 170890075Sobrienalways be zero. Then, by ensuring that the vtable_index is odd, we can 170990075Sobriendistinguish which variant of the union is in use. But, on some 171090075Sobrienplatforms function pointers can be odd, and so this doesn't work. In 171190075Sobrienthat case, we use the low-order bit of the @code{delta} field, and shift 171290075Sobrienthe remainder of the @code{delta} field to the left. 171390075Sobrien 171490075SobrienGCC will automatically make the right selection about where to store 171590075Sobrienthis bit using the @code{FUNCTION_BOUNDARY} setting for your platform. 171690075SobrienHowever, some platforms such as ARM/Thumb have @code{FUNCTION_BOUNDARY} 171790075Sobrienset such that functions always start at even addresses, but the lowest 171890075Sobrienbit of pointers to functions indicate whether the function at that 171990075Sobrienaddress is in ARM or Thumb mode. If this is the case of your 172090075Sobrienarchitecture, you should define this macro to 172190075Sobrien@code{ptrmemfunc_vbit_in_delta}. 172290075Sobrien 172390075SobrienIn general, you should not have to define this macro. On architectures 172490075Sobrienin which function addresses are always even, according to 172590075Sobrien@code{FUNCTION_BOUNDARY}, GCC will automatically define this macro to 172690075Sobrien@code{ptrmemfunc_vbit_in_pfn}. 1727132718Skan@end defmac 172890075Sobrien 1729132718Skan@defmac TARGET_VTABLE_USES_DESCRIPTORS 173090075SobrienNormally, the C++ compiler uses function pointers in vtables. This 173196263Sobrienmacro allows the target to change to use ``function descriptors'' 173290075Sobrieninstead. Function descriptors are found on targets for whom a 173390075Sobrienfunction pointer is actually a small data structure. Normally the 173496263Sobriendata structure consists of the actual code address plus a data 173590075Sobrienpointer to which the function's data is relative. 173690075Sobrien 173790075SobrienIf vtables are used, the value of this macro should be the number 173890075Sobrienof words that the function descriptor occupies. 1739132718Skan@end defmac 1740117395Skan 1741132718Skan@defmac TARGET_VTABLE_ENTRY_ALIGN 1742117395SkanBy default, the vtable entries are void pointers, the so the alignment 1743117395Skanis the same as pointer alignment. The value of this macro specifies 1744117395Skanthe alignment of the vtable entry in bits. It should be defined only 1745117395Skanwhen special alignment is necessary. */ 1746132718Skan@end defmac 1747117395Skan 1748132718Skan@defmac TARGET_VTABLE_DATA_ENTRY_DISTANCE 1749117395SkanThere are a few non-descriptor entries in the vtable at offsets below 1750117395Skanzero. If these entries must be padded (say, to preserve the alignment 1751117395Skanspecified by @code{TARGET_VTABLE_ENTRY_ALIGN}), set this to the number 1752117395Skanof words in each data entry. 1753132718Skan@end defmac 175490075Sobrien 175590075Sobrien@node Registers 175690075Sobrien@section Register Usage 175790075Sobrien@cindex register usage 175890075Sobrien 175990075SobrienThis section explains how to describe what registers the target machine 176090075Sobrienhas, and how (in general) they can be used. 176190075Sobrien 176290075SobrienThe description of which registers a specific instruction can use is 176390075Sobriendone with register classes; see @ref{Register Classes}. For information 176490075Sobrienon using registers to access a stack frame, see @ref{Frame Registers}. 176590075SobrienFor passing values in registers, see @ref{Register Arguments}. 176690075SobrienFor returning values in registers, see @ref{Scalar Return}. 176790075Sobrien 176890075Sobrien@menu 176990075Sobrien* Register Basics:: Number and kinds of registers. 177090075Sobrien* Allocation Order:: Order in which registers are allocated. 177190075Sobrien* Values in Registers:: What kinds of values each reg can hold. 177290075Sobrien* Leaf Functions:: Renumbering registers for leaf functions. 177390075Sobrien* Stack Registers:: Handling a register stack such as 80387. 177490075Sobrien@end menu 177590075Sobrien 177690075Sobrien@node Register Basics 177790075Sobrien@subsection Basic Characteristics of Registers 177890075Sobrien 177990075Sobrien@c prevent bad page break with this line 178090075SobrienRegisters have various characteristics. 178190075Sobrien 1782132718Skan@defmac FIRST_PSEUDO_REGISTER 178390075SobrienNumber of hardware registers known to the compiler. They receive 178490075Sobriennumbers 0 through @code{FIRST_PSEUDO_REGISTER-1}; thus, the first 178590075Sobrienpseudo register's number really is assigned the number 178690075Sobrien@code{FIRST_PSEUDO_REGISTER}. 1787132718Skan@end defmac 178890075Sobrien 1789132718Skan@defmac FIXED_REGISTERS 179090075Sobrien@cindex fixed register 179190075SobrienAn initializer that says which registers are used for fixed purposes 179290075Sobrienall throughout the compiled code and are therefore not available for 179390075Sobriengeneral allocation. These would include the stack pointer, the frame 179490075Sobrienpointer (except on machines where that can be used as a general 179590075Sobrienregister when no frame pointer is needed), the program counter on 179690075Sobrienmachines where that is considered one of the addressable registers, 179790075Sobrienand any other numbered register with a standard use. 179890075Sobrien 179990075SobrienThis information is expressed as a sequence of numbers, separated by 180090075Sobriencommas and surrounded by braces. The @var{n}th number is 1 if 180190075Sobrienregister @var{n} is fixed, 0 otherwise. 180290075Sobrien 180390075SobrienThe table initialized from this macro, and the table initialized by 180490075Sobrienthe following one, may be overridden at run time either automatically, 180590075Sobrienby the actions of the macro @code{CONDITIONAL_REGISTER_USAGE}, or by 180690075Sobrienthe user with the command options @option{-ffixed-@var{reg}}, 180790075Sobrien@option{-fcall-used-@var{reg}} and @option{-fcall-saved-@var{reg}}. 1808132718Skan@end defmac 180990075Sobrien 1810132718Skan@defmac CALL_USED_REGISTERS 181190075Sobrien@cindex call-used register 181290075Sobrien@cindex call-clobbered register 181390075Sobrien@cindex call-saved register 181490075SobrienLike @code{FIXED_REGISTERS} but has 1 for each register that is 181590075Sobrienclobbered (in general) by function calls as well as for fixed 181690075Sobrienregisters. This macro therefore identifies the registers that are not 181790075Sobrienavailable for general allocation of values that must live across 181890075Sobrienfunction calls. 181990075Sobrien 182090075SobrienIf a register has 0 in @code{CALL_USED_REGISTERS}, the compiler 182190075Sobrienautomatically saves it on function entry and restores it on function 182290075Sobrienexit, if the register is used within the function. 1823132718Skan@end defmac 182490075Sobrien 1825132718Skan@defmac CALL_REALLY_USED_REGISTERS 182690075Sobrien@cindex call-used register 182790075Sobrien@cindex call-clobbered register 182890075Sobrien@cindex call-saved register 182996263SobrienLike @code{CALL_USED_REGISTERS} except this macro doesn't require 183096263Sobrienthat the entire set of @code{FIXED_REGISTERS} be included. 183190075Sobrien(@code{CALL_USED_REGISTERS} must be a superset of @code{FIXED_REGISTERS}). 183296263SobrienThis macro is optional. If not specified, it defaults to the value 183390075Sobrienof @code{CALL_USED_REGISTERS}. 1834132718Skan@end defmac 183590075Sobrien 1836132718Skan@defmac HARD_REGNO_CALL_PART_CLOBBERED (@var{regno}, @var{mode}) 183790075Sobrien@cindex call-used register 183890075Sobrien@cindex call-clobbered register 183990075Sobrien@cindex call-saved register 184090075SobrienA C expression that is nonzero if it is not permissible to store a 184190075Sobrienvalue of mode @var{mode} in hard register number @var{regno} across a 184290075Sobriencall without some part of it being clobbered. For most machines this 184390075Sobrienmacro need not be defined. It is only required for machines that do not 184490075Sobrienpreserve the entire contents of a register across a call. 1845132718Skan@end defmac 184690075Sobrien 184790075Sobrien@findex fixed_regs 184890075Sobrien@findex call_used_regs 1849132718Skan@findex global_regs 1850132718Skan@findex reg_names 1851132718Skan@findex reg_class_contents 1852132718Skan@defmac CONDITIONAL_REGISTER_USAGE 185390075SobrienZero or more C statements that may conditionally modify five variables 185490075Sobrien@code{fixed_regs}, @code{call_used_regs}, @code{global_regs}, 185590075Sobrien@code{reg_names}, and @code{reg_class_contents}, to take into account 185690075Sobrienany dependence of these register sets on target flags. The first three 185790075Sobrienof these are of type @code{char []} (interpreted as Boolean vectors). 185890075Sobrien@code{global_regs} is a @code{const char *[]}, and 185990075Sobrien@code{reg_class_contents} is a @code{HARD_REG_SET}. Before the macro is 186090075Sobriencalled, @code{fixed_regs}, @code{call_used_regs}, 186190075Sobrien@code{reg_class_contents}, and @code{reg_names} have been initialized 186290075Sobrienfrom @code{FIXED_REGISTERS}, @code{CALL_USED_REGISTERS}, 186390075Sobrien@code{REG_CLASS_CONTENTS}, and @code{REGISTER_NAMES}, respectively. 186490075Sobrien@code{global_regs} has been cleared, and any @option{-ffixed-@var{reg}}, 186590075Sobrien@option{-fcall-used-@var{reg}} and @option{-fcall-saved-@var{reg}} 186690075Sobriencommand options have been applied. 186790075Sobrien 186890075SobrienYou need not define this macro if it has no work to do. 186990075Sobrien 187090075Sobrien@cindex disabling certain registers 187190075Sobrien@cindex controlling register usage 187290075SobrienIf the usage of an entire class of registers depends on the target 187390075Sobrienflags, you may indicate this to GCC by using this macro to modify 187490075Sobrien@code{fixed_regs} and @code{call_used_regs} to 1 for each of the 187590075Sobrienregisters in the classes which should not be used by GCC@. Also define 1876132718Skanthe macro @code{REG_CLASS_FROM_LETTER} / @code{REG_CLASS_FROM_CONSTRAINT} 1877132718Skanto return @code{NO_REGS} if it 187890075Sobrienis called with a letter for a class that shouldn't be used. 187990075Sobrien 188090075Sobrien(However, if this class is not included in @code{GENERAL_REGS} and all 188190075Sobrienof the insn patterns whose constraints permit this class are 188290075Sobriencontrolled by target switches, then GCC will automatically avoid using 188390075Sobrienthese registers when the target switches are opposed to them.) 1884132718Skan@end defmac 188590075Sobrien 1886132718Skan@defmac INCOMING_REGNO (@var{out}) 188790075SobrienDefine this macro if the target machine has register windows. This C 188890075Sobrienexpression returns the register number as seen by the called function 188990075Sobriencorresponding to the register number @var{out} as seen by the calling 189090075Sobrienfunction. Return @var{out} if register number @var{out} is not an 189190075Sobrienoutbound register. 1892132718Skan@end defmac 189390075Sobrien 1894132718Skan@defmac OUTGOING_REGNO (@var{in}) 189590075SobrienDefine this macro if the target machine has register windows. This C 189690075Sobrienexpression returns the register number as seen by the calling function 189790075Sobriencorresponding to the register number @var{in} as seen by the called 189890075Sobrienfunction. Return @var{in} if register number @var{in} is not an inbound 189990075Sobrienregister. 1900132718Skan@end defmac 190190075Sobrien 1902132718Skan@defmac LOCAL_REGNO (@var{regno}) 190390075SobrienDefine this macro if the target machine has register windows. This C 190490075Sobrienexpression returns true if the register is call-saved but is in the 190590075Sobrienregister window. Unlike most call-saved registers, such registers 190690075Sobrienneed not be explicitly restored on function exit or during non-local 190790075Sobriengotos. 1908132718Skan@end defmac 190990075Sobrien 1910132718Skan@defmac PC_REGNUM 191190075SobrienIf the program counter has a register number, define this as that 191290075Sobrienregister number. Otherwise, do not define it. 1913132718Skan@end defmac 191490075Sobrien 191590075Sobrien@node Allocation Order 191690075Sobrien@subsection Order of Allocation of Registers 191790075Sobrien@cindex order of register allocation 191890075Sobrien@cindex register allocation order 191990075Sobrien 192090075Sobrien@c prevent bad page break with this line 192190075SobrienRegisters are allocated in order. 192290075Sobrien 1923132718Skan@defmac REG_ALLOC_ORDER 192490075SobrienIf defined, an initializer for a vector of integers, containing the 192590075Sobriennumbers of hard registers in the order in which GCC should prefer 192690075Sobriento use them (from most preferred to least). 192790075Sobrien 192890075SobrienIf this macro is not defined, registers are used lowest numbered first 192990075Sobrien(all else being equal). 193090075Sobrien 193190075SobrienOne use of this macro is on machines where the highest numbered 193290075Sobrienregisters must always be saved and the save-multiple-registers 193390075Sobrieninstruction supports only sequences of consecutive registers. On such 193490075Sobrienmachines, define @code{REG_ALLOC_ORDER} to be an initializer that lists 193590075Sobrienthe highest numbered allocable register first. 1936132718Skan@end defmac 193790075Sobrien 1938132718Skan@defmac ORDER_REGS_FOR_LOCAL_ALLOC 193990075SobrienA C statement (sans semicolon) to choose the order in which to allocate 194090075Sobrienhard registers for pseudo-registers local to a basic block. 194190075Sobrien 194290075SobrienStore the desired register order in the array @code{reg_alloc_order}. 194390075SobrienElement 0 should be the register to allocate first; element 1, the next 194490075Sobrienregister; and so on. 194590075Sobrien 194690075SobrienThe macro body should not assume anything about the contents of 194790075Sobrien@code{reg_alloc_order} before execution of the macro. 194890075Sobrien 194990075SobrienOn most machines, it is not necessary to define this macro. 1950132718Skan@end defmac 195190075Sobrien 195290075Sobrien@node Values in Registers 195390075Sobrien@subsection How Values Fit in Registers 195490075Sobrien 195590075SobrienThis section discusses the macros that describe which kinds of values 195690075Sobrien(specifically, which machine modes) each register can hold, and how many 195790075Sobrienconsecutive registers are needed for a given mode. 195890075Sobrien 1959132718Skan@defmac HARD_REGNO_NREGS (@var{regno}, @var{mode}) 196090075SobrienA C expression for the number of consecutive hard registers, starting 196190075Sobrienat register number @var{regno}, required to hold a value of mode 196290075Sobrien@var{mode}. 196390075Sobrien 196490075SobrienOn a machine where all registers are exactly one word, a suitable 196590075Sobriendefinition of this macro is 196690075Sobrien 196790075Sobrien@smallexample 196890075Sobrien#define HARD_REGNO_NREGS(REGNO, MODE) \ 196990075Sobrien ((GET_MODE_SIZE (MODE) + UNITS_PER_WORD - 1) \ 197090075Sobrien / UNITS_PER_WORD) 197190075Sobrien@end smallexample 1972132718Skan@end defmac 197390075Sobrien 1974169689Skan@defmac HARD_REGNO_NREGS_HAS_PADDING (@var{regno}, @var{mode}) 1975169689SkanA C expression that is nonzero if a value of mode @var{mode}, stored 1976169689Skanin memory, ends with padding that causes it to take up more space than 1977169689Skanin registers starting at register number @var{regno} (as determined by 1978169689Skanmultiplying GCC's notion of the size of the register when containing 1979169689Skanthis mode by the number of registers returned by 1980169689Skan@code{HARD_REGNO_NREGS}). By default this is zero. 1981169689Skan 1982169689SkanFor example, if a floating-point value is stored in three 32-bit 1983169689Skanregisters but takes up 128 bits in memory, then this would be 1984169689Skannonzero. 1985169689Skan 1986169689SkanThis macros only needs to be defined if there are cases where 1987169689Skan@code{subreg_regno_offset} and @code{subreg_offset_representable_p} 1988169689Skanwould otherwise wrongly determine that a @code{subreg} can be 1989169689Skanrepresented by an offset to the register number, when in fact such a 1990169689Skan@code{subreg} would contain some of the padding not stored in 1991169689Skanregisters and so not be representable. 1992169689Skan@end defmac 1993169689Skan 1994169689Skan@defmac HARD_REGNO_NREGS_WITH_PADDING (@var{regno}, @var{mode}) 1995169689SkanFor values of @var{regno} and @var{mode} for which 1996169689Skan@code{HARD_REGNO_NREGS_HAS_PADDING} returns nonzero, a C expression 1997169689Skanreturning the greater number of registers required to hold the value 1998169689Skanincluding any padding. In the example above, the value would be four. 1999169689Skan@end defmac 2000169689Skan 2001132718Skan@defmac REGMODE_NATURAL_SIZE (@var{mode}) 2002132718SkanDefine this macro if the natural size of registers that hold values 2003132718Skanof mode @var{mode} is not the word size. It is a C expression that 2004132718Skanshould give the natural size in bytes for the specified mode. It is 2005132718Skanused by the register allocator to try to optimize its results. This 2006132718Skanhappens for example on SPARC 64-bit where the natural size of 2007132718Skanfloating-point registers is still 32-bit. 2008132718Skan@end defmac 2009132718Skan 2010132718Skan@defmac HARD_REGNO_MODE_OK (@var{regno}, @var{mode}) 201190075SobrienA C expression that is nonzero if it is permissible to store a value 201290075Sobrienof mode @var{mode} in hard register number @var{regno} (or in several 201390075Sobrienregisters starting with that one). For a machine where all registers 201490075Sobrienare equivalent, a suitable definition is 201590075Sobrien 201690075Sobrien@smallexample 201790075Sobrien#define HARD_REGNO_MODE_OK(REGNO, MODE) 1 201890075Sobrien@end smallexample 201990075Sobrien 202090075SobrienYou need not include code to check for the numbers of fixed registers, 202190075Sobrienbecause the allocation mechanism considers them to be always occupied. 202290075Sobrien 202390075Sobrien@cindex register pairs 202490075SobrienOn some machines, double-precision values must be kept in even/odd 202590075Sobrienregister pairs. You can implement that by defining this macro to reject 202690075Sobrienodd register numbers for such modes. 202790075Sobrien 202890075SobrienThe minimum requirement for a mode to be OK in a register is that the 202990075Sobrien@samp{mov@var{mode}} instruction pattern support moves between the 203090075Sobrienregister and other hard register in the same class and that moving a 203190075Sobrienvalue into the register and back out not alter it. 203290075Sobrien 203390075SobrienSince the same instruction used to move @code{word_mode} will work for 203490075Sobrienall narrower integer modes, it is not necessary on any machine for 203590075Sobrien@code{HARD_REGNO_MODE_OK} to distinguish between these modes, provided 203690075Sobrienyou define patterns @samp{movhi}, etc., to take advantage of this. This 203790075Sobrienis useful because of the interaction between @code{HARD_REGNO_MODE_OK} 203890075Sobrienand @code{MODES_TIEABLE_P}; it is very desirable for all integer modes 203990075Sobriento be tieable. 204090075Sobrien 204190075SobrienMany machines have special registers for floating point arithmetic. 204290075SobrienOften people assume that floating point machine modes are allowed only 204390075Sobrienin floating point registers. This is not true. Any registers that 204490075Sobriencan hold integers can safely @emph{hold} a floating point machine 204590075Sobrienmode, whether or not floating arithmetic can be done on it in those 204690075Sobrienregisters. Integer move instructions can be used to move the values. 204790075Sobrien 204890075SobrienOn some machines, though, the converse is true: fixed-point machine 204990075Sobrienmodes may not go in floating registers. This is true if the floating 205090075Sobrienregisters normalize any value stored in them, because storing a 205190075Sobriennon-floating value there would garble it. In this case, 205290075Sobrien@code{HARD_REGNO_MODE_OK} should reject fixed-point machine modes in 205390075Sobrienfloating registers. But if the floating registers do not automatically 205490075Sobriennormalize, if you can store any bit pattern in one and retrieve it 205590075Sobrienunchanged without a trap, then any machine mode may go in a floating 205690075Sobrienregister, so you can define this macro to say so. 205790075Sobrien 205890075SobrienThe primary significance of special floating registers is rather that 205990075Sobrienthey are the registers acceptable in floating point arithmetic 206090075Sobrieninstructions. However, this is of no concern to 206190075Sobrien@code{HARD_REGNO_MODE_OK}. You handle it by writing the proper 206290075Sobrienconstraints for those instructions. 206390075Sobrien 206490075SobrienOn some machines, the floating registers are especially slow to access, 206590075Sobrienso that it is better to store a value in a stack frame than in such a 206690075Sobrienregister if floating point arithmetic is not being done. As long as the 206790075Sobrienfloating registers are not in class @code{GENERAL_REGS}, they will not 206890075Sobrienbe used unless some pattern's constraint asks for one. 2069132718Skan@end defmac 207090075Sobrien 2071169689Skan@defmac HARD_REGNO_RENAME_OK (@var{from}, @var{to}) 2072169689SkanA C expression that is nonzero if it is OK to rename a hard register 2073169689Skan@var{from} to another hard register @var{to}. 2074169689Skan 2075169689SkanOne common use of this macro is to prevent renaming of a register to 2076169689Skananother register that is not saved by a prologue in an interrupt 2077169689Skanhandler. 2078169689Skan 2079169689SkanThe default is always nonzero. 2080169689Skan@end defmac 2081169689Skan 2082132718Skan@defmac MODES_TIEABLE_P (@var{mode1}, @var{mode2}) 208390075SobrienA C expression that is nonzero if a value of mode 208490075Sobrien@var{mode1} is accessible in mode @var{mode2} without copying. 208590075Sobrien 208690075SobrienIf @code{HARD_REGNO_MODE_OK (@var{r}, @var{mode1})} and 208790075Sobrien@code{HARD_REGNO_MODE_OK (@var{r}, @var{mode2})} are always the same for 208890075Sobrienany @var{r}, then @code{MODES_TIEABLE_P (@var{mode1}, @var{mode2})} 208990075Sobrienshould be nonzero. If they differ for any @var{r}, you should define 209090075Sobrienthis macro to return zero unless some other mechanism ensures the 209190075Sobrienaccessibility of the value in a narrower mode. 209290075Sobrien 209390075SobrienYou should define this macro to return nonzero in as many cases as 209490075Sobrienpossible since doing so will allow GCC to perform better register 209590075Sobrienallocation. 2096132718Skan@end defmac 209790075Sobrien 2098132718Skan@defmac AVOID_CCMODE_COPIES 209990075SobrienDefine this macro if the compiler should avoid copies to/from @code{CCmode} 210090075Sobrienregisters. You should only define this macro if support for copying to/from 210190075Sobrien@code{CCmode} is incomplete. 2102132718Skan@end defmac 210390075Sobrien 210490075Sobrien@node Leaf Functions 210590075Sobrien@subsection Handling Leaf Functions 210690075Sobrien 210790075Sobrien@cindex leaf functions 210890075Sobrien@cindex functions, leaf 210990075SobrienOn some machines, a leaf function (i.e., one which makes no calls) can run 211090075Sobrienmore efficiently if it does not make its own register window. Often this 211190075Sobrienmeans it is required to receive its arguments in the registers where they 211290075Sobrienare passed by the caller, instead of the registers where they would 211390075Sobriennormally arrive. 211490075Sobrien 211590075SobrienThe special treatment for leaf functions generally applies only when 211690075Sobrienother conditions are met; for example, often they may use only those 211790075Sobrienregisters for its own variables and temporaries. We use the term ``leaf 211890075Sobrienfunction'' to mean a function that is suitable for this special 211990075Sobrienhandling, so that functions with no calls are not necessarily ``leaf 212090075Sobrienfunctions''. 212190075Sobrien 212290075SobrienGCC assigns register numbers before it knows whether the function is 212390075Sobriensuitable for leaf function treatment. So it needs to renumber the 212490075Sobrienregisters in order to output a leaf function. The following macros 212590075Sobrienaccomplish this. 212690075Sobrien 2127132718Skan@defmac LEAF_REGISTERS 212890075SobrienName of a char vector, indexed by hard register number, which 212990075Sobriencontains 1 for a register that is allowable in a candidate for leaf 213090075Sobrienfunction treatment. 213190075Sobrien 213290075SobrienIf leaf function treatment involves renumbering the registers, then the 213390075Sobrienregisters marked here should be the ones before renumbering---those that 213490075SobrienGCC would ordinarily allocate. The registers which will actually be 213590075Sobrienused in the assembler code, after renumbering, should not be marked with 1 213690075Sobrienin this vector. 213790075Sobrien 213890075SobrienDefine this macro only if the target machine offers a way to optimize 213990075Sobrienthe treatment of leaf functions. 2140132718Skan@end defmac 214190075Sobrien 2142132718Skan@defmac LEAF_REG_REMAP (@var{regno}) 214390075SobrienA C expression whose value is the register number to which @var{regno} 214490075Sobrienshould be renumbered, when a function is treated as a leaf function. 214590075Sobrien 214690075SobrienIf @var{regno} is a register number which should not appear in a leaf 214790075Sobrienfunction before renumbering, then the expression should yield @minus{}1, which 214890075Sobrienwill cause the compiler to abort. 214990075Sobrien 215090075SobrienDefine this macro only if the target machine offers a way to optimize the 215190075Sobrientreatment of leaf functions, and registers need to be renumbered to do 215290075Sobrienthis. 2153132718Skan@end defmac 215490075Sobrien 215590075Sobrien@findex current_function_is_leaf 215690075Sobrien@findex current_function_uses_only_leaf_regs 215790075Sobrien@code{TARGET_ASM_FUNCTION_PROLOGUE} and 215890075Sobrien@code{TARGET_ASM_FUNCTION_EPILOGUE} must usually treat leaf functions 215990075Sobrienspecially. They can test the C variable @code{current_function_is_leaf} 216090075Sobrienwhich is nonzero for leaf functions. @code{current_function_is_leaf} is 216190075Sobrienset prior to local register allocation and is valid for the remaining 216290075Sobriencompiler passes. They can also test the C variable 216390075Sobrien@code{current_function_uses_only_leaf_regs} which is nonzero for leaf 216490075Sobrienfunctions which only use leaf registers. 2165169689Skan@code{current_function_uses_only_leaf_regs} is valid after all passes 2166169689Skanthat modify the instructions have been run and is only useful if 2167169689Skan@code{LEAF_REGISTERS} is defined. 216890075Sobrien@c changed this to fix overfull. ALSO: why the "it" at the beginning 216990075Sobrien@c of the next paragraph?! --mew 2feb93 217090075Sobrien 217190075Sobrien@node Stack Registers 217290075Sobrien@subsection Registers That Form a Stack 217390075Sobrien 217490075SobrienThere are special features to handle computers where some of the 2175132718Skan``registers'' form a stack. Stack registers are normally written by 2176132718Skanpushing onto the stack, and are numbered relative to the top of the 2177132718Skanstack. 217890075Sobrien 217990075SobrienCurrently, GCC can only handle one group of stack-like registers, and 2180132718Skanthey must be consecutively numbered. Furthermore, the existing 2181132718Skansupport for stack-like registers is specific to the 80387 floating 2182132718Skanpoint coprocessor. If you have a new architecture that uses 2183132718Skanstack-like registers, you will need to do substantial work on 2184132718Skan@file{reg-stack.c} and write your machine description to cooperate 2185132718Skanwith it, as well as defining these macros. 218690075Sobrien 2187132718Skan@defmac STACK_REGS 218890075SobrienDefine this if the machine has any stack-like registers. 2189132718Skan@end defmac 219090075Sobrien 2191132718Skan@defmac FIRST_STACK_REG 219290075SobrienThe number of the first stack-like register. This one is the top 219390075Sobrienof the stack. 2194132718Skan@end defmac 219590075Sobrien 2196132718Skan@defmac LAST_STACK_REG 219790075SobrienThe number of the last stack-like register. This one is the bottom of 219890075Sobrienthe stack. 2199132718Skan@end defmac 220090075Sobrien 220190075Sobrien@node Register Classes 220290075Sobrien@section Register Classes 220390075Sobrien@cindex register class definitions 220490075Sobrien@cindex class definitions, register 220590075Sobrien 220690075SobrienOn many machines, the numbered registers are not all equivalent. 220790075SobrienFor example, certain registers may not be allowed for indexed addressing; 220890075Sobriencertain registers may not be allowed in some instructions. These machine 220990075Sobrienrestrictions are described to the compiler using @dfn{register classes}. 221090075Sobrien 221190075SobrienYou define a number of register classes, giving each one a name and saying 221290075Sobrienwhich of the registers belong to it. Then you can specify register classes 221390075Sobrienthat are allowed as operands to particular instruction patterns. 221490075Sobrien 221590075Sobrien@findex ALL_REGS 221690075Sobrien@findex NO_REGS 221790075SobrienIn general, each register will belong to several classes. In fact, one 221890075Sobrienclass must be named @code{ALL_REGS} and contain all the registers. Another 221990075Sobrienclass must be named @code{NO_REGS} and contain no registers. Often the 222090075Sobrienunion of two classes will be another class; however, this is not required. 222190075Sobrien 222290075Sobrien@findex GENERAL_REGS 222390075SobrienOne of the classes must be named @code{GENERAL_REGS}. There is nothing 222490075Sobrienterribly special about the name, but the operand constraint letters 222590075Sobrien@samp{r} and @samp{g} specify this class. If @code{GENERAL_REGS} is 222690075Sobrienthe same as @code{ALL_REGS}, just define it as a macro which expands 222790075Sobriento @code{ALL_REGS}. 222890075Sobrien 222990075SobrienOrder the classes so that if class @var{x} is contained in class @var{y} 223090075Sobrienthen @var{x} has a lower class number than @var{y}. 223190075Sobrien 223290075SobrienThe way classes other than @code{GENERAL_REGS} are specified in operand 223390075Sobrienconstraints is through machine-dependent operand constraint letters. 223490075SobrienYou can define such letters to correspond to various classes, then use 223590075Sobrienthem in operand constraints. 223690075Sobrien 223790075SobrienYou should define a class for the union of two classes whenever some 223890075Sobrieninstruction allows both classes. For example, if an instruction allows 223990075Sobrieneither a floating point (coprocessor) register or a general register for a 224090075Sobriencertain operand, you should define a class @code{FLOAT_OR_GENERAL_REGS} 224190075Sobrienwhich includes both of them. Otherwise you will get suboptimal code. 224290075Sobrien 224390075SobrienYou must also specify certain redundant information about the register 224490075Sobrienclasses: for each class, which classes contain it and which ones are 224590075Sobriencontained in it; for each pair of classes, the largest class contained 224690075Sobrienin their union. 224790075Sobrien 224890075SobrienWhen a value occupying several consecutive registers is expected in a 224990075Sobriencertain class, all the registers used must belong to that class. 225090075SobrienTherefore, register classes cannot be used to enforce a requirement for 225190075Sobriena register pair to start with an even-numbered register. The way to 225290075Sobrienspecify this requirement is with @code{HARD_REGNO_MODE_OK}. 225390075Sobrien 225490075SobrienRegister classes used for input-operands of bitwise-and or shift 225590075Sobrieninstructions have a special requirement: each such class must have, for 225690075Sobrieneach fixed-point machine mode, a subclass whose registers can transfer that 225790075Sobrienmode to or from memory. For example, on some machines, the operations for 225890075Sobriensingle-byte values (@code{QImode}) are limited to certain registers. When 225990075Sobrienthis is so, each register class that is used in a bitwise-and or shift 226090075Sobrieninstruction must have a subclass consisting of registers from which 226190075Sobriensingle-byte values can be loaded or stored. This is so that 226290075Sobrien@code{PREFERRED_RELOAD_CLASS} can always have a possible value to return. 226390075Sobrien 2264132718Skan@deftp {Data type} {enum reg_class} 2265132718SkanAn enumerated type that must be defined with all the register class names 2266132718Skanas enumerated values. @code{NO_REGS} must be first. @code{ALL_REGS} 2267132718Skanmust be the last register class, followed by one more enumerated value, 226890075Sobrien@code{LIM_REG_CLASSES}, which is not a register class but rather 226990075Sobrientells how many classes there are. 227090075Sobrien 227190075SobrienEach register class has a number, which is the value of casting 227290075Sobrienthe class name to type @code{int}. The number serves as an index 227390075Sobrienin many of the tables described below. 2274132718Skan@end deftp 227590075Sobrien 2276132718Skan@defmac N_REG_CLASSES 227790075SobrienThe number of distinct register classes, defined as follows: 227890075Sobrien 2279132718Skan@smallexample 228090075Sobrien#define N_REG_CLASSES (int) LIM_REG_CLASSES 2281132718Skan@end smallexample 2282132718Skan@end defmac 228390075Sobrien 2284132718Skan@defmac REG_CLASS_NAMES 228590075SobrienAn initializer containing the names of the register classes as C string 228690075Sobrienconstants. These names are used in writing some of the debugging dumps. 2287132718Skan@end defmac 228890075Sobrien 2289132718Skan@defmac REG_CLASS_CONTENTS 229090075SobrienAn initializer containing the contents of the register classes, as integers 229190075Sobrienwhich are bit masks. The @var{n}th integer specifies the contents of class 229290075Sobrien@var{n}. The way the integer @var{mask} is interpreted is that 229390075Sobrienregister @var{r} is in the class if @code{@var{mask} & (1 << @var{r})} is 1. 229490075Sobrien 229590075SobrienWhen the machine has more than 32 registers, an integer does not suffice. 229690075SobrienThen the integers are replaced by sub-initializers, braced groupings containing 229790075Sobrienseveral integers. Each sub-initializer must be suitable as an initializer 229890075Sobrienfor the type @code{HARD_REG_SET} which is defined in @file{hard-reg-set.h}. 229990075SobrienIn this situation, the first integer in each sub-initializer corresponds to 230090075Sobrienregisters 0 through 31, the second integer to registers 32 through 63, and 230190075Sobrienso on. 2302132718Skan@end defmac 230390075Sobrien 2304132718Skan@defmac REGNO_REG_CLASS (@var{regno}) 230590075SobrienA C expression whose value is a register class containing hard register 230690075Sobrien@var{regno}. In general there is more than one such class; choose a class 230790075Sobrienwhich is @dfn{minimal}, meaning that no smaller class also contains the 230890075Sobrienregister. 2309132718Skan@end defmac 231090075Sobrien 2311132718Skan@defmac BASE_REG_CLASS 231290075SobrienA macro whose definition is the name of the class to which a valid 231390075Sobrienbase register must belong. A base register is one used in an address 231490075Sobrienwhich is the register value plus a displacement. 2315132718Skan@end defmac 231690075Sobrien 2317132718Skan@defmac MODE_BASE_REG_CLASS (@var{mode}) 231890075SobrienThis is a variation of the @code{BASE_REG_CLASS} macro which allows 2319117395Skanthe selection of a base register in a mode dependent manner. If 232090075Sobrien@var{mode} is VOIDmode then it should return the same value as 232190075Sobrien@code{BASE_REG_CLASS}. 2322132718Skan@end defmac 232390075Sobrien 2324169689Skan@defmac MODE_BASE_REG_REG_CLASS (@var{mode}) 2325169689SkanA C expression whose value is the register class to which a valid 2326169689Skanbase register must belong in order to be used in a base plus index 2327169689Skanregister address. You should define this macro if base plus index 2328169689Skanaddresses have different requirements than other base register uses. 2329169689Skan@end defmac 2330169689Skan 2331169689Skan@defmac MODE_CODE_BASE_REG_CLASS (@var{mode}, @var{outer_code}, @var{index_code}) 2332169689SkanA C expression whose value is the register class to which a valid 2333169689Skanbase register must belong. @var{outer_code} and @var{index_code} define the 2334169689Skancontext in which the base register occurs. @var{outer_code} is the code of 2335169689Skanthe immediately enclosing expression (@code{MEM} for the top level of an 2336169689Skanaddress, @code{ADDRESS} for something that occurs in an 2337169689Skan@code{address_operand}). @var{index_code} is the code of the corresponding 2338169689Skanindex expression if @var{outer_code} is @code{PLUS}; @code{SCRATCH} otherwise. 2339169689Skan@end defmac 2340169689Skan 2341132718Skan@defmac INDEX_REG_CLASS 234290075SobrienA macro whose definition is the name of the class to which a valid 234390075Sobrienindex register must belong. An index register is one used in an 234490075Sobrienaddress where its value is either multiplied by a scale factor or 234590075Sobrienadded to another register (as well as added to a displacement). 2346132718Skan@end defmac 234790075Sobrien 2348132718Skan@defmac REGNO_OK_FOR_BASE_P (@var{num}) 234990075SobrienA C expression which is nonzero if register number @var{num} is 235090075Sobriensuitable for use as a base register in operand addresses. It may be 235190075Sobrieneither a suitable hard register or a pseudo register that has been 235290075Sobrienallocated such a hard register. 2353132718Skan@end defmac 235490075Sobrien 2355132718Skan@defmac REGNO_MODE_OK_FOR_BASE_P (@var{num}, @var{mode}) 235690075SobrienA C expression that is just like @code{REGNO_OK_FOR_BASE_P}, except that 235790075Sobrienthat expression may examine the mode of the memory reference in 235890075Sobrien@var{mode}. You should define this macro if the mode of the memory 235990075Sobrienreference affects whether a register may be used as a base register. If 236090075Sobrienyou define this macro, the compiler will use it instead of 2361169689Skan@code{REGNO_OK_FOR_BASE_P}. The mode may be @code{VOIDmode} for addresses 2362169689Skanthat appear outside a @code{MEM}, i.e. as an @code{address_operand}. 2363169689Skan 2364132718Skan@end defmac 236590075Sobrien 2366169689Skan@defmac REGNO_MODE_OK_FOR_REG_BASE_P (@var{num}, @var{mode}) 2367169689SkanA C expression which is nonzero if register number @var{num} is suitable for 2368169689Skanuse as a base register in base plus index operand addresses, accessing 2369169689Skanmemory in mode @var{mode}. It may be either a suitable hard register or a 2370169689Skanpseudo register that has been allocated such a hard register. You should 2371169689Skandefine this macro if base plus index addresses have different requirements 2372169689Skanthan other base register uses. 2373169689Skan 2374169689SkanUse of this macro is deprecated; please use the more general 2375169689Skan@code{REGNO_MODE_CODE_OK_FOR_BASE_P}. 2376169689Skan@end defmac 2377169689Skan 2378169689Skan@defmac REGNO_MODE_CODE_OK_FOR_BASE_P (@var{num}, @var{mode}, @var{outer_code}, @var{index_code}) 2379169689SkanA C expression that is just like @code{REGNO_MODE_OK_FOR_BASE_P}, except that 2380169689Skanthat expression may examine the context in which the register appears in the 2381169689Skanmemory reference. @var{outer_code} is the code of the immediately enclosing 2382169689Skanexpression (@code{MEM} if at the top level of the address, @code{ADDRESS} for 2383169689Skansomething that occurs in an @code{address_operand}). @var{index_code} is the 2384169689Skancode of the corresponding index expression if @var{outer_code} is @code{PLUS}; 2385169689Skan@code{SCRATCH} otherwise. The mode may be @code{VOIDmode} for addresses 2386169689Skanthat appear outside a @code{MEM}, i.e. as an @code{address_operand}. 2387169689Skan@end defmac 2388169689Skan 2389132718Skan@defmac REGNO_OK_FOR_INDEX_P (@var{num}) 239090075SobrienA C expression which is nonzero if register number @var{num} is 239190075Sobriensuitable for use as an index register in operand addresses. It may be 239290075Sobrieneither a suitable hard register or a pseudo register that has been 239390075Sobrienallocated such a hard register. 239490075Sobrien 239590075SobrienThe difference between an index register and a base register is that 239690075Sobrienthe index register may be scaled. If an address involves the sum of 239790075Sobrientwo registers, neither one of them scaled, then either one may be 239890075Sobrienlabeled the ``base'' and the other the ``index''; but whichever 239990075Sobrienlabeling is used must fit the machine's constraints of which registers 240090075Sobrienmay serve in each capacity. The compiler will try both labelings, 240190075Sobrienlooking for one that is valid, and will reload one or both registers 240290075Sobrienonly if neither labeling works. 2403132718Skan@end defmac 240490075Sobrien 2405132718Skan@defmac PREFERRED_RELOAD_CLASS (@var{x}, @var{class}) 240690075SobrienA C expression that places additional restrictions on the register class 240790075Sobriento use when it is necessary to copy value @var{x} into a register in class 240890075Sobrien@var{class}. The value is a register class; perhaps @var{class}, or perhaps 240990075Sobrienanother, smaller class. On many machines, the following definition is 241090075Sobriensafe: 241190075Sobrien 2412132718Skan@smallexample 241390075Sobrien#define PREFERRED_RELOAD_CLASS(X,CLASS) CLASS 2414132718Skan@end smallexample 241590075Sobrien 241690075SobrienSometimes returning a more restrictive class makes better code. For 241790075Sobrienexample, on the 68000, when @var{x} is an integer constant that is in range 241890075Sobrienfor a @samp{moveq} instruction, the value of this macro is always 241990075Sobrien@code{DATA_REGS} as long as @var{class} includes the data registers. 242090075SobrienRequiring a data register guarantees that a @samp{moveq} will be used. 242190075Sobrien 2422132718SkanOne case where @code{PREFERRED_RELOAD_CLASS} must not return 2423132718Skan@var{class} is if @var{x} is a legitimate constant which cannot be 2424132718Skanloaded into some register class. By returning @code{NO_REGS} you can 2425132718Skanforce @var{x} into a memory location. For example, rs6000 can load 2426132718Skanimmediate values into general-purpose registers, but does not have an 2427132718Skaninstruction for loading an immediate value into a floating-point 2428132718Skanregister, so @code{PREFERRED_RELOAD_CLASS} returns @code{NO_REGS} when 2429132718Skan@var{x} is a floating-point constant. If the constant can't be loaded 2430132718Skaninto any kind of register, code generation will be better if 2431132718Skan@code{LEGITIMATE_CONSTANT_P} makes the constant illegitimate instead 2432132718Skanof using @code{PREFERRED_RELOAD_CLASS}. 2433169689Skan 2434169689SkanIf an insn has pseudos in it after register allocation, reload will go 2435169689Skanthrough the alternatives and call repeatedly @code{PREFERRED_RELOAD_CLASS} 2436169689Skanto find the best one. Returning @code{NO_REGS}, in this case, makes 2437169689Skanreload add a @code{!} in front of the constraint: the x86 back-end uses 2438169689Skanthis feature to discourage usage of 387 registers when math is done in 2439169689Skanthe SSE registers (and vice versa). 2440132718Skan@end defmac 244190075Sobrien 2442132718Skan@defmac PREFERRED_OUTPUT_RELOAD_CLASS (@var{x}, @var{class}) 244390075SobrienLike @code{PREFERRED_RELOAD_CLASS}, but for output reloads instead of 244490075Sobrieninput reloads. If you don't define this macro, the default is to use 244590075Sobrien@var{class}, unchanged. 2446169689Skan 2447169689SkanYou can also use @code{PREFERRED_OUTPUT_RELOAD_CLASS} to discourage 2448169689Skanreload from using some alternatives, like @code{PREFERRED_RELOAD_CLASS}. 2449132718Skan@end defmac 245090075Sobrien 2451132718Skan@defmac LIMIT_RELOAD_CLASS (@var{mode}, @var{class}) 245290075SobrienA C expression that places additional restrictions on the register class 245390075Sobriento use when it is necessary to be able to hold a value of mode 245490075Sobrien@var{mode} in a reload register for which class @var{class} would 245590075Sobrienordinarily be used. 245690075Sobrien 245790075SobrienUnlike @code{PREFERRED_RELOAD_CLASS}, this macro should be used when 245890075Sobrienthere are certain modes that simply can't go in certain reload classes. 245990075Sobrien 246090075SobrienThe value is a register class; perhaps @var{class}, or perhaps another, 246190075Sobriensmaller class. 246290075Sobrien 246390075SobrienDon't define this macro unless the target machine has limitations which 246490075Sobrienrequire the macro to do something nontrivial. 2465132718Skan@end defmac 246690075Sobrien 2467169689Skan@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}) 246890075SobrienMany machines have some registers that cannot be copied directly to or 246990075Sobrienfrom memory or even from other types of registers. An example is the 247090075Sobrien@samp{MQ} register, which on most machines, can only be copied to or 2471169689Skanfrom general registers, but not memory. Below, we shall be using the 2472169689Skanterm 'intermediate register' when a move operation cannot be performed 2473169689Skandirectly, but has to be done by copying the source into the intermediate 2474169689Skanregister first, and then copying the intermediate register to the 2475169689Skandestination. An intermediate register always has the same mode as 2476169689Skansource and destination. Since it holds the actual value being copied, 2477169689Skanreload might apply optimizations to re-use an intermediate register 2478169689Skanand eliding the copy from the source when it can determine that the 2479169689Skanintermediate register still holds the required value. 248090075Sobrien 2481169689SkanAnother kind of secondary reload is required on some machines which 2482169689Skanallow copying all registers to and from memory, but require a scratch 2483169689Skanregister for stores to some memory locations (e.g., those with symbolic 2484169689Skanaddress on the RT, and those with certain symbolic address on the SPARC 2485169689Skanwhen compiling PIC)@. Scratch registers need not have the same mode 2486169689Skanas the value being copied, and usually hold a different value that 2487169689Skanthat being copied. Special patterns in the md file are needed to 2488169689Skandescribe how the copy is performed with the help of the scratch register; 2489169689Skanthese patterns also describe the number, register class(es) and mode(s) 2490169689Skanof the scratch register(s). 2491169689Skan 2492169689SkanIn some cases, both an intermediate and a scratch register are required. 2493169689Skan 2494169689SkanFor input reloads, this target hook is called with nonzero @var{in_p}, 2495169689Skanand @var{x} is an rtx that needs to be copied to a register in of class 2496169689Skan@var{reload_class} in @var{reload_mode}. For output reloads, this target 2497169689Skanhook is called with zero @var{in_p}, and a register of class @var{reload_mode} 2498169689Skanneeds to be copied to rtx @var{x} in @var{reload_mode}. 2499169689Skan 2500169689SkanIf copying a register of @var{reload_class} from/to @var{x} requires 2501169689Skanan intermediate register, the hook @code{secondary_reload} should 2502169689Skanreturn the register class required for this intermediate register. 2503169689SkanIf no intermediate register is required, it should return NO_REGS. 2504169689SkanIf more than one intermediate register is required, describe the one 2505169689Skanthat is closest in the copy chain to the reload register. 2506169689Skan 2507169689SkanIf scratch registers are needed, you also have to describe how to 2508169689Skanperform the copy from/to the reload register to/from this 2509169689Skanclosest intermediate register. Or if no intermediate register is 2510169689Skanrequired, but still a scratch register is needed, describe the 2511169689Skancopy from/to the reload register to/from the reload operand @var{x}. 2512169689Skan 2513169689SkanYou do this by setting @code{sri->icode} to the instruction code of a pattern 2514169689Skanin the md file which performs the move. Operands 0 and 1 are the output 2515169689Skanand input of this copy, respectively. Operands from operand 2 onward are 2516169689Skanfor scratch operands. These scratch operands must have a mode, and a 2517169689Skansingle-register-class 2518169689Skan@c [later: or memory] 2519169689Skanoutput constraint. 2520169689Skan 2521169689SkanWhen an intermediate register is used, the @code{secondary_reload} 2522169689Skanhook will be called again to determine how to copy the intermediate 2523169689Skanregister to/from the reload operand @var{x}, so your hook must also 2524169689Skanhave code to handle the register class of the intermediate operand. 2525169689Skan 2526169689Skan@c [For later: maybe we'll allow multi-alternative reload patterns - 2527169689Skan@c the port maintainer could name a mov<mode> pattern that has clobbers - 2528169689Skan@c and match the constraints of input and output to determine the required 2529169689Skan@c alternative. A restriction would be that constraints used to match 2530169689Skan@c against reloads registers would have to be written as register class 2531169689Skan@c constraints, or we need a new target macro / hook that tells us if an 2532169689Skan@c arbitrary constraint can match an unknown register of a given class. 2533169689Skan@c Such a macro / hook would also be useful in other places.] 2534169689Skan 2535169689Skan 2536169689Skan@var{x} might be a pseudo-register or a @code{subreg} of a 2537169689Skanpseudo-register, which could either be in a hard register or in memory. 2538169689SkanUse @code{true_regnum} to find out; it will return @minus{}1 if the pseudo is 2539169689Skanin memory and the hard register number if it is in a register. 2540169689Skan 2541169689SkanScratch operands in memory (constraint @code{"=m"} / @code{"=&m"}) are 2542169689Skancurrently not supported. For the time being, you will have to continue 2543169689Skanto use @code{SECONDARY_MEMORY_NEEDED} for that purpose. 2544169689Skan 2545169689Skan@code{copy_cost} also uses this target hook to find out how values are 2546169689Skancopied. If you want it to include some extra cost for the need to allocate 2547169689Skan(a) scratch register(s), set @code{sri->extra_cost} to the additional cost. 2548169689SkanOr if two dependent moves are supposed to have a lower cost than the sum 2549169689Skanof the individual moves due to expected fortuitous scheduling and/or special 2550169689Skanforwarding logic, you can set @code{sri->extra_cost} to a negative amount. 2551169689Skan@end deftypefn 2552169689Skan 2553169689Skan@defmac SECONDARY_RELOAD_CLASS (@var{class}, @var{mode}, @var{x}) 2554169689Skan@defmacx SECONDARY_INPUT_RELOAD_CLASS (@var{class}, @var{mode}, @var{x}) 2555169689Skan@defmacx SECONDARY_OUTPUT_RELOAD_CLASS (@var{class}, @var{mode}, @var{x}) 2556169689SkanThese macros are obsolete, new ports should use the target hook 2557169689Skan@code{TARGET_SECONDARY_RELOAD} instead. 2558169689Skan 2559169689SkanThese are obsolete macros, replaced by the @code{TARGET_SECONDARY_RELOAD} 2560169689Skantarget hook. Older ports still define these macros to indicate to the 2561169689Skanreload phase that it may 256290075Sobrienneed to allocate at least one register for a reload in addition to the 256390075Sobrienregister to contain the data. Specifically, if copying @var{x} to a 256490075Sobrienregister @var{class} in @var{mode} requires an intermediate register, 2565169689Skanyou were supposed to define @code{SECONDARY_INPUT_RELOAD_CLASS} to return the 256690075Sobrienlargest register class all of whose registers can be used as 256790075Sobrienintermediate registers or scratch registers. 256890075Sobrien 256990075SobrienIf copying a register @var{class} in @var{mode} to @var{x} requires an 257090075Sobrienintermediate or scratch register, @code{SECONDARY_OUTPUT_RELOAD_CLASS} 2571169689Skanwas supposed to be defined be defined to return the largest register 2572169689Skanclass required. If the 2573169689Skanrequirements for input and output reloads were the same, the macro 2574169689Skan@code{SECONDARY_RELOAD_CLASS} should have been used instead of defining both 257590075Sobrienmacros identically. 257690075Sobrien 257790075SobrienThe values returned by these macros are often @code{GENERAL_REGS}. 257890075SobrienReturn @code{NO_REGS} if no spare register is needed; i.e., if @var{x} 257990075Sobriencan be directly copied to or from a register of @var{class} in 258090075Sobrien@var{mode} without requiring a scratch register. Do not define this 258190075Sobrienmacro if it would always return @code{NO_REGS}. 258290075Sobrien 258390075SobrienIf a scratch register is required (either with or without an 2584169689Skanintermediate register), you were supposed to define patterns for 258590075Sobrien@samp{reload_in@var{m}} or @samp{reload_out@var{m}}, as required 2586169689Skan(@pxref{Standard Names}. These patterns, which were normally 258790075Sobrienimplemented with a @code{define_expand}, should be similar to the 258890075Sobrien@samp{mov@var{m}} patterns, except that operand 2 is the scratch 258990075Sobrienregister. 259090075Sobrien 2591169689SkanThese patterns need constraints for the reload register and scratch 2592169689Skanregister that 259390075Sobriencontain a single register class. If the original reload register (whose 259490075Sobrienclass is @var{class}) can meet the constraint given in the pattern, the 259590075Sobrienvalue returned by these macros is used for the class of the scratch 259690075Sobrienregister. Otherwise, two additional reload registers are required. 259790075SobrienTheir classes are obtained from the constraints in the insn pattern. 259890075Sobrien 259990075Sobrien@var{x} might be a pseudo-register or a @code{subreg} of a 260090075Sobrienpseudo-register, which could either be in a hard register or in memory. 260190075SobrienUse @code{true_regnum} to find out; it will return @minus{}1 if the pseudo is 260290075Sobrienin memory and the hard register number if it is in a register. 260390075Sobrien 260490075SobrienThese macros should not be used in the case where a particular class of 260590075Sobrienregisters can only be copied to memory and not to another class of 260690075Sobrienregisters. In that case, secondary reload registers are not needed and 260790075Sobrienwould not be helpful. Instead, a stack location must be used to perform 260890075Sobrienthe copy and the @code{mov@var{m}} pattern should use memory as an 260990075Sobrienintermediate storage. This case often occurs between floating-point and 261090075Sobriengeneral registers. 2611132718Skan@end defmac 261290075Sobrien 2613132718Skan@defmac SECONDARY_MEMORY_NEEDED (@var{class1}, @var{class2}, @var{m}) 261490075SobrienCertain machines have the property that some registers cannot be copied 261590075Sobriento some other registers without using memory. Define this macro on 261690075Sobrienthose machines to be a C expression that is nonzero if objects of mode 261790075Sobrien@var{m} in registers of @var{class1} can only be copied to registers of 261890075Sobrienclass @var{class2} by storing a register of @var{class1} into memory 261990075Sobrienand loading that memory location into a register of @var{class2}. 262090075Sobrien 262190075SobrienDo not define this macro if its value would always be zero. 2622132718Skan@end defmac 262390075Sobrien 2624132718Skan@defmac SECONDARY_MEMORY_NEEDED_RTX (@var{mode}) 262590075SobrienNormally when @code{SECONDARY_MEMORY_NEEDED} is defined, the compiler 262690075Sobrienallocates a stack slot for a memory location needed for register copies. 262790075SobrienIf this macro is defined, the compiler instead uses the memory location 262890075Sobriendefined by this macro. 262990075Sobrien 263090075SobrienDo not define this macro if you do not define 263190075Sobrien@code{SECONDARY_MEMORY_NEEDED}. 2632132718Skan@end defmac 263390075Sobrien 2634132718Skan@defmac SECONDARY_MEMORY_NEEDED_MODE (@var{mode}) 263590075SobrienWhen the compiler needs a secondary memory location to copy between two 263690075Sobrienregisters of mode @var{mode}, it normally allocates sufficient memory to 263790075Sobrienhold a quantity of @code{BITS_PER_WORD} bits and performs the store and 263890075Sobrienload operations in a mode that many bits wide and whose class is the 263990075Sobriensame as that of @var{mode}. 264090075Sobrien 264190075SobrienThis is right thing to do on most machines because it ensures that all 264290075Sobrienbits of the register are copied and prevents accesses to the registers 264390075Sobrienin a narrower mode, which some machines prohibit for floating-point 264490075Sobrienregisters. 264590075Sobrien 264690075SobrienHowever, this default behavior is not correct on some machines, such as 264790075Sobrienthe DEC Alpha, that store short integers in floating-point registers 264890075Sobriendifferently than in integer registers. On those machines, the default 264990075Sobrienwidening will not work correctly and you must define this macro to 265090075Sobriensuppress that widening in some cases. See the file @file{alpha.h} for 265190075Sobriendetails. 265290075Sobrien 265390075SobrienDo not define this macro if you do not define 265490075Sobrien@code{SECONDARY_MEMORY_NEEDED} or if widening @var{mode} to a mode that 265590075Sobrienis @code{BITS_PER_WORD} bits wide is correct for your machine. 2656132718Skan@end defmac 265790075Sobrien 2658132718Skan@defmac SMALL_REGISTER_CLASSES 265990075SobrienOn some machines, it is risky to let hard registers live across arbitrary 266090075Sobrieninsns. Typically, these machines have instructions that require values 266190075Sobriento be in specific registers (like an accumulator), and reload will fail 266290075Sobrienif the required hard register is used for another purpose across such an 266390075Sobrieninsn. 266490075Sobrien 266590075SobrienDefine @code{SMALL_REGISTER_CLASSES} to be an expression with a nonzero 266690075Sobrienvalue on these machines. When this macro has a nonzero value, the 266790075Sobriencompiler will try to minimize the lifetime of hard registers. 266890075Sobrien 266990075SobrienIt is always safe to define this macro with a nonzero value, but if you 267090075Sobrienunnecessarily define it, you will reduce the amount of optimizations 267190075Sobrienthat can be performed in some cases. If you do not define this macro 267290075Sobrienwith a nonzero value when it is required, the compiler will run out of 267390075Sobrienspill registers and print a fatal error message. For most machines, you 267490075Sobrienshould not define this macro at all. 2675132718Skan@end defmac 267690075Sobrien 2677132718Skan@defmac CLASS_LIKELY_SPILLED_P (@var{class}) 267890075SobrienA C expression whose value is nonzero if pseudos that have been assigned 267990075Sobriento registers of class @var{class} would likely be spilled because 268090075Sobrienregisters of @var{class} are needed for spill registers. 268190075Sobrien 268290075SobrienThe default value of this macro returns 1 if @var{class} has exactly one 268390075Sobrienregister and zero otherwise. On most machines, this default should be 268490075Sobrienused. Only define this macro to some other expression if pseudos 268590075Sobrienallocated by @file{local-alloc.c} end up in memory because their hard 268690075Sobrienregisters were needed for spill registers. If this macro returns nonzero 268790075Sobrienfor those classes, those pseudos will only be allocated by 268890075Sobrien@file{global.c}, which knows how to reallocate the pseudo to another 268990075Sobrienregister. If there would not be another register available for 269090075Sobrienreallocation, you should not change the definition of this macro since 269190075Sobrienthe only effect of such a definition would be to slow down register 269290075Sobrienallocation. 2693132718Skan@end defmac 269490075Sobrien 2695132718Skan@defmac CLASS_MAX_NREGS (@var{class}, @var{mode}) 269690075SobrienA C expression for the maximum number of consecutive registers 269790075Sobrienof class @var{class} needed to hold a value of mode @var{mode}. 269890075Sobrien 269990075SobrienThis is closely related to the macro @code{HARD_REGNO_NREGS}. In fact, 270090075Sobrienthe value of the macro @code{CLASS_MAX_NREGS (@var{class}, @var{mode})} 270190075Sobrienshould be the maximum value of @code{HARD_REGNO_NREGS (@var{regno}, 270290075Sobrien@var{mode})} for all @var{regno} values in the class @var{class}. 270390075Sobrien 270490075SobrienThis macro helps control the handling of multiple-word values 270590075Sobrienin the reload pass. 2706132718Skan@end defmac 270790075Sobrien 2708132718Skan@defmac CANNOT_CHANGE_MODE_CLASS (@var{from}, @var{to}, @var{class}) 2709117395SkanIf defined, a C expression that returns nonzero for a @var{class} for which 2710117395Skana change from mode @var{from} to mode @var{to} is invalid. 271190075Sobrien 271290075SobrienFor the example, loading 32-bit integer or floating-point objects into 2713102780Skanfloating-point registers on the Alpha extends them to 64 bits. 271490075SobrienTherefore loading a 64-bit object and then storing it as a 32-bit object 2715102780Skandoes not store the low-order 32 bits, as would be the case for a normal 2716117395Skanregister. Therefore, @file{alpha.h} defines @code{CANNOT_CHANGE_MODE_CLASS} 2717117395Skanas below: 271890075Sobrien 2719132718Skan@smallexample 2720117395Skan#define CANNOT_CHANGE_MODE_CLASS(FROM, TO, CLASS) \ 2721117395Skan (GET_MODE_SIZE (FROM) != GET_MODE_SIZE (TO) \ 2722117395Skan ? reg_classes_intersect_p (FLOAT_REGS, (CLASS)) : 0) 2723132718Skan@end smallexample 2724132718Skan@end defmac 272590075Sobrien 2726169689Skan@node Old Constraints 2727169689Skan@section Obsolete Macros for Defining Constraints 2728169689Skan@cindex defining constraints, obsolete method 2729169689Skan@cindex constraints, defining, obsolete method 273090075Sobrien 2731169689SkanMachine-specific constraints can be defined with these macros instead 2732169689Skanof the machine description constructs described in @ref{Define 2733169689SkanConstraints}. This mechanism is obsolete. New ports should not use 2734169689Skanit; old ports should convert to the new mechanism. 2735169689Skan 2736169689Skan@defmac CONSTRAINT_LEN (@var{char}, @var{str}) 2737169689SkanFor the constraint at the start of @var{str}, which starts with the letter 2738169689Skan@var{c}, return the length. This allows you to have register class / 2739169689Skanconstant / extra constraints that are longer than a single letter; 2740169689Skanyou don't need to define this macro if you can do with single-letter 2741169689Skanconstraints only. The definition of this macro should use 2742169689SkanDEFAULT_CONSTRAINT_LEN for all the characters that you don't want 2743169689Skanto handle specially. 2744169689SkanThere are some sanity checks in genoutput.c that check the constraint lengths 2745169689Skanfor the md file, so you can also use this macro to help you while you are 2746169689Skantransitioning from a byzantine single-letter-constraint scheme: when you 2747169689Skanreturn a negative length for a constraint you want to re-use, genoutput 2748169689Skanwill complain about every instance where it is used in the md file. 2749169689Skan@end defmac 2750169689Skan 2751169689Skan@defmac REG_CLASS_FROM_LETTER (@var{char}) 2752169689SkanA C expression which defines the machine-dependent operand constraint 2753169689Skanletters for register classes. If @var{char} is such a letter, the 2754169689Skanvalue should be the register class corresponding to it. Otherwise, 2755169689Skanthe value should be @code{NO_REGS}. The register letter @samp{r}, 2756169689Skancorresponding to class @code{GENERAL_REGS}, will not be passed 2757169689Skanto this macro; you do not need to handle it. 2758169689Skan@end defmac 2759169689Skan 2760169689Skan@defmac REG_CLASS_FROM_CONSTRAINT (@var{char}, @var{str}) 2761169689SkanLike @code{REG_CLASS_FROM_LETTER}, but you also get the constraint string 2762169689Skanpassed in @var{str}, so that you can use suffixes to distinguish between 2763169689Skandifferent variants. 2764169689Skan@end defmac 2765169689Skan 2766132718Skan@defmac CONST_OK_FOR_LETTER_P (@var{value}, @var{c}) 276790075SobrienA C expression that defines the machine-dependent operand constraint 276890075Sobrienletters (@samp{I}, @samp{J}, @samp{K}, @dots{} @samp{P}) that specify 276990075Sobrienparticular ranges of integer values. If @var{c} is one of those 277090075Sobrienletters, the expression should check that @var{value}, an integer, is in 277190075Sobrienthe appropriate range and return 1 if so, 0 otherwise. If @var{c} is 277290075Sobriennot one of those letters, the value should be 0 regardless of 277390075Sobrien@var{value}. 2774132718Skan@end defmac 277590075Sobrien 2776132718Skan@defmac CONST_OK_FOR_CONSTRAINT_P (@var{value}, @var{c}, @var{str}) 2777132718SkanLike @code{CONST_OK_FOR_LETTER_P}, but you also get the constraint 2778132718Skanstring passed in @var{str}, so that you can use suffixes to distinguish 2779132718Skanbetween different variants. 2780132718Skan@end defmac 2781132718Skan 2782132718Skan@defmac CONST_DOUBLE_OK_FOR_LETTER_P (@var{value}, @var{c}) 278390075SobrienA C expression that defines the machine-dependent operand constraint 278490075Sobrienletters that specify particular ranges of @code{const_double} values 278590075Sobrien(@samp{G} or @samp{H}). 278690075Sobrien 278790075SobrienIf @var{c} is one of those letters, the expression should check that 278890075Sobrien@var{value}, an RTX of code @code{const_double}, is in the appropriate 278990075Sobrienrange and return 1 if so, 0 otherwise. If @var{c} is not one of those 279090075Sobrienletters, the value should be 0 regardless of @var{value}. 279190075Sobrien 279290075Sobrien@code{const_double} is used for all floating-point constants and for 279390075Sobrien@code{DImode} fixed-point constants. A given letter can accept either 279490075Sobrienor both kinds of values. It can use @code{GET_MODE} to distinguish 279590075Sobrienbetween these kinds. 2796132718Skan@end defmac 279790075Sobrien 2798132718Skan@defmac CONST_DOUBLE_OK_FOR_CONSTRAINT_P (@var{value}, @var{c}, @var{str}) 2799132718SkanLike @code{CONST_DOUBLE_OK_FOR_LETTER_P}, but you also get the constraint 2800132718Skanstring passed in @var{str}, so that you can use suffixes to distinguish 2801132718Skanbetween different variants. 2802132718Skan@end defmac 2803132718Skan 2804132718Skan@defmac EXTRA_CONSTRAINT (@var{value}, @var{c}) 280590075SobrienA C expression that defines the optional machine-dependent constraint 280690075Sobrienletters that can be used to segregate specific types of operands, usually 280790075Sobrienmemory references, for the target machine. Any letter that is not 2808132718Skanelsewhere defined and not matched by @code{REG_CLASS_FROM_LETTER} / 2809132718Skan@code{REG_CLASS_FROM_CONSTRAINT} 281090075Sobrienmay be used. Normally this macro will not be defined. 281190075Sobrien 281290075SobrienIf it is required for a particular target machine, it should return 1 281390075Sobrienif @var{value} corresponds to the operand type represented by the 281490075Sobrienconstraint letter @var{c}. If @var{c} is not defined as an extra 281590075Sobrienconstraint, the value returned should be 0 regardless of @var{value}. 281690075Sobrien 281790075SobrienFor example, on the ROMP, load instructions cannot have their output 281890075Sobrienin r0 if the memory reference contains a symbolic address. Constraint 281990075Sobrienletter @samp{Q} is defined as representing a memory address that does 282090075Sobrien@emph{not} contain a symbolic address. An alternative is specified with 282190075Sobriena @samp{Q} constraint on the input and @samp{r} on the output. The next 282290075Sobrienalternative specifies @samp{m} on the input and a register class that 282390075Sobriendoes not include r0 on the output. 2824132718Skan@end defmac 2825117395Skan 2826132718Skan@defmac EXTRA_CONSTRAINT_STR (@var{value}, @var{c}, @var{str}) 2827132718SkanLike @code{EXTRA_CONSTRAINT}, but you also get the constraint string passed 2828132718Skanin @var{str}, so that you can use suffixes to distinguish between different 2829132718Skanvariants. 2830132718Skan@end defmac 2831132718Skan 2832132718Skan@defmac EXTRA_MEMORY_CONSTRAINT (@var{c}, @var{str}) 2833117395SkanA C expression that defines the optional machine-dependent constraint 2834117395Skanletters, amongst those accepted by @code{EXTRA_CONSTRAINT}, that should 2835117395Skanbe treated like memory constraints by the reload pass. 2836117395Skan 2837132718SkanIt should return 1 if the operand type represented by the constraint 2838132718Skanat the start of @var{str}, the first letter of which is the letter @var{c}, 2839132718Skan comprises a subset of all memory references including 2840132718Skanall those whose address is simply a base register. This allows the reload 2841132718Skanpass to reload an operand, if it does not directly correspond to the operand 2842117395Skantype of @var{c}, by copying its address into a base register. 2843117395Skan 2844117395SkanFor example, on the S/390, some instructions do not accept arbitrary 2845117395Skanmemory references, but only those that do not make use of an index 2846117395Skanregister. The constraint letter @samp{Q} is defined via 2847117395Skan@code{EXTRA_CONSTRAINT} as representing a memory address of this type. 2848117395SkanIf the letter @samp{Q} is marked as @code{EXTRA_MEMORY_CONSTRAINT}, 2849117395Skana @samp{Q} constraint can handle any memory operand, because the 2850117395Skanreload pass knows it can be reloaded by copying the memory address 2851117395Skaninto a base register if required. This is analogous to the way 2852117395Skana @samp{o} constraint can handle any memory operand. 2853132718Skan@end defmac 2854117395Skan 2855132718Skan@defmac EXTRA_ADDRESS_CONSTRAINT (@var{c}, @var{str}) 2856117395SkanA C expression that defines the optional machine-dependent constraint 2857132718Skanletters, amongst those accepted by @code{EXTRA_CONSTRAINT} / 2858132718Skan@code{EXTRA_CONSTRAINT_STR}, that should 2859117395Skanbe treated like address constraints by the reload pass. 2860117395Skan 2861132718SkanIt should return 1 if the operand type represented by the constraint 2862132718Skanat the start of @var{str}, which starts with the letter @var{c}, comprises 2863132718Skana subset of all memory addresses including 2864132718Skanall those that consist of just a base register. This allows the reload 2865132718Skanpass to reload an operand, if it does not directly correspond to the operand 2866132718Skantype of @var{str}, by copying it into a base register. 2867117395Skan 2868117395SkanAny constraint marked as @code{EXTRA_ADDRESS_CONSTRAINT} can only 2869132718Skanbe used with the @code{address_operand} predicate. It is treated 2870117395Skananalogously to the @samp{p} constraint. 2871132718Skan@end defmac 287290075Sobrien 287390075Sobrien@node Stack and Calling 287490075Sobrien@section Stack Layout and Calling Conventions 287590075Sobrien@cindex calling conventions 287690075Sobrien 287790075Sobrien@c prevent bad page break with this line 287890075SobrienThis describes the stack layout and calling conventions. 287990075Sobrien 288090075Sobrien@menu 288190075Sobrien* Frame Layout:: 288290075Sobrien* Exception Handling:: 288390075Sobrien* Stack Checking:: 288490075Sobrien* Frame Registers:: 288590075Sobrien* Elimination:: 288690075Sobrien* Stack Arguments:: 288790075Sobrien* Register Arguments:: 288890075Sobrien* Scalar Return:: 288990075Sobrien* Aggregate Return:: 289090075Sobrien* Caller Saves:: 289190075Sobrien* Function Entry:: 289290075Sobrien* Profiling:: 289390075Sobrien* Tail Calls:: 2894169689Skan* Stack Smashing Protection:: 289590075Sobrien@end menu 289690075Sobrien 289790075Sobrien@node Frame Layout 289890075Sobrien@subsection Basic Stack Layout 289990075Sobrien@cindex stack frame layout 290090075Sobrien@cindex frame layout 290190075Sobrien 290290075Sobrien@c prevent bad page break with this line 290390075SobrienHere is the basic stack layout. 290490075Sobrien 2905132718Skan@defmac STACK_GROWS_DOWNWARD 290690075SobrienDefine this macro if pushing a word onto the stack moves the stack 290790075Sobrienpointer to a smaller address. 290890075Sobrien 2909169689SkanWhen we say, ``define this macro if @dots{}'', it means that the 291090075Sobriencompiler checks this macro only with @code{#ifdef} so the precise 291190075Sobriendefinition used does not matter. 2912132718Skan@end defmac 291390075Sobrien 2914132718Skan@defmac STACK_PUSH_CODE 291590075SobrienThis macro defines the operation used when something is pushed 291690075Sobrienon the stack. In RTL, a push operation will be 2917117395Skan@code{(set (mem (STACK_PUSH_CODE (reg sp))) @dots{})} 291890075Sobrien 291990075SobrienThe choices are @code{PRE_DEC}, @code{POST_DEC}, @code{PRE_INC}, 292090075Sobrienand @code{POST_INC}. Which of these is correct depends on 292190075Sobrienthe stack direction and on whether the stack pointer points 292290075Sobriento the last item on the stack or whether it points to the 292390075Sobrienspace for the next item on the stack. 292490075Sobrien 292590075SobrienThe default is @code{PRE_DEC} when @code{STACK_GROWS_DOWNWARD} is 292690075Sobriendefined, which is almost always right, and @code{PRE_INC} otherwise, 292790075Sobrienwhich is often wrong. 2928132718Skan@end defmac 292990075Sobrien 2930132718Skan@defmac FRAME_GROWS_DOWNWARD 2931169689SkanDefine this macro to nonzero value if the addresses of local variable slots 2932169689Skanare at negative offsets from the frame pointer. 2933132718Skan@end defmac 293490075Sobrien 2935132718Skan@defmac ARGS_GROW_DOWNWARD 293690075SobrienDefine this macro if successive arguments to a function occupy decreasing 293790075Sobrienaddresses on the stack. 2938132718Skan@end defmac 293990075Sobrien 2940132718Skan@defmac STARTING_FRAME_OFFSET 294190075SobrienOffset from the frame pointer to the first local variable slot to be allocated. 294290075Sobrien 294390075SobrienIf @code{FRAME_GROWS_DOWNWARD}, find the next slot's offset by 294490075Sobriensubtracting the first slot's length from @code{STARTING_FRAME_OFFSET}. 294590075SobrienOtherwise, it is found by adding the length of the first slot to the 294690075Sobrienvalue @code{STARTING_FRAME_OFFSET}. 294790075Sobrien@c i'm not sure if the above is still correct.. had to change it to get 294890075Sobrien@c rid of an overfull. --mew 2feb93 2949132718Skan@end defmac 295090075Sobrien 2951132718Skan@defmac STACK_ALIGNMENT_NEEDED 2952132718SkanDefine to zero to disable final alignment of the stack during reload. 2953132718SkanThe nonzero default for this macro is suitable for most ports. 2954132718Skan 2955132718SkanOn ports where @code{STARTING_FRAME_OFFSET} is nonzero or where there 2956132718Skanis a register save block following the local block that doesn't require 2957132718Skanalignment to @code{STACK_BOUNDARY}, it may be beneficial to disable 2958132718Skanstack alignment and do it in the backend. 2959132718Skan@end defmac 2960132718Skan 2961132718Skan@defmac STACK_POINTER_OFFSET 296290075SobrienOffset from the stack pointer register to the first location at which 296390075Sobrienoutgoing arguments are placed. If not specified, the default value of 296490075Sobrienzero is used. This is the proper value for most machines. 296590075Sobrien 296690075SobrienIf @code{ARGS_GROW_DOWNWARD}, this is the offset to the location above 296790075Sobrienthe first location at which outgoing arguments are placed. 2968132718Skan@end defmac 296990075Sobrien 2970132718Skan@defmac FIRST_PARM_OFFSET (@var{fundecl}) 297190075SobrienOffset from the argument pointer register to the first argument's 297290075Sobrienaddress. On some machines it may depend on the data type of the 297390075Sobrienfunction. 297490075Sobrien 297590075SobrienIf @code{ARGS_GROW_DOWNWARD}, this is the offset to the location above 297690075Sobrienthe first argument's address. 2977132718Skan@end defmac 297890075Sobrien 2979132718Skan@defmac STACK_DYNAMIC_OFFSET (@var{fundecl}) 298090075SobrienOffset from the stack pointer register to an item dynamically allocated 298190075Sobrienon the stack, e.g., by @code{alloca}. 298290075Sobrien 298390075SobrienThe default value for this macro is @code{STACK_POINTER_OFFSET} plus the 298490075Sobrienlength of the outgoing arguments. The default is correct for most 298590075Sobrienmachines. See @file{function.c} for details. 2986132718Skan@end defmac 298790075Sobrien 2988169689Skan@defmac INITIAL_FRAME_ADDRESS_RTX 2989169689SkanA C expression whose value is RTL representing the address of the initial 2990169689Skanstack frame. This address is passed to @code{RETURN_ADDR_RTX} and 2991169689Skan@code{DYNAMIC_CHAIN_ADDRESS}. If you don't define this macro, a reasonable 2992169689Skandefault value will be used. Define this macro in order to make frame pointer 2993169689Skanelimination work in the presence of @code{__builtin_frame_address (count)} and 2994169689Skan@code{__builtin_return_address (count)} for @code{count} not equal to zero. 2995169689Skan@end defmac 2996169689Skan 2997132718Skan@defmac DYNAMIC_CHAIN_ADDRESS (@var{frameaddr}) 299890075SobrienA C expression whose value is RTL representing the address in a stack 299990075Sobrienframe where the pointer to the caller's frame is stored. Assume that 300090075Sobrien@var{frameaddr} is an RTL expression for the address of the stack frame 300190075Sobrienitself. 300290075Sobrien 300390075SobrienIf you don't define this macro, the default is to return the value 300490075Sobrienof @var{frameaddr}---that is, the stack frame address is also the 300590075Sobrienaddress of the stack word that points to the previous frame. 3006132718Skan@end defmac 300790075Sobrien 3008132718Skan@defmac SETUP_FRAME_ADDRESSES 300990075SobrienIf defined, a C expression that produces the machine-specific code to 301090075Sobriensetup the stack so that arbitrary frames can be accessed. For example, 3011117395Skanon the SPARC, we must flush all of the register windows to the stack 301290075Sobrienbefore we can access arbitrary stack frames. You will seldom need to 301390075Sobriendefine this macro. 3014132718Skan@end defmac 301590075Sobrien 3016169689Skan@deftypefn {Target Hook} bool TARGET_BUILTIN_SETJMP_FRAME_VALUE () 3017169689SkanThis target hook should return an rtx that is used to store 301890075Sobrienthe address of the current frame into the built in @code{setjmp} buffer. 301990075SobrienThe default value, @code{virtual_stack_vars_rtx}, is correct for most 3020169689Skanmachines. One reason you may need to define this target hook is if 302190075Sobrien@code{hard_frame_pointer_rtx} is the appropriate value on your machine. 3022169689Skan@end deftypefn 3023169689Skan 3024169689Skan@defmac FRAME_ADDR_RTX (@var{frameaddr}) 3025169689SkanA C expression whose value is RTL representing the value of the frame 3026169689Skanaddress for the current frame. @var{frameaddr} is the frame pointer 3027169689Skanof the current frame. This is used for __builtin_frame_address. 3028169689SkanYou need only define this macro if the frame address is not the same 3029169689Skanas the frame pointer. Most machines do not need to define it. 3030132718Skan@end defmac 303190075Sobrien 3032132718Skan@defmac RETURN_ADDR_RTX (@var{count}, @var{frameaddr}) 303390075SobrienA C expression whose value is RTL representing the value of the return 303490075Sobrienaddress for the frame @var{count} steps up from the current frame, after 303590075Sobrienthe prologue. @var{frameaddr} is the frame pointer of the @var{count} 303690075Sobrienframe, or the frame pointer of the @var{count} @minus{} 1 frame if 303790075Sobrien@code{RETURN_ADDR_IN_PREVIOUS_FRAME} is defined. 303890075Sobrien 303990075SobrienThe value of the expression must always be the correct address when 304090075Sobrien@var{count} is zero, but may be @code{NULL_RTX} if there is not way to 304190075Sobriendetermine the return address of other frames. 3042132718Skan@end defmac 304390075Sobrien 3044132718Skan@defmac RETURN_ADDR_IN_PREVIOUS_FRAME 304590075SobrienDefine this if the return address of a particular stack frame is accessed 304690075Sobrienfrom the frame pointer of the previous stack frame. 3047132718Skan@end defmac 304890075Sobrien 3049132718Skan@defmac INCOMING_RETURN_ADDR_RTX 305090075SobrienA C expression whose value is RTL representing the location of the 305190075Sobrienincoming return address at the beginning of any function, before the 305290075Sobrienprologue. This RTL is either a @code{REG}, indicating that the return 305390075Sobrienvalue is saved in @samp{REG}, or a @code{MEM} representing a location in 305490075Sobrienthe stack. 305590075Sobrien 305690075SobrienYou only need to define this macro if you want to support call frame 305790075Sobriendebugging information like that provided by DWARF 2. 305890075Sobrien 305990075SobrienIf this RTL is a @code{REG}, you should also define 306090075Sobrien@code{DWARF_FRAME_RETURN_COLUMN} to @code{DWARF_FRAME_REGNUM (REGNO)}. 3061132718Skan@end defmac 306290075Sobrien 3063132718Skan@defmac DWARF_ALT_FRAME_RETURN_COLUMN 3064132718SkanA C expression whose value is an integer giving a DWARF 2 column 3065132718Skannumber that may be used as an alternate return column. This should 3066132718Skanbe defined only if @code{DWARF_FRAME_RETURN_COLUMN} is set to a 3067132718Skangeneral register, but an alternate column needs to be used for 3068132718Skansignal frames. 3069132718Skan@end defmac 3070132718Skan 3071146895Skan@defmac DWARF_ZERO_REG 3072146895SkanA C expression whose value is an integer giving a DWARF 2 register 3073146895Skannumber that is considered to always have the value zero. This should 3074146895Skanonly be defined if the target has an architected zero register, and 3075146895Skansomeone decided it was a good idea to use that register number to 3076146895Skanterminate the stack backtrace. New ports should avoid this. 3077146895Skan@end defmac 3078146895Skan 3079169689Skan@deftypefn {Target Hook} void TARGET_DWARF_HANDLE_FRAME_UNSPEC (const char *@var{label}, rtx @var{pattern}, int @var{index}) 3080169689SkanThis target hook allows the backend to emit frame-related insns that 3081169689Skancontain UNSPECs or UNSPEC_VOLATILEs. The DWARF 2 call frame debugging 3082169689Skaninfo engine will invoke it on insns of the form 3083169689Skan@smallexample 3084169689Skan(set (reg) (unspec [...] UNSPEC_INDEX)) 3085169689Skan@end smallexample 3086169689Skanand 3087169689Skan@smallexample 3088169689Skan(set (reg) (unspec_volatile [...] UNSPECV_INDEX)). 3089169689Skan@end smallexample 3090169689Skanto let the backend emit the call frame instructions. @var{label} is 3091169689Skanthe CFI label attached to the insn, @var{pattern} is the pattern of 3092169689Skanthe insn and @var{index} is @code{UNSPEC_INDEX} or @code{UNSPECV_INDEX}. 3093169689Skan@end deftypefn 3094169689Skan 3095132718Skan@defmac INCOMING_FRAME_SP_OFFSET 309690075SobrienA C expression whose value is an integer giving the offset, in bytes, 309790075Sobrienfrom the value of the stack pointer register to the top of the stack 309890075Sobrienframe at the beginning of any function, before the prologue. The top of 309990075Sobrienthe frame is defined to be the value of the stack pointer in the 310090075Sobrienprevious frame, just before the call instruction. 310190075Sobrien 310290075SobrienYou only need to define this macro if you want to support call frame 310390075Sobriendebugging information like that provided by DWARF 2. 3104132718Skan@end defmac 310590075Sobrien 3106132718Skan@defmac ARG_POINTER_CFA_OFFSET (@var{fundecl}) 310790075SobrienA C expression whose value is an integer giving the offset, in bytes, 310890075Sobrienfrom the argument pointer to the canonical frame address (cfa). The 310990075Sobrienfinal value should coincide with that calculated by 311090075Sobrien@code{INCOMING_FRAME_SP_OFFSET}. Which is unfortunately not usable 311190075Sobrienduring virtual register instantiation. 311290075Sobrien 311390075SobrienThe default value for this macro is @code{FIRST_PARM_OFFSET (fundecl)}, 311490075Sobrienwhich is correct for most machines; in general, the arguments are found 311590075Sobrienimmediately before the stack frame. Note that this is not the case on 311690075Sobriensome targets that save registers into the caller's frame, such as SPARC 311790075Sobrienand rs6000, and so such targets need to define this macro. 311890075Sobrien 311990075SobrienYou only need to define this macro if the default is incorrect, and you 312090075Sobrienwant to support call frame debugging information like that provided by 312190075SobrienDWARF 2. 3122132718Skan@end defmac 312390075Sobrien 3124169689Skan@defmac FRAME_POINTER_CFA_OFFSET (@var{fundecl}) 3125169689SkanIf defined, a C expression whose value is an integer giving the offset 3126169689Skanin bytes from the frame pointer to the canonical frame address (cfa). 3127169689SkanThe final value should coincide with that calculated by 3128169689Skan@code{INCOMING_FRAME_SP_OFFSET}. 3129169689Skan 3130169689SkanNormally the CFA is calculated as an offset from the argument pointer, 3131169689Skanvia @code{ARG_POINTER_CFA_OFFSET}, but if the argument pointer is 3132169689Skanvariable due to the ABI, this may not be possible. If this macro is 3133169689Skandefined, it implies that the virtual register instantiation should be 3134169689Skanbased on the frame pointer instead of the argument pointer. Only one 3135169689Skanof @code{FRAME_POINTER_CFA_OFFSET} and @code{ARG_POINTER_CFA_OFFSET} 3136169689Skanshould be defined. 3137169689Skan@end defmac 3138169689Skan 3139169689Skan@defmac CFA_FRAME_BASE_OFFSET (@var{fundecl}) 3140169689SkanIf defined, a C expression whose value is an integer giving the offset 3141169689Skanin bytes from the canonical frame address (cfa) to the frame base used 3142169689Skanin DWARF 2 debug information. The default is zero. A different value 3143169689Skanmay reduce the size of debug information on some ports. 3144169689Skan@end defmac 3145169689Skan 314690075Sobrien@node Exception Handling 314790075Sobrien@subsection Exception Handling Support 314890075Sobrien@cindex exception handling 314990075Sobrien 3150132718Skan@defmac EH_RETURN_DATA_REGNO (@var{N}) 315190075SobrienA C expression whose value is the @var{N}th register number used for 315290075Sobriendata by exception handlers, or @code{INVALID_REGNUM} if fewer than 315390075Sobrien@var{N} registers are usable. 315490075Sobrien 315590075SobrienThe exception handling library routines communicate with the exception 315690075Sobrienhandlers via a set of agreed upon registers. Ideally these registers 315790075Sobrienshould be call-clobbered; it is possible to use call-saved registers, 315890075Sobrienbut may negatively impact code size. The target must support at least 315990075Sobrien2 data registers, but should define 4 if there are enough free registers. 316090075Sobrien 316190075SobrienYou must define this macro if you want to support call frame exception 316290075Sobrienhandling like that provided by DWARF 2. 3163132718Skan@end defmac 316490075Sobrien 3165132718Skan@defmac EH_RETURN_STACKADJ_RTX 316690075SobrienA C expression whose value is RTL representing a location in which 316790075Sobriento store a stack adjustment to be applied before function return. 316890075SobrienThis is used to unwind the stack to an exception handler's call frame. 316990075SobrienIt will be assigned zero on code paths that return normally. 317090075Sobrien 317190075SobrienTypically this is a call-clobbered hard register that is otherwise 317290075Sobrienuntouched by the epilogue, but could also be a stack slot. 317390075Sobrien 3174117395SkanDo not define this macro if the stack pointer is saved and restored 3175132718Skanby the regular prolog and epilog code in the call frame itself; in 3176132718Skanthis case, the exception handling library routines will update the 3177132718Skanstack location to be restored in place. Otherwise, you must define 3178132718Skanthis macro if you want to support call frame exception handling like 3179117395Skanthat provided by DWARF 2. 3180132718Skan@end defmac 318190075Sobrien 3182132718Skan@defmac EH_RETURN_HANDLER_RTX 318390075SobrienA C expression whose value is RTL representing a location in which 318490075Sobriento store the address of an exception handler to which we should 318590075Sobrienreturn. It will not be assigned on code paths that return normally. 318690075Sobrien 318790075SobrienTypically this is the location in the call frame at which the normal 318890075Sobrienreturn address is stored. For targets that return by popping an 318990075Sobrienaddress off the stack, this might be a memory address just below 319090075Sobrienthe @emph{target} call frame rather than inside the current call 3191132718Skanframe. If defined, @code{EH_RETURN_STACKADJ_RTX} will have already 3192132718Skanbeen assigned, so it may be used to calculate the location of the 3193117395Skantarget call frame. 319490075Sobrien 319590075SobrienSome targets have more complex requirements than storing to an 319690075Sobrienaddress calculable during initial code generation. In that case 319790075Sobrienthe @code{eh_return} instruction pattern should be used instead. 319890075Sobrien 319990075SobrienIf you want to support call frame exception handling, you must 320090075Sobriendefine either this macro or the @code{eh_return} instruction pattern. 3201132718Skan@end defmac 320290075Sobrien 3203132718Skan@defmac RETURN_ADDR_OFFSET 3204132718SkanIf defined, an integer-valued C expression for which rtl will be generated 3205132718Skanto add it to the exception handler address before it is searched in the 3206132718Skanexception handling tables, and to subtract it again from the address before 3207132718Skanusing it to return to the exception handler. 3208132718Skan@end defmac 3209132718Skan 3210132718Skan@defmac ASM_PREFERRED_EH_DATA_FORMAT (@var{code}, @var{global}) 321190075SobrienThis macro chooses the encoding of pointers embedded in the exception 321290075Sobrienhandling sections. If at all possible, this should be defined such 321390075Sobrienthat the exception handling section will not require dynamic relocations, 321490075Sobrienand so may be read-only. 321590075Sobrien 321690075Sobrien@var{code} is 0 for data, 1 for code labels, 2 for function pointers. 321790075Sobrien@var{global} is true if the symbol may be affected by dynamic relocations. 321890075SobrienThe macro should return a combination of the @code{DW_EH_PE_*} defines 321990075Sobrienas found in @file{dwarf2.h}. 322090075Sobrien 322190075SobrienIf this macro is not defined, pointers will not be encoded but 322290075Sobrienrepresented directly. 3223132718Skan@end defmac 322490075Sobrien 3225132718Skan@defmac ASM_MAYBE_OUTPUT_ENCODED_ADDR_RTX (@var{file}, @var{encoding}, @var{size}, @var{addr}, @var{done}) 322690075SobrienThis macro allows the target to emit whatever special magic is required 322790075Sobriento represent the encoding chosen by @code{ASM_PREFERRED_EH_DATA_FORMAT}. 322890075SobrienGeneric code takes care of pc-relative and indirect encodings; this must 322990075Sobrienbe defined if the target uses text-relative or data-relative encodings. 323090075Sobrien 323190075SobrienThis is a C statement that branches to @var{done} if the format was 323290075Sobrienhandled. @var{encoding} is the format chosen, @var{size} is the number 323390075Sobrienof bytes that the format occupies, @var{addr} is the @code{SYMBOL_REF} 323490075Sobriento be emitted. 3235132718Skan@end defmac 323690075Sobrien 3237169689Skan@defmac MD_UNWIND_SUPPORT 3238169689SkanA string specifying a file to be #include'd in unwind-dw2.c. The file 3239169689Skanso included typically defines @code{MD_FALLBACK_FRAME_STATE_FOR}. 3240169689Skan@end defmac 3241169689Skan 3242169689Skan@defmac MD_FALLBACK_FRAME_STATE_FOR (@var{context}, @var{fs}) 324390075SobrienThis macro allows the target to add cpu and operating system specific 324490075Sobriencode to the call-frame unwinder for use when there is no unwind data 324590075Sobrienavailable. The most common reason to implement this macro is to unwind 324690075Sobrienthrough signal frames. 324790075Sobrien 324890075SobrienThis macro is called from @code{uw_frame_state_for} in @file{unwind-dw2.c} 324990075Sobrienand @file{unwind-ia64.c}. @var{context} is an @code{_Unwind_Context}; 325090075Sobrien@var{fs} is an @code{_Unwind_FrameState}. Examine @code{context->ra} 325190075Sobrienfor the address of the code being executed and @code{context->cfa} for 325290075Sobrienthe stack pointer value. If the frame can be decoded, the register save 3253169689Skanaddresses should be updated in @var{fs} and the macro should evaluate to 3254169689Skan@code{_URC_NO_REASON}. If the frame cannot be decoded, the macro should 3255169689Skanevaluate to @code{_URC_END_OF_STACK}. 325690075Sobrien 3257132718SkanFor proper signal handling in Java this macro is accompanied by 3258132718Skan@code{MAKE_THROW_FRAME}, defined in @file{libjava/include/*-signal.h} headers. 3259132718Skan@end defmac 3260132718Skan 3261132718Skan@defmac MD_HANDLE_UNWABI (@var{context}, @var{fs}) 3262132718SkanThis macro allows the target to add operating system specific code to the 3263132718Skancall-frame unwinder to handle the IA-64 @code{.unwabi} unwinding directive, 3264132718Skanusually used for signal or interrupt frames. 3265132718Skan 3266132718SkanThis macro is called from @code{uw_update_context} in @file{unwind-ia64.c}. 3267132718Skan@var{context} is an @code{_Unwind_Context}; 3268132718Skan@var{fs} is an @code{_Unwind_FrameState}. Examine @code{fs->unwabi} 3269132718Skanfor the abi and context in the @code{.unwabi} directive. If the 3270132718Skan@code{.unwabi} directive can be handled, the register save addresses should 3271132718Skanbe updated in @var{fs}. 3272132718Skan@end defmac 3273132718Skan 3274169689Skan@defmac TARGET_USES_WEAK_UNWIND_INFO 3275169689SkanA C expression that evaluates to true if the target requires unwind 3276169689Skaninfo to be given comdat linkage. Define it to be @code{1} if comdat 3277169689Skanlinkage is necessary. The default is @code{0}. 3278169689Skan@end defmac 3279169689Skan 328090075Sobrien@node Stack Checking 328190075Sobrien@subsection Specifying How Stack Checking is Done 328290075Sobrien 328390075SobrienGCC will check that stack references are within the boundaries of 328490075Sobrienthe stack, if the @option{-fstack-check} is specified, in one of three ways: 328590075Sobrien 328690075Sobrien@enumerate 328790075Sobrien@item 328890075SobrienIf the value of the @code{STACK_CHECK_BUILTIN} macro is nonzero, GCC 328990075Sobrienwill assume that you have arranged for stack checking to be done at 329090075Sobrienappropriate places in the configuration files, e.g., in 329190075Sobrien@code{TARGET_ASM_FUNCTION_PROLOGUE}. GCC will do not other special 329290075Sobrienprocessing. 329390075Sobrien 329490075Sobrien@item 329590075SobrienIf @code{STACK_CHECK_BUILTIN} is zero and you defined a named pattern 329690075Sobriencalled @code{check_stack} in your @file{md} file, GCC will call that 329790075Sobrienpattern with one argument which is the address to compare the stack 329890075Sobrienvalue against. You must arrange for this pattern to report an error if 329990075Sobrienthe stack pointer is out of range. 330090075Sobrien 330190075Sobrien@item 330290075SobrienIf neither of the above are true, GCC will generate code to periodically 330390075Sobrien``probe'' the stack pointer using the values of the macros defined below. 330490075Sobrien@end enumerate 330590075Sobrien 330690075SobrienNormally, you will use the default values of these macros, so GCC 330790075Sobrienwill use the third approach. 330890075Sobrien 3309132718Skan@defmac STACK_CHECK_BUILTIN 331090075SobrienA nonzero value if stack checking is done by the configuration files in a 331190075Sobrienmachine-dependent manner. You should define this macro if stack checking 331290075Sobrienis require by the ABI of your machine or if you would like to have to stack 331390075Sobrienchecking in some more efficient way than GCC's portable approach. 331490075SobrienThe default value of this macro is zero. 3315132718Skan@end defmac 331690075Sobrien 3317132718Skan@defmac STACK_CHECK_PROBE_INTERVAL 331890075SobrienAn integer representing the interval at which GCC must generate stack 331990075Sobrienprobe instructions. You will normally define this macro to be no larger 332090075Sobrienthan the size of the ``guard pages'' at the end of a stack area. The 332190075Sobriendefault value of 4096 is suitable for most systems. 3322132718Skan@end defmac 332390075Sobrien 3324132718Skan@defmac STACK_CHECK_PROBE_LOAD 332590075SobrienA integer which is nonzero if GCC should perform the stack probe 332690075Sobrienas a load instruction and zero if GCC should use a store instruction. 332790075SobrienThe default is zero, which is the most efficient choice on most systems. 3328132718Skan@end defmac 332990075Sobrien 3330132718Skan@defmac STACK_CHECK_PROTECT 333190075SobrienThe number of bytes of stack needed to recover from a stack overflow, 333290075Sobrienfor languages where such a recovery is supported. The default value of 333390075Sobrien75 words should be adequate for most machines. 3334132718Skan@end defmac 333590075Sobrien 3336132718Skan@defmac STACK_CHECK_MAX_FRAME_SIZE 333790075SobrienThe maximum size of a stack frame, in bytes. GCC will generate probe 333890075Sobrieninstructions in non-leaf functions to ensure at least this many bytes of 333990075Sobrienstack are available. If a stack frame is larger than this size, stack 334090075Sobrienchecking will not be reliable and GCC will issue a warning. The 334190075Sobriendefault is chosen so that GCC only generates one instruction on most 334290075Sobriensystems. You should normally not change the default value of this macro. 3343132718Skan@end defmac 334490075Sobrien 3345132718Skan@defmac STACK_CHECK_FIXED_FRAME_SIZE 334690075SobrienGCC uses this value to generate the above warning message. It 334790075Sobrienrepresents the amount of fixed frame used by a function, not including 334890075Sobrienspace for any callee-saved registers, temporaries and user variables. 334990075SobrienYou need only specify an upper bound for this amount and will normally 335090075Sobrienuse the default of four words. 3351132718Skan@end defmac 335290075Sobrien 3353132718Skan@defmac STACK_CHECK_MAX_VAR_SIZE 335490075SobrienThe maximum size, in bytes, of an object that GCC will place in the 335590075Sobrienfixed area of the stack frame when the user specifies 335690075Sobrien@option{-fstack-check}. 335790075SobrienGCC computed the default from the values of the above macros and you will 335890075Sobriennormally not need to override that default. 3359132718Skan@end defmac 336090075Sobrien 336190075Sobrien@need 2000 336290075Sobrien@node Frame Registers 336390075Sobrien@subsection Registers That Address the Stack Frame 336490075Sobrien 336590075Sobrien@c prevent bad page break with this line 336690075SobrienThis discusses registers that address the stack frame. 336790075Sobrien 3368132718Skan@defmac STACK_POINTER_REGNUM 336990075SobrienThe register number of the stack pointer register, which must also be a 337090075Sobrienfixed register according to @code{FIXED_REGISTERS}. On most machines, 337190075Sobrienthe hardware determines which register this is. 3372132718Skan@end defmac 337390075Sobrien 3374132718Skan@defmac FRAME_POINTER_REGNUM 337590075SobrienThe register number of the frame pointer register, which is used to 337690075Sobrienaccess automatic variables in the stack frame. On some machines, the 337790075Sobrienhardware determines which register this is. On other machines, you can 337890075Sobrienchoose any register you wish for this purpose. 3379132718Skan@end defmac 338090075Sobrien 3381132718Skan@defmac HARD_FRAME_POINTER_REGNUM 338290075SobrienOn some machines the offset between the frame pointer and starting 338390075Sobrienoffset of the automatic variables is not known until after register 338490075Sobrienallocation has been done (for example, because the saved registers are 338590075Sobrienbetween these two locations). On those machines, define 338690075Sobrien@code{FRAME_POINTER_REGNUM} the number of a special, fixed register to 338790075Sobrienbe used internally until the offset is known, and define 338890075Sobrien@code{HARD_FRAME_POINTER_REGNUM} to be the actual hard register number 338990075Sobrienused for the frame pointer. 339090075Sobrien 339190075SobrienYou should define this macro only in the very rare circumstances when it 339290075Sobrienis not possible to calculate the offset between the frame pointer and 339390075Sobrienthe automatic variables until after register allocation has been 339490075Sobriencompleted. When this macro is defined, you must also indicate in your 339590075Sobriendefinition of @code{ELIMINABLE_REGS} how to eliminate 339690075Sobrien@code{FRAME_POINTER_REGNUM} into either @code{HARD_FRAME_POINTER_REGNUM} 339790075Sobrienor @code{STACK_POINTER_REGNUM}. 339890075Sobrien 339990075SobrienDo not define this macro if it would be the same as 340090075Sobrien@code{FRAME_POINTER_REGNUM}. 3401132718Skan@end defmac 340290075Sobrien 3403132718Skan@defmac ARG_POINTER_REGNUM 340490075SobrienThe register number of the arg pointer register, which is used to access 340590075Sobrienthe function's argument list. On some machines, this is the same as the 340690075Sobrienframe pointer register. On some machines, the hardware determines which 340790075Sobrienregister this is. On other machines, you can choose any register you 340890075Sobrienwish for this purpose. If this is not the same register as the frame 340990075Sobrienpointer register, then you must mark it as a fixed register according to 341090075Sobrien@code{FIXED_REGISTERS}, or arrange to be able to eliminate it 341190075Sobrien(@pxref{Elimination}). 3412132718Skan@end defmac 341390075Sobrien 3414132718Skan@defmac RETURN_ADDRESS_POINTER_REGNUM 341590075SobrienThe register number of the return address pointer register, which is used to 341690075Sobrienaccess the current function's return address from the stack. On some 341790075Sobrienmachines, the return address is not at a fixed offset from the frame 341890075Sobrienpointer or stack pointer or argument pointer. This register can be defined 341990075Sobriento point to the return address on the stack, and then be converted by 342090075Sobrien@code{ELIMINABLE_REGS} into either the frame pointer or stack pointer. 342190075Sobrien 342290075SobrienDo not define this macro unless there is no other way to get the return 342390075Sobrienaddress from the stack. 3424132718Skan@end defmac 342590075Sobrien 3426132718Skan@defmac STATIC_CHAIN_REGNUM 3427132718Skan@defmacx STATIC_CHAIN_INCOMING_REGNUM 342890075SobrienRegister numbers used for passing a function's static chain pointer. If 342990075Sobrienregister windows are used, the register number as seen by the called 343090075Sobrienfunction is @code{STATIC_CHAIN_INCOMING_REGNUM}, while the register 343190075Sobriennumber as seen by the calling function is @code{STATIC_CHAIN_REGNUM}. If 343290075Sobrienthese registers are the same, @code{STATIC_CHAIN_INCOMING_REGNUM} need 343390075Sobriennot be defined. 343490075Sobrien 343590075SobrienThe static chain register need not be a fixed register. 343690075Sobrien 343790075SobrienIf the static chain is passed in memory, these macros should not be 343890075Sobriendefined; instead, the next two macros should be defined. 3439132718Skan@end defmac 344090075Sobrien 3441132718Skan@defmac STATIC_CHAIN 3442132718Skan@defmacx STATIC_CHAIN_INCOMING 344390075SobrienIf the static chain is passed in memory, these macros provide rtx giving 344490075Sobrien@code{mem} expressions that denote where they are stored. 344590075Sobrien@code{STATIC_CHAIN} and @code{STATIC_CHAIN_INCOMING} give the locations 344690075Sobrienas seen by the calling and called functions, respectively. Often the former 344790075Sobrienwill be at an offset from the stack pointer and the latter at an offset from 344890075Sobrienthe frame pointer. 344990075Sobrien 345090075Sobrien@findex stack_pointer_rtx 345190075Sobrien@findex frame_pointer_rtx 345290075Sobrien@findex arg_pointer_rtx 345390075SobrienThe variables @code{stack_pointer_rtx}, @code{frame_pointer_rtx}, and 345490075Sobrien@code{arg_pointer_rtx} will have been initialized prior to the use of these 345590075Sobrienmacros and should be used to refer to those items. 345690075Sobrien 345790075SobrienIf the static chain is passed in a register, the two previous macros should 345890075Sobrienbe defined instead. 3459132718Skan@end defmac 346090075Sobrien 3461132718Skan@defmac DWARF_FRAME_REGISTERS 346290075SobrienThis macro specifies the maximum number of hard registers that can be 346390075Sobriensaved in a call frame. This is used to size data structures used in 346490075SobrienDWARF2 exception handling. 346590075Sobrien 346690075SobrienPrior to GCC 3.0, this macro was needed in order to establish a stable 346790075Sobrienexception handling ABI in the face of adding new hard registers for ISA 346890075Sobrienextensions. In GCC 3.0 and later, the EH ABI is insulated from changes 346990075Sobrienin the number of hard registers. Nevertheless, this macro can still be 347090075Sobrienused to reduce the runtime memory requirements of the exception handling 347190075Sobrienroutines, which can be substantial if the ISA contains a lot of 347290075Sobrienregisters that are not call-saved. 347390075Sobrien 347490075SobrienIf this macro is not defined, it defaults to 347590075Sobrien@code{FIRST_PSEUDO_REGISTER}. 3476132718Skan@end defmac 347790075Sobrien 3478132718Skan@defmac PRE_GCC3_DWARF_FRAME_REGISTERS 347990075Sobrien 348090075SobrienThis macro is similar to @code{DWARF_FRAME_REGISTERS}, but is provided 348190075Sobrienfor backward compatibility in pre GCC 3.0 compiled code. 348290075Sobrien 348390075SobrienIf this macro is not defined, it defaults to 348490075Sobrien@code{DWARF_FRAME_REGISTERS}. 3485132718Skan@end defmac 348690075Sobrien 3487132718Skan@defmac DWARF_REG_TO_UNWIND_COLUMN (@var{regno}) 348890075Sobrien 3489132718SkanDefine this macro if the target's representation for dwarf registers 3490132718Skanis different than the internal representation for unwind column. 3491132718SkanGiven a dwarf register, this macro should return the internal unwind 3492132718Skancolumn number to use instead. 3493132718Skan 3494132718SkanSee the PowerPC's SPE target for an example. 3495132718Skan@end defmac 3496132718Skan 3497132718Skan@defmac DWARF_FRAME_REGNUM (@var{regno}) 3498132718Skan 3499132718SkanDefine this macro if the target's representation for dwarf registers 3500132718Skanused in .eh_frame or .debug_frame is different from that used in other 3501132718Skandebug info sections. Given a GCC hard register number, this macro 3502132718Skanshould return the .eh_frame register number. The default is 3503132718Skan@code{DBX_REGISTER_NUMBER (@var{regno})}. 3504132718Skan 3505132718Skan@end defmac 3506132718Skan 3507132718Skan@defmac DWARF2_FRAME_REG_OUT (@var{regno}, @var{for_eh}) 3508132718Skan 3509132718SkanDefine this macro to map register numbers held in the call frame info 3510132718Skanthat GCC has collected using @code{DWARF_FRAME_REGNUM} to those that 3511132718Skanshould be output in .debug_frame (@code{@var{for_eh}} is zero) and 3512169689Skan.eh_frame (@code{@var{for_eh}} is nonzero). The default is to 3513132718Skanreturn @code{@var{regno}}. 3514132718Skan 3515132718Skan@end defmac 3516132718Skan 351790075Sobrien@node Elimination 351890075Sobrien@subsection Eliminating Frame Pointer and Arg Pointer 351990075Sobrien 352090075Sobrien@c prevent bad page break with this line 352190075SobrienThis is about eliminating the frame pointer and arg pointer. 352290075Sobrien 3523132718Skan@defmac FRAME_POINTER_REQUIRED 352490075SobrienA C expression which is nonzero if a function must have and use a frame 352590075Sobrienpointer. This expression is evaluated in the reload pass. If its value is 352690075Sobriennonzero the function will have a frame pointer. 352790075Sobrien 352890075SobrienThe expression can in principle examine the current function and decide 352990075Sobrienaccording to the facts, but on most machines the constant 0 or the 353090075Sobrienconstant 1 suffices. Use 0 when the machine allows code to be generated 353190075Sobrienwith no frame pointer, and doing so saves some time or space. Use 1 353290075Sobrienwhen there is no possible advantage to avoiding a frame pointer. 353390075Sobrien 353490075SobrienIn certain cases, the compiler does not know how to produce valid code 353590075Sobrienwithout a frame pointer. The compiler recognizes those cases and 353690075Sobrienautomatically gives the function a frame pointer regardless of what 353790075Sobrien@code{FRAME_POINTER_REQUIRED} says. You don't need to worry about 353890075Sobrienthem. 353990075Sobrien 354090075SobrienIn a function that does not require a frame pointer, the frame pointer 354190075Sobrienregister can be allocated for ordinary usage, unless you mark it as a 354290075Sobrienfixed register. See @code{FIXED_REGISTERS} for more information. 3543132718Skan@end defmac 354490075Sobrien 354590075Sobrien@findex get_frame_size 3546132718Skan@defmac INITIAL_FRAME_POINTER_OFFSET (@var{depth-var}) 354790075SobrienA C statement to store in the variable @var{depth-var} the difference 354890075Sobrienbetween the frame pointer and the stack pointer values immediately after 354990075Sobrienthe function prologue. The value would be computed from information 355090075Sobriensuch as the result of @code{get_frame_size ()} and the tables of 355190075Sobrienregisters @code{regs_ever_live} and @code{call_used_regs}. 355290075Sobrien 355390075SobrienIf @code{ELIMINABLE_REGS} is defined, this macro will be not be used and 355490075Sobrienneed not be defined. Otherwise, it must be defined even if 355590075Sobrien@code{FRAME_POINTER_REQUIRED} is defined to always be true; in that 355690075Sobriencase, you may set @var{depth-var} to anything. 3557132718Skan@end defmac 355890075Sobrien 3559132718Skan@defmac ELIMINABLE_REGS 356090075SobrienIf defined, this macro specifies a table of register pairs used to 356190075Sobrieneliminate unneeded registers that point into the stack frame. If it is not 356290075Sobriendefined, the only elimination attempted by the compiler is to replace 356390075Sobrienreferences to the frame pointer with references to the stack pointer. 356490075Sobrien 356590075SobrienThe definition of this macro is a list of structure initializations, each 356690075Sobrienof which specifies an original and replacement register. 356790075Sobrien 356890075SobrienOn some machines, the position of the argument pointer is not known until 356990075Sobrienthe compilation is completed. In such a case, a separate hard register 357090075Sobrienmust be used for the argument pointer. This register can be eliminated by 357190075Sobrienreplacing it with either the frame pointer or the argument pointer, 357290075Sobriendepending on whether or not the frame pointer has been eliminated. 357390075Sobrien 357490075SobrienIn this case, you might specify: 3575132718Skan@smallexample 357690075Sobrien#define ELIMINABLE_REGS \ 357790075Sobrien@{@{ARG_POINTER_REGNUM, STACK_POINTER_REGNUM@}, \ 357890075Sobrien @{ARG_POINTER_REGNUM, FRAME_POINTER_REGNUM@}, \ 357990075Sobrien @{FRAME_POINTER_REGNUM, STACK_POINTER_REGNUM@}@} 3580132718Skan@end smallexample 358190075Sobrien 358290075SobrienNote that the elimination of the argument pointer with the stack pointer is 358390075Sobrienspecified first since that is the preferred elimination. 3584132718Skan@end defmac 358590075Sobrien 3586132718Skan@defmac CAN_ELIMINATE (@var{from-reg}, @var{to-reg}) 358790075SobrienA C expression that returns nonzero if the compiler is allowed to try 358890075Sobriento replace register number @var{from-reg} with register number 358990075Sobrien@var{to-reg}. This macro need only be defined if @code{ELIMINABLE_REGS} 359090075Sobrienis defined, and will usually be the constant 1, since most of the cases 359190075Sobrienpreventing register elimination are things that the compiler already 359290075Sobrienknows about. 3593132718Skan@end defmac 359490075Sobrien 3595132718Skan@defmac INITIAL_ELIMINATION_OFFSET (@var{from-reg}, @var{to-reg}, @var{offset-var}) 359690075SobrienThis macro is similar to @code{INITIAL_FRAME_POINTER_OFFSET}. It 359790075Sobrienspecifies the initial difference between the specified pair of 359890075Sobrienregisters. This macro must be defined if @code{ELIMINABLE_REGS} is 359990075Sobriendefined. 3600132718Skan@end defmac 360190075Sobrien 360290075Sobrien@node Stack Arguments 360390075Sobrien@subsection Passing Function Arguments on the Stack 360490075Sobrien@cindex arguments on stack 360590075Sobrien@cindex stack arguments 360690075Sobrien 360790075SobrienThe macros in this section control how arguments are passed 360890075Sobrienon the stack. See the following section for other macros that 360990075Sobriencontrol passing certain arguments in registers. 361090075Sobrien 3611132718Skan@deftypefn {Target Hook} bool TARGET_PROMOTE_PROTOTYPES (tree @var{fntype}) 3612132718SkanThis target hook returns @code{true} if an argument declared in a 3613132718Skanprototype as an integral type smaller than @code{int} should actually be 3614132718Skanpassed as an @code{int}. In addition to avoiding errors in certain 3615132718Skancases of mismatch, it also makes for better code on certain machines. 3616132718SkanThe default is to not promote prototypes. 3617132718Skan@end deftypefn 361890075Sobrien 3619132718Skan@defmac PUSH_ARGS 362090075SobrienA C expression. If nonzero, push insns will be used to pass 362190075Sobrienoutgoing arguments. 362290075SobrienIf the target machine does not have a push instruction, set it to zero. 362390075SobrienThat directs GCC to use an alternate strategy: to 362490075Sobrienallocate the entire argument block and then store the arguments into 362590075Sobrienit. When @code{PUSH_ARGS} is nonzero, @code{PUSH_ROUNDING} must be defined too. 3626132718Skan@end defmac 362790075Sobrien 3628132718Skan@defmac PUSH_ARGS_REVERSED 3629132718SkanA C expression. If nonzero, function arguments will be evaluated from 3630132718Skanlast to first, rather than from first to last. If this macro is not 3631132718Skandefined, it defaults to @code{PUSH_ARGS} on targets where the stack 3632132718Skanand args grow in opposite directions, and 0 otherwise. 3633132718Skan@end defmac 3634132718Skan 3635132718Skan@defmac PUSH_ROUNDING (@var{npushed}) 363690075SobrienA C expression that is the number of bytes actually pushed onto the 363790075Sobrienstack when an instruction attempts to push @var{npushed} bytes. 363890075Sobrien 363990075SobrienOn some machines, the definition 364090075Sobrien 3641132718Skan@smallexample 364290075Sobrien#define PUSH_ROUNDING(BYTES) (BYTES) 3643132718Skan@end smallexample 364490075Sobrien 364590075Sobrien@noindent 364690075Sobrienwill suffice. But on other machines, instructions that appear 364790075Sobriento push one byte actually push two bytes in an attempt to maintain 364890075Sobrienalignment. Then the definition should be 364990075Sobrien 3650132718Skan@smallexample 365190075Sobrien#define PUSH_ROUNDING(BYTES) (((BYTES) + 1) & ~1) 3652132718Skan@end smallexample 3653132718Skan@end defmac 365490075Sobrien 365590075Sobrien@findex current_function_outgoing_args_size 3656132718Skan@defmac ACCUMULATE_OUTGOING_ARGS 365790075SobrienA C expression. If nonzero, the maximum amount of space required for outgoing arguments 365890075Sobrienwill be computed and placed into the variable 365990075Sobrien@code{current_function_outgoing_args_size}. No space will be pushed 366090075Sobrienonto the stack for each call; instead, the function prologue should 366190075Sobrienincrease the stack frame size by this amount. 366290075Sobrien 366390075SobrienSetting both @code{PUSH_ARGS} and @code{ACCUMULATE_OUTGOING_ARGS} 366490075Sobrienis not proper. 3665132718Skan@end defmac 366690075Sobrien 3667132718Skan@defmac REG_PARM_STACK_SPACE (@var{fndecl}) 366890075SobrienDefine this macro if functions should assume that stack space has been 366990075Sobrienallocated for arguments even when their values are passed in 367090075Sobrienregisters. 367190075Sobrien 367290075SobrienThe value of this macro is the size, in bytes, of the area reserved for 367390075Sobrienarguments passed in registers for the function represented by @var{fndecl}, 367490075Sobrienwhich can be zero if GCC is calling a library function. 367590075Sobrien 367690075SobrienThis space can be allocated by the caller, or be a part of the 367790075Sobrienmachine-dependent stack frame: @code{OUTGOING_REG_PARM_STACK_SPACE} says 367890075Sobrienwhich. 3679132718Skan@end defmac 368090075Sobrien@c above is overfull. not sure what to do. --mew 5feb93 did 368190075Sobrien@c something, not sure if it looks good. --mew 10feb93 368290075Sobrien 3683132718Skan@defmac OUTGOING_REG_PARM_STACK_SPACE 368490075SobrienDefine this if it is the responsibility of the caller to allocate the area 368590075Sobrienreserved for arguments passed in registers. 368690075Sobrien 368790075SobrienIf @code{ACCUMULATE_OUTGOING_ARGS} is defined, this macro controls 368890075Sobrienwhether the space for these arguments counts in the value of 368990075Sobrien@code{current_function_outgoing_args_size}. 3690132718Skan@end defmac 369190075Sobrien 3692132718Skan@defmac STACK_PARMS_IN_REG_PARM_AREA 369390075SobrienDefine this macro if @code{REG_PARM_STACK_SPACE} is defined, but the 369490075Sobrienstack parameters don't skip the area specified by it. 369590075Sobrien@c i changed this, makes more sens and it should have taken care of the 369690075Sobrien@c overfull.. not as specific, tho. --mew 5feb93 369790075Sobrien 369890075SobrienNormally, when a parameter is not passed in registers, it is placed on the 369990075Sobrienstack beyond the @code{REG_PARM_STACK_SPACE} area. Defining this macro 370090075Sobriensuppresses this behavior and causes the parameter to be passed on the 370190075Sobrienstack in its natural location. 3702132718Skan@end defmac 370390075Sobrien 3704132718Skan@defmac RETURN_POPS_ARGS (@var{fundecl}, @var{funtype}, @var{stack-size}) 370590075SobrienA C expression that should indicate the number of bytes of its own 370690075Sobrienarguments that a function pops on returning, or 0 if the 370790075Sobrienfunction pops no arguments and the caller must therefore pop them all 370890075Sobrienafter the function returns. 370990075Sobrien 371090075Sobrien@var{fundecl} is a C variable whose value is a tree node that describes 371190075Sobrienthe function in question. Normally it is a node of type 371290075Sobrien@code{FUNCTION_DECL} that describes the declaration of the function. 371390075SobrienFrom this you can obtain the @code{DECL_ATTRIBUTES} of the function. 371490075Sobrien 371590075Sobrien@var{funtype} is a C variable whose value is a tree node that 371690075Sobriendescribes the function in question. Normally it is a node of type 371790075Sobrien@code{FUNCTION_TYPE} that describes the data type of the function. 371890075SobrienFrom this it is possible to obtain the data types of the value and 371990075Sobrienarguments (if known). 372090075Sobrien 372190075SobrienWhen a call to a library function is being considered, @var{fundecl} 372290075Sobrienwill contain an identifier node for the library function. Thus, if 372390075Sobrienyou need to distinguish among various library functions, you can do so 372490075Sobrienby their names. Note that ``library function'' in this context means 372590075Sobriena function used to perform arithmetic, whose name is known specially 372690075Sobrienin the compiler and was not mentioned in the C code being compiled. 372790075Sobrien 372890075Sobrien@var{stack-size} is the number of bytes of arguments passed on the 372990075Sobrienstack. If a variable number of bytes is passed, it is zero, and 373090075Sobrienargument popping will always be the responsibility of the calling function. 373190075Sobrien 373290075SobrienOn the VAX, all functions always pop their arguments, so the definition 373390075Sobrienof this macro is @var{stack-size}. On the 68000, using the standard 373490075Sobriencalling convention, no functions pop their arguments, so the value of 373590075Sobrienthe macro is always 0 in this case. But an alternative calling 373690075Sobrienconvention is available in which functions that take a fixed number of 373790075Sobrienarguments pop them but other functions (such as @code{printf}) pop 373890075Sobriennothing (the caller pops all). When this convention is in use, 373990075Sobrien@var{funtype} is examined to determine whether a function takes a fixed 374090075Sobriennumber of arguments. 3741132718Skan@end defmac 374296263Sobrien 3743132718Skan@defmac CALL_POPS_ARGS (@var{cum}) 374496263SobrienA C expression that should indicate the number of bytes a call sequence 374596263Sobrienpops off the stack. It is added to the value of @code{RETURN_POPS_ARGS} 374696263Sobrienwhen compiling a function call. 374796263Sobrien 374896263Sobrien@var{cum} is the variable in which all arguments to the called function 374996263Sobrienhave been accumulated. 375096263Sobrien 375196263SobrienOn certain architectures, such as the SH5, a call trampoline is used 375296263Sobrienthat pops certain registers off the stack, depending on the arguments 375396263Sobrienthat have been passed to the function. Since this is a property of the 375496263Sobriencall site, not of the called function, @code{RETURN_POPS_ARGS} is not 375596263Sobrienappropriate. 3756132718Skan@end defmac 375796263Sobrien 375890075Sobrien@node Register Arguments 375990075Sobrien@subsection Passing Arguments in Registers 376090075Sobrien@cindex arguments in registers 376190075Sobrien@cindex registers arguments 376290075Sobrien 376390075SobrienThis section describes the macros which let you control how various 376490075Sobrientypes of arguments are passed in registers or how they are arranged in 376590075Sobrienthe stack. 376690075Sobrien 3767132718Skan@defmac FUNCTION_ARG (@var{cum}, @var{mode}, @var{type}, @var{named}) 376890075SobrienA C expression that controls whether a function argument is passed 376990075Sobrienin a register, and which register. 377090075Sobrien 377190075SobrienThe arguments are @var{cum}, which summarizes all the previous 377290075Sobrienarguments; @var{mode}, the machine mode of the argument; @var{type}, 377390075Sobrienthe data type of the argument as a tree node or 0 if that is not known 377490075Sobrien(which happens for C support library functions); and @var{named}, 377590075Sobrienwhich is 1 for an ordinary argument and 0 for nameless arguments that 377690075Sobriencorrespond to @samp{@dots{}} in the called function's prototype. 377790075Sobrien@var{type} can be an incomplete type if a syntax error has previously 377890075Sobrienoccurred. 377990075Sobrien 378090075SobrienThe value of the expression is usually either a @code{reg} RTX for the 378190075Sobrienhard register in which to pass the argument, or zero to pass the 378290075Sobrienargument on the stack. 378390075Sobrien 378490075SobrienFor machines like the VAX and 68000, where normally all arguments are 378590075Sobrienpushed, zero suffices as a definition. 378690075Sobrien 378790075SobrienThe value of the expression can also be a @code{parallel} RTX@. This is 378890075Sobrienused when an argument is passed in multiple locations. The mode of the 3789132718Skan@code{parallel} should be the mode of the entire argument. The 379090075Sobrien@code{parallel} holds any number of @code{expr_list} pairs; each one 379190075Sobriendescribes where part of the argument is passed. In each 379290075Sobrien@code{expr_list} the first operand must be a @code{reg} RTX for the hard 379390075Sobrienregister in which to pass this part of the argument, and the mode of the 379490075Sobrienregister RTX indicates how large this part of the argument is. The 379590075Sobriensecond operand of the @code{expr_list} is a @code{const_int} which gives 379690075Sobrienthe offset in bytes into the entire argument of where this part starts. 379790075SobrienAs a special exception the first @code{expr_list} in the @code{parallel} 379890075SobrienRTX may have a first operand of zero. This indicates that the entire 379990075Sobrienargument is also stored on the stack. 380090075Sobrien 380190075SobrienThe last time this macro is called, it is called with @code{MODE == 380290075SobrienVOIDmode}, and its result is passed to the @code{call} or @code{call_value} 380390075Sobrienpattern as operands 2 and 3 respectively. 380490075Sobrien 380590075Sobrien@cindex @file{stdarg.h} and register arguments 380690075SobrienThe usual way to make the ISO library @file{stdarg.h} work on a machine 380790075Sobrienwhere some arguments are usually passed in registers, is to cause 380890075Sobriennameless arguments to be passed on the stack instead. This is done 380990075Sobrienby making @code{FUNCTION_ARG} return 0 whenever @var{named} is 0. 381090075Sobrien 3811169689Skan@cindex @code{TARGET_MUST_PASS_IN_STACK}, and @code{FUNCTION_ARG} 381290075Sobrien@cindex @code{REG_PARM_STACK_SPACE}, and @code{FUNCTION_ARG} 3813169689SkanYou may use the hook @code{targetm.calls.must_pass_in_stack} 381490075Sobrienin the definition of this macro to determine if this argument is of a 381590075Sobrientype that must be passed in the stack. If @code{REG_PARM_STACK_SPACE} 381690075Sobrienis not defined and @code{FUNCTION_ARG} returns nonzero for such an 381790075Sobrienargument, the compiler will abort. If @code{REG_PARM_STACK_SPACE} is 381890075Sobriendefined, the argument will be computed in the stack and then loaded into 381990075Sobriena register. 3820132718Skan@end defmac 382190075Sobrien 3822169689Skan@deftypefn {Target Hook} bool TARGET_MUST_PASS_IN_STACK (enum machine_mode @var{mode}, tree @var{type}) 3823169689SkanThis target hook should return @code{true} if we should not pass @var{type} 3824169689Skansolely in registers. The file @file{expr.h} defines a 382590075Sobriendefinition that is usually appropriate, refer to @file{expr.h} for additional 382690075Sobriendocumentation. 3827169689Skan@end deftypefn 382890075Sobrien 3829132718Skan@defmac FUNCTION_INCOMING_ARG (@var{cum}, @var{mode}, @var{type}, @var{named}) 383090075SobrienDefine this macro if the target machine has ``register windows'', so 383190075Sobrienthat the register in which a function sees an arguments is not 383290075Sobriennecessarily the same as the one in which the caller passed the 383390075Sobrienargument. 383490075Sobrien 383590075SobrienFor such machines, @code{FUNCTION_ARG} computes the register in which 383690075Sobrienthe caller passes the value, and @code{FUNCTION_INCOMING_ARG} should 383790075Sobrienbe defined in a similar fashion to tell the function being called 383890075Sobrienwhere the arguments will arrive. 383990075Sobrien 384090075SobrienIf @code{FUNCTION_INCOMING_ARG} is not defined, @code{FUNCTION_ARG} 384190075Sobrienserves both purposes. 3842132718Skan@end defmac 384390075Sobrien 3844169689Skan@deftypefn {Target Hook} int TARGET_ARG_PARTIAL_BYTES (CUMULATIVE_ARGS *@var{cum}, enum machine_mode @var{mode}, tree @var{type}, bool @var{named}) 3845169689SkanThis target hook returns the number of bytes at the beginning of an 3846169689Skanargument that must be put in registers. The value must be zero for 384790075Sobrienarguments that are passed entirely in registers or that are entirely 384890075Sobrienpushed on the stack. 384990075Sobrien 385090075SobrienOn some machines, certain arguments must be passed partially in 385190075Sobrienregisters and partially in memory. On these machines, typically the 3852169689Skanfirst few words of arguments are passed in registers, and the rest 385390075Sobrienon the stack. If a multi-word argument (a @code{double} or a 385490075Sobrienstructure) crosses that boundary, its first few words must be passed 385590075Sobrienin registers and the rest must be pushed. This macro tells the 3856169689Skancompiler when this occurs, and how many bytes should go in registers. 385790075Sobrien 385890075Sobrien@code{FUNCTION_ARG} for these arguments should return the first 385990075Sobrienregister to be used by the caller for this argument; likewise 386090075Sobrien@code{FUNCTION_INCOMING_ARG}, for the called function. 3861169689Skan@end deftypefn 386290075Sobrien 3863169689Skan@deftypefn {Target Hook} bool TARGET_PASS_BY_REFERENCE (CUMULATIVE_ARGS *@var{cum}, enum machine_mode @var{mode}, tree @var{type}, bool @var{named}) 3864169689SkanThis target hook should return @code{true} if an argument at the 3865169689Skanposition indicated by @var{cum} should be passed by reference. This 3866169689Skanpredicate is queried after target independent reasons for being 3867169689Skanpassed by reference, such as @code{TREE_ADDRESSABLE (type)}. 3868169689Skan 3869169689SkanIf the hook returns true, a copy of that argument is made in memory and a 387090075Sobrienpointer to the argument is passed instead of the argument itself. 387190075SobrienThe pointer is passed in whatever way is appropriate for passing a pointer 387290075Sobriento that type. 3873169689Skan@end deftypefn 387490075Sobrien 3875169689Skan@deftypefn {Target Hook} bool TARGET_CALLEE_COPIES (CUMULATIVE_ARGS *@var{cum}, enum machine_mode @var{mode}, tree @var{type}, bool @var{named}) 3876169689SkanThe function argument described by the parameters to this hook is 3877169689Skanknown to be passed by reference. The hook should return true if the 3878169689Skanfunction argument should be copied by the callee instead of copied 3879169689Skanby the caller. 388090075Sobrien 3881169689SkanFor any argument for which the hook returns true, if it can be 3882169689Skandetermined that the argument is not modified, then a copy need 3883169689Skannot be generated. 388490075Sobrien 3885169689SkanThe default version of this hook always returns false. 3886169689Skan@end deftypefn 3887169689Skan 3888132718Skan@defmac CUMULATIVE_ARGS 388990075SobrienA C type for declaring a variable that is used as the first argument of 389090075Sobrien@code{FUNCTION_ARG} and other related values. For some target machines, 389190075Sobrienthe type @code{int} suffices and can hold the number of bytes of 389290075Sobrienargument so far. 389390075Sobrien 389490075SobrienThere is no need to record in @code{CUMULATIVE_ARGS} anything about the 389590075Sobrienarguments that have been passed on the stack. The compiler has other 389690075Sobrienvariables to keep track of that. For target machines on which all 389790075Sobrienarguments are passed on the stack, there is no need to store anything in 389890075Sobrien@code{CUMULATIVE_ARGS}; however, the data structure must exist and 389990075Sobrienshould not be empty, so use @code{int}. 3900132718Skan@end defmac 390190075Sobrien 3902132718Skan@defmac INIT_CUMULATIVE_ARGS (@var{cum}, @var{fntype}, @var{libname}, @var{fndecl}, @var{n_named_args}) 3903132718SkanA C statement (sans semicolon) for initializing the variable 3904132718Skan@var{cum} for the state at the beginning of the argument list. The 3905132718Skanvariable has type @code{CUMULATIVE_ARGS}. The value of @var{fntype} 3906132718Skanis the tree node for the data type of the function which will receive 3907132718Skanthe args, or 0 if the args are to a compiler support library function. 3908132718SkanFor direct calls that are not libcalls, @var{fndecl} contain the 3909132718Skandeclaration node of the function. @var{fndecl} is also set when 391090075Sobrien@code{INIT_CUMULATIVE_ARGS} is used to find arguments for the function 3911132718Skanbeing compiled. @var{n_named_args} is set to the number of named 3912132718Skanarguments, including a structure return address if it is passed as a 3913132718Skanparameter, when making a call. When processing incoming arguments, 3914169689Skan@var{n_named_args} is set to @minus{}1. 391590075Sobrien 391690075SobrienWhen processing a call to a compiler support library function, 391790075Sobrien@var{libname} identifies which one. It is a @code{symbol_ref} rtx which 391890075Sobriencontains the name of the function, as a string. @var{libname} is 0 when 391990075Sobrienan ordinary C function call is being processed. Thus, each time this 392090075Sobrienmacro is called, either @var{libname} or @var{fntype} is nonzero, but 392190075Sobriennever both of them at once. 3922132718Skan@end defmac 392390075Sobrien 3924132718Skan@defmac INIT_CUMULATIVE_LIBCALL_ARGS (@var{cum}, @var{mode}, @var{libname}) 392590075SobrienLike @code{INIT_CUMULATIVE_ARGS} but only used for outgoing libcalls, 392690075Sobrienit gets a @code{MODE} argument instead of @var{fntype}, that would be 392790075Sobrien@code{NULL}. @var{indirect} would always be zero, too. If this macro 392890075Sobrienis not defined, @code{INIT_CUMULATIVE_ARGS (cum, NULL_RTX, libname, 392990075Sobrien0)} is used instead. 3930132718Skan@end defmac 393190075Sobrien 3932132718Skan@defmac INIT_CUMULATIVE_INCOMING_ARGS (@var{cum}, @var{fntype}, @var{libname}) 393390075SobrienLike @code{INIT_CUMULATIVE_ARGS} but overrides it for the purposes of 393490075Sobrienfinding the arguments for the function being compiled. If this macro is 393590075Sobrienundefined, @code{INIT_CUMULATIVE_ARGS} is used instead. 393690075Sobrien 393790075SobrienThe value passed for @var{libname} is always 0, since library routines 393890075Sobrienwith special calling conventions are never compiled with GCC@. The 393990075Sobrienargument @var{libname} exists for symmetry with 394090075Sobrien@code{INIT_CUMULATIVE_ARGS}. 394190075Sobrien@c could use "this macro" in place of @code{INIT_CUMULATIVE_ARGS}, maybe. 394290075Sobrien@c --mew 5feb93 i switched the order of the sentences. --mew 10feb93 3943132718Skan@end defmac 394490075Sobrien 3945132718Skan@defmac FUNCTION_ARG_ADVANCE (@var{cum}, @var{mode}, @var{type}, @var{named}) 394690075SobrienA C statement (sans semicolon) to update the summarizer variable 394790075Sobrien@var{cum} to advance past an argument in the argument list. The 394890075Sobrienvalues @var{mode}, @var{type} and @var{named} describe that argument. 394990075SobrienOnce this is done, the variable @var{cum} is suitable for analyzing 395090075Sobrienthe @emph{following} argument with @code{FUNCTION_ARG}, etc. 395190075Sobrien 395290075SobrienThis macro need not do anything if the argument in question was passed 395390075Sobrienon the stack. The compiler knows how to track the amount of stack space 395490075Sobrienused for arguments without any special help. 3955132718Skan@end defmac 395690075Sobrien 3957132718Skan@defmac FUNCTION_ARG_PADDING (@var{mode}, @var{type}) 395890075SobrienIf defined, a C expression which determines whether, and in which direction, 395990075Sobriento pad out an argument with extra space. The value should be of type 396090075Sobrien@code{enum direction}: either @code{upward} to pad above the argument, 396190075Sobrien@code{downward} to pad below, or @code{none} to inhibit padding. 396290075Sobrien 396390075SobrienThe @emph{amount} of padding is always just enough to reach the next 396490075Sobrienmultiple of @code{FUNCTION_ARG_BOUNDARY}; this macro does not control 396590075Sobrienit. 396690075Sobrien 396790075SobrienThis macro has a default definition which is right for most systems. 396890075SobrienFor little-endian machines, the default is to pad upward. For 396990075Sobrienbig-endian machines, the default is to pad downward for an argument of 397090075Sobrienconstant size shorter than an @code{int}, and upward otherwise. 3971132718Skan@end defmac 397290075Sobrien 3973132718Skan@defmac PAD_VARARGS_DOWN 397490075SobrienIf defined, a C expression which determines whether the default 397590075Sobrienimplementation of va_arg will attempt to pad down before reading the 397690075Sobriennext argument, if that argument is smaller than its aligned space as 397790075Sobriencontrolled by @code{PARM_BOUNDARY}. If this macro is not defined, all such 397890075Sobrienarguments are padded down if @code{BYTES_BIG_ENDIAN} is true. 3979132718Skan@end defmac 398090075Sobrien 3981132718Skan@defmac BLOCK_REG_PADDING (@var{mode}, @var{type}, @var{first}) 3982132718SkanSpecify padding for the last element of a block move between registers and 3983132718Skanmemory. @var{first} is nonzero if this is the only element. Defining this 3984132718Skanmacro allows better control of register function parameters on big-endian 3985132718Skanmachines, without using @code{PARALLEL} rtl. In particular, 3986132718Skan@code{MUST_PASS_IN_STACK} need not test padding and mode of types in 3987132718Skanregisters, as there is no longer a "wrong" part of a register; For example, 3988132718Skana three byte aggregate may be passed in the high part of a register if so 3989132718Skanrequired. 3990132718Skan@end defmac 3991132718Skan 3992132718Skan@defmac FUNCTION_ARG_BOUNDARY (@var{mode}, @var{type}) 399390075SobrienIf defined, a C expression that gives the alignment boundary, in bits, 399490075Sobrienof an argument with the specified mode and type. If it is not defined, 399590075Sobrien@code{PARM_BOUNDARY} is used for all arguments. 3996132718Skan@end defmac 399790075Sobrien 3998132718Skan@defmac FUNCTION_ARG_REGNO_P (@var{regno}) 399990075SobrienA C expression that is nonzero if @var{regno} is the number of a hard 400090075Sobrienregister in which function arguments are sometimes passed. This does 400190075Sobrien@emph{not} include implicit arguments such as the static chain and 400290075Sobrienthe structure-value address. On many machines, no registers can be 400390075Sobrienused for this purpose since all function arguments are pushed on the 400490075Sobrienstack. 4005132718Skan@end defmac 400690075Sobrien 4007132718Skan@deftypefn {Target Hook} bool TARGET_SPLIT_COMPLEX_ARG (tree @var{type}) 4008132718SkanThis hook should return true if parameter of type @var{type} are passed 4009132718Skanas two scalar parameters. By default, GCC will attempt to pack complex 4010132718Skanarguments into the target's word size. Some ABIs require complex arguments 4011132718Skanto be split and treated as their individual components. For example, on 4012132718SkanAIX64, complex floats should be passed in a pair of floating point 4013132718Skanregisters, even though a complex float would fit in one 64-bit floating 4014132718Skanpoint register. 401590075Sobrien 4016132718SkanThe default value of this hook is @code{NULL}, which is treated as always 4017132718Skanfalse. 4018132718Skan@end deftypefn 401990075Sobrien 4020169689Skan@deftypefn {Target Hook} tree TARGET_BUILD_BUILTIN_VA_LIST (void) 4021169689SkanThis hook returns a type node for @code{va_list} for the target. 4022169689SkanThe default version of the hook returns @code{void*}. 4023169689Skan@end deftypefn 4024169689Skan 4025169689Skan@deftypefn {Target Hook} tree TARGET_GIMPLIFY_VA_ARG_EXPR (tree @var{valist}, tree @var{type}, tree *@var{pre_p}, tree *@var{post_p}) 4026169689SkanThis hook performs target-specific gimplification of 4027169689Skan@code{VA_ARG_EXPR}. The first two parameters correspond to the 4028169689Skanarguments to @code{va_arg}; the latter two are as in 4029169689Skan@code{gimplify.c:gimplify_expr}. 4030169689Skan@end deftypefn 4031169689Skan 4032169689Skan@deftypefn {Target Hook} bool TARGET_VALID_POINTER_MODE (enum machine_mode @var{mode}) 4033169689SkanDefine this to return nonzero if the port can handle pointers 4034169689Skanwith machine mode @var{mode}. The default version of this 4035169689Skanhook returns true for both @code{ptr_mode} and @code{Pmode}. 4036169689Skan@end deftypefn 4037169689Skan 4038169689Skan@deftypefn {Target Hook} bool TARGET_SCALAR_MODE_SUPPORTED_P (enum machine_mode @var{mode}) 4039169689SkanDefine this to return nonzero if the port is prepared to handle 4040169689Skaninsns involving scalar mode @var{mode}. For a scalar mode to be 4041169689Skanconsidered supported, all the basic arithmetic and comparisons 4042169689Skanmust work. 4043169689Skan 4044169689SkanThe default version of this hook returns true for any mode 4045169689Skanrequired to handle the basic C types (as defined by the port). 4046169689SkanIncluded here are the double-word arithmetic supported by the 4047169689Skancode in @file{optabs.c}. 4048169689Skan@end deftypefn 4049169689Skan 4050169689Skan@deftypefn {Target Hook} bool TARGET_VECTOR_MODE_SUPPORTED_P (enum machine_mode @var{mode}) 4051169689SkanDefine this to return nonzero if the port is prepared to handle 4052169689Skaninsns involving vector mode @var{mode}. At the very least, it 4053169689Skanmust have move patterns for this mode. 4054169689Skan@end deftypefn 4055169689Skan 405690075Sobrien@node Scalar Return 405790075Sobrien@subsection How Scalar Function Values Are Returned 405890075Sobrien@cindex return values in registers 405990075Sobrien@cindex values, returned by functions 406090075Sobrien@cindex scalars, returned as values 406190075Sobrien 406290075SobrienThis section discusses the macros that control returning scalars as 406390075Sobrienvalues---values that can fit in registers. 406490075Sobrien 4065169689Skan@deftypefn {Target Hook} rtx TARGET_FUNCTION_VALUE (tree @var{ret_type}, tree @var{fn_decl_or_type}, bool @var{outgoing}) 406690075Sobrien 4067169689SkanDefine this to return an RTX representing the place where a function 4068169689Skanreturns or receives a value of data type @var{ret_type}, a tree node 4069169689Skannode representing a data type. @var{fn_decl_or_type} is a tree node 4070169689Skanrepresenting @code{FUNCTION_DECL} or @code{FUNCTION_TYPE} of a 4071169689Skanfunction being called. If @var{outgoing} is false, the hook should 4072169689Skancompute the register in which the caller will see the return value. 4073169689SkanOtherwise, the hook should return an RTX representing the place where 4074169689Skana function returns a value. 407590075Sobrien 4076169689SkanOn many machines, only @code{TYPE_MODE (@var{ret_type})} is relevant. 4077169689Skan(Actually, on most machines, scalar values are returned in the same 4078169689Skanplace regardless of mode.) The value of the expression is usually a 4079169689Skan@code{reg} RTX for the hard register where the return value is stored. 4080169689SkanThe value can also be a @code{parallel} RTX, if the return value is in 4081169689Skanmultiple places. See @code{FUNCTION_ARG} for an explanation of the 4082169689Skan@code{parallel} form. 408390075Sobrien 4084169689SkanIf @code{TARGET_PROMOTE_FUNCTION_RETURN} returns true, you must apply 4085169689Skanthe same promotion rules specified in @code{PROMOTE_MODE} if 4086169689Skan@var{valtype} is a scalar type. 4087169689Skan 408890075SobrienIf the precise function being called is known, @var{func} is a tree 408990075Sobriennode (@code{FUNCTION_DECL}) for it; otherwise, @var{func} is a null 409090075Sobrienpointer. This makes it possible to use a different value-returning 409190075Sobrienconvention for specific functions when all their calls are 409290075Sobrienknown. 409390075Sobrien 4094169689SkanSome target machines have ``register windows'' so that the register in 4095169689Skanwhich a function returns its value is not the same as the one in which 4096169689Skanthe caller sees the value. For such machines, you should return 4097169689Skandifferent RTX depending on @var{outgoing}. 4098169689Skan 4099169689Skan@code{TARGET_FUNCTION_VALUE} is not used for return values with 4100169689Skanaggregate data types, because these are returned in another way. See 4101132718Skan@code{TARGET_STRUCT_VALUE_RTX} and related macros, below. 4102169689Skan@end deftypefn 4103169689Skan 4104169689Skan@defmac FUNCTION_VALUE (@var{valtype}, @var{func}) 4105169689SkanThis macro has been deprecated. Use @code{TARGET_FUNCTION_VALUE} for 4106169689Skana new target instead. 4107132718Skan@end defmac 410890075Sobrien 4109132718Skan@defmac FUNCTION_OUTGOING_VALUE (@var{valtype}, @var{func}) 4110169689SkanThis macro has been deprecated. Use @code{TARGET_FUNCTION_VALUE} for 4111169689Skana new target instead. 4112132718Skan@end defmac 411390075Sobrien 4114132718Skan@defmac LIBCALL_VALUE (@var{mode}) 411590075SobrienA C expression to create an RTX representing the place where a library 411690075Sobrienfunction returns a value of mode @var{mode}. If the precise function 411790075Sobrienbeing called is known, @var{func} is a tree node 411890075Sobrien(@code{FUNCTION_DECL}) for it; otherwise, @var{func} is a null 411990075Sobrienpointer. This makes it possible to use a different value-returning 412090075Sobrienconvention for specific functions when all their calls are 412190075Sobrienknown. 412290075Sobrien 412390075SobrienNote that ``library function'' in this context means a compiler 412490075Sobriensupport routine, used to perform arithmetic, whose name is known 412590075Sobrienspecially by the compiler and was not mentioned in the C code being 412690075Sobriencompiled. 412790075Sobrien 412890075SobrienThe definition of @code{LIBRARY_VALUE} need not be concerned aggregate 412990075Sobriendata types, because none of the library functions returns such types. 4130132718Skan@end defmac 413190075Sobrien 4132132718Skan@defmac FUNCTION_VALUE_REGNO_P (@var{regno}) 413390075SobrienA C expression that is nonzero if @var{regno} is the number of a hard 413490075Sobrienregister in which the values of called function may come back. 413590075Sobrien 413690075SobrienA register whose use for returning values is limited to serving as the 413790075Sobriensecond of a pair (for a value of type @code{double}, say) need not be 413890075Sobrienrecognized by this macro. So for most machines, this definition 413990075Sobriensuffices: 414090075Sobrien 4141132718Skan@smallexample 414290075Sobrien#define FUNCTION_VALUE_REGNO_P(N) ((N) == 0) 4143132718Skan@end smallexample 414490075Sobrien 414590075SobrienIf the machine has register windows, so that the caller and the called 414690075Sobrienfunction use different registers for the return value, this macro 414790075Sobrienshould recognize only the caller's register numbers. 4148132718Skan@end defmac 414990075Sobrien 4150132718Skan@defmac APPLY_RESULT_SIZE 415190075SobrienDefine this macro if @samp{untyped_call} and @samp{untyped_return} 415290075Sobrienneed more space than is implied by @code{FUNCTION_VALUE_REGNO_P} for 415390075Sobriensaving and restoring an arbitrary return value. 4154132718Skan@end defmac 415590075Sobrien 4156132718Skan@deftypefn {Target Hook} bool TARGET_RETURN_IN_MSB (tree @var{type}) 4157132718SkanThis hook should return true if values of type @var{type} are returned 4158132718Skanat the most significant end of a register (in other words, if they are 4159132718Skanpadded at the least significant end). You can assume that @var{type} 4160132718Skanis returned in a register; the caller is required to check this. 4161132718Skan 4162169689SkanNote that the register provided by @code{TARGET_FUNCTION_VALUE} must 4163169689Skanbe able to hold the complete return value. For example, if a 1-, 2- 4164169689Skanor 3-byte structure is returned at the most significant end of a 4165169689Skan4-byte register, @code{TARGET_FUNCTION_VALUE} should provide an 4166169689Skan@code{SImode} rtx. 4167132718Skan@end deftypefn 4168132718Skan 416990075Sobrien@node Aggregate Return 417090075Sobrien@subsection How Large Values Are Returned 417190075Sobrien@cindex aggregates as return values 417290075Sobrien@cindex large return values 417390075Sobrien@cindex returning aggregate values 417490075Sobrien@cindex structure value address 417590075Sobrien 417690075SobrienWhen a function value's mode is @code{BLKmode} (and in some other 4177169689Skancases), the value is not returned according to 4178169689Skan@code{TARGET_FUNCTION_VALUE} (@pxref{Scalar Return}). Instead, the 4179169689Skancaller passes the address of a block of memory in which the value 4180169689Skanshould be stored. This address is called the @dfn{structure value 4181169689Skanaddress}. 418290075Sobrien 418390075SobrienThis section describes how to control returning structure values in 418490075Sobrienmemory. 418590075Sobrien 4186132718Skan@deftypefn {Target Hook} bool TARGET_RETURN_IN_MEMORY (tree @var{type}, tree @var{fntype}) 4187132718SkanThis target hook should return a nonzero value to say to return the 4188132718Skanfunction value in memory, just as large structures are always returned. 4189132718SkanHere @var{type} will be the data type of the value, and @var{fntype} 4190132718Skanwill be the type of the function doing the returning, or @code{NULL} for 4191132718Skanlibcalls. 419290075Sobrien 419390075SobrienNote that values of mode @code{BLKmode} must be explicitly handled 4194132718Skanby this function. Also, the option @option{-fpcc-struct-return} 419590075Sobrientakes effect regardless of this macro. On most systems, it is 4196132718Skanpossible to leave the hook undefined; this causes a default 419790075Sobriendefinition to be used, whose value is the constant 1 for @code{BLKmode} 419890075Sobrienvalues, and 0 otherwise. 419990075Sobrien 4200132718SkanDo not use this hook to indicate that structures and unions should always 420190075Sobrienbe returned in memory. You should instead use @code{DEFAULT_PCC_STRUCT_RETURN} 420290075Sobriento indicate this. 4203132718Skan@end deftypefn 420490075Sobrien 4205132718Skan@defmac DEFAULT_PCC_STRUCT_RETURN 420690075SobrienDefine this macro to be 1 if all structure and union return values must be 420790075Sobrienin memory. Since this results in slower code, this should be defined 420890075Sobrienonly if needed for compatibility with other compilers or with an ABI@. 420990075SobrienIf you define this macro to be 0, then the conventions used for structure 4210132718Skanand union return values are decided by the @code{TARGET_RETURN_IN_MEMORY} 4211132718Skantarget hook. 421290075Sobrien 421390075SobrienIf not defined, this defaults to the value 1. 4214132718Skan@end defmac 421590075Sobrien 4216132718Skan@deftypefn {Target Hook} rtx TARGET_STRUCT_VALUE_RTX (tree @var{fndecl}, int @var{incoming}) 4217132718SkanThis target hook should return the location of the structure value 4218132718Skanaddress (normally a @code{mem} or @code{reg}), or 0 if the address is 4219132718Skanpassed as an ``invisible'' first argument. Note that @var{fndecl} may 4220169689Skanbe @code{NULL}, for libcalls. You do not need to define this target 4221169689Skanhook if the address is always passed as an ``invisible'' first 4222169689Skanargument. 422390075Sobrien 422490075SobrienOn some architectures the place where the structure value address 422590075Sobrienis found by the called function is not the same place that the 422690075Sobriencaller put it. This can be due to register windows, or it could 422790075Sobrienbe because the function prologue moves it to a different place. 4228169689Skan@var{incoming} is @code{1} or @code{2} when the location is needed in 4229169689Skanthe context of the called function, and @code{0} in the context of 4230132718Skanthe caller. 423190075Sobrien 4232169689SkanIf @var{incoming} is nonzero and the address is to be found on the 4233169689Skanstack, return a @code{mem} which refers to the frame pointer. If 4234169689Skan@var{incoming} is @code{2}, the result is being used to fetch the 4235169689Skanstructure value address at the beginning of a function. If you need 4236169689Skanto emit adjusting code, you should do it at this point. 4237132718Skan@end deftypefn 423890075Sobrien 4239132718Skan@defmac PCC_STATIC_STRUCT_RETURN 424090075SobrienDefine this macro if the usual system convention on the target machine 424190075Sobrienfor returning structures and unions is for the called function to return 424290075Sobrienthe address of a static variable containing the value. 424390075Sobrien 424490075SobrienDo not define this if the usual system convention is for the caller to 424590075Sobrienpass an address to the subroutine. 424690075Sobrien 424790075SobrienThis macro has effect in @option{-fpcc-struct-return} mode, but it does 424890075Sobriennothing when you use @option{-freg-struct-return} mode. 4249132718Skan@end defmac 425090075Sobrien 425190075Sobrien@node Caller Saves 425290075Sobrien@subsection Caller-Saves Register Allocation 425390075Sobrien 425490075SobrienIf you enable it, GCC can save registers around function calls. This 425590075Sobrienmakes it possible to use call-clobbered registers to hold variables that 425690075Sobrienmust live across calls. 425790075Sobrien 4258132718Skan@defmac CALLER_SAVE_PROFITABLE (@var{refs}, @var{calls}) 425990075SobrienA C expression to determine whether it is worthwhile to consider placing 426090075Sobriena pseudo-register in a call-clobbered hard register and saving and 426190075Sobrienrestoring it around each function call. The expression should be 1 when 426290075Sobrienthis is worth doing, and 0 otherwise. 426390075Sobrien 426490075SobrienIf you don't define this macro, a default is used which is good on most 426590075Sobrienmachines: @code{4 * @var{calls} < @var{refs}}. 4266132718Skan@end defmac 426790075Sobrien 4268132718Skan@defmac HARD_REGNO_CALLER_SAVE_MODE (@var{regno}, @var{nregs}) 426990075SobrienA C expression specifying which mode is required for saving @var{nregs} 427090075Sobrienof a pseudo-register in call-clobbered hard register @var{regno}. If 427190075Sobrien@var{regno} is unsuitable for caller save, @code{VOIDmode} should be 427290075Sobrienreturned. For most machines this macro need not be defined since GCC 427390075Sobrienwill select the smallest suitable mode. 4274132718Skan@end defmac 427590075Sobrien 427690075Sobrien@node Function Entry 427790075Sobrien@subsection Function Entry and Exit 427890075Sobrien@cindex function entry and exit 427990075Sobrien@cindex prologue 428090075Sobrien@cindex epilogue 428190075Sobrien 428290075SobrienThis section describes the macros that output function entry 428390075Sobrien(@dfn{prologue}) and exit (@dfn{epilogue}) code. 428490075Sobrien 428590075Sobrien@deftypefn {Target Hook} void TARGET_ASM_FUNCTION_PROLOGUE (FILE *@var{file}, HOST_WIDE_INT @var{size}) 428690075SobrienIf defined, a function that outputs the assembler code for entry to a 428790075Sobrienfunction. The prologue is responsible for setting up the stack frame, 428890075Sobrieninitializing the frame pointer register, saving registers that must be 428990075Sobriensaved, and allocating @var{size} additional bytes of storage for the 429090075Sobrienlocal variables. @var{size} is an integer. @var{file} is a stdio 429190075Sobrienstream to which the assembler code should be output. 429290075Sobrien 429390075SobrienThe label for the beginning of the function need not be output by this 429490075Sobrienmacro. That has already been done when the macro is run. 429590075Sobrien 429690075Sobrien@findex regs_ever_live 429790075SobrienTo determine which registers to save, the macro can refer to the array 429890075Sobrien@code{regs_ever_live}: element @var{r} is nonzero if hard register 429990075Sobrien@var{r} is used anywhere within the function. This implies the function 430090075Sobrienprologue should save register @var{r}, provided it is not one of the 430190075Sobriencall-used registers. (@code{TARGET_ASM_FUNCTION_EPILOGUE} must likewise use 430290075Sobrien@code{regs_ever_live}.) 430390075Sobrien 430490075SobrienOn machines that have ``register windows'', the function entry code does 430590075Sobriennot save on the stack the registers that are in the windows, even if 430690075Sobrienthey are supposed to be preserved by function calls; instead it takes 430790075Sobrienappropriate steps to ``push'' the register stack, if any non-call-used 430890075Sobrienregisters are used in the function. 430990075Sobrien 431090075Sobrien@findex frame_pointer_needed 431190075SobrienOn machines where functions may or may not have frame-pointers, the 431290075Sobrienfunction entry code must vary accordingly; it must set up the frame 431390075Sobrienpointer if one is wanted, and not otherwise. To determine whether a 431490075Sobrienframe pointer is in wanted, the macro can refer to the variable 431590075Sobrien@code{frame_pointer_needed}. The variable's value will be 1 at run 431690075Sobrientime in a function that needs a frame pointer. @xref{Elimination}. 431790075Sobrien 431890075SobrienThe function entry code is responsible for allocating any stack space 431990075Sobrienrequired for the function. This stack space consists of the regions 432090075Sobrienlisted below. In most cases, these regions are allocated in the 432190075Sobrienorder listed, with the last listed region closest to the top of the 432290075Sobrienstack (the lowest address if @code{STACK_GROWS_DOWNWARD} is defined, and 432390075Sobrienthe highest address if it is not defined). You can use a different order 432490075Sobrienfor a machine if doing so is more convenient or required for 432590075Sobriencompatibility reasons. Except in cases where required by standard 432690075Sobrienor by a debugger, there is no reason why the stack layout used by GCC 432790075Sobrienneed agree with that used by other compilers for a machine. 432890075Sobrien@end deftypefn 432990075Sobrien 433090075Sobrien@deftypefn {Target Hook} void TARGET_ASM_FUNCTION_END_PROLOGUE (FILE *@var{file}) 433190075SobrienIf defined, a function that outputs assembler code at the end of a 433290075Sobrienprologue. This should be used when the function prologue is being 433390075Sobrienemitted as RTL, and you have some extra assembler that needs to be 433490075Sobrienemitted. @xref{prologue instruction pattern}. 433590075Sobrien@end deftypefn 433690075Sobrien 433790075Sobrien@deftypefn {Target Hook} void TARGET_ASM_FUNCTION_BEGIN_EPILOGUE (FILE *@var{file}) 433890075SobrienIf defined, a function that outputs assembler code at the start of an 433990075Sobrienepilogue. This should be used when the function epilogue is being 434090075Sobrienemitted as RTL, and you have some extra assembler that needs to be 434190075Sobrienemitted. @xref{epilogue instruction pattern}. 434290075Sobrien@end deftypefn 434390075Sobrien 434490075Sobrien@deftypefn {Target Hook} void TARGET_ASM_FUNCTION_EPILOGUE (FILE *@var{file}, HOST_WIDE_INT @var{size}) 434590075SobrienIf defined, a function that outputs the assembler code for exit from a 434690075Sobrienfunction. The epilogue is responsible for restoring the saved 434790075Sobrienregisters and stack pointer to their values when the function was 434890075Sobriencalled, and returning control to the caller. This macro takes the 434990075Sobriensame arguments as the macro @code{TARGET_ASM_FUNCTION_PROLOGUE}, and the 435090075Sobrienregisters to restore are determined from @code{regs_ever_live} and 435190075Sobrien@code{CALL_USED_REGISTERS} in the same way. 435290075Sobrien 435390075SobrienOn some machines, there is a single instruction that does all the work 435490075Sobrienof returning from the function. On these machines, give that 435590075Sobrieninstruction the name @samp{return} and do not define the macro 435690075Sobrien@code{TARGET_ASM_FUNCTION_EPILOGUE} at all. 435790075Sobrien 435890075SobrienDo not define a pattern named @samp{return} if you want the 435990075Sobrien@code{TARGET_ASM_FUNCTION_EPILOGUE} to be used. If you want the target 436090075Sobrienswitches to control whether return instructions or epilogues are used, 436190075Sobriendefine a @samp{return} pattern with a validity condition that tests the 436290075Sobrientarget switches appropriately. If the @samp{return} pattern's validity 436390075Sobriencondition is false, epilogues will be used. 436490075Sobrien 436590075SobrienOn machines where functions may or may not have frame-pointers, the 436690075Sobrienfunction exit code must vary accordingly. Sometimes the code for these 436790075Sobrientwo cases is completely different. To determine whether a frame pointer 436890075Sobrienis wanted, the macro can refer to the variable 436990075Sobrien@code{frame_pointer_needed}. The variable's value will be 1 when compiling 437090075Sobriena function that needs a frame pointer. 437190075Sobrien 437290075SobrienNormally, @code{TARGET_ASM_FUNCTION_PROLOGUE} and 437390075Sobrien@code{TARGET_ASM_FUNCTION_EPILOGUE} must treat leaf functions specially. 437490075SobrienThe C variable @code{current_function_is_leaf} is nonzero for such a 437590075Sobrienfunction. @xref{Leaf Functions}. 437690075Sobrien 437790075SobrienOn some machines, some functions pop their arguments on exit while 437890075Sobrienothers leave that for the caller to do. For example, the 68020 when 437990075Sobriengiven @option{-mrtd} pops arguments in functions that take a fixed 438090075Sobriennumber of arguments. 438190075Sobrien 438290075Sobrien@findex current_function_pops_args 438390075SobrienYour definition of the macro @code{RETURN_POPS_ARGS} decides which 438490075Sobrienfunctions pop their own arguments. @code{TARGET_ASM_FUNCTION_EPILOGUE} 438590075Sobrienneeds to know what was decided. The variable that is called 438690075Sobrien@code{current_function_pops_args} is the number of bytes of its 438790075Sobrienarguments that a function should pop. @xref{Scalar Return}. 438890075Sobrien@c what is the "its arguments" in the above sentence referring to, pray 438990075Sobrien@c tell? --mew 5feb93 439090075Sobrien@end deftypefn 439190075Sobrien 439290075Sobrien@itemize @bullet 439390075Sobrien@item 439490075Sobrien@findex current_function_pretend_args_size 439590075SobrienA region of @code{current_function_pretend_args_size} bytes of 439690075Sobrienuninitialized space just underneath the first argument arriving on the 439790075Sobrienstack. (This may not be at the very start of the allocated stack region 439890075Sobrienif the calling sequence has pushed anything else since pushing the stack 439990075Sobrienarguments. But usually, on such machines, nothing else has been pushed 440090075Sobrienyet, because the function prologue itself does all the pushing.) This 440190075Sobrienregion is used on machines where an argument may be passed partly in 440290075Sobrienregisters and partly in memory, and, in some cases to support the 4403117395Skanfeatures in @code{<stdarg.h>}. 440490075Sobrien 440590075Sobrien@item 440690075SobrienAn area of memory used to save certain registers used by the function. 440790075SobrienThe size of this area, which may also include space for such things as 440890075Sobrienthe return address and pointers to previous stack frames, is 440990075Sobrienmachine-specific and usually depends on which registers have been used 441090075Sobrienin the function. Machines with register windows often do not require 441190075Sobriena save area. 441290075Sobrien 441390075Sobrien@item 441490075SobrienA region of at least @var{size} bytes, possibly rounded up to an allocation 441590075Sobrienboundary, to contain the local variables of the function. On some machines, 441690075Sobrienthis region and the save area may occur in the opposite order, with the 441790075Sobriensave area closer to the top of the stack. 441890075Sobrien 441990075Sobrien@item 442090075Sobrien@cindex @code{ACCUMULATE_OUTGOING_ARGS} and stack frames 442190075SobrienOptionally, when @code{ACCUMULATE_OUTGOING_ARGS} is defined, a region of 442290075Sobrien@code{current_function_outgoing_args_size} bytes to be used for outgoing 442390075Sobrienargument lists of the function. @xref{Stack Arguments}. 442490075Sobrien@end itemize 442590075Sobrien 4426132718Skan@defmac EXIT_IGNORE_STACK 442790075SobrienDefine this macro as a C expression that is nonzero if the return 442890075Sobrieninstruction or the function epilogue ignores the value of the stack 442990075Sobrienpointer; in other words, if it is safe to delete an instruction to 4430132718Skanadjust the stack pointer before a return from the function. The 4431132718Skandefault is 0. 443290075Sobrien 443390075SobrienNote that this macro's value is relevant only for functions for which 443490075Sobrienframe pointers are maintained. It is never safe to delete a final 443590075Sobrienstack adjustment in a function that has no frame pointer, and the 443690075Sobriencompiler knows this regardless of @code{EXIT_IGNORE_STACK}. 4437132718Skan@end defmac 443890075Sobrien 4439132718Skan@defmac EPILOGUE_USES (@var{regno}) 444090075SobrienDefine this macro as a C expression that is nonzero for registers that are 444190075Sobrienused by the epilogue or the @samp{return} pattern. The stack and frame 4442169689Skanpointer registers are already assumed to be used as needed. 4443132718Skan@end defmac 444490075Sobrien 4445132718Skan@defmac EH_USES (@var{regno}) 444696263SobrienDefine this macro as a C expression that is nonzero for registers that are 444796263Sobrienused by the exception handling mechanism, and so should be considered live 444896263Sobrienon entry to an exception edge. 4449132718Skan@end defmac 445096263Sobrien 4451132718Skan@defmac DELAY_SLOTS_FOR_EPILOGUE 445290075SobrienDefine this macro if the function epilogue contains delay slots to which 445390075Sobrieninstructions from the rest of the function can be ``moved''. The 445490075Sobriendefinition should be a C expression whose value is an integer 445590075Sobrienrepresenting the number of delay slots there. 4456132718Skan@end defmac 445790075Sobrien 4458132718Skan@defmac ELIGIBLE_FOR_EPILOGUE_DELAY (@var{insn}, @var{n}) 445990075SobrienA C expression that returns 1 if @var{insn} can be placed in delay 446090075Sobrienslot number @var{n} of the epilogue. 446190075Sobrien 446290075SobrienThe argument @var{n} is an integer which identifies the delay slot now 446390075Sobrienbeing considered (since different slots may have different rules of 446490075Sobrieneligibility). It is never negative and is always less than the number 446590075Sobrienof epilogue delay slots (what @code{DELAY_SLOTS_FOR_EPILOGUE} returns). 446690075SobrienIf you reject a particular insn for a given delay slot, in principle, it 446790075Sobrienmay be reconsidered for a subsequent delay slot. Also, other insns may 446890075Sobrien(at least in principle) be considered for the so far unfilled delay 446990075Sobrienslot. 447090075Sobrien 447190075Sobrien@findex current_function_epilogue_delay_list 447290075Sobrien@findex final_scan_insn 447390075SobrienThe insns accepted to fill the epilogue delay slots are put in an RTL 447490075Sobrienlist made with @code{insn_list} objects, stored in the variable 447590075Sobrien@code{current_function_epilogue_delay_list}. The insn for the first 447690075Sobriendelay slot comes first in the list. Your definition of the macro 447790075Sobrien@code{TARGET_ASM_FUNCTION_EPILOGUE} should fill the delay slots by 447890075Sobrienoutputting the insns in this list, usually by calling 447990075Sobrien@code{final_scan_insn}. 448090075Sobrien 448190075SobrienYou need not define this macro if you did not define 448290075Sobrien@code{DELAY_SLOTS_FOR_EPILOGUE}. 4483132718Skan@end defmac 448490075Sobrien 4485146895Skan@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}) 4486117395SkanA function that outputs the assembler code for a thunk 448790075Sobrienfunction, used to implement C++ virtual function calls with multiple 448890075Sobrieninheritance. The thunk acts as a wrapper around a virtual function, 448990075Sobrienadjusting the implicit object parameter before handing control off to 449090075Sobrienthe real function. 449190075Sobrien 449290075SobrienFirst, emit code to add the integer @var{delta} to the location that 449390075Sobriencontains the incoming first argument. Assume that this argument 449490075Sobriencontains a pointer, and is the one used to pass the @code{this} pointer 449590075Sobrienin C++. This is the incoming argument @emph{before} the function prologue, 449690075Sobriene.g.@: @samp{%o0} on a sparc. The addition must preserve the values of 449790075Sobrienall other incoming arguments. 449890075Sobrien 4499146895SkanThen, if @var{vcall_offset} is nonzero, an additional adjustment should be 4500146895Skanmade after adding @code{delta}. In particular, if @var{p} is the 4501146895Skanadjusted pointer, the following adjustment should be made: 4502146895Skan 4503146895Skan@smallexample 4504146895Skanp += (*((ptrdiff_t **)p))[vcall_offset/sizeof(ptrdiff_t)] 4505146895Skan@end smallexample 4506146895Skan 4507146895SkanAfter the additions, emit code to jump to @var{function}, which is a 450890075Sobrien@code{FUNCTION_DECL}. This is a direct pure jump, not a call, and does 450990075Sobriennot touch the return address. Hence returning from @var{FUNCTION} will 451090075Sobrienreturn to whoever called the current @samp{thunk}. 451190075Sobrien 451290075SobrienThe effect must be as if @var{function} had been called directly with 451390075Sobrienthe adjusted first argument. This macro is responsible for emitting all 451490075Sobrienof the code for a thunk function; @code{TARGET_ASM_FUNCTION_PROLOGUE} 451590075Sobrienand @code{TARGET_ASM_FUNCTION_EPILOGUE} are not invoked. 451690075Sobrien 451790075SobrienThe @var{thunk_fndecl} is redundant. (@var{delta} and @var{function} 451890075Sobrienhave already been extracted from it.) It might possibly be useful on 451990075Sobriensome targets, but probably not. 452090075Sobrien 452190075SobrienIf you do not define this macro, the target-independent code in the C++ 452290075Sobrienfront end will generate a less efficient heavyweight thunk that calls 452390075Sobrien@var{function} instead of jumping to it. The generic approach does 452490075Sobriennot support varargs. 4525117395Skan@end deftypefn 452690075Sobrien 4527146895Skan@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}) 4528146895SkanA function that returns true if TARGET_ASM_OUTPUT_MI_THUNK would be able 4529146895Skanto output the assembler code for the thunk function specified by the 4530146895Skanarguments it is passed, and false otherwise. In the latter case, the 4531146895Skangeneric approach will be used by the C++ front end, with the limitations 4532146895Skanpreviously exposed. 4533117395Skan@end deftypefn 4534117395Skan 453590075Sobrien@node Profiling 453690075Sobrien@subsection Generating Code for Profiling 453790075Sobrien@cindex profiling, code generation 453890075Sobrien 453990075SobrienThese macros will help you generate code for profiling. 454090075Sobrien 4541132718Skan@defmac FUNCTION_PROFILER (@var{file}, @var{labelno}) 454290075SobrienA C statement or compound statement to output to @var{file} some 454390075Sobrienassembler code to call the profiling subroutine @code{mcount}. 454490075Sobrien 454590075Sobrien@findex mcount 454690075SobrienThe details of how @code{mcount} expects to be called are determined by 454790075Sobrienyour operating system environment, not by GCC@. To figure them out, 454890075Sobriencompile a small program for profiling using the system's installed C 454990075Sobriencompiler and look at the assembler code that results. 455090075Sobrien 455190075SobrienOlder implementations of @code{mcount} expect the address of a counter 455290075Sobrienvariable to be loaded into some register. The name of this variable is 455390075Sobrien@samp{LP} followed by the number @var{labelno}, so you would generate 455490075Sobrienthe name using @samp{LP%d} in a @code{fprintf}. 4555132718Skan@end defmac 455690075Sobrien 4557132718Skan@defmac PROFILE_HOOK 455890075SobrienA C statement or compound statement to output to @var{file} some assembly 455990075Sobriencode to call the profiling subroutine @code{mcount} even the target does 456090075Sobriennot support profiling. 4561132718Skan@end defmac 456290075Sobrien 4563132718Skan@defmac NO_PROFILE_COUNTERS 4564169689SkanDefine this macro to be an expression with a nonzero value if the 4565169689Skan@code{mcount} subroutine on your system does not need a counter variable 4566169689Skanallocated for each function. This is true for almost all modern 4567169689Skanimplementations. If you define this macro, you must not use the 4568169689Skan@var{labelno} argument to @code{FUNCTION_PROFILER}. 4569132718Skan@end defmac 457090075Sobrien 4571132718Skan@defmac PROFILE_BEFORE_PROLOGUE 457290075SobrienDefine this macro if the code for function profiling should come before 457390075Sobrienthe function prologue. Normally, the profiling code comes after. 4574132718Skan@end defmac 457590075Sobrien 457690075Sobrien@node Tail Calls 457790075Sobrien@subsection Permitting tail calls 457890075Sobrien@cindex tail calls 457990075Sobrien 4580132718Skan@deftypefn {Target Hook} bool TARGET_FUNCTION_OK_FOR_SIBCALL (tree @var{decl}, tree @var{exp}) 4581132718SkanTrue if it is ok to do sibling call optimization for the specified 4582132718Skancall expression @var{exp}. @var{decl} will be the called function, 4583132718Skanor @code{NULL} if this is an indirect call. 458490075Sobrien 458590075SobrienIt is not uncommon for limitations of calling conventions to prevent 458690075Sobrientail calls to functions outside the current unit of translation, or 4587132718Skanduring PIC compilation. The hook is used to enforce these restrictions, 458890075Sobrienas the @code{sibcall} md pattern can not fail, or fall over to a 4589132718Skan``normal'' call. The criteria for successful sibling call optimization 4590132718Skanmay vary greatly between different architectures. 4591132718Skan@end deftypefn 459290075Sobrien 4593169689Skan@deftypefn {Target Hook} void TARGET_EXTRA_LIVE_ON_ENTRY (bitmap *@var{regs}) 4594169689SkanAdd any hard registers to @var{regs} that are live on entry to the 4595169689Skanfunction. This hook only needs to be defined to provide registers that 4596169689Skancannot be found by examination of FUNCTION_ARG_REGNO_P, the callee saved 4597169689Skanregisters, STATIC_CHAIN_INCOMING_REGNUM, STATIC_CHAIN_REGNUM, 4598169689SkanTARGET_STRUCT_VALUE_RTX, FRAME_POINTER_REGNUM, EH_USES, 4599169689SkanFRAME_POINTER_REGNUM, ARG_POINTER_REGNUM, and the PIC_OFFSET_TABLE_REGNUM. 4600169689Skan@end deftypefn 4601169689Skan 4602169689Skan@node Stack Smashing Protection 4603169689Skan@subsection Stack smashing protection 4604169689Skan@cindex stack smashing protection 4605169689Skan 4606169689Skan@deftypefn {Target Hook} tree TARGET_STACK_PROTECT_GUARD (void) 4607169689SkanThis hook returns a @code{DECL} node for the external variable to use 4608169689Skanfor the stack protection guard. This variable is initialized by the 4609169689Skanruntime to some random value and is used to initialize the guard value 4610169689Skanthat is placed at the top of the local stack frame. The type of this 4611169689Skanvariable must be @code{ptr_type_node}. 4612169689Skan 4613169689SkanThe default version of this hook creates a variable called 4614169689Skan@samp{__stack_chk_guard}, which is normally defined in @file{libgcc2.c}. 4615169689Skan@end deftypefn 4616169689Skan 4617169689Skan@deftypefn {Target Hook} tree TARGET_STACK_PROTECT_FAIL (void) 4618169689SkanThis hook returns a tree expression that alerts the runtime that the 4619169689Skanstack protect guard variable has been modified. This expression should 4620169689Skaninvolve a call to a @code{noreturn} function. 4621169689Skan 4622169689SkanThe default version of this hook invokes a function called 4623169689Skan@samp{__stack_chk_fail}, taking no arguments. This function is 4624169689Skannormally defined in @file{libgcc2.c}. 4625169689Skan@end deftypefn 4626169689Skan 462790075Sobrien@node Varargs 462890075Sobrien@section Implementing the Varargs Macros 462990075Sobrien@cindex varargs implementation 463090075Sobrien 463190075SobrienGCC comes with an implementation of @code{<varargs.h>} and 463290075Sobrien@code{<stdarg.h>} that work without change on machines that pass arguments 463390075Sobrienon the stack. Other machines require their own implementations of 463490075Sobrienvarargs, and the two machine independent header files must have 463590075Sobrienconditionals to include it. 463690075Sobrien 463790075SobrienISO @code{<stdarg.h>} differs from traditional @code{<varargs.h>} mainly in 463890075Sobrienthe calling convention for @code{va_start}. The traditional 463990075Sobrienimplementation takes just one argument, which is the variable in which 464090075Sobriento store the argument pointer. The ISO implementation of 464190075Sobrien@code{va_start} takes an additional second argument. The user is 464290075Sobriensupposed to write the last named argument of the function here. 464390075Sobrien 464490075SobrienHowever, @code{va_start} should not use this argument. The way to find 464590075Sobrienthe end of the named arguments is with the built-in functions described 464690075Sobrienbelow. 464790075Sobrien 4648132718Skan@defmac __builtin_saveregs () 464990075SobrienUse this built-in function to save the argument registers in memory so 465090075Sobrienthat the varargs mechanism can access them. Both ISO and traditional 465190075Sobrienversions of @code{va_start} must use @code{__builtin_saveregs}, unless 4652169689Skanyou use @code{TARGET_SETUP_INCOMING_VARARGS} (see below) instead. 465390075Sobrien 465490075SobrienOn some machines, @code{__builtin_saveregs} is open-coded under the 4655169689Skancontrol of the target hook @code{TARGET_EXPAND_BUILTIN_SAVEREGS}. On 4656169689Skanother machines, it calls a routine written in assembler language, 4657169689Skanfound in @file{libgcc2.c}. 465890075Sobrien 465990075SobrienCode generated for the call to @code{__builtin_saveregs} appears at the 466090075Sobrienbeginning of the function, as opposed to where the call to 466190075Sobrien@code{__builtin_saveregs} is written, regardless of what the code is. 466290075SobrienThis is because the registers must be saved before the function starts 466390075Sobriento use them for its own purposes. 466490075Sobrien@c i rewrote the first sentence above to fix an overfull hbox. --mew 466590075Sobrien@c 10feb93 4666132718Skan@end defmac 466790075Sobrien 4668132718Skan@defmac __builtin_args_info (@var{category}) 466990075SobrienUse this built-in function to find the first anonymous arguments in 467090075Sobrienregisters. 467190075Sobrien 467290075SobrienIn general, a machine may have several categories of registers used for 467390075Sobrienarguments, each for a particular category of data types. (For example, 467490075Sobrienon some machines, floating-point registers are used for floating-point 467590075Sobrienarguments while other arguments are passed in the general registers.) 467690075SobrienTo make non-varargs functions use the proper calling convention, you 467790075Sobrienhave defined the @code{CUMULATIVE_ARGS} data type to record how many 467890075Sobrienregisters in each category have been used so far 467990075Sobrien 468090075Sobrien@code{__builtin_args_info} accesses the same data structure of type 468190075Sobrien@code{CUMULATIVE_ARGS} after the ordinary argument layout is finished 468290075Sobrienwith it, with @var{category} specifying which word to access. Thus, the 468390075Sobrienvalue indicates the first unused register in a given category. 468490075Sobrien 468590075SobrienNormally, you would use @code{__builtin_args_info} in the implementation 468690075Sobrienof @code{va_start}, accessing each category just once and storing the 468790075Sobrienvalue in the @code{va_list} object. This is because @code{va_list} will 468890075Sobrienhave to update the values, and there is no way to alter the 468990075Sobrienvalues accessed by @code{__builtin_args_info}. 4690132718Skan@end defmac 469190075Sobrien 4692132718Skan@defmac __builtin_next_arg (@var{lastarg}) 469390075SobrienThis is the equivalent of @code{__builtin_args_info}, for stack 469490075Sobrienarguments. It returns the address of the first anonymous stack 469590075Sobrienargument, as type @code{void *}. If @code{ARGS_GROW_DOWNWARD}, it 469690075Sobrienreturns the address of the location above the first anonymous stack 469790075Sobrienargument. Use it in @code{va_start} to initialize the pointer for 469890075Sobrienfetching arguments from the stack. Also use it in @code{va_start} to 469990075Sobrienverify that the second parameter @var{lastarg} is the last named argument 470090075Sobrienof the current function. 4701132718Skan@end defmac 470290075Sobrien 4703132718Skan@defmac __builtin_classify_type (@var{object}) 470490075SobrienSince each machine has its own conventions for which data types are 470590075Sobrienpassed in which kind of register, your implementation of @code{va_arg} 470690075Sobrienhas to embody these conventions. The easiest way to categorize the 470790075Sobrienspecified data type is to use @code{__builtin_classify_type} together 470890075Sobrienwith @code{sizeof} and @code{__alignof__}. 470990075Sobrien 471090075Sobrien@code{__builtin_classify_type} ignores the value of @var{object}, 471190075Sobrienconsidering only its data type. It returns an integer describing what 471290075Sobrienkind of type that is---integer, floating, pointer, structure, and so on. 471390075Sobrien 471490075SobrienThe file @file{typeclass.h} defines an enumeration that you can use to 471590075Sobrieninterpret the values of @code{__builtin_classify_type}. 4716132718Skan@end defmac 471790075Sobrien 471890075SobrienThese machine description macros help implement varargs: 471990075Sobrien 4720132718Skan@deftypefn {Target Hook} rtx TARGET_EXPAND_BUILTIN_SAVEREGS (void) 4721132718SkanIf defined, this hook produces the machine-specific code for a call to 4722132718Skan@code{__builtin_saveregs}. This code will be moved to the very 4723132718Skanbeginning of the function, before any parameter access are made. The 4724132718Skanreturn value of this function should be an RTX that contains the value 4725132718Skanto use as the return of @code{__builtin_saveregs}. 4726132718Skan@end deftypefn 472790075Sobrien 4728132718Skan@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}) 4729132718SkanThis target hook offers an alternative to using 4730132718Skan@code{__builtin_saveregs} and defining the hook 4731132718Skan@code{TARGET_EXPAND_BUILTIN_SAVEREGS}. Use it to store the anonymous 4732132718Skanregister arguments into the stack so that all the arguments appear to 4733132718Skanhave been passed consecutively on the stack. Once this is done, you can 4734132718Skanuse the standard implementation of varargs that works for machines that 4735132718Skanpass all their arguments on the stack. 473690075Sobrien 4737132718SkanThe argument @var{args_so_far} points to the @code{CUMULATIVE_ARGS} data 473890075Sobrienstructure, containing the values that are obtained after processing the 473990075Sobriennamed arguments. The arguments @var{mode} and @var{type} describe the 474090075Sobrienlast named argument---its machine mode and its data type as a tree node. 474190075Sobrien 4742132718SkanThe target hook should do two things: first, push onto the stack all the 4743132718Skanargument registers @emph{not} used for the named arguments, and second, 4744132718Skanstore the size of the data thus pushed into the @code{int}-valued 4745132718Skanvariable pointed to by @var{pretend_args_size}. The value that you 4746132718Skanstore here will serve as additional offset for setting up the stack 4747132718Skanframe. 474890075Sobrien 474990075SobrienBecause you must generate code to push the anonymous arguments at 475090075Sobriencompile time without knowing their data types, 4751132718Skan@code{TARGET_SETUP_INCOMING_VARARGS} is only useful on machines that 4752132718Skanhave just a single category of argument register and use it uniformly 4753132718Skanfor all data types. 475490075Sobrien 475590075SobrienIf the argument @var{second_time} is nonzero, it means that the 475690075Sobrienarguments of the function are being analyzed for the second time. This 475790075Sobrienhappens for an inline function, which is not actually compiled until the 4758132718Skanend of the source file. The hook @code{TARGET_SETUP_INCOMING_VARARGS} should 475990075Sobriennot generate any instructions in this case. 4760132718Skan@end deftypefn 476190075Sobrien 4762132718Skan@deftypefn {Target Hook} bool TARGET_STRICT_ARGUMENT_NAMING (CUMULATIVE_ARGS *@var{ca}) 4763132718SkanDefine this hook to return @code{true} if the location where a function 476490075Sobrienargument is passed depends on whether or not it is a named argument. 476590075Sobrien 4766132718SkanThis hook controls how the @var{named} argument to @code{FUNCTION_ARG} 4767132718Skanis set for varargs and stdarg functions. If this hook returns 4768132718Skan@code{true}, the @var{named} argument is always true for named 4769132718Skanarguments, and false for unnamed arguments. If it returns @code{false}, 4770169689Skanbut @code{TARGET_PRETEND_OUTGOING_VARARGS_NAMED} returns @code{true}, 4771132718Skanthen all arguments are treated as named. Otherwise, all named arguments 4772132718Skanexcept the last are treated as named. 477390075Sobrien 4774132718SkanYou need not define this hook if it always returns zero. 4775132718Skan@end deftypefn 477690075Sobrien 4777132718Skan@deftypefn {Target Hook} bool TARGET_PRETEND_OUTGOING_VARARGS_NAMED 477890075SobrienIf you need to conditionally change ABIs so that one works with 4779132718Skan@code{TARGET_SETUP_INCOMING_VARARGS}, but the other works like neither 4780132718Skan@code{TARGET_SETUP_INCOMING_VARARGS} nor @code{TARGET_STRICT_ARGUMENT_NAMING} was 4781132718Skandefined, then define this hook to return @code{true} if 4782169689Skan@code{TARGET_SETUP_INCOMING_VARARGS} is used, @code{false} otherwise. 4783132718SkanOtherwise, you should not define this hook. 4784132718Skan@end deftypefn 478590075Sobrien 478690075Sobrien@node Trampolines 478790075Sobrien@section Trampolines for Nested Functions 478890075Sobrien@cindex trampolines for nested functions 478990075Sobrien@cindex nested functions, trampolines for 479090075Sobrien 479190075SobrienA @dfn{trampoline} is a small piece of code that is created at run time 479290075Sobrienwhen the address of a nested function is taken. It normally resides on 479390075Sobrienthe stack, in the stack frame of the containing function. These macros 479490075Sobrientell GCC how to generate code to allocate and initialize a 479590075Sobrientrampoline. 479690075Sobrien 479790075SobrienThe instructions in the trampoline must do two things: load a constant 479890075Sobrienaddress into the static chain register, and jump to the real address of 479990075Sobrienthe nested function. On CISC machines such as the m68k, this requires 480090075Sobrientwo instructions, a move immediate and a jump. Then the two addresses 480190075Sobrienexist in the trampoline as word-long immediate operands. On RISC 480290075Sobrienmachines, it is often necessary to load each address into a register in 480390075Sobrientwo parts. Then pieces of each address form separate immediate 480490075Sobrienoperands. 480590075Sobrien 480690075SobrienThe code generated to initialize the trampoline must store the variable 480790075Sobrienparts---the static chain value and the function address---into the 480890075Sobrienimmediate operands of the instructions. On a CISC machine, this is 480990075Sobriensimply a matter of copying each address to a memory reference at the 481090075Sobrienproper offset from the start of the trampoline. On a RISC machine, it 481190075Sobrienmay be necessary to take out pieces of the address and store them 481290075Sobrienseparately. 481390075Sobrien 4814132718Skan@defmac TRAMPOLINE_TEMPLATE (@var{file}) 481590075SobrienA C statement to output, on the stream @var{file}, assembler code for a 481690075Sobrienblock of data that contains the constant parts of a trampoline. This 481790075Sobriencode should not include a label---the label is taken care of 481890075Sobrienautomatically. 481990075Sobrien 482090075SobrienIf you do not define this macro, it means no template is needed 482190075Sobrienfor the target. Do not define this macro on systems where the block move 482290075Sobriencode to copy the trampoline into place would be larger than the code 482390075Sobriento generate it on the spot. 4824132718Skan@end defmac 482590075Sobrien 4826132718Skan@defmac TRAMPOLINE_SECTION 4827169689SkanReturn the section into which the trampoline template is to be placed 4828169689Skan(@pxref{Sections}). The default value is @code{readonly_data_section}. 4829132718Skan@end defmac 483090075Sobrien 4831132718Skan@defmac TRAMPOLINE_SIZE 483290075SobrienA C expression for the size in bytes of the trampoline, as an integer. 4833132718Skan@end defmac 483490075Sobrien 4835132718Skan@defmac TRAMPOLINE_ALIGNMENT 483690075SobrienAlignment required for trampolines, in bits. 483790075Sobrien 483890075SobrienIf you don't define this macro, the value of @code{BIGGEST_ALIGNMENT} 483990075Sobrienis used for aligning trampolines. 4840132718Skan@end defmac 484190075Sobrien 4842132718Skan@defmac INITIALIZE_TRAMPOLINE (@var{addr}, @var{fnaddr}, @var{static_chain}) 484390075SobrienA C statement to initialize the variable parts of a trampoline. 484490075Sobrien@var{addr} is an RTX for the address of the trampoline; @var{fnaddr} is 484590075Sobrienan RTX for the address of the nested function; @var{static_chain} is an 484690075SobrienRTX for the static chain value that should be passed to the function 484790075Sobrienwhen it is called. 4848132718Skan@end defmac 484990075Sobrien 4850132718Skan@defmac TRAMPOLINE_ADJUST_ADDRESS (@var{addr}) 485190075SobrienA C statement that should perform any machine-specific adjustment in 485290075Sobrienthe address of the trampoline. Its argument contains the address that 485390075Sobrienwas passed to @code{INITIALIZE_TRAMPOLINE}. In case the address to be 485490075Sobrienused for a function call should be different from the address in which 485590075Sobrienthe template was stored, the different address should be assigned to 485690075Sobrien@var{addr}. If this macro is not defined, @var{addr} will be used for 485790075Sobrienfunction calls. 485890075Sobrien 485990075Sobrien@cindex @code{TARGET_ASM_FUNCTION_EPILOGUE} and trampolines 486090075Sobrien@cindex @code{TARGET_ASM_FUNCTION_PROLOGUE} and trampolines 486190075SobrienIf this macro is not defined, by default the trampoline is allocated as 486290075Sobriena stack slot. This default is right for most machines. The exceptions 486390075Sobrienare machines where it is impossible to execute instructions in the stack 486490075Sobrienarea. On such machines, you may have to implement a separate stack, 486590075Sobrienusing this macro in conjunction with @code{TARGET_ASM_FUNCTION_PROLOGUE} 486690075Sobrienand @code{TARGET_ASM_FUNCTION_EPILOGUE}. 486790075Sobrien 486890075Sobrien@var{fp} points to a data structure, a @code{struct function}, which 486990075Sobriendescribes the compilation status of the immediate containing function of 4870132718Skanthe function which the trampoline is for. The stack slot for the 487190075Sobrientrampoline is in the stack frame of this containing function. Other 487290075Sobrienallocation strategies probably must do something analogous with this 487390075Sobrieninformation. 4874132718Skan@end defmac 487590075Sobrien 487690075SobrienImplementing trampolines is difficult on many machines because they have 487790075Sobrienseparate instruction and data caches. Writing into a stack location 487890075Sobrienfails to clear the memory in the instruction cache, so when the program 487990075Sobrienjumps to that location, it executes the old contents. 488090075Sobrien 488190075SobrienHere are two possible solutions. One is to clear the relevant parts of 488290075Sobrienthe instruction cache whenever a trampoline is set up. The other is to 488390075Sobrienmake all trampolines identical, by having them jump to a standard 488490075Sobriensubroutine. The former technique makes trampoline execution faster; the 488590075Sobrienlatter makes initialization faster. 488690075Sobrien 488790075SobrienTo clear the instruction cache when a trampoline is initialized, define 4888132718Skanthe following macro. 488990075Sobrien 4890132718Skan@defmac CLEAR_INSN_CACHE (@var{beg}, @var{end}) 4891132718SkanIf defined, expands to a C expression clearing the @emph{instruction 4892132718Skancache} in the specified interval. The definition of this macro would 4893132718Skantypically be a series of @code{asm} statements. Both @var{beg} and 4894132718Skan@var{end} are both pointer expressions. 4895132718Skan@end defmac 489690075Sobrien 4897132718SkanThe operating system may also require the stack to be made executable 4898132718Skanbefore calling the trampoline. To implement this requirement, define 4899132718Skanthe following macro. 490090075Sobrien 4901132718Skan@defmac ENABLE_EXECUTE_STACK 4902132718SkanDefine this macro if certain operations must be performed before executing 4903132718Skancode located on the stack. The macro should expand to a series of C 4904169689Skanfile-scope constructs (e.g.@: functions) and provide a unique entry point 4905132718Skannamed @code{__enable_execute_stack}. The target is responsible for 4906132718Skanemitting calls to the entry point in the code, for example from the 4907132718Skan@code{INITIALIZE_TRAMPOLINE} macro. 4908132718Skan@end defmac 490990075Sobrien 491090075SobrienTo use a standard subroutine, define the following macro. In addition, 491190075Sobrienyou must make sure that the instructions in a trampoline fill an entire 491290075Sobriencache line with identical instructions, or else ensure that the 491390075Sobrienbeginning of the trampoline code is always aligned at the same point in 491490075Sobrienits cache line. Look in @file{m68k.h} as a guide. 491590075Sobrien 4916132718Skan@defmac TRANSFER_FROM_TRAMPOLINE 491790075SobrienDefine this macro if trampolines need a special subroutine to do their 491890075Sobrienwork. The macro should expand to a series of @code{asm} statements 491990075Sobrienwhich will be compiled with GCC@. They go in a library function named 492090075Sobrien@code{__transfer_from_trampoline}. 492190075Sobrien 492290075SobrienIf you need to avoid executing the ordinary prologue code of a compiled 492390075SobrienC function when you jump to the subroutine, you can do so by placing a 492490075Sobrienspecial label of your own in the assembler code. Use one @code{asm} 492590075Sobrienstatement to generate an assembler label, and another to make the label 492690075Sobrienglobal. Then trampolines can use that label to jump directly to your 492790075Sobrienspecial assembler code. 4928132718Skan@end defmac 492990075Sobrien 493090075Sobrien@node Library Calls 493190075Sobrien@section Implicit Calls to Library Routines 493290075Sobrien@cindex library subroutine names 493390075Sobrien@cindex @file{libgcc.a} 493490075Sobrien 493590075Sobrien@c prevent bad page break with this line 493690075SobrienHere is an explanation of implicit calls to library routines. 493790075Sobrien 4938132718Skan@defmac DECLARE_LIBRARY_RENAMES 4939132718SkanThis macro, if defined, should expand to a piece of C code that will get 4940132718Skanexpanded when compiling functions for libgcc.a. It can be used to 4941132718Skanprovide alternate names for GCC's internal library functions if there 4942132718Skanare ABI-mandated names that the compiler should provide. 4943132718Skan@end defmac 494490075Sobrien 4945132718Skan@findex init_one_libfunc 4946132718Skan@findex set_optab_libfunc 4947132718Skan@deftypefn {Target Hook} void TARGET_INIT_LIBFUNCS (void) 4948132718SkanThis hook should declare additional library routines or rename 4949132718Skanexisting ones, using the functions @code{set_optab_libfunc} and 4950132718Skan@code{init_one_libfunc} defined in @file{optabs.c}. 4951132718Skan@code{init_optabs} calls this macro after initializing all the normal 4952132718Skanlibrary routines. 495390075Sobrien 4954132718SkanThe default is to do nothing. Most ports don't need to define this hook. 4955132718Skan@end deftypefn 495690075Sobrien 4957169689Skan@defmac FLOAT_LIB_COMPARE_RETURNS_BOOL (@var{mode}, @var{comparison}) 4958132718SkanThis macro should return @code{true} if the library routine that 4959132718Skanimplements the floating point comparison operator @var{comparison} in 4960132718Skanmode @var{mode} will return a boolean, and @var{false} if it will 4961132718Skanreturn a tristate. 496290075Sobrien 4963132718SkanGCC's own floating point libraries return tristates from the 4964132718Skancomparison operators, so the default returns false always. Most ports 4965132718Skandon't need to define this macro. 4966132718Skan@end defmac 496790075Sobrien 4968169689Skan@defmac TARGET_LIB_INT_CMP_BIASED 4969169689SkanThis macro should evaluate to @code{true} if the integer comparison 4970169689Skanfunctions (like @code{__cmpdi2}) return 0 to indicate that the first 4971169689Skanoperand is smaller than the second, 1 to indicate that they are equal, 4972169689Skanand 2 to indicate that the first operand is greater than the second. 4973169689SkanIf this macro evaluates to @code{false} the comparison functions return 4974169689Skan@minus{}1, 0, and 1 instead of 0, 1, and 2. If the target uses the routines 4975169689Skanin @file{libgcc.a}, you do not need to define this macro. 4976169689Skan@end defmac 4977169689Skan 4978132718Skan@cindex US Software GOFAST, floating point emulation library 4979132718Skan@cindex floating point emulation library, US Software GOFAST 4980132718Skan@cindex GOFAST, floating point emulation library 4981132718Skan@findex gofast_maybe_init_libfuncs 4982132718Skan@defmac US_SOFTWARE_GOFAST 4983132718SkanDefine this macro if your system C library uses the US Software GOFAST 4984132718Skanlibrary to provide floating point emulation. 498590075Sobrien 4986132718SkanIn addition to defining this macro, your architecture must set 4987132718Skan@code{TARGET_INIT_LIBFUNCS} to @code{gofast_maybe_init_libfuncs}, or 4988132718Skanelse call that function from its version of that hook. It is defined 4989132718Skanin @file{config/gofast.h}, which must be included by your 4990132718Skanarchitecture's @file{@var{cpu}.c} file. See @file{sparc/sparc.c} for 4991132718Skanan example. 499290075Sobrien 4993132718SkanIf this macro is defined, the 4994132718Skan@code{TARGET_FLOAT_LIB_COMPARE_RETURNS_BOOL} target hook must return 4995132718Skanfalse for @code{SFmode} and @code{DFmode} comparisons. 4996132718Skan@end defmac 499790075Sobrien 499890075Sobrien@cindex @code{EDOM}, implicit usage 4999132718Skan@findex matherr 5000132718Skan@defmac TARGET_EDOM 500190075SobrienThe value of @code{EDOM} on the target machine, as a C integer constant 500290075Sobrienexpression. If you don't define this macro, GCC does not attempt to 500390075Sobriendeposit the value of @code{EDOM} into @code{errno} directly. Look in 500490075Sobrien@file{/usr/include/errno.h} to find the value of @code{EDOM} on your 500590075Sobriensystem. 500690075Sobrien 500790075SobrienIf you do not define @code{TARGET_EDOM}, then compiled code reports 500890075Sobriendomain errors by calling the library function and letting it report the 500990075Sobrienerror. If mathematical functions on your system use @code{matherr} when 501090075Sobrienthere is an error, then you should leave @code{TARGET_EDOM} undefined so 501190075Sobrienthat @code{matherr} is used normally. 5012132718Skan@end defmac 501390075Sobrien 501490075Sobrien@cindex @code{errno}, implicit usage 5015132718Skan@defmac GEN_ERRNO_RTX 501690075SobrienDefine this macro as a C expression to create an rtl expression that 501790075Sobrienrefers to the global ``variable'' @code{errno}. (On certain systems, 501890075Sobrien@code{errno} may not actually be a variable.) If you don't define this 501990075Sobrienmacro, a reasonable default is used. 5020132718Skan@end defmac 502190075Sobrien 5022132718Skan@cindex C99 math functions, implicit usage 5023132718Skan@defmac TARGET_C99_FUNCTIONS 5024132718SkanWhen this macro is nonzero, GCC will implicitly optimize @code{sin} calls into 5025132718Skan@code{sinf} and similarly for other functions defined by C99 standard. The 5026132718Skandefault is nonzero that should be proper value for most modern systems, however 5027132718Skannumber of existing systems lacks support for these functions in the runtime so 5028132718Skanthey needs this macro to be redefined to 0. 5029132718Skan@end defmac 503090075Sobrien 503190075Sobrien@node Addressing Modes 503290075Sobrien@section Addressing Modes 503390075Sobrien@cindex addressing modes 503490075Sobrien 503590075Sobrien@c prevent bad page break with this line 503690075SobrienThis is about addressing modes. 503790075Sobrien 5038132718Skan@defmac HAVE_PRE_INCREMENT 5039132718Skan@defmacx HAVE_PRE_DECREMENT 5040132718Skan@defmacx HAVE_POST_INCREMENT 5041132718Skan@defmacx HAVE_POST_DECREMENT 504290075SobrienA C expression that is nonzero if the machine supports pre-increment, 504390075Sobrienpre-decrement, post-increment, or post-decrement addressing respectively. 5044132718Skan@end defmac 504590075Sobrien 5046132718Skan@defmac HAVE_PRE_MODIFY_DISP 5047132718Skan@defmacx HAVE_POST_MODIFY_DISP 504890075SobrienA C expression that is nonzero if the machine supports pre- or 504990075Sobrienpost-address side-effect generation involving constants other than 505090075Sobrienthe size of the memory operand. 5051132718Skan@end defmac 505290075Sobrien 5053132718Skan@defmac HAVE_PRE_MODIFY_REG 5054132718Skan@defmacx HAVE_POST_MODIFY_REG 505590075SobrienA C expression that is nonzero if the machine supports pre- or 505690075Sobrienpost-address side-effect generation involving a register displacement. 5057132718Skan@end defmac 505890075Sobrien 5059132718Skan@defmac CONSTANT_ADDRESS_P (@var{x}) 506090075SobrienA C expression that is 1 if the RTX @var{x} is a constant which 506190075Sobrienis a valid address. On most machines, this can be defined as 506290075Sobrien@code{CONSTANT_P (@var{x})}, but a few machines are more restrictive 506390075Sobrienin which constant addresses are supported. 5064132718Skan@end defmac 506590075Sobrien 5066132718Skan@defmac CONSTANT_P (@var{x}) 5067132718Skan@code{CONSTANT_P}, which is defined by target-independent code, 5068132718Skanaccepts integer-values expressions whose values are not explicitly 5069132718Skanknown, such as @code{symbol_ref}, @code{label_ref}, and @code{high} 5070132718Skanexpressions and @code{const} arithmetic expressions, in addition to 5071132718Skan@code{const_int} and @code{const_double} expressions. 5072132718Skan@end defmac 507390075Sobrien 5074132718Skan@defmac MAX_REGS_PER_ADDRESS 507590075SobrienA number, the maximum number of registers that can appear in a valid 507690075Sobrienmemory address. Note that it is up to you to specify a value equal to 507790075Sobrienthe maximum number that @code{GO_IF_LEGITIMATE_ADDRESS} would ever 507890075Sobrienaccept. 5079132718Skan@end defmac 508090075Sobrien 5081132718Skan@defmac GO_IF_LEGITIMATE_ADDRESS (@var{mode}, @var{x}, @var{label}) 508290075SobrienA C compound statement with a conditional @code{goto @var{label};} 508390075Sobrienexecuted if @var{x} (an RTX) is a legitimate memory address on the 508490075Sobrientarget machine for a memory operand of mode @var{mode}. 508590075Sobrien 508690075SobrienIt usually pays to define several simpler macros to serve as 508790075Sobriensubroutines for this one. Otherwise it may be too complicated to 508890075Sobrienunderstand. 508990075Sobrien 509090075SobrienThis macro must exist in two variants: a strict variant and a 509190075Sobriennon-strict one. The strict variant is used in the reload pass. It 509290075Sobrienmust be defined so that any pseudo-register that has not been 509390075Sobrienallocated a hard register is considered a memory reference. In 509490075Sobriencontexts where some kind of register is required, a pseudo-register 509590075Sobrienwith no hard register must be rejected. 509690075Sobrien 509790075SobrienThe non-strict variant is used in other passes. It must be defined to 509890075Sobrienaccept all pseudo-registers in every context where some kind of 509990075Sobrienregister is required. 510090075Sobrien 510190075Sobrien@findex REG_OK_STRICT 510290075SobrienCompiler source files that want to use the strict variant of this 510390075Sobrienmacro define the macro @code{REG_OK_STRICT}. You should use an 510490075Sobrien@code{#ifdef REG_OK_STRICT} conditional to define the strict variant 510590075Sobrienin that case and the non-strict variant otherwise. 510690075Sobrien 510790075SobrienSubroutines to check for acceptable registers for various purposes (one 510890075Sobrienfor base registers, one for index registers, and so on) are typically 510990075Sobrienamong the subroutines used to define @code{GO_IF_LEGITIMATE_ADDRESS}. 511090075SobrienThen only these subroutine macros need have two variants; the higher 511190075Sobrienlevels of macros may be the same whether strict or not. 511290075Sobrien 511390075SobrienNormally, constant addresses which are the sum of a @code{symbol_ref} 511490075Sobrienand an integer are stored inside a @code{const} RTX to mark them as 511590075Sobrienconstant. Therefore, there is no need to recognize such sums 511690075Sobrienspecifically as legitimate addresses. Normally you would simply 511790075Sobrienrecognize any @code{const} as legitimate. 511890075Sobrien 511990075SobrienUsually @code{PRINT_OPERAND_ADDRESS} is not prepared to handle constant 512090075Sobriensums that are not marked with @code{const}. It assumes that a naked 512190075Sobrien@code{plus} indicates indexing. If so, then you @emph{must} reject such 512290075Sobriennaked constant sums as illegitimate addresses, so that none of them will 512390075Sobrienbe given to @code{PRINT_OPERAND_ADDRESS}. 512490075Sobrien 5125117395Skan@cindex @code{TARGET_ENCODE_SECTION_INFO} and address validation 512690075SobrienOn some machines, whether a symbolic address is legitimate depends on 512790075Sobrienthe section that the address refers to. On these machines, define the 5128117395Skantarget hook @code{TARGET_ENCODE_SECTION_INFO} to store the information 5129117395Skaninto the @code{symbol_ref}, and then check for it here. When you see a 513090075Sobrien@code{const}, you will have to look inside it to find the 513190075Sobrien@code{symbol_ref} in order to determine the section. @xref{Assembler 513290075SobrienFormat}. 5133132718Skan@end defmac 513490075Sobrien 5135132718Skan@defmac FIND_BASE_TERM (@var{x}) 513690075SobrienA C expression to determine the base term of address @var{x}. 513790075SobrienThis macro is used in only one place: `find_base_term' in alias.c. 513890075Sobrien 513990075SobrienIt is always safe for this macro to not be defined. It exists so 514090075Sobrienthat alias analysis can understand machine-dependent addresses. 514190075Sobrien 514290075SobrienThe typical use of this macro is to handle addresses containing 514390075Sobriena label_ref or symbol_ref within an UNSPEC@. 5144132718Skan@end defmac 514590075Sobrien 5146132718Skan@defmac LEGITIMIZE_ADDRESS (@var{x}, @var{oldx}, @var{mode}, @var{win}) 514790075SobrienA C compound statement that attempts to replace @var{x} with a valid 514890075Sobrienmemory address for an operand of mode @var{mode}. @var{win} will be a 514990075SobrienC statement label elsewhere in the code; the macro definition may use 515090075Sobrien 5151132718Skan@smallexample 515290075SobrienGO_IF_LEGITIMATE_ADDRESS (@var{mode}, @var{x}, @var{win}); 5153132718Skan@end smallexample 515490075Sobrien 515590075Sobrien@noindent 515690075Sobriento avoid further processing if the address has become legitimate. 515790075Sobrien 515890075Sobrien@findex break_out_memory_refs 515990075Sobrien@var{x} will always be the result of a call to @code{break_out_memory_refs}, 516090075Sobrienand @var{oldx} will be the operand that was given to that function to produce 516190075Sobrien@var{x}. 516290075Sobrien 516390075SobrienThe code generated by this macro should not alter the substructure of 516490075Sobrien@var{x}. If it transforms @var{x} into a more legitimate form, it 516590075Sobrienshould assign @var{x} (which will always be a C variable) a new value. 516690075Sobrien 516790075SobrienIt is not necessary for this macro to come up with a legitimate 516890075Sobrienaddress. The compiler has standard ways of doing so in all cases. In 5169169689Skanfact, it is safe to omit this macro. But often a 517090075Sobrienmachine-dependent strategy can generate better code. 5171132718Skan@end defmac 517290075Sobrien 5173132718Skan@defmac LEGITIMIZE_RELOAD_ADDRESS (@var{x}, @var{mode}, @var{opnum}, @var{type}, @var{ind_levels}, @var{win}) 517490075SobrienA C compound statement that attempts to replace @var{x}, which is an address 517590075Sobrienthat needs reloading, with a valid memory address for an operand of mode 517690075Sobrien@var{mode}. @var{win} will be a C statement label elsewhere in the code. 517790075SobrienIt is not necessary to define this macro, but it might be useful for 517890075Sobrienperformance reasons. 517990075Sobrien 518090075SobrienFor example, on the i386, it is sometimes possible to use a single 518190075Sobrienreload register instead of two by reloading a sum of two pseudo 518290075Sobrienregisters into a register. On the other hand, for number of RISC 518390075Sobrienprocessors offsets are limited so that often an intermediate address 518490075Sobrienneeds to be generated in order to address a stack slot. By defining 518590075Sobrien@code{LEGITIMIZE_RELOAD_ADDRESS} appropriately, the intermediate addresses 518690075Sobriengenerated for adjacent some stack slots can be made identical, and thus 518790075Sobrienbe shared. 518890075Sobrien 518990075Sobrien@emph{Note}: This macro should be used with caution. It is necessary 519090075Sobriento know something of how reload works in order to effectively use this, 519190075Sobrienand it is quite easy to produce macros that build in too much knowledge 519290075Sobrienof reload internals. 519390075Sobrien 519490075Sobrien@emph{Note}: This macro must be able to reload an address created by a 519590075Sobrienprevious invocation of this macro. If it fails to handle such addresses 519690075Sobrienthen the compiler may generate incorrect code or abort. 519790075Sobrien 519890075Sobrien@findex push_reload 519990075SobrienThe macro definition should use @code{push_reload} to indicate parts that 520090075Sobrienneed reloading; @var{opnum}, @var{type} and @var{ind_levels} are usually 520190075Sobriensuitable to be passed unaltered to @code{push_reload}. 520290075Sobrien 520390075SobrienThe code generated by this macro must not alter the substructure of 520490075Sobrien@var{x}. If it transforms @var{x} into a more legitimate form, it 520590075Sobrienshould assign @var{x} (which will always be a C variable) a new value. 520690075SobrienThis also applies to parts that you change indirectly by calling 520790075Sobrien@code{push_reload}. 520890075Sobrien 520990075Sobrien@findex strict_memory_address_p 521090075SobrienThe macro definition may use @code{strict_memory_address_p} to test if 521190075Sobrienthe address has become legitimate. 521290075Sobrien 521390075Sobrien@findex copy_rtx 521490075SobrienIf you want to change only a part of @var{x}, one standard way of doing 521590075Sobrienthis is to use @code{copy_rtx}. Note, however, that is unshares only a 521690075Sobriensingle level of rtl. Thus, if the part to be changed is not at the 521790075Sobrientop level, you'll need to replace first the top level. 521890075SobrienIt is not necessary for this macro to come up with a legitimate 521990075Sobrienaddress; but often a machine-dependent strategy can generate better code. 5220132718Skan@end defmac 522190075Sobrien 5222132718Skan@defmac GO_IF_MODE_DEPENDENT_ADDRESS (@var{addr}, @var{label}) 522390075SobrienA C statement or compound statement with a conditional @code{goto 522490075Sobrien@var{label};} executed if memory address @var{x} (an RTX) can have 522590075Sobriendifferent meanings depending on the machine mode of the memory 522690075Sobrienreference it is used for or if the address is valid for some modes 522790075Sobrienbut not others. 522890075Sobrien 522990075SobrienAutoincrement and autodecrement addresses typically have mode-dependent 523090075Sobrieneffects because the amount of the increment or decrement is the size 523190075Sobrienof the operand being addressed. Some machines have other mode-dependent 523290075Sobrienaddresses. Many RISC machines have no mode-dependent addresses. 523390075Sobrien 523490075SobrienYou may assume that @var{addr} is a valid address for the machine. 5235132718Skan@end defmac 523690075Sobrien 5237132718Skan@defmac LEGITIMATE_CONSTANT_P (@var{x}) 523890075SobrienA C expression that is nonzero if @var{x} is a legitimate constant for 523990075Sobrienan immediate operand on the target machine. You can assume that 524090075Sobrien@var{x} satisfies @code{CONSTANT_P}, so you need not check this. In fact, 524190075Sobrien@samp{1} is a suitable definition for this macro on machines where 524290075Sobrienanything @code{CONSTANT_P} is valid. 5243132718Skan@end defmac 524490075Sobrien 5245169689Skan@deftypefn {Target Hook} rtx TARGET_DELEGITIMIZE_ADDRESS (rtx @var{x}) 5246169689SkanThis hook is used to undo the possibly obfuscating effects of the 5247169689Skan@code{LEGITIMIZE_ADDRESS} and @code{LEGITIMIZE_RELOAD_ADDRESS} target 5248169689Skanmacros. Some backend implementations of these macros wrap symbol 5249169689Skanreferences inside an @code{UNSPEC} rtx to represent PIC or similar 5250169689Skanaddressing modes. This target hook allows GCC's optimizers to understand 5251169689Skanthe semantics of these opaque @code{UNSPEC}s by converting them back 5252169689Skaninto their original form. 5253169689Skan@end deftypefn 5254169689Skan 5255169689Skan@deftypefn {Target Hook} bool TARGET_CANNOT_FORCE_CONST_MEM (rtx @var{x}) 5256169689SkanThis hook should return true if @var{x} is of a form that cannot (or 5257169689Skanshould not) be spilled to the constant pool. The default version of 5258169689Skanthis hook returns false. 5259169689Skan 5260169689SkanThe primary reason to define this hook is to prevent reload from 5261169689Skandeciding that a non-legitimate constant would be better reloaded 5262169689Skanfrom the constant pool instead of spilling and reloading a register 5263169689Skanholding the constant. This restriction is often true of addresses 5264169689Skanof TLS symbols for various targets. 5265169689Skan@end deftypefn 5266169689Skan 5267169689Skan@deftypefn {Target Hook} bool TARGET_USE_BLOCKS_FOR_CONSTANT_P (enum machine_mode @var{mode}, rtx @var{x}) 5268169689SkanThis hook should return true if pool entries for constant @var{x} can 5269169689Skanbe placed in an @code{object_block} structure. @var{mode} is the mode 5270169689Skanof @var{x}. 5271169689Skan 5272169689SkanThe default version returns false for all constants. 5273169689Skan@end deftypefn 5274169689Skan 5275169689Skan@deftypefn {Target Hook} tree TARGET_VECTORIZE_BUILTIN_MASK_FOR_LOAD (void) 5276169689SkanThis hook should return the DECL of a function @var{f} that given an 5277169689Skanaddress @var{addr} as an argument returns a mask @var{m} that can be 5278169689Skanused to extract from two vectors the relevant data that resides in 5279169689Skan@var{addr} in case @var{addr} is not properly aligned. 5280169689Skan 5281169689SkanThe autovectrizer, when vectorizing a load operation from an address 5282169689Skan@var{addr} that may be unaligned, will generate two vector loads from 5283169689Skanthe two aligned addresses around @var{addr}. It then generates a 5284169689Skan@code{REALIGN_LOAD} operation to extract the relevant data from the 5285169689Skantwo loaded vectors. The first two arguments to @code{REALIGN_LOAD}, 5286169689Skan@var{v1} and @var{v2}, are the two vectors, each of size @var{VS}, and 5287169689Skanthe third argument, @var{OFF}, defines how the data will be extracted 5288169689Skanfrom these two vectors: if @var{OFF} is 0, then the returned vector is 5289169689Skan@var{v2}; otherwise, the returned vector is composed from the last 5290169689Skan@var{VS}-@var{OFF} elements of @var{v1} concatenated to the first 5291169689Skan@var{OFF} elements of @var{v2}. 5292169689Skan 5293169689SkanIf this hook is defined, the autovectorizer will generate a call 5294169689Skanto @var{f} (using the DECL tree that this hook returns) and will 5295169689Skanuse the return value of @var{f} as the argument @var{OFF} to 5296169689Skan@code{REALIGN_LOAD}. Therefore, the mask @var{m} returned by @var{f} 5297169689Skanshould comply with the semantics expected by @code{REALIGN_LOAD} 5298169689Skandescribed above. 5299169689SkanIf this hook is not defined, then @var{addr} will be used as 5300169689Skanthe argument @var{OFF} to @code{REALIGN_LOAD}, in which case the low 5301169689Skanlog2(@var{VS})-1 bits of @var{addr} will be considered. 5302169689Skan@end deftypefn 5303169689Skan 5304169689Skan@node Anchored Addresses 5305169689Skan@section Anchored Addresses 5306169689Skan@cindex anchored addresses 5307169689Skan@cindex @option{-fsection-anchors} 5308169689Skan 5309169689SkanGCC usually addresses every static object as a separate entity. 5310169689SkanFor example, if we have: 5311169689Skan 5312169689Skan@smallexample 5313169689Skanstatic int a, b, c; 5314169689Skanint foo (void) @{ return a + b + c; @} 5315169689Skan@end smallexample 5316169689Skan 5317169689Skanthe code for @code{foo} will usually calculate three separate symbolic 5318169689Skanaddresses: those of @code{a}, @code{b} and @code{c}. On some targets, 5319169689Skanit would be better to calculate just one symbolic address and access 5320169689Skanthe three variables relative to it. The equivalent pseudocode would 5321169689Skanbe something like: 5322169689Skan 5323169689Skan@smallexample 5324169689Skanint foo (void) 5325169689Skan@{ 5326169689Skan register int *xr = &x; 5327169689Skan return xr[&a - &x] + xr[&b - &x] + xr[&c - &x]; 5328169689Skan@} 5329169689Skan@end smallexample 5330169689Skan 5331169689Skan(which isn't valid C). We refer to shared addresses like @code{x} as 5332169689Skan``section anchors''. Their use is controlled by @option{-fsection-anchors}. 5333169689Skan 5334169689SkanThe hooks below describe the target properties that GCC needs to know 5335169689Skanin order to make effective use of section anchors. It won't use 5336169689Skansection anchors at all unless either @code{TARGET_MIN_ANCHOR_OFFSET} 5337169689Skanor @code{TARGET_MAX_ANCHOR_OFFSET} is set to a nonzero value. 5338169689Skan 5339169689Skan@deftypevar {Target Hook} HOST_WIDE_INT TARGET_MIN_ANCHOR_OFFSET 5340169689SkanThe minimum offset that should be applied to a section anchor. 5341169689SkanOn most targets, it should be the smallest offset that can be 5342169689Skanapplied to a base register while still giving a legitimate address 5343169689Skanfor every mode. The default value is 0. 5344169689Skan@end deftypevar 5345169689Skan 5346169689Skan@deftypevar {Target Hook} HOST_WIDE_INT TARGET_MAX_ANCHOR_OFFSET 5347169689SkanLike @code{TARGET_MIN_ANCHOR_OFFSET}, but the maximum (inclusive) 5348169689Skanoffset that should be applied to section anchors. The default 5349169689Skanvalue is 0. 5350169689Skan@end deftypevar 5351169689Skan 5352169689Skan@deftypefn {Target Hook} void TARGET_ASM_OUTPUT_ANCHOR (rtx @var{x}) 5353169689SkanWrite the assembly code to define section anchor @var{x}, which is a 5354169689Skan@code{SYMBOL_REF} for which @samp{SYMBOL_REF_ANCHOR_P (@var{x})} is true. 5355169689SkanThe hook is called with the assembly output position set to the beginning 5356169689Skanof @code{SYMBOL_REF_BLOCK (@var{x})}. 5357169689Skan 5358169689SkanIf @code{ASM_OUTPUT_DEF} is available, the hook's default definition uses 5359169689Skanit to define the symbol as @samp{. + SYMBOL_REF_BLOCK_OFFSET (@var{x})}. 5360169689SkanIf @code{ASM_OUTPUT_DEF} is not available, the hook's default definition 5361169689Skanis @code{NULL}, which disables the use of section anchors altogether. 5362169689Skan@end deftypefn 5363169689Skan 5364169689Skan@deftypefn {Target Hook} bool TARGET_USE_ANCHORS_FOR_SYMBOL_P (rtx @var{x}) 5365169689SkanReturn true if GCC should attempt to use anchors to access @code{SYMBOL_REF} 5366169689Skan@var{x}. You can assume @samp{SYMBOL_REF_HAS_BLOCK_INFO_P (@var{x})} and 5367169689Skan@samp{!SYMBOL_REF_ANCHOR_P (@var{x})}. 5368169689Skan 5369169689SkanThe default version is correct for most targets, but you might need to 5370169689Skanintercept this hook to handle things like target-specific attributes 5371169689Skanor target-specific sections. 5372169689Skan@end deftypefn 5373169689Skan 537490075Sobrien@node Condition Code 537590075Sobrien@section Condition Code Status 537690075Sobrien@cindex condition code status 537790075Sobrien 537890075Sobrien@c prevent bad page break with this line 537990075SobrienThis describes the condition code status. 538090075Sobrien 538190075Sobrien@findex cc_status 538290075SobrienThe file @file{conditions.h} defines a variable @code{cc_status} to 538390075Sobriendescribe how the condition code was computed (in case the interpretation of 538490075Sobrienthe condition code depends on the instruction that it was set by). This 538590075Sobrienvariable contains the RTL expressions on which the condition code is 538690075Sobriencurrently based, and several standard flags. 538790075Sobrien 538890075SobrienSometimes additional machine-specific flags must be defined in the machine 538990075Sobriendescription header file. It can also add additional machine-specific 539090075Sobrieninformation by defining @code{CC_STATUS_MDEP}. 539190075Sobrien 5392132718Skan@defmac CC_STATUS_MDEP 539390075SobrienC code for a data type which is used for declaring the @code{mdep} 539490075Sobriencomponent of @code{cc_status}. It defaults to @code{int}. 539590075Sobrien 539690075SobrienThis macro is not used on machines that do not use @code{cc0}. 5397132718Skan@end defmac 539890075Sobrien 5399132718Skan@defmac CC_STATUS_MDEP_INIT 540090075SobrienA C expression to initialize the @code{mdep} field to ``empty''. 540190075SobrienThe default definition does nothing, since most machines don't use 540290075Sobrienthe field anyway. If you want to use the field, you should probably 540390075Sobriendefine this macro to initialize it. 540490075Sobrien 540590075SobrienThis macro is not used on machines that do not use @code{cc0}. 5406132718Skan@end defmac 540790075Sobrien 5408132718Skan@defmac NOTICE_UPDATE_CC (@var{exp}, @var{insn}) 540990075SobrienA C compound statement to set the components of @code{cc_status} 541090075Sobrienappropriately for an insn @var{insn} whose body is @var{exp}. It is 541190075Sobrienthis macro's responsibility to recognize insns that set the condition 541290075Sobriencode as a byproduct of other activity as well as those that explicitly 541390075Sobrienset @code{(cc0)}. 541490075Sobrien 541590075SobrienThis macro is not used on machines that do not use @code{cc0}. 541690075Sobrien 541790075SobrienIf there are insns that do not set the condition code but do alter 541890075Sobrienother machine registers, this macro must check to see whether they 541990075Sobrieninvalidate the expressions that the condition code is recorded as 542090075Sobrienreflecting. For example, on the 68000, insns that store in address 542190075Sobrienregisters do not set the condition code, which means that usually 542290075Sobrien@code{NOTICE_UPDATE_CC} can leave @code{cc_status} unaltered for such 542390075Sobrieninsns. But suppose that the previous insn set the condition code 542490075Sobrienbased on location @samp{a4@@(102)} and the current insn stores a new 542590075Sobrienvalue in @samp{a4}. Although the condition code is not changed by 542690075Sobrienthis, it will no longer be true that it reflects the contents of 542790075Sobrien@samp{a4@@(102)}. Therefore, @code{NOTICE_UPDATE_CC} must alter 542890075Sobrien@code{cc_status} in this case to say that nothing is known about the 542990075Sobriencondition code value. 543090075Sobrien 543190075SobrienThe definition of @code{NOTICE_UPDATE_CC} must be prepared to deal 543290075Sobrienwith the results of peephole optimization: insns whose patterns are 543390075Sobrien@code{parallel} RTXs containing various @code{reg}, @code{mem} or 543490075Sobrienconstants which are just the operands. The RTL structure of these 543590075Sobrieninsns is not sufficient to indicate what the insns actually do. What 543690075Sobrien@code{NOTICE_UPDATE_CC} should do when it sees one is just to run 543790075Sobrien@code{CC_STATUS_INIT}. 543890075Sobrien 543990075SobrienA possible definition of @code{NOTICE_UPDATE_CC} is to call a function 544090075Sobrienthat looks at an attribute (@pxref{Insn Attributes}) named, for example, 544190075Sobrien@samp{cc}. This avoids having detailed information about patterns in 544290075Sobrientwo places, the @file{md} file and in @code{NOTICE_UPDATE_CC}. 5443132718Skan@end defmac 544490075Sobrien 5445132718Skan@defmac SELECT_CC_MODE (@var{op}, @var{x}, @var{y}) 544690075SobrienReturns a mode from class @code{MODE_CC} to be used when comparison 544790075Sobrienoperation code @var{op} is applied to rtx @var{x} and @var{y}. For 5448117395Skanexample, on the SPARC, @code{SELECT_CC_MODE} is defined as (see 544990075Sobrien@pxref{Jump Patterns} for a description of the reason for this 545090075Sobriendefinition) 545190075Sobrien 545290075Sobrien@smallexample 545390075Sobrien#define SELECT_CC_MODE(OP,X,Y) \ 545490075Sobrien (GET_MODE_CLASS (GET_MODE (X)) == MODE_FLOAT \ 545590075Sobrien ? ((OP == EQ || OP == NE) ? CCFPmode : CCFPEmode) \ 545690075Sobrien : ((GET_CODE (X) == PLUS || GET_CODE (X) == MINUS \ 545790075Sobrien || GET_CODE (X) == NEG) \ 545890075Sobrien ? CC_NOOVmode : CCmode)) 545990075Sobrien@end smallexample 546090075Sobrien 5461132718SkanYou should define this macro if and only if you define extra CC modes 5462132718Skanin @file{@var{machine}-modes.def}. 5463132718Skan@end defmac 546490075Sobrien 5465132718Skan@defmac CANONICALIZE_COMPARISON (@var{code}, @var{op0}, @var{op1}) 546690075SobrienOn some machines not all possible comparisons are defined, but you can 546790075Sobrienconvert an invalid comparison into a valid one. For example, the Alpha 546890075Sobriendoes not have a @code{GT} comparison, but you can use an @code{LT} 546990075Sobriencomparison instead and swap the order of the operands. 547090075Sobrien 547190075SobrienOn such machines, define this macro to be a C statement to do any 547290075Sobrienrequired conversions. @var{code} is the initial comparison code 547390075Sobrienand @var{op0} and @var{op1} are the left and right operands of the 547490075Sobriencomparison, respectively. You should modify @var{code}, @var{op0}, and 547590075Sobrien@var{op1} as required. 547690075Sobrien 547790075SobrienGCC will not assume that the comparison resulting from this macro is 547890075Sobrienvalid but will see if the resulting insn matches a pattern in the 547990075Sobrien@file{md} file. 548090075Sobrien 548190075SobrienYou need not define this macro if it would never change the comparison 548290075Sobriencode or operands. 5483132718Skan@end defmac 548490075Sobrien 5485132718Skan@defmac REVERSIBLE_CC_MODE (@var{mode}) 548690075SobrienA C expression whose value is one if it is always safe to reverse a 548790075Sobriencomparison whose mode is @var{mode}. If @code{SELECT_CC_MODE} 548890075Sobriencan ever return @var{mode} for a floating-point inequality comparison, 548990075Sobrienthen @code{REVERSIBLE_CC_MODE (@var{mode})} must be zero. 549090075Sobrien 549190075SobrienYou need not define this macro if it would always returns zero or if the 549290075Sobrienfloating-point format is anything other than @code{IEEE_FLOAT_FORMAT}. 5493117395SkanFor example, here is the definition used on the SPARC, where floating-point 549490075Sobrieninequality comparisons are always given @code{CCFPEmode}: 549590075Sobrien 549690075Sobrien@smallexample 549790075Sobrien#define REVERSIBLE_CC_MODE(MODE) ((MODE) != CCFPEmode) 549890075Sobrien@end smallexample 5499132718Skan@end defmac 550090075Sobrien 5501132718Skan@defmac REVERSE_CONDITION (@var{code}, @var{mode}) 550290075SobrienA C expression whose value is reversed condition code of the @var{code} for 550390075Sobriencomparison done in CC_MODE @var{mode}. The macro is used only in case 550490075Sobrien@code{REVERSIBLE_CC_MODE (@var{mode})} is nonzero. Define this macro in case 550590075Sobrienmachine has some non-standard way how to reverse certain conditionals. For 550690075Sobrieninstance in case all floating point conditions are non-trapping, compiler may 550790075Sobrienfreely convert unordered compares to ordered one. Then definition may look 550890075Sobrienlike: 550990075Sobrien 551090075Sobrien@smallexample 551190075Sobrien#define REVERSE_CONDITION(CODE, MODE) \ 551290075Sobrien ((MODE) != CCFPmode ? reverse_condition (CODE) \ 551390075Sobrien : reverse_condition_maybe_unordered (CODE)) 551490075Sobrien@end smallexample 5515132718Skan@end defmac 551690075Sobrien 5517169689Skan@defmac REVERSE_CONDEXEC_PREDICATES_P (@var{op1}, @var{op2}) 551890075SobrienA C expression that returns true if the conditional execution predicate 5519169689Skan@var{op1}, a comparison operation, is the inverse of @var{op2} and vice 5520169689Skanversa. Define this to return 0 if the target has conditional execution 5521169689Skanpredicates that cannot be reversed safely. There is no need to validate 5522169689Skanthat the arguments of op1 and op2 are the same, this is done separately. 5523169689SkanIf no expansion is specified, this macro is defined as follows: 552490075Sobrien 552590075Sobrien@smallexample 552690075Sobrien#define REVERSE_CONDEXEC_PREDICATES_P (x, y) \ 5527169689Skan (GET_CODE ((x)) == reversed_comparison_code ((y), NULL)) 552890075Sobrien@end smallexample 5529132718Skan@end defmac 553090075Sobrien 5531132718Skan@deftypefn {Target Hook} bool TARGET_FIXED_CONDITION_CODE_REGS (unsigned int *, unsigned int *) 5532132718SkanOn targets which do not use @code{(cc0)}, and which use a hard 5533132718Skanregister rather than a pseudo-register to hold condition codes, the 5534132718Skanregular CSE passes are often not able to identify cases in which the 5535132718Skanhard register is set to a common value. Use this hook to enable a 5536132718Skansmall pass which optimizes such cases. This hook should return true 5537132718Skanto enable this pass, and it should set the integers to which its 5538132718Skanarguments point to the hard register numbers used for condition codes. 5539132718SkanWhen there is only one such register, as is true on most systems, the 5540132718Skaninteger pointed to by the second argument should be set to 5541132718Skan@code{INVALID_REGNUM}. 554290075Sobrien 5543132718SkanThe default version of this hook returns false. 5544132718Skan@end deftypefn 5545132718Skan 5546132718Skan@deftypefn {Target Hook} enum machine_mode TARGET_CC_MODES_COMPATIBLE (enum machine_mode, enum machine_mode) 5547132718SkanOn targets which use multiple condition code modes in class 5548132718Skan@code{MODE_CC}, it is sometimes the case that a comparison can be 5549132718Skanvalidly done in more than one mode. On such a system, define this 5550132718Skantarget hook to take two mode arguments and to return a mode in which 5551132718Skanboth comparisons may be validly done. If there is no such mode, 5552132718Skanreturn @code{VOIDmode}. 5553132718Skan 5554132718SkanThe default version of this hook checks whether the modes are the 5555132718Skansame. If they are, it returns that mode. If they are different, it 5556132718Skanreturns @code{VOIDmode}. 5557132718Skan@end deftypefn 5558132718Skan 555990075Sobrien@node Costs 556090075Sobrien@section Describing Relative Costs of Operations 556190075Sobrien@cindex costs of instructions 556290075Sobrien@cindex relative costs 556390075Sobrien@cindex speed of instructions 556490075Sobrien 556590075SobrienThese macros let you describe the relative speed of various operations 556690075Sobrienon the target machine. 556790075Sobrien 5568132718Skan@defmac REGISTER_MOVE_COST (@var{mode}, @var{from}, @var{to}) 556990075SobrienA C expression for the cost of moving data of mode @var{mode} from a 557090075Sobrienregister in class @var{from} to one in class @var{to}. The classes are 557190075Sobrienexpressed using the enumeration values such as @code{GENERAL_REGS}. A 557290075Sobrienvalue of 2 is the default; other values are interpreted relative to 557390075Sobrienthat. 557490075Sobrien 557590075SobrienIt is not required that the cost always equal 2 when @var{from} is the 557690075Sobriensame as @var{to}; on some machines it is expensive to move between 557790075Sobrienregisters if they are not general registers. 557890075Sobrien 557990075SobrienIf reload sees an insn consisting of a single @code{set} between two 558090075Sobrienhard registers, and if @code{REGISTER_MOVE_COST} applied to their 558190075Sobrienclasses returns a value of 2, reload does not check to ensure that the 558290075Sobrienconstraints of the insn are met. Setting a cost of other than 2 will 558390075Sobrienallow reload to verify that the constraints are met. You should do this 558490075Sobrienif the @samp{mov@var{m}} pattern's constraints do not allow such copying. 5585132718Skan@end defmac 558690075Sobrien 5587132718Skan@defmac MEMORY_MOVE_COST (@var{mode}, @var{class}, @var{in}) 558890075SobrienA C expression for the cost of moving data of mode @var{mode} between a 558990075Sobrienregister of class @var{class} and memory; @var{in} is zero if the value 559090075Sobrienis to be written to memory, nonzero if it is to be read in. This cost 559190075Sobrienis relative to those in @code{REGISTER_MOVE_COST}. If moving between 559290075Sobrienregisters and memory is more expensive than between two registers, you 559390075Sobrienshould define this macro to express the relative cost. 559490075Sobrien 559590075SobrienIf you do not define this macro, GCC uses a default cost of 4 plus 559690075Sobrienthe cost of copying via a secondary reload register, if one is 559790075Sobrienneeded. If your machine requires a secondary reload register to copy 559890075Sobrienbetween memory and a register of @var{class} but the reload mechanism is 559990075Sobrienmore complex than copying via an intermediate, define this macro to 560090075Sobrienreflect the actual cost of the move. 560190075Sobrien 560290075SobrienGCC defines the function @code{memory_move_secondary_cost} if 560390075Sobriensecondary reloads are needed. It computes the costs due to copying via 560490075Sobriena secondary register. If your machine copies from memory using a 560590075Sobriensecondary register in the conventional way but the default base value of 560690075Sobrien4 is not correct for your machine, define this macro to add some other 560790075Sobrienvalue to the result of that function. The arguments to that function 560890075Sobrienare the same as to this macro. 5609132718Skan@end defmac 561090075Sobrien 5611132718Skan@defmac BRANCH_COST 561290075SobrienA C expression for the cost of a branch instruction. A value of 1 is 561390075Sobrienthe default; other values are interpreted relative to that. 5614132718Skan@end defmac 561590075Sobrien 561690075SobrienHere are additional macros which do not specify precise relative costs, 561790075Sobrienbut only that certain actions are more expensive than GCC would 561890075Sobrienordinarily expect. 561990075Sobrien 5620132718Skan@defmac SLOW_BYTE_ACCESS 562190075SobrienDefine this macro as a C expression which is nonzero if accessing less 562290075Sobrienthan a word of memory (i.e.@: a @code{char} or a @code{short}) is no 562390075Sobrienfaster than accessing a word of memory, i.e., if such access 562490075Sobrienrequire more than one instruction or if there is no difference in cost 562590075Sobrienbetween byte and (aligned) word loads. 562690075Sobrien 562790075SobrienWhen this macro is not defined, the compiler will access a field by 562890075Sobrienfinding the smallest containing object; when it is defined, a fullword 562990075Sobrienload will be used if alignment permits. Unless bytes accesses are 563090075Sobrienfaster than word accesses, using word accesses is preferable since it 563190075Sobrienmay eliminate subsequent memory access if subsequent accesses occur to 563290075Sobrienother fields in the same word of the structure, but to different bytes. 5633132718Skan@end defmac 563490075Sobrien 5635132718Skan@defmac SLOW_UNALIGNED_ACCESS (@var{mode}, @var{alignment}) 563690075SobrienDefine this macro to be the value 1 if memory accesses described by the 563790075Sobrien@var{mode} and @var{alignment} parameters have a cost many times greater 563890075Sobrienthan aligned accesses, for example if they are emulated in a trap 563990075Sobrienhandler. 564090075Sobrien 564190075SobrienWhen this macro is nonzero, the compiler will act as if 564290075Sobrien@code{STRICT_ALIGNMENT} were nonzero when generating code for block 564390075Sobrienmoves. This can cause significantly more instructions to be produced. 564490075SobrienTherefore, do not set this macro nonzero if unaligned accesses only add a 564590075Sobriencycle or two to the time for a memory access. 564690075Sobrien 564790075SobrienIf the value of this macro is always zero, it need not be defined. If 564890075Sobrienthis macro is defined, it should produce a nonzero value when 564990075Sobrien@code{STRICT_ALIGNMENT} is nonzero. 5650132718Skan@end defmac 565190075Sobrien 5652132718Skan@defmac MOVE_RATIO 565390075SobrienThe threshold of number of scalar memory-to-memory move insns, @emph{below} 565490075Sobrienwhich a sequence of insns should be generated instead of a 565590075Sobrienstring move insn or a library call. Increasing the value will always 565690075Sobrienmake code faster, but eventually incurs high cost in increased code size. 565790075Sobrien 565890075SobrienNote that on machines where the corresponding move insn is a 565990075Sobrien@code{define_expand} that emits a sequence of insns, this macro counts 566090075Sobrienthe number of such sequences. 566190075Sobrien 566290075SobrienIf you don't define this, a reasonable default is used. 5663132718Skan@end defmac 566490075Sobrien 5665132718Skan@defmac MOVE_BY_PIECES_P (@var{size}, @var{alignment}) 566690075SobrienA C expression used to determine whether @code{move_by_pieces} will be used to 566790075Sobriencopy a chunk of memory, or whether some other block move mechanism 566890075Sobrienwill be used. Defaults to 1 if @code{move_by_pieces_ninsns} returns less 566990075Sobrienthan @code{MOVE_RATIO}. 5670132718Skan@end defmac 567190075Sobrien 5672132718Skan@defmac MOVE_MAX_PIECES 567390075SobrienA C expression used by @code{move_by_pieces} to determine the largest unit 567490075Sobriena load or store used to copy memory is. Defaults to @code{MOVE_MAX}. 5675132718Skan@end defmac 567690075Sobrien 5677132718Skan@defmac CLEAR_RATIO 5678117395SkanThe threshold of number of scalar move insns, @emph{below} which a sequence 5679117395Skanof insns should be generated to clear memory instead of a string clear insn 5680117395Skanor a library call. Increasing the value will always make code faster, but 5681117395Skaneventually incurs high cost in increased code size. 5682117395Skan 5683117395SkanIf you don't define this, a reasonable default is used. 5684132718Skan@end defmac 5685117395Skan 5686132718Skan@defmac CLEAR_BY_PIECES_P (@var{size}, @var{alignment}) 5687117395SkanA C expression used to determine whether @code{clear_by_pieces} will be used 5688117395Skanto clear a chunk of memory, or whether some other block clear mechanism 5689117395Skanwill be used. Defaults to 1 if @code{move_by_pieces_ninsns} returns less 5690117395Skanthan @code{CLEAR_RATIO}. 5691132718Skan@end defmac 5692117395Skan 5693132718Skan@defmac STORE_BY_PIECES_P (@var{size}, @var{alignment}) 5694132718SkanA C expression used to determine whether @code{store_by_pieces} will be 5695132718Skanused to set a chunk of memory to a constant value, or whether some other 5696132718Skanmechanism will be used. Used by @code{__builtin_memset} when storing 5697132718Skanvalues other than constant zero and by @code{__builtin_strcpy} when 5698132718Skanwhen called with a constant source string. 5699169689SkanDefaults to 1 if @code{move_by_pieces_ninsns} returns less 5700169689Skanthan @code{MOVE_RATIO}. 5701132718Skan@end defmac 5702132718Skan 5703132718Skan@defmac USE_LOAD_POST_INCREMENT (@var{mode}) 570490075SobrienA C expression used to determine whether a load postincrement is a good 570590075Sobrienthing to use for a given mode. Defaults to the value of 570690075Sobrien@code{HAVE_POST_INCREMENT}. 5707132718Skan@end defmac 570890075Sobrien 5709132718Skan@defmac USE_LOAD_POST_DECREMENT (@var{mode}) 571090075SobrienA C expression used to determine whether a load postdecrement is a good 571190075Sobrienthing to use for a given mode. Defaults to the value of 571290075Sobrien@code{HAVE_POST_DECREMENT}. 5713132718Skan@end defmac 571490075Sobrien 5715132718Skan@defmac USE_LOAD_PRE_INCREMENT (@var{mode}) 571690075SobrienA C expression used to determine whether a load preincrement is a good 571790075Sobrienthing to use for a given mode. Defaults to the value of 571890075Sobrien@code{HAVE_PRE_INCREMENT}. 5719132718Skan@end defmac 572090075Sobrien 5721132718Skan@defmac USE_LOAD_PRE_DECREMENT (@var{mode}) 572290075SobrienA C expression used to determine whether a load predecrement is a good 572390075Sobrienthing to use for a given mode. Defaults to the value of 572490075Sobrien@code{HAVE_PRE_DECREMENT}. 5725132718Skan@end defmac 572690075Sobrien 5727132718Skan@defmac USE_STORE_POST_INCREMENT (@var{mode}) 572890075SobrienA C expression used to determine whether a store postincrement is a good 572990075Sobrienthing to use for a given mode. Defaults to the value of 573090075Sobrien@code{HAVE_POST_INCREMENT}. 5731132718Skan@end defmac 573290075Sobrien 5733132718Skan@defmac USE_STORE_POST_DECREMENT (@var{mode}) 573490075SobrienA C expression used to determine whether a store postdecrement is a good 573590075Sobrienthing to use for a given mode. Defaults to the value of 573690075Sobrien@code{HAVE_POST_DECREMENT}. 5737132718Skan@end defmac 573890075Sobrien 5739132718Skan@defmac USE_STORE_PRE_INCREMENT (@var{mode}) 574090075SobrienThis macro is used to determine whether a store preincrement is a good 574190075Sobrienthing to use for a given mode. Defaults to the value of 574290075Sobrien@code{HAVE_PRE_INCREMENT}. 5743132718Skan@end defmac 574490075Sobrien 5745132718Skan@defmac USE_STORE_PRE_DECREMENT (@var{mode}) 574690075SobrienThis macro is used to determine whether a store predecrement is a good 574790075Sobrienthing to use for a given mode. Defaults to the value of 574890075Sobrien@code{HAVE_PRE_DECREMENT}. 5749132718Skan@end defmac 575090075Sobrien 5751132718Skan@defmac NO_FUNCTION_CSE 575290075SobrienDefine this macro if it is as good or better to call a constant 575390075Sobrienfunction address than to call an address kept in a register. 5754132718Skan@end defmac 575590075Sobrien 5756132718Skan@defmac RANGE_TEST_NON_SHORT_CIRCUIT 5757132718SkanDefine this macro if a non-short-circuit operation produced by 5758132718Skan@samp{fold_range_test ()} is optimal. This macro defaults to true if 5759132718Skan@code{BRANCH_COST} is greater than or equal to the value 2. 5760132718Skan@end defmac 5761132718Skan 5762132718Skan@deftypefn {Target Hook} bool TARGET_RTX_COSTS (rtx @var{x}, int @var{code}, int @var{outer_code}, int *@var{total}) 5763132718SkanThis target hook describes the relative costs of RTL expressions. 5764132718Skan 5765132718SkanThe cost may depend on the precise form of the expression, which is 5766132718Skanavailable for examination in @var{x}, and the rtx code of the expression 5767132718Skanin which it is contained, found in @var{outer_code}. @var{code} is the 5768132718Skanexpression code---redundant, since it can be obtained with 5769132718Skan@code{GET_CODE (@var{x})}. 5770132718Skan 5771132718SkanIn implementing this hook, you can use the construct 5772132718Skan@code{COSTS_N_INSNS (@var{n})} to specify a cost equal to @var{n} fast 5773132718Skaninstructions. 5774132718Skan 5775132718SkanOn entry to the hook, @code{*@var{total}} contains a default estimate 5776132718Skanfor the cost of the expression. The hook should modify this value as 5777169689Skannecessary. Traditionally, the default costs are @code{COSTS_N_INSNS (5)} 5778169689Skanfor multiplications, @code{COSTS_N_INSNS (7)} for division and modulus 5779169689Skanoperations, and @code{COSTS_N_INSNS (1)} for all other operations. 5780132718Skan 5781169689SkanWhen optimizing for code size, i.e.@: when @code{optimize_size} is 5782169689Skannonzero, this target hook should be used to estimate the relative 5783169689Skansize cost of an expression, again relative to @code{COSTS_N_INSNS}. 5784169689Skan 5785132718SkanThe hook returns true when all subexpressions of @var{x} have been 5786132718Skanprocessed, and false when @code{rtx_cost} should recurse. 5787132718Skan@end deftypefn 5788132718Skan 5789132718Skan@deftypefn {Target Hook} int TARGET_ADDRESS_COST (rtx @var{address}) 5790132718SkanThis hook computes the cost of an addressing mode that contains 5791132718Skan@var{address}. If not defined, the cost is computed from 5792132718Skanthe @var{address} expression and the @code{TARGET_RTX_COST} hook. 5793132718Skan 5794132718SkanFor most CISC machines, the default cost is a good approximation of the 5795132718Skantrue cost of the addressing mode. However, on RISC machines, all 5796132718Skaninstructions normally have the same length and execution time. Hence 5797132718Skanall addresses will have equal costs. 5798132718Skan 5799132718SkanIn cases where more than one form of an address is known, the form with 5800132718Skanthe lowest cost will be used. If multiple forms have the same, lowest, 5801132718Skancost, the one that is the most complex will be used. 5802132718Skan 5803132718SkanFor example, suppose an address that is equal to the sum of a register 5804132718Skanand a constant is used twice in the same basic block. When this macro 5805132718Skanis not defined, the address will be computed in a register and memory 5806132718Skanreferences will be indirect through that register. On machines where 5807132718Skanthe cost of the addressing mode containing the sum is no higher than 5808132718Skanthat of a simple indirect reference, this will produce an additional 5809132718Skaninstruction and possibly require an additional register. Proper 5810132718Skanspecification of this macro eliminates this overhead for such machines. 5811132718Skan 5812132718SkanThis hook is never called with an invalid address. 5813132718Skan 5814132718SkanOn machines where an address involving more than one register is as 5815132718Skancheap as an address computation involving only one register, defining 5816132718Skan@code{TARGET_ADDRESS_COST} to reflect this can cause two registers to 5817132718Skanbe live over a region of code where only one would have been if 5818132718Skan@code{TARGET_ADDRESS_COST} were not defined in that manner. This effect 5819132718Skanshould be considered in the definition of this macro. Equivalent costs 5820132718Skanshould probably only be given to addresses with different numbers of 5821132718Skanregisters on machines with lots of registers. 5822132718Skan@end deftypefn 5823132718Skan 582490075Sobrien@node Scheduling 582590075Sobrien@section Adjusting the Instruction Scheduler 582690075Sobrien 582790075SobrienThe instruction scheduler may need a fair amount of machine-specific 582890075Sobrienadjustment in order to produce good code. GCC provides several target 582990075Sobrienhooks for this purpose. It is usually enough to define just a few of 583090075Sobrienthem: try the first ones in this list first. 583190075Sobrien 583290075Sobrien@deftypefn {Target Hook} int TARGET_SCHED_ISSUE_RATE (void) 5833117395SkanThis hook returns the maximum number of instructions that can ever 5834117395Skanissue at the same time on the target machine. The default is one. 5835117395SkanAlthough the insn scheduler can define itself the possibility of issue 5836117395Skanan insn on the same cycle, the value can serve as an additional 5837117395Skanconstraint to issue insns on the same simulated processor cycle (see 5838117395Skanhooks @samp{TARGET_SCHED_REORDER} and @samp{TARGET_SCHED_REORDER2}). 5839117395SkanThis value must be constant over the entire compilation. If you need 5840117395Skanit to vary depending on what the instructions are, you must use 584190075Sobrien@samp{TARGET_SCHED_VARIABLE_ISSUE}. 584290075Sobrien@end deftypefn 584390075Sobrien 584490075Sobrien@deftypefn {Target Hook} int TARGET_SCHED_VARIABLE_ISSUE (FILE *@var{file}, int @var{verbose}, rtx @var{insn}, int @var{more}) 584590075SobrienThis hook is executed by the scheduler after it has scheduled an insn 584690075Sobrienfrom the ready list. It should return the number of insns which can 5847132718Skanstill be issued in the current cycle. The default is 5848132718Skan@samp{@w{@var{more} - 1}} for insns other than @code{CLOBBER} and 5849132718Skan@code{USE}, which normally are not counted against the issue rate. 5850132718SkanYou should define this hook if some insns take more machine resources 5851132718Skanthan others, so that fewer insns can follow them in the same cycle. 5852132718Skan@var{file} is either a null pointer, or a stdio stream to write any 5853132718Skandebug output to. @var{verbose} is the verbose level provided by 5854132718Skan@option{-fsched-verbose-@var{n}}. @var{insn} is the instruction that 5855132718Skanwas scheduled. 585690075Sobrien@end deftypefn 585790075Sobrien 585890075Sobrien@deftypefn {Target Hook} int TARGET_SCHED_ADJUST_COST (rtx @var{insn}, rtx @var{link}, rtx @var{dep_insn}, int @var{cost}) 5859117395SkanThis function corrects the value of @var{cost} based on the 5860117395Skanrelationship between @var{insn} and @var{dep_insn} through the 5861117395Skandependence @var{link}. It should return the new value. The default 5862117395Skanis to make no adjustment to @var{cost}. This can be used for example 5863117395Skanto specify to the scheduler using the traditional pipeline description 586490075Sobrienthat an output- or anti-dependence does not incur the same cost as a 5865117395Skandata-dependence. If the scheduler using the automaton based pipeline 5866117395Skandescription, the cost of anti-dependence is zero and the cost of 5867117395Skanoutput-dependence is maximum of one and the difference of latency 5868117395Skantimes of the first and the second insns. If these values are not 5869117395Skanacceptable, you could use the hook to modify them too. See also 5870169689Skan@pxref{Processor pipeline description}. 587190075Sobrien@end deftypefn 587290075Sobrien 587390075Sobrien@deftypefn {Target Hook} int TARGET_SCHED_ADJUST_PRIORITY (rtx @var{insn}, int @var{priority}) 587490075SobrienThis hook adjusts the integer scheduling priority @var{priority} of 5875169689Skan@var{insn}. It should return the new priority. Increase the priority to 5876169689Skanexecute @var{insn} earlier, reduce the priority to execute @var{insn} 587790075Sobrienlater. Do not define this hook if you do not need to adjust the 587890075Sobrienscheduling priorities of insns. 587990075Sobrien@end deftypefn 588090075Sobrien 588190075Sobrien@deftypefn {Target Hook} int TARGET_SCHED_REORDER (FILE *@var{file}, int @var{verbose}, rtx *@var{ready}, int *@var{n_readyp}, int @var{clock}) 588290075SobrienThis hook is executed by the scheduler after it has scheduled the ready 588390075Sobrienlist, to allow the machine description to reorder it (for example to 588490075Sobriencombine two small instructions together on @samp{VLIW} machines). 588590075Sobrien@var{file} is either a null pointer, or a stdio stream to write any 588690075Sobriendebug output to. @var{verbose} is the verbose level provided by 588790075Sobrien@option{-fsched-verbose-@var{n}}. @var{ready} is a pointer to the ready 588890075Sobrienlist of instructions that are ready to be scheduled. @var{n_readyp} is 588990075Sobriena pointer to the number of elements in the ready list. The scheduler 589090075Sobrienreads the ready list in reverse order, starting with 589190075Sobrien@var{ready}[@var{*n_readyp}-1] and going to @var{ready}[0]. @var{clock} 589290075Sobrienis the timer tick of the scheduler. You may modify the ready list and 589390075Sobrienthe number of ready insns. The return value is the number of insns that 589490075Sobriencan issue this cycle; normally this is just @code{issue_rate}. See also 589590075Sobrien@samp{TARGET_SCHED_REORDER2}. 589690075Sobrien@end deftypefn 589790075Sobrien 589890075Sobrien@deftypefn {Target Hook} int TARGET_SCHED_REORDER2 (FILE *@var{file}, int @var{verbose}, rtx *@var{ready}, int *@var{n_ready}, @var{clock}) 589990075SobrienLike @samp{TARGET_SCHED_REORDER}, but called at a different time. That 590090075Sobrienfunction is called whenever the scheduler starts a new cycle. This one 590190075Sobrienis called once per iteration over a cycle, immediately after 590290075Sobrien@samp{TARGET_SCHED_VARIABLE_ISSUE}; it can reorder the ready list and 590390075Sobrienreturn the number of insns to be scheduled in the same cycle. Defining 590490075Sobrienthis hook can be useful if there are frequent situations where 590590075Sobrienscheduling one insn causes other insns to become ready in the same 590690075Sobriencycle. These other insns can then be taken into account properly. 590790075Sobrien@end deftypefn 590890075Sobrien 5909132718Skan@deftypefn {Target Hook} void TARGET_SCHED_DEPENDENCIES_EVALUATION_HOOK (rtx @var{head}, rtx @var{tail}) 5910132718SkanThis hook is called after evaluation forward dependencies of insns in 5911132718Skanchain given by two parameter values (@var{head} and @var{tail} 5912132718Skancorrespondingly) but before insns scheduling of the insn chain. For 5913132718Skanexample, it can be used for better insn classification if it requires 5914132718Skananalysis of dependencies. This hook can use backward and forward 5915132718Skandependencies of the insn scheduler because they are already 5916132718Skancalculated. 5917132718Skan@end deftypefn 5918132718Skan 591990075Sobrien@deftypefn {Target Hook} void TARGET_SCHED_INIT (FILE *@var{file}, int @var{verbose}, int @var{max_ready}) 592090075SobrienThis hook is executed by the scheduler at the beginning of each block of 592190075Sobrieninstructions that are to be scheduled. @var{file} is either a null 592290075Sobrienpointer, or a stdio stream to write any debug output to. @var{verbose} 592390075Sobrienis the verbose level provided by @option{-fsched-verbose-@var{n}}. 592490075Sobrien@var{max_ready} is the maximum number of insns in the current scheduling 592590075Sobrienregion that can be live at the same time. This can be used to allocate 5926169689Skanscratch space if it is needed, e.g.@: by @samp{TARGET_SCHED_REORDER}. 592790075Sobrien@end deftypefn 592890075Sobrien 592990075Sobrien@deftypefn {Target Hook} void TARGET_SCHED_FINISH (FILE *@var{file}, int @var{verbose}) 593090075SobrienThis hook is executed by the scheduler at the end of each block of 593190075Sobrieninstructions that are to be scheduled. It can be used to perform 593290075Sobriencleanup of any actions done by the other scheduling hooks. @var{file} 593390075Sobrienis either a null pointer, or a stdio stream to write any debug output 593490075Sobriento. @var{verbose} is the verbose level provided by 593590075Sobrien@option{-fsched-verbose-@var{n}}. 593690075Sobrien@end deftypefn 593790075Sobrien 5938169689Skan@deftypefn {Target Hook} void TARGET_SCHED_INIT_GLOBAL (FILE *@var{file}, int @var{verbose}, int @var{old_max_uid}) 5939169689SkanThis hook is executed by the scheduler after function level initializations. 5940169689Skan@var{file} is either a null pointer, or a stdio stream to write any debug output to. 5941169689Skan@var{verbose} is the verbose level provided by @option{-fsched-verbose-@var{n}}. 5942169689Skan@var{old_max_uid} is the maximum insn uid when scheduling begins. 5943169689Skan@end deftypefn 5944117395Skan 5945169689Skan@deftypefn {Target Hook} void TARGET_SCHED_FINISH_GLOBAL (FILE *@var{file}, int @var{verbose}) 5946169689SkanThis is the cleanup hook corresponding to @code{TARGET_SCHED_INIT_GLOBAL}. 5947169689Skan@var{file} is either a null pointer, or a stdio stream to write any debug output to. 5948169689Skan@var{verbose} is the verbose level provided by @option{-fsched-verbose-@var{n}}. 594990075Sobrien@end deftypefn 595090075Sobrien 5951117395Skan@deftypefn {Target Hook} int TARGET_SCHED_DFA_PRE_CYCLE_INSN (void) 5952117395SkanThe hook returns an RTL insn. The automaton state used in the 5953117395Skanpipeline hazard recognizer is changed as if the insn were scheduled 5954117395Skanwhen the new simulated processor cycle starts. Usage of the hook may 5955117395Skansimplify the automaton pipeline description for some @acronym{VLIW} 5956117395Skanprocessors. If the hook is defined, it is used only for the automaton 5957117395Skanbased pipeline description. The default is not to change the state 5958117395Skanwhen the new simulated processor cycle starts. 5959117395Skan@end deftypefn 5960117395Skan 5961117395Skan@deftypefn {Target Hook} void TARGET_SCHED_INIT_DFA_PRE_CYCLE_INSN (void) 5962117395SkanThe hook can be used to initialize data used by the previous hook. 5963117395Skan@end deftypefn 5964117395Skan 5965117395Skan@deftypefn {Target Hook} int TARGET_SCHED_DFA_POST_CYCLE_INSN (void) 5966117395SkanThe hook is analogous to @samp{TARGET_SCHED_DFA_PRE_CYCLE_INSN} but used 5967117395Skanto changed the state as if the insn were scheduled when the new 5968117395Skansimulated processor cycle finishes. 5969117395Skan@end deftypefn 5970117395Skan 5971117395Skan@deftypefn {Target Hook} void TARGET_SCHED_INIT_DFA_POST_CYCLE_INSN (void) 5972117395SkanThe hook is analogous to @samp{TARGET_SCHED_INIT_DFA_PRE_CYCLE_INSN} but 5973117395Skanused to initialize data used by the previous hook. 5974117395Skan@end deftypefn 5975117395Skan 5976117395Skan@deftypefn {Target Hook} int TARGET_SCHED_FIRST_CYCLE_MULTIPASS_DFA_LOOKAHEAD (void) 5977117395SkanThis hook controls better choosing an insn from the ready insn queue 5978117395Skanfor the @acronym{DFA}-based insn scheduler. Usually the scheduler 5979117395Skanchooses the first insn from the queue. If the hook returns a positive 5980117395Skanvalue, an additional scheduler code tries all permutations of 5981117395Skan@samp{TARGET_SCHED_FIRST_CYCLE_MULTIPASS_DFA_LOOKAHEAD ()} 5982117395Skansubsequent ready insns to choose an insn whose issue will result in 5983117395Skanmaximal number of issued insns on the same cycle. For the 5984117395Skan@acronym{VLIW} processor, the code could actually solve the problem of 5985117395Skanpacking simple insns into the @acronym{VLIW} insn. Of course, if the 5986117395Skanrules of @acronym{VLIW} packing are described in the automaton. 5987117395Skan 5988117395SkanThis code also could be used for superscalar @acronym{RISC} 5989117395Skanprocessors. Let us consider a superscalar @acronym{RISC} processor 5990117395Skanwith 3 pipelines. Some insns can be executed in pipelines @var{A} or 5991117395Skan@var{B}, some insns can be executed only in pipelines @var{B} or 5992117395Skan@var{C}, and one insn can be executed in pipeline @var{B}. The 5993117395Skanprocessor may issue the 1st insn into @var{A} and the 2nd one into 5994117395Skan@var{B}. In this case, the 3rd insn will wait for freeing @var{B} 5995117395Skanuntil the next cycle. If the scheduler issues the 3rd insn the first, 5996117395Skanthe processor could issue all 3 insns per cycle. 5997117395Skan 5998117395SkanActually this code demonstrates advantages of the automaton based 5999117395Skanpipeline hazard recognizer. We try quickly and easy many insn 6000117395Skanschedules to choose the best one. 6001117395Skan 6002117395SkanThe default is no multipass scheduling. 6003117395Skan@end deftypefn 6004117395Skan 6005132718Skan@deftypefn {Target Hook} int TARGET_SCHED_FIRST_CYCLE_MULTIPASS_DFA_LOOKAHEAD_GUARD (rtx) 6006132718Skan 6007132718SkanThis hook controls what insns from the ready insn queue will be 6008132718Skanconsidered for the multipass insn scheduling. If the hook returns 6009132718Skanzero for insn passed as the parameter, the insn will be not chosen to 6010132718Skanbe issued. 6011132718Skan 6012132718SkanThe default is that any ready insns can be chosen to be issued. 6013132718Skan@end deftypefn 6014132718Skan 6015132718Skan@deftypefn {Target Hook} int TARGET_SCHED_DFA_NEW_CYCLE (FILE *, int, rtx, int, int, int *) 6016132718Skan 6017132718SkanThis hook is called by the insn scheduler before issuing insn passed 6018132718Skanas the third parameter on given cycle. If the hook returns nonzero, 6019132718Skanthe insn is not issued on given processors cycle. Instead of that, 6020132718Skanthe processor cycle is advanced. If the value passed through the last 6021132718Skanparameter is zero, the insn ready queue is not sorted on the new cycle 6022132718Skanstart as usually. The first parameter passes file for debugging 6023132718Skanoutput. The second one passes the scheduler verbose level of the 6024132718Skandebugging output. The forth and the fifth parameter values are 6025132718Skancorrespondingly processor cycle on which the previous insn has been 6026132718Skanissued and the current processor cycle. 6027132718Skan@end deftypefn 6028132718Skan 6029169689Skan@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}) 6030132718SkanThis hook is used to define which dependences are considered costly by 6031132718Skanthe target, so costly that it is not advisable to schedule the insns that 6032132718Skanare involved in the dependence too close to one another. The parameters 6033132718Skanto this hook are as follows: The second parameter @var{insn2} is dependent 6034132718Skanupon the first parameter @var{insn1}. The dependence between @var{insn1} 6035132718Skanand @var{insn2} is represented by the third parameter @var{dep_link}. The 6036132718Skanfourth parameter @var{cost} is the cost of the dependence, and the fifth 6037132718Skanparameter @var{distance} is the distance in cycles between the two insns. 6038132718SkanThe hook returns @code{true} if considering the distance between the two 6039132718Skaninsns the dependence between them is considered costly by the target, 6040132718Skanand @code{false} otherwise. 6041132718Skan 6042132718SkanDefining this hook can be useful in multiple-issue out-of-order machines, 6043132718Skanwhere (a) it's practically hopeless to predict the actual data/resource 6044132718Skandelays, however: (b) there's a better chance to predict the actual grouping 6045132718Skanthat will be formed, and (c) correctly emulating the grouping can be very 6046132718Skanimportant. In such targets one may want to allow issuing dependent insns 6047169689Skancloser to one another---i.e., closer than the dependence distance; however, 6048132718Skannot in cases of "costly dependences", which this hooks allows to define. 6049132718Skan@end deftypefn 6050132718Skan 6051169689Skan@deftypefn {Target Hook} int TARGET_SCHED_ADJUST_COST_2 (rtx @var{insn}, int @var{dep_type}, rtx @var{dep_insn}, int @var{cost}) 6052169689SkanThis hook is a modified version of @samp{TARGET_SCHED_ADJUST_COST}. Instead 6053169689Skanof passing dependence as a second parameter, it passes a type of that 6054169689Skandependence. This is useful to calculate cost of dependence between insns 6055169689Skannot having the corresponding link. If @samp{TARGET_SCHED_ADJUST_COST_2} is 6056169689Skandefined it is used instead of @samp{TARGET_SCHED_ADJUST_COST}. 6057169689Skan@end deftypefn 6058117395Skan 6059169689Skan@deftypefn {Target Hook} void TARGET_SCHED_H_I_D_EXTENDED (void) 6060169689SkanThis hook is called by the insn scheduler after emitting a new instruction to 6061169689Skanthe instruction stream. The hook notifies a target backend to extend its 6062169689Skanper instruction data structures. 6063169689Skan@end deftypefn 6064117395Skan 6065169689Skan@deftypefn {Target Hook} int TARGET_SCHED_SPECULATE_INSN (rtx @var{insn}, int @var{request}, rtx *@var{new_pat}) 6066169689SkanThis hook is called by the insn scheduler when @var{insn} has only 6067169689Skanspeculative dependencies and therefore can be scheduled speculatively. 6068169689SkanThe hook is used to check if the pattern of @var{insn} has a speculative 6069169689Skanversion and, in case of successful check, to generate that speculative 6070169689Skanpattern. The hook should return 1, if the instruction has a speculative form, 6071169689Skanor -1, if it doesn't. @var{request} describes the type of requested 6072169689Skanspeculation. If the return value equals 1 then @var{new_pat} is assigned 6073169689Skanthe generated speculative pattern. 6074169689Skan@end deftypefn 6075117395Skan 6076169689Skan@deftypefn {Target Hook} int TARGET_SCHED_NEEDS_BLOCK_P (rtx @var{insn}) 6077169689SkanThis hook is called by the insn scheduler during generation of recovery code 6078169689Skanfor @var{insn}. It should return nonzero, if the corresponding check 6079169689Skaninstruction should branch to recovery code, or zero otherwise. 6080169689Skan@end deftypefn 6081117395Skan 6082169689Skan@deftypefn {Target Hook} rtx TARGET_SCHED_GEN_CHECK (rtx @var{insn}, rtx @var{label}, int @var{mutate_p}) 6083169689SkanThis hook is called by the insn scheduler to generate a pattern for recovery 6084169689Skancheck instruction. If @var{mutate_p} is zero, then @var{insn} is a 6085169689Skanspeculative instruction for which the check should be generated. 6086169689Skan@var{label} is either a label of a basic block, where recovery code should 6087169689Skanbe emitted, or a null pointer, when requested check doesn't branch to 6088169689Skanrecovery code (a simple check). If @var{mutate_p} is nonzero, then 6089169689Skana pattern for a branchy check corresponding to a simple check denoted by 6090169689Skan@var{insn} should be generated. In this case @var{label} can't be null. 6091169689Skan@end deftypefn 6092169689Skan 6093169689Skan@deftypefn {Target Hook} int TARGET_SCHED_FIRST_CYCLE_MULTIPASS_DFA_LOOKAHEAD_GUARD_SPEC (rtx @var{insn}) 6094169689SkanThis hook is used as a workaround for 6095169689Skan@samp{TARGET_SCHED_FIRST_CYCLE_MULTIPASS_DFA_LOOKAHEAD_GUARD} not being 6096169689Skancalled on the first instruction of the ready list. The hook is used to 6097169689Skandiscard speculative instruction that stand first in the ready list from 6098169689Skanbeing scheduled on the current cycle. For non-speculative instructions, 6099169689Skanthe hook should always return nonzero. For example, in the ia64 backend 6100169689Skanthe hook is used to cancel data speculative insns when the ALAT table 6101169689Skanis nearly full. 6102169689Skan@end deftypefn 6103169689Skan 6104169689Skan@deftypefn {Target Hook} void TARGET_SCHED_SET_SCHED_FLAGS (unsigned int *@var{flags}, spec_info_t @var{spec_info}) 6105169689SkanThis hook is used by the insn scheduler to find out what features should be 6106169689Skanenabled/used. @var{flags} initially may have either the SCHED_RGN or SCHED_EBB 6107169689Skanbit set. This denotes the scheduler pass for which the data should be 6108169689Skanprovided. The target backend should modify @var{flags} by modifying 6109169689Skanthe bits corresponding to the following features: USE_DEPS_LIST, USE_GLAT, 6110169689SkanDETACH_LIFE_INFO, and DO_SPECULATION. For the DO_SPECULATION feature 6111169689Skanan additional structure @var{spec_info} should be filled by the target. 6112169689SkanThe structure describes speculation types that can be used in the scheduler. 6113169689Skan@end deftypefn 6114169689Skan 611590075Sobrien@node Sections 611690075Sobrien@section Dividing the Output into Sections (Texts, Data, @dots{}) 611790075Sobrien@c the above section title is WAY too long. maybe cut the part between 611890075Sobrien@c the (...)? --mew 10feb93 611990075Sobrien 612090075SobrienAn object file is divided into sections containing different types of 612190075Sobriendata. In the most common case, there are three sections: the @dfn{text 612290075Sobriensection}, which holds instructions and read-only data; the @dfn{data 612390075Sobriensection}, which holds initialized writable data; and the @dfn{bss 612490075Sobriensection}, which holds uninitialized data. Some systems have other kinds 612590075Sobrienof sections. 612690075Sobrien 6127169689Skan@file{varasm.c} provides several well-known sections, such as 6128169689Skan@code{text_section}, @code{data_section} and @code{bss_section}. 6129169689SkanThe normal way of controlling a @code{@var{foo}_section} variable 6130169689Skanis to define the associated @code{@var{FOO}_SECTION_ASM_OP} macro, 6131169689Skanas described below. The macros are only read once, when @file{varasm.c} 6132169689Skaninitializes itself, so their values must be run-time constants. 6133169689SkanThey may however depend on command-line flags. 613490075Sobrien 6135169689Skan@emph{Note:} Some run-time files, such @file{crtstuff.c}, also make 6136169689Skanuse of the @code{@var{FOO}_SECTION_ASM_OP} macros, and expect them 6137169689Skanto be string literals. 6138169689Skan 6139169689SkanSome assemblers require a different string to be written every time a 6140169689Skansection is selected. If your assembler falls into this category, you 6141169689Skanshould define the @code{TARGET_ASM_INIT_SECTIONS} hook and use 6142169689Skan@code{get_unnamed_section} to set up the sections. 6143169689Skan 6144169689SkanYou must always create a @code{text_section}, either by defining 6145169689Skan@code{TEXT_SECTION_ASM_OP} or by initializing @code{text_section} 6146169689Skanin @code{TARGET_ASM_INIT_SECTIONS}. The same is true of 6147169689Skan@code{data_section} and @code{DATA_SECTION_ASM_OP}. If you do not 6148169689Skancreate a distinct @code{readonly_data_section}, the default is to 6149169689Skanreuse @code{text_section}. 6150169689Skan 6151169689SkanAll the other @file{varasm.c} sections are optional, and are null 6152169689Skanif the target does not provide them. 6153169689Skan 6154132718Skan@defmac TEXT_SECTION_ASM_OP 615590075SobrienA C expression whose value is a string, including spacing, containing the 615690075Sobrienassembler operation that should precede instructions and read-only data. 615790075SobrienNormally @code{"\t.text"} is right. 6158132718Skan@end defmac 615990075Sobrien 6160132718Skan@defmac HOT_TEXT_SECTION_NAME 6161117395SkanIf defined, a C string constant for the name of the section containing most 6162117395Skanfrequently executed functions of the program. If not defined, GCC will provide 6163117395Skana default definition if the target supports named sections. 6164132718Skan@end defmac 6165117395Skan 6166132718Skan@defmac UNLIKELY_EXECUTED_TEXT_SECTION_NAME 6167117395SkanIf defined, a C string constant for the name of the section containing unlikely 6168117395Skanexecuted functions in the program. 6169132718Skan@end defmac 6170117395Skan 6171132718Skan@defmac DATA_SECTION_ASM_OP 617290075SobrienA C expression whose value is a string, including spacing, containing the 617390075Sobrienassembler operation to identify the following data as writable initialized 617490075Sobriendata. Normally @code{"\t.data"} is right. 6175132718Skan@end defmac 617690075Sobrien 6177169689Skan@defmac SDATA_SECTION_ASM_OP 6178169689SkanIf defined, a C expression whose value is a string, including spacing, 6179169689Skancontaining the assembler operation to identify the following data as 6180169689Skaninitialized, writable small data. 6181169689Skan@end defmac 6182169689Skan 6183132718Skan@defmac READONLY_DATA_SECTION_ASM_OP 6184117395SkanA C expression whose value is a string, including spacing, containing the 6185117395Skanassembler operation to identify the following data as read-only initialized 6186117395Skandata. 6187132718Skan@end defmac 6188117395Skan 6189132718Skan@defmac BSS_SECTION_ASM_OP 619090075SobrienIf defined, a C expression whose value is a string, including spacing, 619190075Sobriencontaining the assembler operation to identify the following data as 619290075Sobrienuninitialized global data. If not defined, and neither 619390075Sobrien@code{ASM_OUTPUT_BSS} nor @code{ASM_OUTPUT_ALIGNED_BSS} are defined, 619490075Sobrienuninitialized global data will be output in the data section if 619590075Sobrien@option{-fno-common} is passed, otherwise @code{ASM_OUTPUT_COMMON} will be 619690075Sobrienused. 6197132718Skan@end defmac 619890075Sobrien 6199169689Skan@defmac SBSS_SECTION_ASM_OP 6200169689SkanIf defined, a C expression whose value is a string, including spacing, 6201169689Skancontaining the assembler operation to identify the following data as 6202169689Skanuninitialized, writable small data. 6203169689Skan@end defmac 6204169689Skan 6205132718Skan@defmac INIT_SECTION_ASM_OP 620690075SobrienIf defined, a C expression whose value is a string, including spacing, 620790075Sobriencontaining the assembler operation to identify the following data as 620890075Sobrieninitialization code. If not defined, GCC will assume such a section does 6209169689Skannot exist. This section has no corresponding @code{init_section} 6210169689Skanvariable; it is used entirely in runtime code. 6211132718Skan@end defmac 621290075Sobrien 6213132718Skan@defmac FINI_SECTION_ASM_OP 621490075SobrienIf defined, a C expression whose value is a string, including spacing, 621590075Sobriencontaining the assembler operation to identify the following data as 621690075Sobrienfinalization code. If not defined, GCC will assume such a section does 6217169689Skannot exist. This section has no corresponding @code{fini_section} 6218169689Skanvariable; it is used entirely in runtime code. 6219132718Skan@end defmac 622090075Sobrien 6221169689Skan@defmac INIT_ARRAY_SECTION_ASM_OP 6222169689SkanIf defined, a C expression whose value is a string, including spacing, 6223169689Skancontaining the assembler operation to identify the following data as 6224169689Skanpart of the @code{.init_array} (or equivalent) section. If not 6225169689Skandefined, GCC will assume such a section does not exist. Do not define 6226169689Skanboth this macro and @code{INIT_SECTION_ASM_OP}. 6227169689Skan@end defmac 6228169689Skan 6229169689Skan@defmac FINI_ARRAY_SECTION_ASM_OP 6230169689SkanIf defined, a C expression whose value is a string, including spacing, 6231169689Skancontaining the assembler operation to identify the following data as 6232169689Skanpart of the @code{.fini_array} (or equivalent) section. If not 6233169689Skandefined, GCC will assume such a section does not exist. Do not define 6234169689Skanboth this macro and @code{FINI_SECTION_ASM_OP}. 6235169689Skan@end defmac 6236169689Skan 6237132718Skan@defmac CRT_CALL_STATIC_FUNCTION (@var{section_op}, @var{function}) 623890075SobrienIf defined, an ASM statement that switches to a different section 623990075Sobrienvia @var{section_op}, calls @var{function}, and switches back to 624090075Sobrienthe text section. This is used in @file{crtstuff.c} if 624190075Sobrien@code{INIT_SECTION_ASM_OP} or @code{FINI_SECTION_ASM_OP} to calls 624290075Sobriento initialization and finalization functions from the init and fini 624390075Sobriensections. By default, this macro uses a simple function call. Some 624490075Sobrienports need hand-crafted assembly code to avoid dependencies on 624590075Sobrienregisters initialized in the function prologue or to ensure that 624690075Sobrienconstant pools don't end up too far way in the text section. 6247132718Skan@end defmac 624890075Sobrien 6249169689Skan@defmac TARGET_LIBGCC_SDATA_SECTION 6250169689SkanIf defined, a string which names the section into which small 6251169689Skanvariables defined in crtstuff and libgcc should go. This is useful 6252169689Skanwhen the target has options for optimizing access to small data, and 6253169689Skanyou want the crtstuff and libgcc routines to be conservative in what 6254169689Skanthey expect of your application yet liberal in what your application 6255169689Skanexpects. For example, for targets with a @code{.sdata} section (like 6256169689SkanMIPS), you could compile crtstuff with @code{-G 0} so that it doesn't 6257169689Skanrequire small data support from your application, but use this macro 6258169689Skanto put small data into @code{.sdata} so that your application can 6259169689Skanaccess these variables whether it uses small data or not. 6260169689Skan@end defmac 6261169689Skan 6262132718Skan@defmac FORCE_CODE_SECTION_ALIGN 626390075SobrienIf defined, an ASM statement that aligns a code section to some 626490075Sobrienarbitrary boundary. This is used to force all fragments of the 626590075Sobrien@code{.init} and @code{.fini} sections to have to same alignment 626690075Sobrienand thus prevent the linker from having to add any padding. 6267132718Skan@end defmac 626890075Sobrien 6269132718Skan@defmac JUMP_TABLES_IN_TEXT_SECTION 627090075SobrienDefine this macro to be an expression with a nonzero value if jump 627190075Sobrientables (for @code{tablejump} insns) should be output in the text 627290075Sobriensection, along with the assembler instructions. Otherwise, the 627390075Sobrienreadonly data section is used. 627490075Sobrien 627590075SobrienThis macro is irrelevant if there is no separate readonly data section. 6276132718Skan@end defmac 627790075Sobrien 6278169689Skan@deftypefn {Target Hook} void TARGET_ASM_INIT_SECTIONS (void) 6279169689SkanDefine this hook if you need to do something special to set up the 6280169689Skan@file{varasm.c} sections, or if your target has some special sections 6281169689Skanof its own that you need to create. 6282169689Skan 6283169689SkanGCC calls this hook after processing the command line, but before writing 6284169689Skanany assembly code, and before calling any of the section-returning hooks 6285169689Skandescribed below. 6286169689Skan@end deftypefn 6287169689Skan 6288169689Skan@deftypefn {Target Hook} TARGET_ASM_RELOC_RW_MASK (void) 6289169689SkanReturn a mask describing how relocations should be treated when 6290169689Skanselecting sections. Bit 1 should be set if global relocations 6291169689Skanshould be placed in a read-write section; bit 0 should be set if 6292169689Skanlocal relocations should be placed in a read-write section. 6293169689Skan 6294169689SkanThe default version of this function returns 3 when @option{-fpic} 6295169689Skanis in effect, and 0 otherwise. The hook is typically redefined 6296169689Skanwhen the target cannot support (some kinds of) dynamic relocations 6297169689Skanin read-only sections even in executables. 6298169689Skan@end deftypefn 6299169689Skan 6300169689Skan@deftypefn {Target Hook} {section *} TARGET_ASM_SELECT_SECTION (tree @var{exp}, int @var{reloc}, unsigned HOST_WIDE_INT @var{align}) 6301169689SkanReturn the section into which @var{exp} should be placed. You can 6302117395Skanassume that @var{exp} is either a @code{VAR_DECL} node or a constant of 6303117395Skansome sort. @var{reloc} indicates whether the initial value of @var{exp} 6304117395Skanrequires link-time relocations. Bit 0 is set when variable contains 6305117395Skanlocal relocations only, while bit 1 is set for global relocations. 6306169689Skan@var{align} is the constant alignment in bits. 6307117395Skan 6308117395SkanThe default version of this function takes care of putting read-only 6309117395Skanvariables in @code{readonly_data_section}. 6310169689Skan 6311169689SkanSee also @var{USE_SELECT_SECTION_FOR_FUNCTIONS}. 6312117395Skan@end deftypefn 6313117395Skan 6314169689Skan@defmac USE_SELECT_SECTION_FOR_FUNCTIONS 6315169689SkanDefine this macro if you wish TARGET_ASM_SELECT_SECTION to be called 6316169689Skanfor @code{FUNCTION_DECL}s as well as for variables and constants. 6317169689Skan 6318169689SkanIn the case of a @code{FUNCTION_DECL}, @var{reloc} will be zero if the 6319169689Skanfunction has been determined to be likely to be called, and nonzero if 6320169689Skanit is unlikely to be called. 6321169689Skan@end defmac 6322169689Skan 6323117395Skan@deftypefn {Target Hook} void TARGET_ASM_UNIQUE_SECTION (tree @var{decl}, int @var{reloc}) 6324117395SkanBuild up a unique section name, expressed as a @code{STRING_CST} node, 6325117395Skanand assign it to @samp{DECL_SECTION_NAME (@var{decl})}. 6326117395SkanAs with @code{TARGET_ASM_SELECT_SECTION}, @var{reloc} indicates whether 6327117395Skanthe initial value of @var{exp} requires link-time relocations. 6328117395Skan 6329117395SkanThe default version of this function appends the symbol name to the 6330117395SkanELF section name that would normally be used for the symbol. For 6331117395Skanexample, the function @code{foo} would be placed in @code{.text.foo}. 6332117395SkanWhatever the actual target object format, this is often good enough. 6333117395Skan@end deftypefn 6334117395Skan 6335169689Skan@deftypefn {Target Hook} {section *} TARGET_ASM_FUNCTION_RODATA_SECTION (tree @var{decl}) 6336169689SkanReturn the readonly data section associated with 6337169689Skan@samp{DECL_SECTION_NAME (@var{decl})}. 6338169689SkanThe default version of this function selects @code{.gnu.linkonce.r.name} if 6339169689Skanthe function's section is @code{.gnu.linkonce.t.name}, @code{.rodata.name} 6340169689Skanif function is in @code{.text.name}, and the normal readonly-data section 6341169689Skanotherwise. 6342169689Skan@end deftypefn 6343169689Skan 6344169689Skan@deftypefn {Target Hook} {section *} TARGET_ASM_SELECT_RTX_SECTION (enum machine_mode @var{mode}, rtx @var{x}, unsigned HOST_WIDE_INT @var{align}) 6345169689SkanReturn the section into which a constant @var{x}, of mode @var{mode}, 6346169689Skanshould be placed. You can assume that @var{x} is some kind of 6347117395Skanconstant in RTL@. The argument @var{mode} is redundant except in the 6348169689Skancase of a @code{const_int} rtx. @var{align} is the constant alignment 6349169689Skanin bits. 6350117395Skan 6351117395SkanThe default version of this function takes care of putting symbolic 6352117395Skanconstants in @code{flag_pic} mode in @code{data_section} and everything 6353117395Skanelse in @code{readonly_data_section}. 6354117395Skan@end deftypefn 6355117395Skan 6356132718Skan@deftypefn {Target Hook} void TARGET_ENCODE_SECTION_INFO (tree @var{decl}, rtx @var{rtl}, int @var{new_decl_p}) 6357117395SkanDefine this hook if references to a symbol or a constant must be 635890075Sobrientreated differently depending on something about the variable or 635990075Sobrienfunction named by the symbol (such as what section it is in). 636090075Sobrien 6361132718SkanThe hook is executed immediately after rtl has been created for 6362132718Skan@var{decl}, which may be a variable or function declaration or 6363132718Skanan entry in the constant pool. In either case, @var{rtl} is the 6364132718Skanrtl in question. Do @emph{not} use @code{DECL_RTL (@var{decl})} 6365132718Skanin this hook; that field may not have been initialized yet. 636690075Sobrien 6367132718SkanIn the case of a constant, it is safe to assume that the rtl is 6368132718Skana @code{mem} whose address is a @code{symbol_ref}. Most decls 6369132718Skanwill also have this form, but that is not guaranteed. Global 6370132718Skanregister variables, for instance, will have a @code{reg} for their 6371132718Skanrtl. (Normally the right thing to do with such unusual rtl is 6372132718Skanleave it alone.) 6373132718Skan 6374117395SkanThe @var{new_decl_p} argument will be true if this is the first time 6375132718Skanthat @code{TARGET_ENCODE_SECTION_INFO} has been invoked on this decl. It will 6376117395Skanbe false for subsequent invocations, which will happen for duplicate 6377117395Skandeclarations. Whether or not anything must be done for the duplicate 6378117395Skandeclaration depends on whether the hook examines @code{DECL_ATTRIBUTES}. 6379132718Skan@var{new_decl_p} is always true when the hook is called for a constant. 6380117395Skan 6381117395Skan@cindex @code{SYMBOL_REF_FLAG}, in @code{TARGET_ENCODE_SECTION_INFO} 6382132718SkanThe usual thing for this hook to do is to record flags in the 6383132718Skan@code{symbol_ref}, using @code{SYMBOL_REF_FLAG} or @code{SYMBOL_REF_FLAGS}. 6384132718SkanHistorically, the name string was modified if it was necessary to 6385132718Skanencode more than one bit of information, but this practice is now 6386132718Skandiscouraged; use @code{SYMBOL_REF_FLAGS}. 6387132718Skan 6388132718SkanThe default definition of this hook, @code{default_encode_section_info} 6389132718Skanin @file{varasm.c}, sets a number of commonly-useful bits in 6390132718Skan@code{SYMBOL_REF_FLAGS}. Check whether the default does what you need 6391132718Skanbefore overriding it. 6392117395Skan@end deftypefn 639390075Sobrien 6394117395Skan@deftypefn {Target Hook} const char *TARGET_STRIP_NAME_ENCODING (const char *name) 6395117395SkanDecode @var{name} and return the real name part, sans 6396117395Skanthe characters that @code{TARGET_ENCODE_SECTION_INFO} 6397117395Skanmay have added. 6398117395Skan@end deftypefn 639990075Sobrien 6400117395Skan@deftypefn {Target Hook} bool TARGET_IN_SMALL_DATA_P (tree @var{exp}) 6401117395SkanReturns true if @var{exp} should be placed into a ``small data'' section. 6402117395SkanThe default version of this hook always returns false. 6403117395Skan@end deftypefn 640490075Sobrien 6405117395Skan@deftypevar {Target Hook} bool TARGET_HAVE_SRODATA_SECTION 6406117395SkanContains the value true if the target places read-only 6407117395Skan``small data'' into a separate section. The default value is false. 6408117395Skan@end deftypevar 6409117395Skan 6410117395Skan@deftypefn {Target Hook} bool TARGET_BINDS_LOCAL_P (tree @var{exp}) 6411117395SkanReturns true if @var{exp} names an object for which name resolution 6412117395Skanrules must resolve to the current ``module'' (dynamic shared library 6413117395Skanor executable image). 6414117395Skan 6415117395SkanThe default version of this hook implements the name resolution rules 6416117395Skanfor ELF, which has a looser model of global name binding than other 6417117395Skancurrently supported object file formats. 6418117395Skan@end deftypefn 6419117395Skan 6420117395Skan@deftypevar {Target Hook} bool TARGET_HAVE_TLS 6421117395SkanContains the value true if the target supports thread-local storage. 6422117395SkanThe default value is false. 6423117395Skan@end deftypevar 6424117395Skan 6425117395Skan 642690075Sobrien@node PIC 642790075Sobrien@section Position Independent Code 642890075Sobrien@cindex position independent code 642990075Sobrien@cindex PIC 643090075Sobrien 643190075SobrienThis section describes macros that help implement generation of position 643290075Sobrienindependent code. Simply defining these macros is not enough to 643390075Sobriengenerate valid PIC; you must also add support to the macros 643490075Sobrien@code{GO_IF_LEGITIMATE_ADDRESS} and @code{PRINT_OPERAND_ADDRESS}, as 643590075Sobrienwell as @code{LEGITIMIZE_ADDRESS}. You must modify the definition of 643690075Sobrien@samp{movsi} to do something appropriate when the source operand 643790075Sobriencontains a symbolic address. You may also need to alter the handling of 643890075Sobrienswitch statements so that they use relative addresses. 643990075Sobrien@c i rearranged the order of the macros above to try to force one of 644090075Sobrien@c them to the next line, to eliminate an overfull hbox. --mew 10feb93 644190075Sobrien 6442132718Skan@defmac PIC_OFFSET_TABLE_REGNUM 644390075SobrienThe register number of the register used to address a table of static 644490075Sobriendata addresses in memory. In some cases this register is defined by a 644590075Sobrienprocessor's ``application binary interface'' (ABI)@. When this macro 644690075Sobrienis defined, RTL is generated for this register once, as with the stack 644790075Sobrienpointer and frame pointer registers. If this macro is not defined, it 644890075Sobrienis up to the machine-dependent files to allocate such a register (if 644990075Sobriennecessary). Note that this register must be fixed when in use (e.g.@: 645090075Sobrienwhen @code{flag_pic} is true). 6451132718Skan@end defmac 645290075Sobrien 6453132718Skan@defmac PIC_OFFSET_TABLE_REG_CALL_CLOBBERED 645490075SobrienDefine this macro if the register defined by 645590075Sobrien@code{PIC_OFFSET_TABLE_REGNUM} is clobbered by calls. Do not define 645690075Sobrienthis macro if @code{PIC_OFFSET_TABLE_REGNUM} is not defined. 6457132718Skan@end defmac 645890075Sobrien 6459132718Skan@defmac LEGITIMATE_PIC_OPERAND_P (@var{x}) 646090075SobrienA C expression that is nonzero if @var{x} is a legitimate immediate 646190075Sobrienoperand on the target machine when generating position independent code. 646290075SobrienYou can assume that @var{x} satisfies @code{CONSTANT_P}, so you need not 646390075Sobriencheck this. You can also assume @var{flag_pic} is true, so you need not 646490075Sobriencheck it either. You need not define this macro if all constants 646590075Sobrien(including @code{SYMBOL_REF}) can be immediate operands when generating 646690075Sobrienposition independent code. 6467132718Skan@end defmac 646890075Sobrien 646990075Sobrien@node Assembler Format 647090075Sobrien@section Defining the Output Assembler Language 647190075Sobrien 647290075SobrienThis section describes macros whose principal purpose is to describe how 647390075Sobriento write instructions in assembler language---rather than what the 647490075Sobrieninstructions do. 647590075Sobrien 647690075Sobrien@menu 647790075Sobrien* File Framework:: Structural information for the assembler file. 647890075Sobrien* Data Output:: Output of constants (numbers, strings, addresses). 647990075Sobrien* Uninitialized Data:: Output of uninitialized variables. 648090075Sobrien* Label Output:: Output and generation of labels. 648190075Sobrien* Initialization:: General principles of initialization 648290075Sobrien and termination routines. 648390075Sobrien* Macros for Initialization:: 648490075Sobrien Specific macros that control the handling of 648590075Sobrien initialization and termination routines. 648690075Sobrien* Instruction Output:: Output of actual instructions. 648790075Sobrien* Dispatch Tables:: Output of jump tables. 648890075Sobrien* Exception Region Output:: Output of exception region code. 648990075Sobrien* Alignment Output:: Pseudo ops for alignment and skipping data. 649090075Sobrien@end menu 649190075Sobrien 649290075Sobrien@node File Framework 649390075Sobrien@subsection The Overall Framework of an Assembler File 649490075Sobrien@cindex assembler format 649590075Sobrien@cindex output of assembler code 649690075Sobrien 649790075Sobrien@c prevent bad page break with this line 6498132718SkanThis describes the overall framework of an assembly file. 649990075Sobrien 6500132718Skan@deftypefn {Target Hook} void TARGET_ASM_FILE_START () 6501132718Skan@findex default_file_start 6502132718SkanOutput to @code{asm_out_file} any text which the assembler expects to 6503132718Skanfind at the beginning of a file. The default behavior is controlled 6504132718Skanby two flags, documented below. Unless your target's assembler is 6505132718Skanquite unusual, if you override the default, you should call 6506132718Skan@code{default_file_start} at some point in your target hook. This 6507132718Skanlets other target files rely on these variables. 6508132718Skan@end deftypefn 650990075Sobrien 6510132718Skan@deftypevr {Target Hook} bool TARGET_ASM_FILE_START_APP_OFF 6511132718SkanIf this flag is true, the text of the macro @code{ASM_APP_OFF} will be 6512132718Skanprinted as the very first line in the assembly file, unless 6513132718Skan@option{-fverbose-asm} is in effect. (If that macro has been defined 6514132718Skanto the empty string, this variable has no effect.) With the normal 6515132718Skandefinition of @code{ASM_APP_OFF}, the effect is to notify the GNU 6516132718Skanassembler that it need not bother stripping comments or extra 6517132718Skanwhitespace from its input. This allows it to work a bit faster. 651890075Sobrien 6519132718SkanThe default is false. You should not set it to true unless you have 6520132718Skanverified that your port does not generate any extra whitespace or 6521132718Skancomments that will cause GAS to issue errors in NO_APP mode. 6522132718Skan@end deftypevr 652390075Sobrien 6524132718Skan@deftypevr {Target Hook} bool TARGET_ASM_FILE_START_FILE_DIRECTIVE 6525132718SkanIf this flag is true, @code{output_file_directive} will be called 6526132718Skanfor the primary source file, immediately after printing 6527132718Skan@code{ASM_APP_OFF} (if that is enabled). Most ELF assemblers expect 6528132718Skanthis to be done. The default is false. 6529132718Skan@end deftypevr 653090075Sobrien 6531132718Skan@deftypefn {Target Hook} void TARGET_ASM_FILE_END () 6532132718SkanOutput to @code{asm_out_file} any text which the assembler expects 6533132718Skanto find at the end of a file. The default is to output nothing. 6534132718Skan@end deftypefn 653590075Sobrien 6536132718Skan@deftypefun void file_end_indicate_exec_stack () 6537132718SkanSome systems use a common convention, the @samp{.note.GNU-stack} 6538132718Skanspecial section, to indicate whether or not an object file relies on 6539132718Skanthe stack being executable. If your system uses this convention, you 6540132718Skanshould define @code{TARGET_ASM_FILE_END} to this function. If you 6541132718Skanneed to do other things in that hook, have your hook function call 6542132718Skanthis function. 6543132718Skan@end deftypefun 654490075Sobrien 6545132718Skan@defmac ASM_COMMENT_START 654690075SobrienA C string constant describing how to begin a comment in the target 654790075Sobrienassembler language. The compiler assumes that the comment will end at 654890075Sobrienthe end of the line. 6549132718Skan@end defmac 655090075Sobrien 6551132718Skan@defmac ASM_APP_ON 655290075SobrienA C string constant for text to be output before each @code{asm} 655390075Sobrienstatement or group of consecutive ones. Normally this is 655490075Sobrien@code{"#APP"}, which is a comment that has no effect on most 655590075Sobrienassemblers but tells the GNU assembler that it must check the lines 655690075Sobrienthat follow for all valid assembler constructs. 6557132718Skan@end defmac 655890075Sobrien 6559132718Skan@defmac ASM_APP_OFF 656090075SobrienA C string constant for text to be output after each @code{asm} 656190075Sobrienstatement or group of consecutive ones. Normally this is 656290075Sobrien@code{"#NO_APP"}, which tells the GNU assembler to resume making the 656390075Sobrientime-saving assumptions that are valid for ordinary compiler output. 6564132718Skan@end defmac 656590075Sobrien 6566132718Skan@defmac ASM_OUTPUT_SOURCE_FILENAME (@var{stream}, @var{name}) 656790075SobrienA C statement to output COFF information or DWARF debugging information 656890075Sobrienwhich indicates that filename @var{name} is the current source file to 656990075Sobrienthe stdio stream @var{stream}. 657090075Sobrien 657190075SobrienThis macro need not be defined if the standard form of output 657290075Sobrienfor the file format in use is appropriate. 6573132718Skan@end defmac 657490075Sobrien 6575132718Skan@defmac OUTPUT_QUOTED_STRING (@var{stream}, @var{string}) 657690075SobrienA C statement to output the string @var{string} to the stdio stream 657790075Sobrien@var{stream}. If you do not call the function @code{output_quoted_string} 657890075Sobrienin your config files, GCC will only call it to output filenames to 657990075Sobrienthe assembler source. So you can use it to canonicalize the format 658090075Sobrienof the filename using this macro. 6581132718Skan@end defmac 658290075Sobrien 6583132718Skan@defmac ASM_OUTPUT_IDENT (@var{stream}, @var{string}) 658490075SobrienA C statement to output something to the assembler file to handle a 658590075Sobrien@samp{#ident} directive containing the text @var{string}. If this 658690075Sobrienmacro is not defined, nothing is output for a @samp{#ident} directive. 6587132718Skan@end defmac 658890075Sobrien 658990075Sobrien@deftypefn {Target Hook} void TARGET_ASM_NAMED_SECTION (const char *@var{name}, unsigned int @var{flags}, unsigned int @var{align}) 659090075SobrienOutput assembly directives to switch to section @var{name}. The section 659190075Sobrienshould have attributes as specified by @var{flags}, which is a bit mask 659290075Sobrienof the @code{SECTION_*} flags defined in @file{output.h}. If @var{align} 659390075Sobrienis nonzero, it contains an alignment in bytes to be used for the section, 659496263Sobrienotherwise some target default should be used. Only targets that must 659590075Sobrienspecify an alignment within the section directive need pay attention to 659690075Sobrien@var{align} -- we will still use @code{ASM_OUTPUT_ALIGN}. 659790075Sobrien@end deftypefn 659890075Sobrien 659990075Sobrien@deftypefn {Target Hook} bool TARGET_HAVE_NAMED_SECTIONS 660090075SobrienThis flag is true if the target supports @code{TARGET_ASM_NAMED_SECTION}. 660190075Sobrien@end deftypefn 660290075Sobrien 6603169689Skan@anchor{TARGET_HAVE_SWITCHABLE_BSS_SECTIONS} 6604169689Skan@deftypefn {Target Hook} bool TARGET_HAVE_SWITCHABLE_BSS_SECTIONS 6605169689SkanThis flag is true if we can create zeroed data by switching to a BSS 6606169689Skansection and then using @code{ASM_OUTPUT_SKIP} to allocate the space. 6607169689SkanThis is true on most ELF targets. 6608169689Skan@end deftypefn 6609169689Skan 661090075Sobrien@deftypefn {Target Hook} {unsigned int} TARGET_SECTION_TYPE_FLAGS (tree @var{decl}, const char *@var{name}, int @var{reloc}) 661190075SobrienChoose a set of section attributes for use by @code{TARGET_ASM_NAMED_SECTION} 661290075Sobrienbased on a variable or function decl, a section name, and whether or not the 661390075Sobriendeclaration's initializer may contain runtime relocations. @var{decl} may be 661490075Sobrien null, in which case read-write data should be assumed. 661590075Sobrien 6616169689SkanThe default version of this function handles choosing code vs data, 661790075Sobrienread-only vs read-write data, and @code{flag_pic}. You should only 661890075Sobrienneed to override this if your target has special flags that might be 661990075Sobrienset via @code{__attribute__}. 662090075Sobrien@end deftypefn 662190075Sobrien 662290075Sobrien@need 2000 662390075Sobrien@node Data Output 662490075Sobrien@subsection Output of Data 662590075Sobrien 662690075Sobrien 662790075Sobrien@deftypevr {Target Hook} {const char *} TARGET_ASM_BYTE_OP 662890075Sobrien@deftypevrx {Target Hook} {const char *} TARGET_ASM_ALIGNED_HI_OP 662990075Sobrien@deftypevrx {Target Hook} {const char *} TARGET_ASM_ALIGNED_SI_OP 663090075Sobrien@deftypevrx {Target Hook} {const char *} TARGET_ASM_ALIGNED_DI_OP 663190075Sobrien@deftypevrx {Target Hook} {const char *} TARGET_ASM_ALIGNED_TI_OP 663290075Sobrien@deftypevrx {Target Hook} {const char *} TARGET_ASM_UNALIGNED_HI_OP 663390075Sobrien@deftypevrx {Target Hook} {const char *} TARGET_ASM_UNALIGNED_SI_OP 663490075Sobrien@deftypevrx {Target Hook} {const char *} TARGET_ASM_UNALIGNED_DI_OP 663590075Sobrien@deftypevrx {Target Hook} {const char *} TARGET_ASM_UNALIGNED_TI_OP 663690075SobrienThese hooks specify assembly directives for creating certain kinds 663790075Sobrienof integer object. The @code{TARGET_ASM_BYTE_OP} directive creates a 663890075Sobrienbyte-sized object, the @code{TARGET_ASM_ALIGNED_HI_OP} one creates an 663990075Sobrienaligned two-byte object, and so on. Any of the hooks may be 664090075Sobrien@code{NULL}, indicating that no suitable directive is available. 664190075Sobrien 664290075SobrienThe compiler will print these strings at the start of a new line, 664390075Sobrienfollowed immediately by the object's initial value. In most cases, 664490075Sobrienthe string should contain a tab, a pseudo-op, and then another tab. 664590075Sobrien@end deftypevr 664690075Sobrien 664790075Sobrien@deftypefn {Target Hook} bool TARGET_ASM_INTEGER (rtx @var{x}, unsigned int @var{size}, int @var{aligned_p}) 664890075SobrienThe @code{assemble_integer} function uses this hook to output an 664990075Sobrieninteger object. @var{x} is the object's value, @var{size} is its size 665090075Sobrienin bytes and @var{aligned_p} indicates whether it is aligned. The 665190075Sobrienfunction should return @code{true} if it was able to output the 665290075Sobrienobject. If it returns false, @code{assemble_integer} will try to 665390075Sobriensplit the object into smaller parts. 665490075Sobrien 665590075SobrienThe default implementation of this hook will use the 665690075Sobrien@code{TARGET_ASM_BYTE_OP} family of strings, returning @code{false} 665790075Sobrienwhen the relevant string is @code{NULL}. 665890075Sobrien@end deftypefn 665990075Sobrien 6660132718Skan@defmac OUTPUT_ADDR_CONST_EXTRA (@var{stream}, @var{x}, @var{fail}) 666190075SobrienA C statement to recognize @var{rtx} patterns that 666290075Sobrien@code{output_addr_const} can't deal with, and output assembly code to 666390075Sobrien@var{stream} corresponding to the pattern @var{x}. This may be used to 666490075Sobrienallow machine-dependent @code{UNSPEC}s to appear within constants. 666590075Sobrien 666690075SobrienIf @code{OUTPUT_ADDR_CONST_EXTRA} fails to recognize a pattern, it must 666790075Sobrien@code{goto fail}, so that a standard error message is printed. If it 666890075Sobrienprints an error message itself, by calling, for example, 666990075Sobrien@code{output_operand_lossage}, it may just complete normally. 6670132718Skan@end defmac 667190075Sobrien 6672132718Skan@defmac ASM_OUTPUT_ASCII (@var{stream}, @var{ptr}, @var{len}) 667390075SobrienA C statement to output to the stdio stream @var{stream} an assembler 667490075Sobrieninstruction to assemble a string constant containing the @var{len} 667590075Sobrienbytes at @var{ptr}. @var{ptr} will be a C expression of type 667690075Sobrien@code{char *} and @var{len} a C expression of type @code{int}. 667790075Sobrien 667890075SobrienIf the assembler has a @code{.ascii} pseudo-op as found in the 667990075SobrienBerkeley Unix assembler, do not define the macro 668090075Sobrien@code{ASM_OUTPUT_ASCII}. 6681132718Skan@end defmac 668290075Sobrien 6683132718Skan@defmac ASM_OUTPUT_FDESC (@var{stream}, @var{decl}, @var{n}) 668490075SobrienA C statement to output word @var{n} of a function descriptor for 668590075Sobrien@var{decl}. This must be defined if @code{TARGET_VTABLE_USES_DESCRIPTORS} 668690075Sobrienis defined, and is otherwise unused. 6687132718Skan@end defmac 668890075Sobrien 6689132718Skan@defmac CONSTANT_POOL_BEFORE_FUNCTION 669090075SobrienYou may define this macro as a C expression. You should define the 669190075Sobrienexpression to have a nonzero value if GCC should output the constant 669290075Sobrienpool for a function before the code for the function, or a zero value if 669390075SobrienGCC should output the constant pool after the function. If you do 669490075Sobriennot define this macro, the usual case, GCC will output the constant 669590075Sobrienpool before the function. 6696132718Skan@end defmac 669790075Sobrien 6698132718Skan@defmac ASM_OUTPUT_POOL_PROLOGUE (@var{file}, @var{funname}, @var{fundecl}, @var{size}) 669990075SobrienA C statement to output assembler commands to define the start of the 670090075Sobrienconstant pool for a function. @var{funname} is a string giving 670190075Sobrienthe name of the function. Should the return type of the function 670290075Sobrienbe required, it can be obtained via @var{fundecl}. @var{size} 670390075Sobrienis the size, in bytes, of the constant pool that will be written 670490075Sobrienimmediately after this call. 670590075Sobrien 670690075SobrienIf no constant-pool prefix is required, the usual case, this macro need 670790075Sobriennot be defined. 6708132718Skan@end defmac 670990075Sobrien 6710132718Skan@defmac ASM_OUTPUT_SPECIAL_POOL_ENTRY (@var{file}, @var{x}, @var{mode}, @var{align}, @var{labelno}, @var{jumpto}) 671190075SobrienA C statement (with or without semicolon) to output a constant in the 671290075Sobrienconstant pool, if it needs special treatment. (This macro need not do 671390075Sobrienanything for RTL expressions that can be output normally.) 671490075Sobrien 671590075SobrienThe argument @var{file} is the standard I/O stream to output the 671690075Sobrienassembler code on. @var{x} is the RTL expression for the constant to 671790075Sobrienoutput, and @var{mode} is the machine mode (in case @var{x} is a 671890075Sobrien@samp{const_int}). @var{align} is the required alignment for the value 671990075Sobrien@var{x}; you should output an assembler directive to force this much 672090075Sobrienalignment. 672190075Sobrien 672290075SobrienThe argument @var{labelno} is a number to use in an internal label for 672390075Sobrienthe address of this pool entry. The definition of this macro is 672490075Sobrienresponsible for outputting the label definition at the proper place. 672590075SobrienHere is how to do this: 672690075Sobrien 6727132718Skan@smallexample 6728132718Skan@code{(*targetm.asm_out.internal_label)} (@var{file}, "LC", @var{labelno}); 6729132718Skan@end smallexample 673090075Sobrien 673190075SobrienWhen you output a pool entry specially, you should end with a 673290075Sobrien@code{goto} to the label @var{jumpto}. This will prevent the same pool 673390075Sobrienentry from being output a second time in the usual manner. 673490075Sobrien 673590075SobrienYou need not define this macro if it would do nothing. 6736132718Skan@end defmac 673790075Sobrien 6738132718Skan@defmac ASM_OUTPUT_POOL_EPILOGUE (@var{file} @var{funname} @var{fundecl} @var{size}) 673990075SobrienA C statement to output assembler commands to at the end of the constant 674090075Sobrienpool for a function. @var{funname} is a string giving the name of the 674190075Sobrienfunction. Should the return type of the function be required, you can 674290075Sobrienobtain it via @var{fundecl}. @var{size} is the size, in bytes, of the 674390075Sobrienconstant pool that GCC wrote immediately before this call. 674490075Sobrien 674590075SobrienIf no constant-pool epilogue is required, the usual case, you need not 674690075Sobriendefine this macro. 6747132718Skan@end defmac 674890075Sobrien 6749132718Skan@defmac IS_ASM_LOGICAL_LINE_SEPARATOR (@var{C}) 675090075SobrienDefine this macro as a C expression which is nonzero if @var{C} is 675190075Sobrienused as a logical line separator by the assembler. 675290075Sobrien 675390075SobrienIf you do not define this macro, the default is that only 675490075Sobrienthe character @samp{;} is treated as a logical line separator. 6755132718Skan@end defmac 675690075Sobrien 675790075Sobrien@deftypevr {Target Hook} {const char *} TARGET_ASM_OPEN_PAREN 675890075Sobrien@deftypevrx {Target Hook} {const char *} TARGET_ASM_CLOSE_PAREN 675990075SobrienThese target hooks are C string constants, describing the syntax in the 676090075Sobrienassembler for grouping arithmetic expressions. If not overridden, they 676190075Sobriendefault to normal parentheses, which is correct for most assemblers. 676290075Sobrien@end deftypevr 676390075Sobrien 676490075Sobrien These macros are provided by @file{real.h} for writing the definitions 676590075Sobrienof @code{ASM_OUTPUT_DOUBLE} and the like: 676690075Sobrien 6767132718Skan@defmac REAL_VALUE_TO_TARGET_SINGLE (@var{x}, @var{l}) 6768132718Skan@defmacx REAL_VALUE_TO_TARGET_DOUBLE (@var{x}, @var{l}) 6769132718Skan@defmacx REAL_VALUE_TO_TARGET_LONG_DOUBLE (@var{x}, @var{l}) 6770169689Skan@defmacx REAL_VALUE_TO_TARGET_DECIMAL32 (@var{x}, @var{l}) 6771169689Skan@defmacx REAL_VALUE_TO_TARGET_DECIMAL64 (@var{x}, @var{l}) 6772169689Skan@defmacx REAL_VALUE_TO_TARGET_DECIMAL128 (@var{x}, @var{l}) 6773169689SkanThese translate @var{x}, of type @code{REAL_VALUE_TYPE}, to the 6774169689Skantarget's floating point representation, and store its bit pattern in 6775169689Skanthe variable @var{l}. For @code{REAL_VALUE_TO_TARGET_SINGLE} and 6776169689Skan@code{REAL_VALUE_TO_TARGET_DECIMAL32}, this variable should be a 6777169689Skansimple @code{long int}. For the others, it should be an array of 6778169689Skan@code{long int}. The number of elements in this array is determined 6779169689Skanby the size of the desired target floating point data type: 32 bits of 6780169689Skanit go in each @code{long int} array element. Each array element holds 6781169689Skan32 bits of the result, even if @code{long int} is wider than 32 bits 6782169689Skanon the host machine. 678390075Sobrien 678490075SobrienThe array element values are designed so that you can print them out 678590075Sobrienusing @code{fprintf} in the order they should appear in the target 678690075Sobrienmachine's memory. 6787132718Skan@end defmac 678890075Sobrien 678990075Sobrien@node Uninitialized Data 679090075Sobrien@subsection Output of Uninitialized Variables 679190075Sobrien 679290075SobrienEach of the macros in this section is used to do the whole job of 679390075Sobrienoutputting a single uninitialized variable. 679490075Sobrien 6795132718Skan@defmac ASM_OUTPUT_COMMON (@var{stream}, @var{name}, @var{size}, @var{rounded}) 679690075SobrienA C statement (sans semicolon) to output to the stdio stream 679790075Sobrien@var{stream} the assembler definition of a common-label named 679890075Sobrien@var{name} whose size is @var{size} bytes. The variable @var{rounded} 679990075Sobrienis the size rounded up to whatever alignment the caller wants. 680090075Sobrien 680190075SobrienUse the expression @code{assemble_name (@var{stream}, @var{name})} to 680290075Sobrienoutput the name itself; before and after that, output the additional 680390075Sobrienassembler syntax for defining the name, and a newline. 680490075Sobrien 680590075SobrienThis macro controls how the assembler definitions of uninitialized 680690075Sobriencommon global variables are output. 6807132718Skan@end defmac 680890075Sobrien 6809132718Skan@defmac ASM_OUTPUT_ALIGNED_COMMON (@var{stream}, @var{name}, @var{size}, @var{alignment}) 681090075SobrienLike @code{ASM_OUTPUT_COMMON} except takes the required alignment as a 681190075Sobrienseparate, explicit argument. If you define this macro, it is used in 681290075Sobrienplace of @code{ASM_OUTPUT_COMMON}, and gives you more flexibility in 681390075Sobrienhandling the required alignment of the variable. The alignment is specified 681490075Sobrienas the number of bits. 6815132718Skan@end defmac 681690075Sobrien 6817132718Skan@defmac ASM_OUTPUT_ALIGNED_DECL_COMMON (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{alignment}) 681890075SobrienLike @code{ASM_OUTPUT_ALIGNED_COMMON} except that @var{decl} of the 681990075Sobrienvariable to be output, if there is one, or @code{NULL_TREE} if there 682090075Sobrienis no corresponding variable. If you define this macro, GCC will use it 682190075Sobrienin place of both @code{ASM_OUTPUT_COMMON} and 682290075Sobrien@code{ASM_OUTPUT_ALIGNED_COMMON}. Define this macro when you need to see 682390075Sobrienthe variable's decl in order to chose what to output. 6824132718Skan@end defmac 682590075Sobrien 6826132718Skan@defmac ASM_OUTPUT_BSS (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{rounded}) 682790075SobrienA C statement (sans semicolon) to output to the stdio stream 682890075Sobrien@var{stream} the assembler definition of uninitialized global @var{decl} named 682990075Sobrien@var{name} whose size is @var{size} bytes. The variable @var{rounded} 683090075Sobrienis the size rounded up to whatever alignment the caller wants. 683190075Sobrien 683290075SobrienTry to use function @code{asm_output_bss} defined in @file{varasm.c} when 683390075Sobriendefining this macro. If unable, use the expression 683490075Sobrien@code{assemble_name (@var{stream}, @var{name})} to output the name itself; 683590075Sobrienbefore and after that, output the additional assembler syntax for defining 683690075Sobrienthe name, and a newline. 683790075Sobrien 6838169689SkanThere are two ways of handling global BSS. One is to define either 6839169689Skanthis macro or its aligned counterpart, @code{ASM_OUTPUT_ALIGNED_BSS}. 6840169689SkanThe other is to have @code{TARGET_ASM_SELECT_SECTION} return a 6841169689Skanswitchable BSS section (@pxref{TARGET_HAVE_SWITCHABLE_BSS_SECTIONS}). 6842169689SkanYou do not need to do both. 6843169689Skan 6844169689SkanSome languages do not have @code{common} data, and require a 6845169689Skannon-common form of global BSS in order to handle uninitialized globals 6846169689Skanefficiently. C++ is one example of this. However, if the target does 6847169689Skannot support global BSS, the front end may choose to make globals 6848169689Skancommon in order to save space in the object file. 6849132718Skan@end defmac 685090075Sobrien 6851132718Skan@defmac ASM_OUTPUT_ALIGNED_BSS (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{alignment}) 685290075SobrienLike @code{ASM_OUTPUT_BSS} except takes the required alignment as a 685390075Sobrienseparate, explicit argument. If you define this macro, it is used in 685490075Sobrienplace of @code{ASM_OUTPUT_BSS}, and gives you more flexibility in 685590075Sobrienhandling the required alignment of the variable. The alignment is specified 685690075Sobrienas the number of bits. 685790075Sobrien 685890075SobrienTry to use function @code{asm_output_aligned_bss} defined in file 685990075Sobrien@file{varasm.c} when defining this macro. 6860132718Skan@end defmac 686190075Sobrien 6862132718Skan@defmac ASM_OUTPUT_LOCAL (@var{stream}, @var{name}, @var{size}, @var{rounded}) 686390075SobrienA C statement (sans semicolon) to output to the stdio stream 686490075Sobrien@var{stream} the assembler definition of a local-common-label named 686590075Sobrien@var{name} whose size is @var{size} bytes. The variable @var{rounded} 686690075Sobrienis the size rounded up to whatever alignment the caller wants. 686790075Sobrien 686890075SobrienUse the expression @code{assemble_name (@var{stream}, @var{name})} to 686990075Sobrienoutput the name itself; before and after that, output the additional 687090075Sobrienassembler syntax for defining the name, and a newline. 687190075Sobrien 687290075SobrienThis macro controls how the assembler definitions of uninitialized 687390075Sobrienstatic variables are output. 6874132718Skan@end defmac 687590075Sobrien 6876132718Skan@defmac ASM_OUTPUT_ALIGNED_LOCAL (@var{stream}, @var{name}, @var{size}, @var{alignment}) 687790075SobrienLike @code{ASM_OUTPUT_LOCAL} except takes the required alignment as a 687890075Sobrienseparate, explicit argument. If you define this macro, it is used in 687990075Sobrienplace of @code{ASM_OUTPUT_LOCAL}, and gives you more flexibility in 688090075Sobrienhandling the required alignment of the variable. The alignment is specified 688190075Sobrienas the number of bits. 6882132718Skan@end defmac 688390075Sobrien 6884132718Skan@defmac ASM_OUTPUT_ALIGNED_DECL_LOCAL (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{alignment}) 688590075SobrienLike @code{ASM_OUTPUT_ALIGNED_DECL} except that @var{decl} of the 688690075Sobrienvariable to be output, if there is one, or @code{NULL_TREE} if there 688790075Sobrienis no corresponding variable. If you define this macro, GCC will use it 688890075Sobrienin place of both @code{ASM_OUTPUT_DECL} and 688990075Sobrien@code{ASM_OUTPUT_ALIGNED_DECL}. Define this macro when you need to see 689090075Sobrienthe variable's decl in order to chose what to output. 6891132718Skan@end defmac 689290075Sobrien 689390075Sobrien@node Label Output 689490075Sobrien@subsection Output and Generation of Labels 689590075Sobrien 689690075Sobrien@c prevent bad page break with this line 689790075SobrienThis is about outputting labels. 689890075Sobrien 689990075Sobrien@findex assemble_name 6900132718Skan@defmac ASM_OUTPUT_LABEL (@var{stream}, @var{name}) 690190075SobrienA C statement (sans semicolon) to output to the stdio stream 690290075Sobrien@var{stream} the assembler definition of a label named @var{name}. 690390075SobrienUse the expression @code{assemble_name (@var{stream}, @var{name})} to 690490075Sobrienoutput the name itself; before and after that, output the additional 6905117395Skanassembler syntax for defining the name, and a newline. A default 6906117395Skandefinition of this macro is provided which is correct for most systems. 6907132718Skan@end defmac 690890075Sobrien 6909169689Skan@findex assemble_name_raw 6910169689Skan@defmac ASM_OUTPUT_INTERNAL_LABEL (@var{stream}, @var{name}) 6911169689SkanIdentical to @code{ASM_OUTPUT_LABEL}, except that @var{name} is known 6912169689Skanto refer to a compiler-generated label. The default definition uses 6913169689Skan@code{assemble_name_raw}, which is like @code{assemble_name} except 6914169689Skanthat it is more efficient. 6915169689Skan@end defmac 6916169689Skan 6917132718Skan@defmac SIZE_ASM_OP 6918117395SkanA C string containing the appropriate assembler directive to specify the 6919117395Skansize of a symbol, without any arguments. On systems that use ELF, the 6920117395Skandefault (in @file{config/elfos.h}) is @samp{"\t.size\t"}; on other 6921117395Skansystems, the default is not to define this macro. 6922117395Skan 6923117395SkanDefine this macro only if it is correct to use the default definitions 6924117395Skanof @code{ASM_OUTPUT_SIZE_DIRECTIVE} and @code{ASM_OUTPUT_MEASURED_SIZE} 6925117395Skanfor your system. If you need your own custom definitions of those 6926117395Skanmacros, or if you do not need explicit symbol sizes at all, do not 6927117395Skandefine this macro. 6928132718Skan@end defmac 6929117395Skan 6930132718Skan@defmac ASM_OUTPUT_SIZE_DIRECTIVE (@var{stream}, @var{name}, @var{size}) 6931117395SkanA C statement (sans semicolon) to output to the stdio stream 6932117395Skan@var{stream} a directive telling the assembler that the size of the 6933117395Skansymbol @var{name} is @var{size}. @var{size} is a @code{HOST_WIDE_INT}. 6934117395SkanIf you define @code{SIZE_ASM_OP}, a default definition of this macro is 6935117395Skanprovided. 6936132718Skan@end defmac 6937117395Skan 6938132718Skan@defmac ASM_OUTPUT_MEASURED_SIZE (@var{stream}, @var{name}) 6939117395SkanA C statement (sans semicolon) to output to the stdio stream 6940117395Skan@var{stream} a directive telling the assembler to calculate the size of 6941117395Skanthe symbol @var{name} by subtracting its address from the current 6942132718Skanaddress. 6943117395Skan 6944117395SkanIf you define @code{SIZE_ASM_OP}, a default definition of this macro is 6945117395Skanprovided. The default assumes that the assembler recognizes a special 6946117395Skan@samp{.} symbol as referring to the current address, and can calculate 6947117395Skanthe difference between this and another symbol. If your assembler does 6948117395Skannot recognize @samp{.} or cannot do calculations with it, you will need 6949117395Skanto redefine @code{ASM_OUTPUT_MEASURED_SIZE} to use some other technique. 6950132718Skan@end defmac 6951117395Skan 6952132718Skan@defmac TYPE_ASM_OP 6953117395SkanA C string containing the appropriate assembler directive to specify the 6954117395Skantype of a symbol, without any arguments. On systems that use ELF, the 6955117395Skandefault (in @file{config/elfos.h}) is @samp{"\t.type\t"}; on other 6956117395Skansystems, the default is not to define this macro. 6957117395Skan 6958117395SkanDefine this macro only if it is correct to use the default definition of 6959117395Skan@code{ASM_OUTPUT_TYPE_DIRECTIVE} for your system. If you need your own 6960117395Skancustom definition of this macro, or if you do not need explicit symbol 6961117395Skantypes at all, do not define this macro. 6962132718Skan@end defmac 6963117395Skan 6964132718Skan@defmac TYPE_OPERAND_FMT 6965117395SkanA C string which specifies (using @code{printf} syntax) the format of 6966117395Skanthe second operand to @code{TYPE_ASM_OP}. On systems that use ELF, the 6967117395Skandefault (in @file{config/elfos.h}) is @samp{"@@%s"}; on other systems, 6968117395Skanthe default is not to define this macro. 6969117395Skan 6970117395SkanDefine this macro only if it is correct to use the default definition of 6971117395Skan@code{ASM_OUTPUT_TYPE_DIRECTIVE} for your system. If you need your own 6972117395Skancustom definition of this macro, or if you do not need explicit symbol 6973117395Skantypes at all, do not define this macro. 6974132718Skan@end defmac 6975117395Skan 6976132718Skan@defmac ASM_OUTPUT_TYPE_DIRECTIVE (@var{stream}, @var{type}) 6977117395SkanA C statement (sans semicolon) to output to the stdio stream 6978117395Skan@var{stream} a directive telling the assembler that the type of the 6979117395Skansymbol @var{name} is @var{type}. @var{type} is a C string; currently, 6980117395Skanthat string is always either @samp{"function"} or @samp{"object"}, but 6981117395Skanyou should not count on this. 6982117395Skan 6983117395SkanIf you define @code{TYPE_ASM_OP} and @code{TYPE_OPERAND_FMT}, a default 6984117395Skandefinition of this macro is provided. 6985132718Skan@end defmac 6986117395Skan 6987132718Skan@defmac ASM_DECLARE_FUNCTION_NAME (@var{stream}, @var{name}, @var{decl}) 698890075SobrienA C statement (sans semicolon) to output to the stdio stream 698990075Sobrien@var{stream} any text necessary for declaring the name @var{name} of a 699090075Sobrienfunction which is being defined. This macro is responsible for 699190075Sobrienoutputting the label definition (perhaps using 699290075Sobrien@code{ASM_OUTPUT_LABEL}). The argument @var{decl} is the 699390075Sobrien@code{FUNCTION_DECL} tree node representing the function. 699490075Sobrien 699590075SobrienIf this macro is not defined, then the function name is defined in the 699690075Sobrienusual manner as a label (by means of @code{ASM_OUTPUT_LABEL}). 699790075Sobrien 6998117395SkanYou may wish to use @code{ASM_OUTPUT_TYPE_DIRECTIVE} in the definition 6999117395Skanof this macro. 7000132718Skan@end defmac 7001117395Skan 7002132718Skan@defmac ASM_DECLARE_FUNCTION_SIZE (@var{stream}, @var{name}, @var{decl}) 700390075SobrienA C statement (sans semicolon) to output to the stdio stream 700490075Sobrien@var{stream} any text necessary for declaring the size of a function 700590075Sobrienwhich is being defined. The argument @var{name} is the name of the 700690075Sobrienfunction. The argument @var{decl} is the @code{FUNCTION_DECL} tree node 700790075Sobrienrepresenting the function. 700890075Sobrien 700990075SobrienIf this macro is not defined, then the function size is not defined. 701090075Sobrien 7011117395SkanYou may wish to use @code{ASM_OUTPUT_MEASURED_SIZE} in the definition 7012117395Skanof this macro. 7013132718Skan@end defmac 7014117395Skan 7015132718Skan@defmac ASM_DECLARE_OBJECT_NAME (@var{stream}, @var{name}, @var{decl}) 701690075SobrienA C statement (sans semicolon) to output to the stdio stream 701790075Sobrien@var{stream} any text necessary for declaring the name @var{name} of an 701890075Sobrieninitialized variable which is being defined. This macro must output the 701990075Sobrienlabel definition (perhaps using @code{ASM_OUTPUT_LABEL}). The argument 702090075Sobrien@var{decl} is the @code{VAR_DECL} tree node representing the variable. 702190075Sobrien 702290075SobrienIf this macro is not defined, then the variable name is defined in the 702390075Sobrienusual manner as a label (by means of @code{ASM_OUTPUT_LABEL}). 702490075Sobrien 7025117395SkanYou may wish to use @code{ASM_OUTPUT_TYPE_DIRECTIVE} and/or 7026117395Skan@code{ASM_OUTPUT_SIZE_DIRECTIVE} in the definition of this macro. 7027132718Skan@end defmac 7028117395Skan 7029132718Skan@defmac ASM_DECLARE_CONSTANT_NAME (@var{stream}, @var{name}, @var{exp}, @var{size}) 7030122180SkanA C statement (sans semicolon) to output to the stdio stream 7031122180Skan@var{stream} any text necessary for declaring the name @var{name} of a 7032122180Skanconstant which is being defined. This macro is responsible for 7033122180Skanoutputting the label definition (perhaps using 7034122180Skan@code{ASM_OUTPUT_LABEL}). The argument @var{exp} is the 7035122180Skanvalue of the constant, and @var{size} is the size of the constant 7036122180Skanin bytes. @var{name} will be an internal label. 7037122180Skan 7038122180SkanIf this macro is not defined, then the @var{name} is defined in the 7039122180Skanusual manner as a label (by means of @code{ASM_OUTPUT_LABEL}). 7040122180Skan 7041122180SkanYou may wish to use @code{ASM_OUTPUT_TYPE_DIRECTIVE} in the definition 7042122180Skanof this macro. 7043132718Skan@end defmac 7044122180Skan 7045132718Skan@defmac ASM_DECLARE_REGISTER_GLOBAL (@var{stream}, @var{decl}, @var{regno}, @var{name}) 704690075SobrienA C statement (sans semicolon) to output to the stdio stream 704790075Sobrien@var{stream} any text necessary for claiming a register @var{regno} 704890075Sobrienfor a global variable @var{decl} with name @var{name}. 704990075Sobrien 705090075SobrienIf you don't define this macro, that is equivalent to defining it to do 705190075Sobriennothing. 7052132718Skan@end defmac 705390075Sobrien 7054132718Skan@defmac ASM_FINISH_DECLARE_OBJECT (@var{stream}, @var{decl}, @var{toplevel}, @var{atend}) 705590075SobrienA C statement (sans semicolon) to finish up declaring a variable name 705690075Sobrienonce the compiler has processed its initializer fully and thus has had a 705790075Sobrienchance to determine the size of an array when controlled by an 705890075Sobrieninitializer. This is used on systems where it's necessary to declare 705990075Sobriensomething about the size of the object. 706090075Sobrien 706190075SobrienIf you don't define this macro, that is equivalent to defining it to do 706290075Sobriennothing. 706390075Sobrien 7064117395SkanYou may wish to use @code{ASM_OUTPUT_SIZE_DIRECTIVE} and/or 7065117395Skan@code{ASM_OUTPUT_MEASURED_SIZE} in the definition of this macro. 7066132718Skan@end defmac 7067117395Skan 7068117395Skan@deftypefn {Target Hook} void TARGET_ASM_GLOBALIZE_LABEL (FILE *@var{stream}, const char *@var{name}) 7069117395SkanThis target hook is a function to output to the stdio stream 707090075Sobrien@var{stream} some commands that will make the label @var{name} global; 7071117395Skanthat is, available for reference from other files. 707290075Sobrien 7073117395SkanThe default implementation relies on a proper definition of 7074117395Skan@code{GLOBAL_ASM_OP}. 7075117395Skan@end deftypefn 7076117395Skan 7077132718Skan@defmac ASM_WEAKEN_LABEL (@var{stream}, @var{name}) 707890075SobrienA C statement (sans semicolon) to output to the stdio stream 707990075Sobrien@var{stream} some commands that will make the label @var{name} weak; 708090075Sobrienthat is, available for reference from other files but only used if 708190075Sobrienno other definition is available. Use the expression 708290075Sobrien@code{assemble_name (@var{stream}, @var{name})} to output the name 708390075Sobrienitself; before and after that, output the additional assembler syntax 708490075Sobrienfor making that name weak, and a newline. 708590075Sobrien 708696263SobrienIf you don't define this macro or @code{ASM_WEAKEN_DECL}, GCC will not 708796263Sobriensupport weak symbols and you should not define the @code{SUPPORTS_WEAK} 708896263Sobrienmacro. 7089132718Skan@end defmac 709090075Sobrien 7091132718Skan@defmac ASM_WEAKEN_DECL (@var{stream}, @var{decl}, @var{name}, @var{value}) 709296263SobrienCombines (and replaces) the function of @code{ASM_WEAKEN_LABEL} and 709396263Sobrien@code{ASM_OUTPUT_WEAK_ALIAS}, allowing access to the associated function 709496263Sobrienor variable decl. If @var{value} is not @code{NULL}, this C statement 709596263Sobrienshould output to the stdio stream @var{stream} assembler code which 709696263Sobriendefines (equates) the weak symbol @var{name} to have the value 709796263Sobrien@var{value}. If @var{value} is @code{NULL}, it should output commands 709896263Sobriento make @var{name} weak. 7099132718Skan@end defmac 710096263Sobrien 7101169689Skan@defmac ASM_OUTPUT_WEAKREF (@var{stream}, @var{decl}, @var{name}, @var{value}) 7102169689SkanOutputs a directive that enables @var{name} to be used to refer to 7103169689Skansymbol @var{value} with weak-symbol semantics. @code{decl} is the 7104169689Skandeclaration of @code{name}. 7105169689Skan@end defmac 7106169689Skan 7107132718Skan@defmac SUPPORTS_WEAK 710890075SobrienA C expression which evaluates to true if the target supports weak symbols. 710990075Sobrien 711090075SobrienIf you don't define this macro, @file{defaults.h} provides a default 711196263Sobriendefinition. If either @code{ASM_WEAKEN_LABEL} or @code{ASM_WEAKEN_DECL} 711296263Sobrienis defined, the default definition is @samp{1}; otherwise, it is 711396263Sobrien@samp{0}. Define this macro if you want to control weak symbol support 711496263Sobrienwith a compiler flag such as @option{-melf}. 7115132718Skan@end defmac 711690075Sobrien 7117132718Skan@defmac MAKE_DECL_ONE_ONLY (@var{decl}) 711890075SobrienA C statement (sans semicolon) to mark @var{decl} to be emitted as a 711990075Sobrienpublic symbol such that extra copies in multiple translation units will 712090075Sobrienbe discarded by the linker. Define this macro if your object file 712190075Sobrienformat provides support for this concept, such as the @samp{COMDAT} 712290075Sobriensection flags in the Microsoft Windows PE/COFF format, and this support 712390075Sobrienrequires changes to @var{decl}, such as putting it in a separate section. 7124132718Skan@end defmac 712590075Sobrien 7126132718Skan@defmac SUPPORTS_ONE_ONLY 712790075SobrienA C expression which evaluates to true if the target supports one-only 712890075Sobriensemantics. 712990075Sobrien 713090075SobrienIf you don't define this macro, @file{varasm.c} provides a default 713190075Sobriendefinition. If @code{MAKE_DECL_ONE_ONLY} is defined, the default 713290075Sobriendefinition is @samp{1}; otherwise, it is @samp{0}. Define this macro if 713390075Sobrienyou want to control one-only symbol support with a compiler flag, or if 713490075Sobriensetting the @code{DECL_ONE_ONLY} flag is enough to mark a declaration to 713590075Sobrienbe emitted as one-only. 7136132718Skan@end defmac 713790075Sobrien 7138117395Skan@deftypefn {Target Hook} void TARGET_ASM_ASSEMBLE_VISIBILITY (tree @var{decl}, const char *@var{visibility}) 7139117395SkanThis target hook is a function to output to @var{asm_out_file} some 7140117395Skancommands that will make the symbol(s) associated with @var{decl} have 7141117395Skanhidden, protected or internal visibility as specified by @var{visibility}. 7142117395Skan@end deftypefn 7143117395Skan 7144169689Skan@defmac TARGET_WEAK_NOT_IN_ARCHIVE_TOC 7145169689SkanA C expression that evaluates to true if the target's linker expects 7146169689Skanthat weak symbols do not appear in a static archive's table of contents. 7147169689SkanThe default is @code{0}. 7148169689Skan 7149169689SkanLeaving weak symbols out of an archive's table of contents means that, 7150169689Skanif a symbol will only have a definition in one translation unit and 7151169689Skanwill have undefined references from other translation units, that 7152169689Skansymbol should not be weak. Defining this macro to be nonzero will 7153169689Skanthus have the effect that certain symbols that would normally be weak 7154169689Skan(explicit template instantiations, and vtables for polymorphic classes 7155169689Skanwith noninline key methods) will instead be nonweak. 7156169689Skan 7157169689SkanThe C++ ABI requires this macro to be zero. Define this macro for 7158169689Skantargets where full C++ ABI compliance is impossible and where linker 7159169689Skanrestrictions require weak symbols to be left out of a static archive's 7160169689Skantable of contents. 7161169689Skan@end defmac 7162169689Skan 7163132718Skan@defmac ASM_OUTPUT_EXTERNAL (@var{stream}, @var{decl}, @var{name}) 716490075SobrienA C statement (sans semicolon) to output to the stdio stream 716590075Sobrien@var{stream} any text necessary for declaring the name of an external 716690075Sobriensymbol named @var{name} which is referenced in this compilation but 716790075Sobriennot defined. The value of @var{decl} is the tree node for the 716890075Sobriendeclaration. 716990075Sobrien 717090075SobrienThis macro need not be defined if it does not need to output anything. 717190075SobrienThe GNU assembler and most Unix assemblers don't require anything. 7172132718Skan@end defmac 717390075Sobrien 7174132718Skan@deftypefn {Target Hook} void TARGET_ASM_EXTERNAL_LIBCALL (rtx @var{symref}) 7175132718SkanThis target hook is a function to output to @var{asm_out_file} an assembler 717690075Sobrienpseudo-op to declare a library function name external. The name of the 7177132718Skanlibrary function is given by @var{symref}, which is a @code{symbol_ref}. 7178132718Skan@end deftypefn 717990075Sobrien 7180169689Skan@deftypefn {Target Hook} void TARGET_ASM_MARK_DECL_PRESERVED (tree @var{decl}) 7181169689SkanThis target hook is a function to output to @var{asm_out_file} an assembler 7182169689Skandirective to annotate used symbol. Darwin target use .no_dead_code_strip 7183169689Skandirective. 7184169689Skan@end deftypefn 7185169689Skan 7186132718Skan@defmac ASM_OUTPUT_LABELREF (@var{stream}, @var{name}) 718790075SobrienA C statement (sans semicolon) to output to the stdio stream 718890075Sobrien@var{stream} a reference in assembler syntax to a label named 718990075Sobrien@var{name}. This should add @samp{_} to the front of the name, if that 719090075Sobrienis customary on your operating system, as it is in most Berkeley Unix 719190075Sobriensystems. This macro is used in @code{assemble_name}. 7192132718Skan@end defmac 719390075Sobrien 7194132718Skan@defmac ASM_OUTPUT_SYMBOL_REF (@var{stream}, @var{sym}) 719590075SobrienA C statement (sans semicolon) to output a reference to 719690075Sobrien@code{SYMBOL_REF} @var{sym}. If not defined, @code{assemble_name} 719790075Sobrienwill be used to output the name of the symbol. This macro may be used 719890075Sobriento modify the way a symbol is referenced depending on information 7199117395Skanencoded by @code{TARGET_ENCODE_SECTION_INFO}. 7200132718Skan@end defmac 720190075Sobrien 7202132718Skan@defmac ASM_OUTPUT_LABEL_REF (@var{stream}, @var{buf}) 720390075SobrienA C statement (sans semicolon) to output a reference to @var{buf}, the 7204117395Skanresult of @code{ASM_GENERATE_INTERNAL_LABEL}. If not defined, 720590075Sobrien@code{assemble_name} will be used to output the name of the symbol. 720690075SobrienThis macro is not used by @code{output_asm_label}, or the @code{%l} 720790075Sobrienspecifier that calls it; the intention is that this macro should be set 7208117395Skanwhen it is necessary to output a label differently when its address is 7209117395Skanbeing taken. 7210132718Skan@end defmac 721190075Sobrien 7212132718Skan@deftypefn {Target Hook} void TARGET_ASM_INTERNAL_LABEL (FILE *@var{stream}, const char *@var{prefix}, unsigned long @var{labelno}) 7213132718SkanA function to output to the stdio stream @var{stream} a label whose 7214132718Skanname is made from the string @var{prefix} and the number @var{labelno}. 721590075Sobrien 721690075SobrienIt is absolutely essential that these labels be distinct from the labels 721790075Sobrienused for user-level functions and variables. Otherwise, certain programs 721890075Sobrienwill have name conflicts with internal labels. 721990075Sobrien 722090075SobrienIt is desirable to exclude internal labels from the symbol table of the 722190075Sobrienobject file. Most assemblers have a naming convention for labels that 722290075Sobrienshould be excluded; on many systems, the letter @samp{L} at the 722390075Sobrienbeginning of a label has this effect. You should find out what 722490075Sobrienconvention your system uses, and follow it. 722590075Sobrien 7226169689SkanThe default version of this function utilizes @code{ASM_GENERATE_INTERNAL_LABEL}. 7227132718Skan@end deftypefn 722890075Sobrien 7229132718Skan@defmac ASM_OUTPUT_DEBUG_LABEL (@var{stream}, @var{prefix}, @var{num}) 723090075SobrienA C statement to output to the stdio stream @var{stream} a debug info 723190075Sobrienlabel whose name is made from the string @var{prefix} and the number 723290075Sobrien@var{num}. This is useful for VLIW targets, where debug info labels 723390075Sobrienmay need to be treated differently than branch target labels. On some 723490075Sobriensystems, branch target labels must be at the beginning of instruction 723590075Sobrienbundles, but debug info labels can occur in the middle of instruction 723690075Sobrienbundles. 723790075Sobrien 7238132718SkanIf this macro is not defined, then @code{(*targetm.asm_out.internal_label)} will be 723990075Sobrienused. 7240132718Skan@end defmac 724190075Sobrien 7242132718Skan@defmac ASM_GENERATE_INTERNAL_LABEL (@var{string}, @var{prefix}, @var{num}) 724390075SobrienA C statement to store into the string @var{string} a label whose name 724490075Sobrienis made from the string @var{prefix} and the number @var{num}. 724590075Sobrien 724690075SobrienThis string, when output subsequently by @code{assemble_name}, should 7247132718Skanproduce the output that @code{(*targetm.asm_out.internal_label)} would produce 724890075Sobrienwith the same @var{prefix} and @var{num}. 724990075Sobrien 725090075SobrienIf the string begins with @samp{*}, then @code{assemble_name} will 725190075Sobrienoutput the rest of the string unchanged. It is often convenient for 725290075Sobrien@code{ASM_GENERATE_INTERNAL_LABEL} to use @samp{*} in this way. If the 725390075Sobrienstring doesn't start with @samp{*}, then @code{ASM_OUTPUT_LABELREF} gets 725490075Sobriento output the string, and may change it. (Of course, 725590075Sobrien@code{ASM_OUTPUT_LABELREF} is also part of your machine description, so 725690075Sobrienyou should know what it does on your machine.) 7257132718Skan@end defmac 725890075Sobrien 7259132718Skan@defmac ASM_FORMAT_PRIVATE_NAME (@var{outvar}, @var{name}, @var{number}) 726090075SobrienA C expression to assign to @var{outvar} (which is a variable of type 726190075Sobrien@code{char *}) a newly allocated string made from the string 726290075Sobrien@var{name} and the number @var{number}, with some suitable punctuation 726390075Sobrienadded. Use @code{alloca} to get space for the string. 726490075Sobrien 726590075SobrienThe string will be used as an argument to @code{ASM_OUTPUT_LABELREF} to 726690075Sobrienproduce an assembler label for an internal static variable whose name is 726790075Sobrien@var{name}. Therefore, the string must be such as to result in valid 726890075Sobrienassembler code. The argument @var{number} is different each time this 726990075Sobrienmacro is executed; it prevents conflicts between similarly-named 727090075Sobrieninternal static variables in different scopes. 727190075Sobrien 727290075SobrienIdeally this string should not be a valid C identifier, to prevent any 727390075Sobrienconflict with the user's own symbols. Most assemblers allow periods 727490075Sobrienor percent signs in assembler symbols; putting at least one of these 727590075Sobrienbetween the name and the number will suffice. 727690075Sobrien 7277132718SkanIf this macro is not defined, a default definition will be provided 7278132718Skanwhich is correct for most systems. 7279132718Skan@end defmac 7280132718Skan 7281132718Skan@defmac ASM_OUTPUT_DEF (@var{stream}, @var{name}, @var{value}) 728290075SobrienA C statement to output to the stdio stream @var{stream} assembler code 728390075Sobrienwhich defines (equates) the symbol @var{name} to have the value @var{value}. 728490075Sobrien 728590075Sobrien@findex SET_ASM_OP 728690075SobrienIf @code{SET_ASM_OP} is defined, a default definition is provided which is 728790075Sobriencorrect for most systems. 7288132718Skan@end defmac 728990075Sobrien 7290132718Skan@defmac ASM_OUTPUT_DEF_FROM_DECLS (@var{stream}, @var{decl_of_name}, @var{decl_of_value}) 729190075SobrienA C statement to output to the stdio stream @var{stream} assembler code 729290075Sobrienwhich defines (equates) the symbol whose tree node is @var{decl_of_name} 729390075Sobriento have the value of the tree node @var{decl_of_value}. This macro will 729490075Sobrienbe used in preference to @samp{ASM_OUTPUT_DEF} if it is defined and if 729590075Sobrienthe tree nodes are available. 729690075Sobrien 729790075Sobrien@findex SET_ASM_OP 729890075SobrienIf @code{SET_ASM_OP} is defined, a default definition is provided which is 729990075Sobriencorrect for most systems. 7300132718Skan@end defmac 730190075Sobrien 7302146895Skan@defmac TARGET_DEFERRED_OUTPUT_DEFS (@var{decl_of_name}, @var{decl_of_value}) 7303146895SkanA C statement that evaluates to true if the assembler code which defines 7304146895Skan(equates) the symbol whose tree node is @var{decl_of_name} to have the value 7305146895Skanof the tree node @var{decl_of_value} should be emitted near the end of the 7306146895Skancurrent compilation unit. The default is to not defer output of defines. 7307146895SkanThis macro affects defines output by @samp{ASM_OUTPUT_DEF} and 7308146895Skan@samp{ASM_OUTPUT_DEF_FROM_DECLS}. 7309146895Skan@end defmac 7310146895Skan 7311132718Skan@defmac ASM_OUTPUT_WEAK_ALIAS (@var{stream}, @var{name}, @var{value}) 731290075SobrienA C statement to output to the stdio stream @var{stream} assembler code 731390075Sobrienwhich defines (equates) the weak symbol @var{name} to have the value 731490075Sobrien@var{value}. If @var{value} is @code{NULL}, it defines @var{name} as 731590075Sobrienan undefined weak symbol. 731690075Sobrien 731790075SobrienDefine this macro if the target only supports weak aliases; define 731890075Sobrien@code{ASM_OUTPUT_DEF} instead if possible. 7319132718Skan@end defmac 732090075Sobrien 732190075Sobrien@node Initialization 732290075Sobrien@subsection How Initialization Functions Are Handled 732390075Sobrien@cindex initialization routines 732490075Sobrien@cindex termination routines 732590075Sobrien@cindex constructors, output of 732690075Sobrien@cindex destructors, output of 732790075Sobrien 732890075SobrienThe compiled code for certain languages includes @dfn{constructors} 732990075Sobrien(also called @dfn{initialization routines})---functions to initialize 733090075Sobriendata in the program when the program is started. These functions need 733190075Sobriento be called before the program is ``started''---that is to say, before 733290075Sobrien@code{main} is called. 733390075Sobrien 733490075SobrienCompiling some languages generates @dfn{destructors} (also called 733590075Sobrien@dfn{termination routines}) that should be called when the program 733690075Sobrienterminates. 733790075Sobrien 733890075SobrienTo make the initialization and termination functions work, the compiler 733990075Sobrienmust output something in the assembler code to cause those functions to 734090075Sobrienbe called at the appropriate time. When you port the compiler to a new 734190075Sobriensystem, you need to specify how to do this. 734290075Sobrien 734390075SobrienThere are two major ways that GCC currently supports the execution of 734490075Sobrieninitialization and termination functions. Each way has two variants. 734590075SobrienMuch of the structure is common to all four variations. 734690075Sobrien 734790075Sobrien@findex __CTOR_LIST__ 734890075Sobrien@findex __DTOR_LIST__ 734990075SobrienThe linker must build two lists of these functions---a list of 735090075Sobrieninitialization functions, called @code{__CTOR_LIST__}, and a list of 735190075Sobrientermination functions, called @code{__DTOR_LIST__}. 735290075Sobrien 735390075SobrienEach list always begins with an ignored function pointer (which may hold 735490075Sobrien0, @minus{}1, or a count of the function pointers after it, depending on 735590075Sobrienthe environment). This is followed by a series of zero or more function 735690075Sobrienpointers to constructors (or destructors), followed by a function 735790075Sobrienpointer containing zero. 735890075Sobrien 735990075SobrienDepending on the operating system and its executable file format, either 736090075Sobrien@file{crtstuff.c} or @file{libgcc2.c} traverses these lists at startup 736190075Sobrientime and exit time. Constructors are called in reverse order of the 736290075Sobrienlist; destructors in forward order. 736390075Sobrien 736490075SobrienThe best way to handle static constructors works only for object file 736590075Sobrienformats which provide arbitrarily-named sections. A section is set 736690075Sobrienaside for a list of constructors, and another for a list of destructors. 736790075SobrienTraditionally these are called @samp{.ctors} and @samp{.dtors}. Each 736890075Sobrienobject file that defines an initialization function also puts a word in 736990075Sobrienthe constructor section to point to that function. The linker 737090075Sobrienaccumulates all these words into one contiguous @samp{.ctors} section. 737190075SobrienTermination functions are handled similarly. 737290075Sobrien 737390075SobrienThis method will be chosen as the default by @file{target-def.h} if 737490075Sobrien@code{TARGET_ASM_NAMED_SECTION} is defined. A target that does not 737596263Sobriensupport arbitrary sections, but does support special designated 737690075Sobrienconstructor and destructor sections may define @code{CTORS_SECTION_ASM_OP} 737790075Sobrienand @code{DTORS_SECTION_ASM_OP} to achieve the same effect. 737890075Sobrien 737990075SobrienWhen arbitrary sections are available, there are two variants, depending 738090075Sobrienupon how the code in @file{crtstuff.c} is called. On systems that 738190075Sobriensupport a @dfn{.init} section which is executed at program startup, 738290075Sobrienparts of @file{crtstuff.c} are compiled into that section. The 7383117395Skanprogram is linked by the @command{gcc} driver like this: 738490075Sobrien 7385132718Skan@smallexample 738690075Sobrienld -o @var{output_file} crti.o crtbegin.o @dots{} -lgcc crtend.o crtn.o 7387132718Skan@end smallexample 738890075Sobrien 738990075SobrienThe prologue of a function (@code{__init}) appears in the @code{.init} 739090075Sobriensection of @file{crti.o}; the epilogue appears in @file{crtn.o}. Likewise 739190075Sobrienfor the function @code{__fini} in the @dfn{.fini} section. Normally these 739290075Sobrienfiles are provided by the operating system or by the GNU C library, but 739390075Sobrienare provided by GCC for a few targets. 739490075Sobrien 739590075SobrienThe objects @file{crtbegin.o} and @file{crtend.o} are (for most targets) 739690075Sobriencompiled from @file{crtstuff.c}. They contain, among other things, code 739790075Sobrienfragments within the @code{.init} and @code{.fini} sections that branch 739890075Sobriento routines in the @code{.text} section. The linker will pull all parts 739990075Sobrienof a section together, which results in a complete @code{__init} function 740090075Sobrienthat invokes the routines we need at startup. 740190075Sobrien 740290075SobrienTo use this variant, you must define the @code{INIT_SECTION_ASM_OP} 740390075Sobrienmacro properly. 740490075Sobrien 740590075SobrienIf no init section is available, when GCC compiles any function called 740690075Sobrien@code{main} (or more accurately, any function designated as a program 740790075Sobrienentry point by the language front end calling @code{expand_main_function}), 740890075Sobrienit inserts a procedure call to @code{__main} as the first executable code 740990075Sobrienafter the function prologue. The @code{__main} function is defined 741090075Sobrienin @file{libgcc2.c} and runs the global constructors. 741190075Sobrien 741290075SobrienIn file formats that don't support arbitrary sections, there are again 741390075Sobrientwo variants. In the simplest variant, the GNU linker (GNU @code{ld}) 741490075Sobrienand an `a.out' format must be used. In this case, 741590075Sobrien@code{TARGET_ASM_CONSTRUCTOR} is defined to produce a @code{.stabs} 741690075Sobrienentry of type @samp{N_SETT}, referencing the name @code{__CTOR_LIST__}, 741790075Sobrienand with the address of the void function containing the initialization 741890075Sobriencode as its value. The GNU linker recognizes this as a request to add 741990075Sobrienthe value to a @dfn{set}; the values are accumulated, and are eventually 742090075Sobrienplaced in the executable as a vector in the format described above, with 742190075Sobriena leading (ignored) count and a trailing zero element. 742290075Sobrien@code{TARGET_ASM_DESTRUCTOR} is handled similarly. Since no init 742390075Sobriensection is available, the absence of @code{INIT_SECTION_ASM_OP} causes 742490075Sobrienthe compilation of @code{main} to call @code{__main} as above, starting 742590075Sobrienthe initialization process. 742690075Sobrien 742790075SobrienThe last variant uses neither arbitrary sections nor the GNU linker. 742890075SobrienThis is preferable when you want to do dynamic linking and when using 742990075Sobrienfile formats which the GNU linker does not support, such as `ECOFF'@. In 743090075Sobrienthis case, @code{TARGET_HAVE_CTORS_DTORS} is false, initialization and 743190075Sobrientermination functions are recognized simply by their names. This requires 743290075Sobrienan extra program in the linkage step, called @command{collect2}. This program 743390075Sobrienpretends to be the linker, for use with GCC; it does its job by running 743490075Sobrienthe ordinary linker, but also arranges to include the vectors of 743590075Sobrieninitialization and termination functions. These functions are called 743690075Sobrienvia @code{__main} as described above. In order to use this method, 743790075Sobrien@code{use_collect2} must be defined in the target in @file{config.gcc}. 743890075Sobrien 743990075Sobrien@ifinfo 744090075SobrienThe following section describes the specific macros that control and 744190075Sobriencustomize the handling of initialization and termination functions. 744290075Sobrien@end ifinfo 744390075Sobrien 744490075Sobrien@node Macros for Initialization 744590075Sobrien@subsection Macros Controlling Initialization Routines 744690075Sobrien 744790075SobrienHere are the macros that control how the compiler handles initialization 744890075Sobrienand termination functions: 744990075Sobrien 7450132718Skan@defmac INIT_SECTION_ASM_OP 745190075SobrienIf defined, a C string constant, including spacing, for the assembler 745290075Sobrienoperation to identify the following data as initialization code. If not 745390075Sobriendefined, GCC will assume such a section does not exist. When you are 745490075Sobrienusing special sections for initialization and termination functions, this 745590075Sobrienmacro also controls how @file{crtstuff.c} and @file{libgcc2.c} arrange to 745690075Sobrienrun the initialization functions. 7457132718Skan@end defmac 745890075Sobrien 7459132718Skan@defmac HAS_INIT_SECTION 746090075SobrienIf defined, @code{main} will not call @code{__main} as described above. 746190075SobrienThis macro should be defined for systems that control start-up code 746290075Sobrienon a symbol-by-symbol basis, such as OSF/1, and should not 746390075Sobrienbe defined explicitly for systems that support @code{INIT_SECTION_ASM_OP}. 7464132718Skan@end defmac 746590075Sobrien 7466132718Skan@defmac LD_INIT_SWITCH 746790075SobrienIf defined, a C string constant for a switch that tells the linker that 746890075Sobrienthe following symbol is an initialization routine. 7469132718Skan@end defmac 747090075Sobrien 7471132718Skan@defmac LD_FINI_SWITCH 747290075SobrienIf defined, a C string constant for a switch that tells the linker that 747390075Sobrienthe following symbol is a finalization routine. 7474132718Skan@end defmac 747590075Sobrien 7476132718Skan@defmac COLLECT_SHARED_INIT_FUNC (@var{stream}, @var{func}) 747790075SobrienIf defined, a C statement that will write a function that can be 747890075Sobrienautomatically called when a shared library is loaded. The function 747990075Sobrienshould call @var{func}, which takes no arguments. If not defined, and 748090075Sobrienthe object format requires an explicit initialization function, then a 748190075Sobrienfunction called @code{_GLOBAL__DI} will be generated. 748290075Sobrien 748390075SobrienThis function and the following one are used by collect2 when linking a 748496263Sobrienshared library that needs constructors or destructors, or has DWARF2 748590075Sobrienexception tables embedded in the code. 7486132718Skan@end defmac 748790075Sobrien 7488132718Skan@defmac COLLECT_SHARED_FINI_FUNC (@var{stream}, @var{func}) 748990075SobrienIf defined, a C statement that will write a function that can be 749090075Sobrienautomatically called when a shared library is unloaded. The function 749190075Sobrienshould call @var{func}, which takes no arguments. If not defined, and 749290075Sobrienthe object format requires an explicit finalization function, then a 749390075Sobrienfunction called @code{_GLOBAL__DD} will be generated. 7494132718Skan@end defmac 749590075Sobrien 7496132718Skan@defmac INVOKE__main 749790075SobrienIf defined, @code{main} will call @code{__main} despite the presence of 749890075Sobrien@code{INIT_SECTION_ASM_OP}. This macro should be defined for systems 749990075Sobrienwhere the init section is not actually run automatically, but is still 750090075Sobrienuseful for collecting the lists of constructors and destructors. 7501132718Skan@end defmac 750290075Sobrien 7503132718Skan@defmac SUPPORTS_INIT_PRIORITY 750490075SobrienIf nonzero, the C++ @code{init_priority} attribute is supported and the 750590075Sobriencompiler should emit instructions to control the order of initialization 750690075Sobrienof objects. If zero, the compiler will issue an error message upon 750790075Sobrienencountering an @code{init_priority} attribute. 7508132718Skan@end defmac 750990075Sobrien 751090075Sobrien@deftypefn {Target Hook} bool TARGET_HAVE_CTORS_DTORS 751190075SobrienThis value is true if the target supports some ``native'' method of 751290075Sobriencollecting constructors and destructors to be run at startup and exit. 751390075SobrienIt is false if we must use @command{collect2}. 751490075Sobrien@end deftypefn 751590075Sobrien 751690075Sobrien@deftypefn {Target Hook} void TARGET_ASM_CONSTRUCTOR (rtx @var{symbol}, int @var{priority}) 751790075SobrienIf defined, a function that outputs assembler code to arrange to call 751890075Sobrienthe function referenced by @var{symbol} at initialization time. 751990075Sobrien 752090075SobrienAssume that @var{symbol} is a @code{SYMBOL_REF} for a function taking 752190075Sobrienno arguments and with no return value. If the target supports initialization 752290075Sobrienpriorities, @var{priority} is a value between 0 and @code{MAX_INIT_PRIORITY}; 752390075Sobrienotherwise it must be @code{DEFAULT_INIT_PRIORITY}. 752490075Sobrien 752590075SobrienIf this macro is not defined by the target, a suitable default will 752690075Sobrienbe chosen if (1) the target supports arbitrary section names, (2) the 752790075Sobrientarget defines @code{CTORS_SECTION_ASM_OP}, or (3) @code{USE_COLLECT2} 752890075Sobrienis not defined. 752990075Sobrien@end deftypefn 753090075Sobrien 753190075Sobrien@deftypefn {Target Hook} void TARGET_ASM_DESTRUCTOR (rtx @var{symbol}, int @var{priority}) 753290075SobrienThis is like @code{TARGET_ASM_CONSTRUCTOR} but used for termination 753390075Sobrienfunctions rather than initialization functions. 753490075Sobrien@end deftypefn 753590075Sobrien 753690075SobrienIf @code{TARGET_HAVE_CTORS_DTORS} is true, the initialization routine 753790075Sobriengenerated for the generated object file will have static linkage. 753890075Sobrien 753990075SobrienIf your system uses @command{collect2} as the means of processing 754090075Sobrienconstructors, then that program normally uses @command{nm} to scan 754190075Sobrienan object file for constructor functions to be called. 754290075Sobrien 7543132718SkanOn certain kinds of systems, you can define this macro to make 754490075Sobrien@command{collect2} work faster (and, in some cases, make it work at all): 754590075Sobrien 7546132718Skan@defmac OBJECT_FORMAT_COFF 754790075SobrienDefine this macro if the system uses COFF (Common Object File Format) 754890075Sobrienobject files, so that @command{collect2} can assume this format and scan 754990075Sobrienobject files directly for dynamic constructor/destructor functions. 755090075Sobrien 7551132718SkanThis macro is effective only in a native compiler; @command{collect2} as 755290075Sobrienpart of a cross compiler always uses @command{nm} for the target machine. 7553132718Skan@end defmac 755490075Sobrien 7555132718Skan@defmac REAL_NM_FILE_NAME 755690075SobrienDefine this macro as a C string constant containing the file name to use 755790075Sobriento execute @command{nm}. The default is to search the path normally for 755890075Sobrien@command{nm}. 755990075Sobrien 756090075SobrienIf your system supports shared libraries and has a program to list the 756190075Sobriendynamic dependencies of a given library or executable, you can define 756290075Sobrienthese macros to enable support for running initialization and 756390075Sobrientermination functions in shared libraries: 7564132718Skan@end defmac 756590075Sobrien 7566132718Skan@defmac LDD_SUFFIX 756790075SobrienDefine this macro to a C string constant containing the name of the program 756890075Sobrienwhich lists dynamic dependencies, like @command{"ldd"} under SunOS 4. 7569132718Skan@end defmac 757090075Sobrien 7571132718Skan@defmac PARSE_LDD_OUTPUT (@var{ptr}) 757290075SobrienDefine this macro to be C code that extracts filenames from the output 757390075Sobrienof the program denoted by @code{LDD_SUFFIX}. @var{ptr} is a variable 757490075Sobrienof type @code{char *} that points to the beginning of a line of output 757590075Sobrienfrom @code{LDD_SUFFIX}. If the line lists a dynamic dependency, the 757690075Sobriencode must advance @var{ptr} to the beginning of the filename on that 757790075Sobrienline. Otherwise, it must set @var{ptr} to @code{NULL}. 7578132718Skan@end defmac 757990075Sobrien 758090075Sobrien@node Instruction Output 758190075Sobrien@subsection Output of Assembler Instructions 758290075Sobrien 758390075Sobrien@c prevent bad page break with this line 758490075SobrienThis describes assembler instruction output. 758590075Sobrien 7586132718Skan@defmac REGISTER_NAMES 758790075SobrienA C initializer containing the assembler's names for the machine 758890075Sobrienregisters, each one as a C string constant. This is what translates 758990075Sobrienregister numbers in the compiler into assembler language. 7590132718Skan@end defmac 759190075Sobrien 7592132718Skan@defmac ADDITIONAL_REGISTER_NAMES 759390075SobrienIf defined, a C initializer for an array of structures containing a name 759490075Sobrienand a register number. This macro defines additional names for hard 759590075Sobrienregisters, thus allowing the @code{asm} option in declarations to refer 759690075Sobriento registers using alternate names. 7597132718Skan@end defmac 759890075Sobrien 7599132718Skan@defmac ASM_OUTPUT_OPCODE (@var{stream}, @var{ptr}) 760090075SobrienDefine this macro if you are using an unusual assembler that 760190075Sobrienrequires different names for the machine instructions. 760290075Sobrien 760390075SobrienThe definition is a C statement or statements which output an 760490075Sobrienassembler instruction opcode to the stdio stream @var{stream}. The 760590075Sobrienmacro-operand @var{ptr} is a variable of type @code{char *} which 760690075Sobrienpoints to the opcode name in its ``internal'' form---the form that is 760790075Sobrienwritten in the machine description. The definition should output the 760890075Sobrienopcode name to @var{stream}, performing any translation you desire, and 760990075Sobrienincrement the variable @var{ptr} to point at the end of the opcode 761090075Sobrienso that it will not be output twice. 761190075Sobrien 761290075SobrienIn fact, your macro definition may process less than the entire opcode 761390075Sobrienname, or more than the opcode name; but if you want to process text 761490075Sobrienthat includes @samp{%}-sequences to substitute operands, you must take 761590075Sobriencare of the substitution yourself. Just be sure to increment 761690075Sobrien@var{ptr} over whatever text should not be output normally. 761790075Sobrien 761890075Sobrien@findex recog_data.operand 761990075SobrienIf you need to look at the operand values, they can be found as the 762090075Sobrienelements of @code{recog_data.operand}. 762190075Sobrien 762290075SobrienIf the macro definition does nothing, the instruction is output 762390075Sobrienin the usual way. 7624132718Skan@end defmac 762590075Sobrien 7626132718Skan@defmac FINAL_PRESCAN_INSN (@var{insn}, @var{opvec}, @var{noperands}) 762790075SobrienIf defined, a C statement to be executed just prior to the output of 762890075Sobrienassembler code for @var{insn}, to modify the extracted operands so 762990075Sobrienthey will be output differently. 763090075Sobrien 763190075SobrienHere the argument @var{opvec} is the vector containing the operands 763290075Sobrienextracted from @var{insn}, and @var{noperands} is the number of 763390075Sobrienelements of the vector which contain meaningful data for this insn. 763490075SobrienThe contents of this vector are what will be used to convert the insn 763590075Sobrientemplate into assembler code, so you can change the assembler output 763690075Sobrienby changing the contents of the vector. 763790075Sobrien 763890075SobrienThis macro is useful when various assembler syntaxes share a single 763990075Sobrienfile of instruction patterns; by defining this macro differently, you 764090075Sobriencan cause a large class of instructions to be output differently (such 764190075Sobrienas with rearranged operands). Naturally, variations in assembler 764290075Sobriensyntax affecting individual insn patterns ought to be handled by 764390075Sobrienwriting conditional output routines in those patterns. 764490075Sobrien 764590075SobrienIf this macro is not defined, it is equivalent to a null statement. 7646132718Skan@end defmac 764790075Sobrien 7648132718Skan@defmac PRINT_OPERAND (@var{stream}, @var{x}, @var{code}) 764990075SobrienA C compound statement to output to stdio stream @var{stream} the 765090075Sobrienassembler syntax for an instruction operand @var{x}. @var{x} is an 765190075SobrienRTL expression. 765290075Sobrien 765390075Sobrien@var{code} is a value that can be used to specify one of several ways 765490075Sobrienof printing the operand. It is used when identical operands must be 765590075Sobrienprinted differently depending on the context. @var{code} comes from 765690075Sobrienthe @samp{%} specification that was used to request printing of the 765790075Sobrienoperand. If the specification was just @samp{%@var{digit}} then 765890075Sobrien@var{code} is 0; if the specification was @samp{%@var{ltr} 765990075Sobrien@var{digit}} then @var{code} is the ASCII code for @var{ltr}. 766090075Sobrien 766190075Sobrien@findex reg_names 766290075SobrienIf @var{x} is a register, this macro should print the register's name. 766390075SobrienThe names can be found in an array @code{reg_names} whose type is 766490075Sobrien@code{char *[]}. @code{reg_names} is initialized from 766590075Sobrien@code{REGISTER_NAMES}. 766690075Sobrien 766790075SobrienWhen the machine description has a specification @samp{%@var{punct}} 766890075Sobrien(a @samp{%} followed by a punctuation character), this macro is called 766990075Sobrienwith a null pointer for @var{x} and the punctuation character for 767090075Sobrien@var{code}. 7671132718Skan@end defmac 767290075Sobrien 7673132718Skan@defmac PRINT_OPERAND_PUNCT_VALID_P (@var{code}) 767490075SobrienA C expression which evaluates to true if @var{code} is a valid 767590075Sobrienpunctuation character for use in the @code{PRINT_OPERAND} macro. If 767690075Sobrien@code{PRINT_OPERAND_PUNCT_VALID_P} is not defined, it means that no 767790075Sobrienpunctuation characters (except for the standard one, @samp{%}) are used 767890075Sobrienin this way. 7679132718Skan@end defmac 768090075Sobrien 7681132718Skan@defmac PRINT_OPERAND_ADDRESS (@var{stream}, @var{x}) 768290075SobrienA C compound statement to output to stdio stream @var{stream} the 768390075Sobrienassembler syntax for an instruction operand that is a memory reference 768490075Sobrienwhose address is @var{x}. @var{x} is an RTL expression. 768590075Sobrien 7686117395Skan@cindex @code{TARGET_ENCODE_SECTION_INFO} usage 768790075SobrienOn some machines, the syntax for a symbolic address depends on the 7688117395Skansection that the address refers to. On these machines, define the hook 7689117395Skan@code{TARGET_ENCODE_SECTION_INFO} to store the information into the 7690132718Skan@code{symbol_ref}, and then check for it here. @xref{Assembler 7691132718SkanFormat}. 7692132718Skan@end defmac 769390075Sobrien 769490075Sobrien@findex dbr_sequence_length 7695132718Skan@defmac DBR_OUTPUT_SEQEND (@var{file}) 769690075SobrienA C statement, to be executed after all slot-filler instructions have 769790075Sobrienbeen output. If necessary, call @code{dbr_sequence_length} to 769890075Sobriendetermine the number of slots filled in a sequence (zero if not 769990075Sobriencurrently outputting a sequence), to decide how many no-ops to output, 770090075Sobrienor whatever. 770190075Sobrien 770290075SobrienDon't define this macro if it has nothing to do, but it is helpful in 770390075Sobrienreading assembly output if the extent of the delay sequence is made 770490075Sobrienexplicit (e.g.@: with white space). 7705132718Skan@end defmac 770690075Sobrien 770790075Sobrien@findex final_sequence 770890075SobrienNote that output routines for instructions with delay slots must be 770990075Sobrienprepared to deal with not being output as part of a sequence 771090075Sobrien(i.e.@: when the scheduling pass is not run, or when no slot fillers could be 771190075Sobrienfound.) The variable @code{final_sequence} is null when not 771290075Sobrienprocessing a sequence, otherwise it contains the @code{sequence} rtx 771390075Sobrienbeing output. 771490075Sobrien 771590075Sobrien@findex asm_fprintf 7716132718Skan@defmac REGISTER_PREFIX 7717132718Skan@defmacx LOCAL_LABEL_PREFIX 7718132718Skan@defmacx USER_LABEL_PREFIX 7719132718Skan@defmacx IMMEDIATE_PREFIX 772090075SobrienIf defined, C string expressions to be used for the @samp{%R}, @samp{%L}, 772190075Sobrien@samp{%U}, and @samp{%I} options of @code{asm_fprintf} (see 772290075Sobrien@file{final.c}). These are useful when a single @file{md} file must 772390075Sobriensupport multiple assembler formats. In that case, the various @file{tm.h} 772490075Sobrienfiles can define these macros differently. 7725132718Skan@end defmac 772690075Sobrien 7727132718Skan@defmac ASM_FPRINTF_EXTENSIONS (@var{file}, @var{argptr}, @var{format}) 772890075SobrienIf defined this macro should expand to a series of @code{case} 772990075Sobrienstatements which will be parsed inside the @code{switch} statement of 773090075Sobrienthe @code{asm_fprintf} function. This allows targets to define extra 773190075Sobrienprintf formats which may useful when generating their assembler 7732132718Skanstatements. Note that uppercase letters are reserved for future 773390075Sobriengeneric extensions to asm_fprintf, and so are not available to target 773490075Sobrienspecific code. The output file is given by the parameter @var{file}. 773590075SobrienThe varargs input pointer is @var{argptr} and the rest of the format 773690075Sobrienstring, starting the character after the one that is being switched 773790075Sobrienupon, is pointed to by @var{format}. 7738132718Skan@end defmac 773990075Sobrien 7740132718Skan@defmac ASSEMBLER_DIALECT 774190075SobrienIf your target supports multiple dialects of assembler language (such as 774290075Sobriendifferent opcodes), define this macro as a C expression that gives the 774390075Sobriennumeric index of the assembler language dialect to use, with zero as the 774490075Sobrienfirst variant. 774590075Sobrien 774690075SobrienIf this macro is defined, you may use constructs of the form 774790075Sobrien@smallexample 774896263Sobrien@samp{@{option0|option1|option2@dots{}@}} 774990075Sobrien@end smallexample 775090075Sobrien@noindent 775190075Sobrienin the output templates of patterns (@pxref{Output Template}) or in the 775290075Sobrienfirst argument of @code{asm_fprintf}. This construct outputs 775390075Sobrien@samp{option0}, @samp{option1}, @samp{option2}, etc., if the value of 775490075Sobrien@code{ASSEMBLER_DIALECT} is zero, one, two, etc. Any special characters 775590075Sobrienwithin these strings retain their usual meaning. If there are fewer 775690075Sobrienalternatives within the braces than the value of 775790075Sobrien@code{ASSEMBLER_DIALECT}, the construct outputs nothing. 775890075Sobrien 775990075SobrienIf you do not define this macro, the characters @samp{@{}, @samp{|} and 776090075Sobrien@samp{@}} do not have any special meaning when used in templates or 776190075Sobrienoperands to @code{asm_fprintf}. 776290075Sobrien 776390075SobrienDefine the macros @code{REGISTER_PREFIX}, @code{LOCAL_LABEL_PREFIX}, 776490075Sobrien@code{USER_LABEL_PREFIX} and @code{IMMEDIATE_PREFIX} if you can express 776590075Sobrienthe variations in assembler language syntax with that mechanism. Define 776690075Sobrien@code{ASSEMBLER_DIALECT} and use the @samp{@{option0|option1@}} syntax 776790075Sobrienif the syntax variant are larger and involve such things as different 776890075Sobrienopcodes or operand order. 7769132718Skan@end defmac 777090075Sobrien 7771132718Skan@defmac ASM_OUTPUT_REG_PUSH (@var{stream}, @var{regno}) 777290075SobrienA C expression to output to @var{stream} some assembler code 777390075Sobrienwhich will push hard register number @var{regno} onto the stack. 777490075SobrienThe code need not be optimal, since this macro is used only when 777590075Sobrienprofiling. 7776132718Skan@end defmac 777790075Sobrien 7778132718Skan@defmac ASM_OUTPUT_REG_POP (@var{stream}, @var{regno}) 777990075SobrienA C expression to output to @var{stream} some assembler code 778090075Sobrienwhich will pop hard register number @var{regno} off of the stack. 778190075SobrienThe code need not be optimal, since this macro is used only when 778290075Sobrienprofiling. 7783132718Skan@end defmac 778490075Sobrien 778590075Sobrien@node Dispatch Tables 778690075Sobrien@subsection Output of Dispatch Tables 778790075Sobrien 778890075Sobrien@c prevent bad page break with this line 778990075SobrienThis concerns dispatch tables. 779090075Sobrien 779190075Sobrien@cindex dispatch table 7792132718Skan@defmac ASM_OUTPUT_ADDR_DIFF_ELT (@var{stream}, @var{body}, @var{value}, @var{rel}) 779390075SobrienA C statement to output to the stdio stream @var{stream} an assembler 779490075Sobrienpseudo-instruction to generate a difference between two labels. 779590075Sobrien@var{value} and @var{rel} are the numbers of two internal labels. The 779690075Sobriendefinitions of these labels are output using 7797132718Skan@code{(*targetm.asm_out.internal_label)}, and they must be printed in the same 779890075Sobrienway here. For example, 779990075Sobrien 7800132718Skan@smallexample 780190075Sobrienfprintf (@var{stream}, "\t.word L%d-L%d\n", 780290075Sobrien @var{value}, @var{rel}) 7803132718Skan@end smallexample 780490075Sobrien 780590075SobrienYou must provide this macro on machines where the addresses in a 780690075Sobriendispatch table are relative to the table's own address. If defined, GCC 780790075Sobrienwill also use this macro on all machines when producing PIC@. 780890075Sobrien@var{body} is the body of the @code{ADDR_DIFF_VEC}; it is provided so that the 780990075Sobrienmode and flags can be read. 7810132718Skan@end defmac 781190075Sobrien 7812132718Skan@defmac ASM_OUTPUT_ADDR_VEC_ELT (@var{stream}, @var{value}) 781390075SobrienThis macro should be provided on machines where the addresses 781490075Sobrienin a dispatch table are absolute. 781590075Sobrien 781690075SobrienThe definition should be a C statement to output to the stdio stream 781790075Sobrien@var{stream} an assembler pseudo-instruction to generate a reference to 781890075Sobriena label. @var{value} is the number of an internal label whose 7819132718Skandefinition is output using @code{(*targetm.asm_out.internal_label)}. 782090075SobrienFor example, 782190075Sobrien 7822132718Skan@smallexample 782390075Sobrienfprintf (@var{stream}, "\t.word L%d\n", @var{value}) 7824132718Skan@end smallexample 7825132718Skan@end defmac 782690075Sobrien 7827132718Skan@defmac ASM_OUTPUT_CASE_LABEL (@var{stream}, @var{prefix}, @var{num}, @var{table}) 782890075SobrienDefine this if the label before a jump-table needs to be output 782990075Sobrienspecially. The first three arguments are the same as for 7830132718Skan@code{(*targetm.asm_out.internal_label)}; the fourth argument is the 783190075Sobrienjump-table which follows (a @code{jump_insn} containing an 783290075Sobrien@code{addr_vec} or @code{addr_diff_vec}). 783390075Sobrien 783490075SobrienThis feature is used on system V to output a @code{swbeg} statement 783590075Sobrienfor the table. 783690075Sobrien 783790075SobrienIf this macro is not defined, these labels are output with 7838132718Skan@code{(*targetm.asm_out.internal_label)}. 7839132718Skan@end defmac 784090075Sobrien 7841132718Skan@defmac ASM_OUTPUT_CASE_END (@var{stream}, @var{num}, @var{table}) 784290075SobrienDefine this if something special must be output at the end of a 784390075Sobrienjump-table. The definition should be a C statement to be executed 784490075Sobrienafter the assembler code for the table is written. It should write 784590075Sobrienthe appropriate code to stdio stream @var{stream}. The argument 784690075Sobrien@var{table} is the jump-table insn, and @var{num} is the label-number 784790075Sobrienof the preceding label. 784890075Sobrien 784990075SobrienIf this macro is not defined, nothing special is output at the end of 785090075Sobrienthe jump-table. 7851132718Skan@end defmac 785290075Sobrien 7853169689Skan@deftypefn {Target Hook} void TARGET_ASM_EMIT_UNWIND_LABEL (@var{stream}, @var{decl}, @var{for_eh}, @var{empty}) 7854169689SkanThis target hook emits a label at the beginning of each FDE@. It 7855169689Skanshould be defined on targets where FDEs need special labels, and it 7856169689Skanshould write the appropriate label, for the FDE associated with the 7857169689Skanfunction declaration @var{decl}, to the stdio stream @var{stream}. 7858169689SkanThe third argument, @var{for_eh}, is a boolean: true if this is for an 7859169689Skanexception table. The fourth argument, @var{empty}, is a boolean: 7860169689Skantrue if this is a placeholder label for an omitted FDE@. 7861169689Skan 7862169689SkanThe default is that FDEs are not given nonlocal labels. 7863169689Skan@end deftypefn 7864169689Skan 7865169689Skan@deftypefn {Target Hook} void TARGET_ASM_EMIT_EXCEPT_TABLE_LABEL (@var{stream}) 7866169689SkanThis target hook emits a label at the beginning of the exception table. 7867169689SkanIt should be defined on targets where it is desirable for the table 7868169689Skanto be broken up according to function. 7869169689Skan 7870169689SkanThe default is that no label is emitted. 7871169689Skan@end deftypefn 7872169689Skan 7873169689Skan@deftypefn {Target Hook} void TARGET_UNWIND_EMIT (FILE * @var{stream}, rtx @var{insn}) 7874169689SkanThis target hook emits and assembly directives required to unwind the 7875169689Skangiven instruction. This is only used when TARGET_UNWIND_INFO is set. 7876169689Skan@end deftypefn 7877169689Skan 787890075Sobrien@node Exception Region Output 787990075Sobrien@subsection Assembler Commands for Exception Regions 788090075Sobrien 788190075Sobrien@c prevent bad page break with this line 788290075Sobrien 788390075SobrienThis describes commands marking the start and the end of an exception 788490075Sobrienregion. 788590075Sobrien 7886132718Skan@defmac EH_FRAME_SECTION_NAME 788790075SobrienIf defined, a C string constant for the name of the section containing 788890075Sobrienexception handling frame unwind information. If not defined, GCC will 788990075Sobrienprovide a default definition if the target supports named sections. 789090075Sobrien@file{crtstuff.c} uses this macro to switch to the appropriate section. 789190075Sobrien 789290075SobrienYou should define this symbol if your target supports DWARF 2 frame 789390075Sobrienunwind information and the default definition does not work. 7894132718Skan@end defmac 789590075Sobrien 7896132718Skan@defmac EH_FRAME_IN_DATA_SECTION 789790075SobrienIf defined, DWARF 2 frame unwind information will be placed in the 789890075Sobriendata section even though the target supports named sections. This 789990075Sobrienmight be necessary, for instance, if the system linker does garbage 790090075Sobriencollection and sections cannot be marked as not to be collected. 790190075Sobrien 790290075SobrienDo not define this macro unless @code{TARGET_ASM_NAMED_SECTION} is 790390075Sobrienalso defined. 7904132718Skan@end defmac 790590075Sobrien 7906169689Skan@defmac EH_TABLES_CAN_BE_READ_ONLY 7907169689SkanDefine this macro to 1 if your target is such that no frame unwind 7908169689Skaninformation encoding used with non-PIC code will ever require a 7909169689Skanruntime relocation, but the linker may not support merging read-only 7910169689Skanand read-write sections into a single read-write section. 7911169689Skan@end defmac 7912169689Skan 7913132718Skan@defmac MASK_RETURN_ADDR 791490075SobrienAn rtx used to mask the return address found via @code{RETURN_ADDR_RTX}, so 791590075Sobrienthat it does not contain any extraneous set bits in it. 7916132718Skan@end defmac 791790075Sobrien 7918132718Skan@defmac DWARF2_UNWIND_INFO 791990075SobrienDefine this macro to 0 if your target supports DWARF 2 frame unwind 792090075Sobrieninformation, but it does not yet work with exception handling. 792190075SobrienOtherwise, if your target supports this information (if it defines 792290075Sobrien@samp{INCOMING_RETURN_ADDR_RTX} and either @samp{UNALIGNED_INT_ASM_OP} 7923169689Skanor @samp{OBJECT_FORMAT_ELF}), GCC will provide a default definition of 1. 792490075Sobrien 7925169689SkanIf @code{TARGET_UNWIND_INFO} is defined, the target specific unwinder 7926169689Skanwill be used in all cases. Defining this macro will enable the generation 7927169689Skanof DWARF 2 frame debugging information. 7928169689Skan 7929169689SkanIf @code{TARGET_UNWIND_INFO} is not defined, and this macro is defined to 1, 7930169689Skanthe DWARF 2 unwinder will be the default exception handling mechanism; 7931169689Skanotherwise, the @code{setjmp}/@code{longjmp}-based scheme will be used by 793290075Sobriendefault. 7933169689Skan@end defmac 793490075Sobrien 7935169689Skan@defmac TARGET_UNWIND_INFO 7936169689SkanDefine this macro if your target has ABI specified unwind tables. Usually 7937169689Skanthese will be output by @code{TARGET_UNWIND_EMIT}. 7938132718Skan@end defmac 793990075Sobrien 7940169689Skan@deftypevar {Target Hook} bool TARGET_UNWIND_TABLES_DEFAULT 7941169689SkanThis variable should be set to @code{true} if the target ABI requires unwinding 7942169689Skantables even when exceptions are not used. 7943169689Skan@end deftypevar 7944169689Skan 7945132718Skan@defmac MUST_USE_SJLJ_EXCEPTIONS 7946132718SkanThis macro need only be defined if @code{DWARF2_UNWIND_INFO} is 7947132718Skanruntime-variable. In that case, @file{except.h} cannot correctly 7948169689Skandetermine the corresponding definition of @code{MUST_USE_SJLJ_EXCEPTIONS}, 7949169689Skanso the target must provide it directly. 7950132718Skan@end defmac 7951132718Skan 7952169689Skan@defmac DONT_USE_BUILTIN_SETJMP 7953169689SkanDefine this macro to 1 if the @code{setjmp}/@code{longjmp}-based scheme 7954169689Skanshould use the @code{setjmp}/@code{longjmp} functions from the C library 7955169689Skaninstead of the @code{__builtin_setjmp}/@code{__builtin_longjmp} machinery. 7956169689Skan@end defmac 7957169689Skan 7958132718Skan@defmac DWARF_CIE_DATA_ALIGNMENT 795990075SobrienThis macro need only be defined if the target might save registers in the 796090075Sobrienfunction prologue at an offset to the stack pointer that is not aligned to 796190075Sobrien@code{UNITS_PER_WORD}. The definition should be the negative minimum 796290075Sobrienalignment if @code{STACK_GROWS_DOWNWARD} is defined, and the positive 796390075Sobrienminimum alignment otherwise. @xref{SDB and DWARF}. Only applicable if 796490075Sobrienthe target supports DWARF 2 frame unwind information. 7965132718Skan@end defmac 796690075Sobrien 7967117395Skan@deftypevar {Target Hook} bool TARGET_TERMINATE_DW2_EH_FRAME_INFO 7968117395SkanContains the value true if the target should add a zero word onto the 7969117395Skanend of a Dwarf-2 frame info section when used for exception handling. 7970117395SkanDefault value is false if @code{EH_FRAME_SECTION_NAME} is defined, and 7971117395Skantrue otherwise. 7972117395Skan@end deftypevar 7973117395Skan 7974132718Skan@deftypefn {Target Hook} rtx TARGET_DWARF_REGISTER_SPAN (rtx @var{reg}) 7975132718SkanGiven a register, this hook should return a parallel of registers to 7976132718Skanrepresent where to find the register pieces. Define this hook if the 7977132718Skanregister and its mode are represented in Dwarf in non-contiguous 7978132718Skanlocations, or if the register should be represented in more than one 7979132718Skanregister in Dwarf. Otherwise, this hook should return @code{NULL_RTX}. 7980132718SkanIf not defined, the default is to return @code{NULL_RTX}. 7981132718Skan@end deftypefn 7982132718Skan 7983169689Skan@deftypefn {Target Hook} bool TARGET_ASM_TTYPE (rtx @var{sym}) 7984169689SkanThis hook is used to output a reference from a frame unwinding table to 7985169689Skanthe type_info object identified by @var{sym}. It should return @code{true} 7986169689Skanif the reference was output. Returning @code{false} will cause the 7987169689Skanreference to be output using the normal Dwarf2 routines. 7988169689Skan@end deftypefn 7989169689Skan 7990169689Skan@deftypefn {Target Hook} bool TARGET_ARM_EABI_UNWINDER 7991169689SkanThis hook should be set to @code{true} on targets that use an ARM EABI 7992169689Skanbased unwinding library, and @code{false} on other targets. This effects 7993169689Skanthe format of unwinding tables, and how the unwinder in entered after 7994169689Skanrunning a cleanup. The default is @code{false}. 7995169689Skan@end deftypefn 7996169689Skan 799790075Sobrien@node Alignment Output 799890075Sobrien@subsection Assembler Commands for Alignment 799990075Sobrien 800090075Sobrien@c prevent bad page break with this line 800190075SobrienThis describes commands for alignment. 800290075Sobrien 8003132718Skan@defmac JUMP_ALIGN (@var{label}) 800490075SobrienThe alignment (log base 2) to put in front of @var{label}, which is 800590075Sobriena common destination of jumps and has no fallthru incoming edge. 800690075Sobrien 800790075SobrienThis macro need not be defined if you don't want any special alignment 800890075Sobriento be done at such a time. Most machine descriptions do not currently 800990075Sobriendefine the macro. 801090075Sobrien 801190075SobrienUnless it's necessary to inspect the @var{label} parameter, it is better 801290075Sobriento set the variable @var{align_jumps} in the target's 801390075Sobrien@code{OVERRIDE_OPTIONS}. Otherwise, you should try to honor the user's 801490075Sobrienselection in @var{align_jumps} in a @code{JUMP_ALIGN} implementation. 8015132718Skan@end defmac 801690075Sobrien 8017132718Skan@defmac LABEL_ALIGN_AFTER_BARRIER (@var{label}) 801890075SobrienThe alignment (log base 2) to put in front of @var{label}, which follows 801990075Sobriena @code{BARRIER}. 802090075Sobrien 802190075SobrienThis macro need not be defined if you don't want any special alignment 802290075Sobriento be done at such a time. Most machine descriptions do not currently 802390075Sobriendefine the macro. 8024132718Skan@end defmac 802590075Sobrien 8026132718Skan@defmac LABEL_ALIGN_AFTER_BARRIER_MAX_SKIP 802790075SobrienThe maximum number of bytes to skip when applying 802890075Sobrien@code{LABEL_ALIGN_AFTER_BARRIER}. This works only if 802990075Sobrien@code{ASM_OUTPUT_MAX_SKIP_ALIGN} is defined. 8030132718Skan@end defmac 803190075Sobrien 8032132718Skan@defmac LOOP_ALIGN (@var{label}) 803390075SobrienThe alignment (log base 2) to put in front of @var{label}, which follows 803490075Sobriena @code{NOTE_INSN_LOOP_BEG} note. 803590075Sobrien 803690075SobrienThis macro need not be defined if you don't want any special alignment 803790075Sobriento be done at such a time. Most machine descriptions do not currently 803890075Sobriendefine the macro. 803990075Sobrien 804090075SobrienUnless it's necessary to inspect the @var{label} parameter, it is better 804190075Sobriento set the variable @code{align_loops} in the target's 804290075Sobrien@code{OVERRIDE_OPTIONS}. Otherwise, you should try to honor the user's 804390075Sobrienselection in @code{align_loops} in a @code{LOOP_ALIGN} implementation. 8044132718Skan@end defmac 804590075Sobrien 8046132718Skan@defmac LOOP_ALIGN_MAX_SKIP 804790075SobrienThe maximum number of bytes to skip when applying @code{LOOP_ALIGN}. 804890075SobrienThis works only if @code{ASM_OUTPUT_MAX_SKIP_ALIGN} is defined. 8049132718Skan@end defmac 805090075Sobrien 8051132718Skan@defmac LABEL_ALIGN (@var{label}) 805290075SobrienThe alignment (log base 2) to put in front of @var{label}. 805390075SobrienIf @code{LABEL_ALIGN_AFTER_BARRIER} / @code{LOOP_ALIGN} specify a different alignment, 805490075Sobrienthe maximum of the specified values is used. 805590075Sobrien 805690075SobrienUnless it's necessary to inspect the @var{label} parameter, it is better 805790075Sobriento set the variable @code{align_labels} in the target's 805890075Sobrien@code{OVERRIDE_OPTIONS}. Otherwise, you should try to honor the user's 805990075Sobrienselection in @code{align_labels} in a @code{LABEL_ALIGN} implementation. 8060132718Skan@end defmac 806190075Sobrien 8062132718Skan@defmac LABEL_ALIGN_MAX_SKIP 806390075SobrienThe maximum number of bytes to skip when applying @code{LABEL_ALIGN}. 806490075SobrienThis works only if @code{ASM_OUTPUT_MAX_SKIP_ALIGN} is defined. 8065132718Skan@end defmac 806690075Sobrien 8067132718Skan@defmac ASM_OUTPUT_SKIP (@var{stream}, @var{nbytes}) 806890075SobrienA C statement to output to the stdio stream @var{stream} an assembler 806990075Sobrieninstruction to advance the location counter by @var{nbytes} bytes. 807090075SobrienThose bytes should be zero when loaded. @var{nbytes} will be a C 807190075Sobrienexpression of type @code{int}. 8072132718Skan@end defmac 807390075Sobrien 8074132718Skan@defmac ASM_NO_SKIP_IN_TEXT 807590075SobrienDefine this macro if @code{ASM_OUTPUT_SKIP} should not be used in the 807690075Sobrientext section because it fails to put zeros in the bytes that are skipped. 807790075SobrienThis is true on many Unix systems, where the pseudo--op to skip bytes 807890075Sobrienproduces no-op instructions rather than zeros when used in the text 807990075Sobriensection. 8080132718Skan@end defmac 808190075Sobrien 8082132718Skan@defmac ASM_OUTPUT_ALIGN (@var{stream}, @var{power}) 808390075SobrienA C statement to output to the stdio stream @var{stream} an assembler 808490075Sobriencommand to advance the location counter to a multiple of 2 to the 808590075Sobrien@var{power} bytes. @var{power} will be a C expression of type @code{int}. 8086132718Skan@end defmac 808790075Sobrien 8088132718Skan@defmac ASM_OUTPUT_ALIGN_WITH_NOP (@var{stream}, @var{power}) 8089117395SkanLike @code{ASM_OUTPUT_ALIGN}, except that the ``nop'' instruction is used 8090117395Skanfor padding, if necessary. 8091132718Skan@end defmac 8092117395Skan 8093132718Skan@defmac ASM_OUTPUT_MAX_SKIP_ALIGN (@var{stream}, @var{power}, @var{max_skip}) 809490075SobrienA C statement to output to the stdio stream @var{stream} an assembler 809590075Sobriencommand to advance the location counter to a multiple of 2 to the 809690075Sobrien@var{power} bytes, but only if @var{max_skip} or fewer bytes are needed to 809790075Sobriensatisfy the alignment request. @var{power} and @var{max_skip} will be 809890075Sobriena C expression of type @code{int}. 8099132718Skan@end defmac 810090075Sobrien 810190075Sobrien@need 3000 810290075Sobrien@node Debugging Info 810390075Sobrien@section Controlling Debugging Information Format 810490075Sobrien 810590075Sobrien@c prevent bad page break with this line 810690075SobrienThis describes how to specify debugging information. 810790075Sobrien 810890075Sobrien@menu 810990075Sobrien* All Debuggers:: Macros that affect all debugging formats uniformly. 811090075Sobrien* DBX Options:: Macros enabling specific options in DBX format. 811190075Sobrien* DBX Hooks:: Hook macros for varying DBX format. 811290075Sobrien* File Names and DBX:: Macros controlling output of file names in DBX format. 811390075Sobrien* SDB and DWARF:: Macros for SDB (COFF) and DWARF formats. 811490075Sobrien* VMS Debug:: Macros for VMS debug format. 811590075Sobrien@end menu 811690075Sobrien 811790075Sobrien@node All Debuggers 811890075Sobrien@subsection Macros Affecting All Debugging Formats 811990075Sobrien 812090075Sobrien@c prevent bad page break with this line 812190075SobrienThese macros affect all debugging formats. 812290075Sobrien 8123132718Skan@defmac DBX_REGISTER_NUMBER (@var{regno}) 812490075SobrienA C expression that returns the DBX register number for the compiler 812590075Sobrienregister number @var{regno}. In the default macro provided, the value 812690075Sobrienof this expression will be @var{regno} itself. But sometimes there are 812790075Sobriensome registers that the compiler knows about and DBX does not, or vice 812890075Sobrienversa. In such cases, some register may need to have one number in the 812990075Sobriencompiler and another for DBX@. 813090075Sobrien 813190075SobrienIf two registers have consecutive numbers inside GCC, and they can be 813290075Sobrienused as a pair to hold a multiword value, then they @emph{must} have 813390075Sobrienconsecutive numbers after renumbering with @code{DBX_REGISTER_NUMBER}. 813490075SobrienOtherwise, debuggers will be unable to access such a pair, because they 813590075Sobrienexpect register pairs to be consecutive in their own numbering scheme. 813690075Sobrien 813790075SobrienIf you find yourself defining @code{DBX_REGISTER_NUMBER} in way that 813890075Sobriendoes not preserve register pairs, then what you must do instead is 813990075Sobrienredefine the actual register numbering scheme. 8140132718Skan@end defmac 814190075Sobrien 8142132718Skan@defmac DEBUGGER_AUTO_OFFSET (@var{x}) 814390075SobrienA C expression that returns the integer offset value for an automatic 814490075Sobrienvariable having address @var{x} (an RTL expression). The default 814590075Sobriencomputation assumes that @var{x} is based on the frame-pointer and 814690075Sobriengives the offset from the frame-pointer. This is required for targets 814790075Sobrienthat produce debugging output for DBX or COFF-style debugging output 814890075Sobrienfor SDB and allow the frame-pointer to be eliminated when the 814990075Sobrien@option{-g} options is used. 8150132718Skan@end defmac 815190075Sobrien 8152132718Skan@defmac DEBUGGER_ARG_OFFSET (@var{offset}, @var{x}) 815390075SobrienA C expression that returns the integer offset value for an argument 815490075Sobrienhaving address @var{x} (an RTL expression). The nominal offset is 815590075Sobrien@var{offset}. 8156132718Skan@end defmac 815790075Sobrien 8158132718Skan@defmac PREFERRED_DEBUGGING_TYPE 815990075SobrienA C expression that returns the type of debugging output GCC should 816090075Sobrienproduce when the user specifies just @option{-g}. Define 816190075Sobrienthis if you have arranged for GCC to support more than one format of 816290075Sobriendebugging output. Currently, the allowable values are @code{DBX_DEBUG}, 816390075Sobrien@code{SDB_DEBUG}, @code{DWARF_DEBUG}, @code{DWARF2_DEBUG}, 816490075Sobrien@code{XCOFF_DEBUG}, @code{VMS_DEBUG}, and @code{VMS_AND_DWARF2_DEBUG}. 816590075Sobrien 816690075SobrienWhen the user specifies @option{-ggdb}, GCC normally also uses the 816790075Sobrienvalue of this macro to select the debugging output format, but with two 8168132718Skanexceptions. If @code{DWARF2_DEBUGGING_INFO} is defined, GCC uses the 816990075Sobrienvalue @code{DWARF2_DEBUG}. Otherwise, if @code{DBX_DEBUGGING_INFO} is 817090075Sobriendefined, GCC uses @code{DBX_DEBUG}. 817190075Sobrien 817290075SobrienThe value of this macro only affects the default debugging output; the 817390075Sobrienuser can always get a specific type of output by using @option{-gstabs}, 8174132718Skan@option{-gcoff}, @option{-gdwarf-2}, @option{-gxcoff}, or @option{-gvms}. 8175132718Skan@end defmac 817690075Sobrien 817790075Sobrien@node DBX Options 817890075Sobrien@subsection Specific Options for DBX Output 817990075Sobrien 818090075Sobrien@c prevent bad page break with this line 818190075SobrienThese are specific options for DBX output. 818290075Sobrien 8183132718Skan@defmac DBX_DEBUGGING_INFO 818490075SobrienDefine this macro if GCC should produce debugging output for DBX 818590075Sobrienin response to the @option{-g} option. 8186132718Skan@end defmac 818790075Sobrien 8188132718Skan@defmac XCOFF_DEBUGGING_INFO 818990075SobrienDefine this macro if GCC should produce XCOFF format debugging output 819090075Sobrienin response to the @option{-g} option. This is a variant of DBX format. 8191132718Skan@end defmac 819290075Sobrien 8193132718Skan@defmac DEFAULT_GDB_EXTENSIONS 819490075SobrienDefine this macro to control whether GCC should by default generate 819590075SobrienGDB's extended version of DBX debugging information (assuming DBX-format 819690075Sobriendebugging information is enabled at all). If you don't define the 819790075Sobrienmacro, the default is 1: always generate the extended information 819890075Sobrienif there is any occasion to. 8199132718Skan@end defmac 820090075Sobrien 8201132718Skan@defmac DEBUG_SYMS_TEXT 820290075SobrienDefine this macro if all @code{.stabs} commands should be output while 820390075Sobrienin the text section. 8204132718Skan@end defmac 820590075Sobrien 8206132718Skan@defmac ASM_STABS_OP 820790075SobrienA C string constant, including spacing, naming the assembler pseudo op to 820890075Sobrienuse instead of @code{"\t.stabs\t"} to define an ordinary debugging symbol. 820990075SobrienIf you don't define this macro, @code{"\t.stabs\t"} is used. This macro 821090075Sobrienapplies only to DBX debugging information format. 8211132718Skan@end defmac 821290075Sobrien 8213132718Skan@defmac ASM_STABD_OP 821490075SobrienA C string constant, including spacing, naming the assembler pseudo op to 821590075Sobrienuse instead of @code{"\t.stabd\t"} to define a debugging symbol whose 821690075Sobrienvalue is the current location. If you don't define this macro, 821790075Sobrien@code{"\t.stabd\t"} is used. This macro applies only to DBX debugging 821890075Sobrieninformation format. 8219132718Skan@end defmac 822090075Sobrien 8221132718Skan@defmac ASM_STABN_OP 822290075SobrienA C string constant, including spacing, naming the assembler pseudo op to 822390075Sobrienuse instead of @code{"\t.stabn\t"} to define a debugging symbol with no 822490075Sobrienname. If you don't define this macro, @code{"\t.stabn\t"} is used. This 822590075Sobrienmacro applies only to DBX debugging information format. 8226132718Skan@end defmac 822790075Sobrien 8228132718Skan@defmac DBX_NO_XREFS 822990075SobrienDefine this macro if DBX on your system does not support the construct 823090075Sobrien@samp{xs@var{tagname}}. On some systems, this construct is used to 823190075Sobriendescribe a forward reference to a structure named @var{tagname}. 823290075SobrienOn other systems, this construct is not supported at all. 8233132718Skan@end defmac 823490075Sobrien 8235132718Skan@defmac DBX_CONTIN_LENGTH 823690075SobrienA symbol name in DBX-format debugging information is normally 823790075Sobriencontinued (split into two separate @code{.stabs} directives) when it 823890075Sobrienexceeds a certain length (by default, 80 characters). On some 823990075Sobrienoperating systems, DBX requires this splitting; on others, splitting 824090075Sobrienmust not be done. You can inhibit splitting by defining this macro 824190075Sobrienwith the value zero. You can override the default splitting-length by 824290075Sobriendefining this macro as an expression for the length you desire. 8243132718Skan@end defmac 824490075Sobrien 8245132718Skan@defmac DBX_CONTIN_CHAR 824690075SobrienNormally continuation is indicated by adding a @samp{\} character to 824790075Sobrienthe end of a @code{.stabs} string when a continuation follows. To use 824890075Sobriena different character instead, define this macro as a character 824990075Sobrienconstant for the character you want to use. Do not define this macro 825090075Sobrienif backslash is correct for your system. 8251132718Skan@end defmac 825290075Sobrien 8253132718Skan@defmac DBX_STATIC_STAB_DATA_SECTION 825490075SobrienDefine this macro if it is necessary to go to the data section before 825590075Sobrienoutputting the @samp{.stabs} pseudo-op for a non-global static 825690075Sobrienvariable. 8257132718Skan@end defmac 825890075Sobrien 8259132718Skan@defmac DBX_TYPE_DECL_STABS_CODE 826090075SobrienThe value to use in the ``code'' field of the @code{.stabs} directive 826190075Sobrienfor a typedef. The default is @code{N_LSYM}. 8262132718Skan@end defmac 826390075Sobrien 8264132718Skan@defmac DBX_STATIC_CONST_VAR_CODE 826590075SobrienThe value to use in the ``code'' field of the @code{.stabs} directive 826690075Sobrienfor a static variable located in the text section. DBX format does not 826790075Sobrienprovide any ``right'' way to do this. The default is @code{N_FUN}. 8268132718Skan@end defmac 826990075Sobrien 8270132718Skan@defmac DBX_REGPARM_STABS_CODE 827190075SobrienThe value to use in the ``code'' field of the @code{.stabs} directive 827290075Sobrienfor a parameter passed in registers. DBX format does not provide any 827390075Sobrien``right'' way to do this. The default is @code{N_RSYM}. 8274132718Skan@end defmac 827590075Sobrien 8276132718Skan@defmac DBX_REGPARM_STABS_LETTER 827790075SobrienThe letter to use in DBX symbol data to identify a symbol as a parameter 827890075Sobrienpassed in registers. DBX format does not customarily provide any way to 827990075Sobriendo this. The default is @code{'P'}. 8280132718Skan@end defmac 828190075Sobrien 8282132718Skan@defmac DBX_FUNCTION_FIRST 828390075SobrienDefine this macro if the DBX information for a function and its 828490075Sobrienarguments should precede the assembler code for the function. Normally, 828590075Sobrienin DBX format, the debugging information entirely follows the assembler 828690075Sobriencode. 8287132718Skan@end defmac 828890075Sobrien 8289132718Skan@defmac DBX_BLOCKS_FUNCTION_RELATIVE 8290169689SkanDefine this macro, with value 1, if the value of a symbol describing 8291169689Skanthe scope of a block (@code{N_LBRAC} or @code{N_RBRAC}) should be 8292169689Skanrelative to the start of the enclosing function. Normally, GCC uses 8293169689Skanan absolute address. 8294132718Skan@end defmac 829590075Sobrien 8296169689Skan@defmac DBX_LINES_FUNCTION_RELATIVE 8297169689SkanDefine this macro, with value 1, if the value of a symbol indicating 8298169689Skanthe current line number (@code{N_SLINE}) should be relative to the 8299169689Skanstart of the enclosing function. Normally, GCC uses an absolute address. 8300169689Skan@end defmac 8301169689Skan 8302132718Skan@defmac DBX_USE_BINCL 830390075SobrienDefine this macro if GCC should generate @code{N_BINCL} and 830490075Sobrien@code{N_EINCL} stabs for included header files, as on Sun systems. This 830590075Sobrienmacro also directs GCC to output a type number as a pair of a file 830690075Sobriennumber and a type number within the file. Normally, GCC does not 830790075Sobriengenerate @code{N_BINCL} or @code{N_EINCL} stabs, and it outputs a single 830890075Sobriennumber for a type number. 8309132718Skan@end defmac 831090075Sobrien 831190075Sobrien@node DBX Hooks 831290075Sobrien@subsection Open-Ended Hooks for DBX Format 831390075Sobrien 831490075Sobrien@c prevent bad page break with this line 831590075SobrienThese are hooks for DBX format. 831690075Sobrien 8317132718Skan@defmac DBX_OUTPUT_LBRAC (@var{stream}, @var{name}) 831890075SobrienDefine this macro to say how to output to @var{stream} the debugging 831990075Sobrieninformation for the start of a scope level for variable names. The 832090075Sobrienargument @var{name} is the name of an assembler symbol (for use with 832190075Sobrien@code{assemble_name}) whose value is the address where the scope begins. 8322132718Skan@end defmac 832390075Sobrien 8324132718Skan@defmac DBX_OUTPUT_RBRAC (@var{stream}, @var{name}) 832590075SobrienLike @code{DBX_OUTPUT_LBRAC}, but for the end of a scope level. 8326132718Skan@end defmac 832790075Sobrien 8328132718Skan@defmac DBX_OUTPUT_NFUN (@var{stream}, @var{lscope_label}, @var{decl}) 8329103445SkanDefine this macro if the target machine requires special handling to 8330103445Skanoutput an @code{N_FUN} entry for the function @var{decl}. 8331132718Skan@end defmac 8332103445Skan 8333169689Skan@defmac DBX_OUTPUT_SOURCE_LINE (@var{stream}, @var{line}, @var{counter}) 8334169689SkanA C statement to output DBX debugging information before code for line 8335169689Skannumber @var{line} of the current source file to the stdio stream 8336169689Skan@var{stream}. @var{counter} is the number of time the macro was 8337169689Skaninvoked, including the current invocation; it is intended to generate 8338169689Skanunique labels in the assembly output. 833990075Sobrien 8340169689SkanThis macro should not be defined if the default output is correct, or 8341169689Skanif it can be made correct by defining @code{DBX_LINES_FUNCTION_RELATIVE}. 8342132718Skan@end defmac 834390075Sobrien 8344132718Skan@defmac NO_DBX_FUNCTION_END 834590075SobrienSome stabs encapsulation formats (in particular ECOFF), cannot handle the 834690075Sobrien@code{.stabs "",N_FUN,,0,0,Lscope-function-1} gdb dbx extension construct. 834790075SobrienOn those machines, define this macro to turn this feature off without 834890075Sobriendisturbing the rest of the gdb extensions. 8349132718Skan@end defmac 835090075Sobrien 8351169689Skan@defmac NO_DBX_BNSYM_ENSYM 8352169689SkanSome assemblers cannot handle the @code{.stabd BNSYM/ENSYM,0,0} gdb dbx 8353169689Skanextension construct. On those machines, define this macro to turn this 8354169689Skanfeature off without disturbing the rest of the gdb extensions. 8355169689Skan@end defmac 8356169689Skan 835790075Sobrien@node File Names and DBX 835890075Sobrien@subsection File Names in DBX Format 835990075Sobrien 836090075Sobrien@c prevent bad page break with this line 836190075SobrienThis describes file names in DBX format. 836290075Sobrien 8363132718Skan@defmac DBX_OUTPUT_MAIN_SOURCE_FILENAME (@var{stream}, @var{name}) 836490075SobrienA C statement to output DBX debugging information to the stdio stream 8365169689Skan@var{stream}, which indicates that file @var{name} is the main source 836690075Sobrienfile---the file specified as the input file for compilation. 836790075SobrienThis macro is called only once, at the beginning of compilation. 836890075Sobrien 836990075SobrienThis macro need not be defined if the standard form of output 837090075Sobrienfor DBX debugging information is appropriate. 8371169689Skan 8372169689SkanIt may be necessary to refer to a label equal to the beginning of the 8373169689Skantext section. You can use @samp{assemble_name (stream, ltext_label_name)} 8374169689Skanto do so. If you do this, you must also set the variable 8375169689Skan@var{used_ltext_label_name} to @code{true}. 8376132718Skan@end defmac 837790075Sobrien 8378169689Skan@defmac NO_DBX_MAIN_SOURCE_DIRECTORY 8379169689SkanDefine this macro, with value 1, if GCC should not emit an indication 8380169689Skanof the current directory for compilation and current source language at 8381169689Skanthe beginning of the file. 8382169689Skan@end defmac 838390075Sobrien 8384169689Skan@defmac NO_DBX_GCC_MARKER 8385169689SkanDefine this macro, with value 1, if GCC should not emit an indication 8386169689Skanthat this object file was compiled by GCC@. The default is to emit 8387169689Skanan @code{N_OPT} stab at the beginning of every source file, with 8388169689Skan@samp{gcc2_compiled.} for the string and value 0. 8389132718Skan@end defmac 839090075Sobrien 8391132718Skan@defmac DBX_OUTPUT_MAIN_SOURCE_FILE_END (@var{stream}, @var{name}) 839290075SobrienA C statement to output DBX debugging information at the end of 8393169689Skancompilation of the main source file @var{name}. Output should be 8394169689Skanwritten to the stdio stream @var{stream}. 839590075Sobrien 839690075SobrienIf you don't define this macro, nothing special is output at the end 839790075Sobrienof compilation, which is correct for most machines. 8398132718Skan@end defmac 839990075Sobrien 8400169689Skan@defmac DBX_OUTPUT_NULL_N_SO_AT_MAIN_SOURCE_FILE_END 8401169689SkanDefine this macro @emph{instead of} defining 8402169689Skan@code{DBX_OUTPUT_MAIN_SOURCE_FILE_END}, if what needs to be output at 8403169689Skanthe end of compilation is a @code{N_SO} stab with an empty string, 8404169689Skanwhose value is the highest absolute text address in the file. 8405169689Skan@end defmac 8406169689Skan 840790075Sobrien@need 2000 840890075Sobrien@node SDB and DWARF 840990075Sobrien@subsection Macros for SDB and DWARF Output 841090075Sobrien 841190075Sobrien@c prevent bad page break with this line 841290075SobrienHere are macros for SDB and DWARF output. 841390075Sobrien 8414132718Skan@defmac SDB_DEBUGGING_INFO 841590075SobrienDefine this macro if GCC should produce COFF-style debugging output 841690075Sobrienfor SDB in response to the @option{-g} option. 8417132718Skan@end defmac 841890075Sobrien 8419132718Skan@defmac DWARF2_DEBUGGING_INFO 842090075SobrienDefine this macro if GCC should produce dwarf version 2 format 842190075Sobriendebugging output in response to the @option{-g} option. 842290075Sobrien 8423169689Skan@deftypefn {Target Hook} int TARGET_DWARF_CALLING_CONVENTION (tree @var{function}) 8424169689SkanDefine this to enable the dwarf attribute @code{DW_AT_calling_convention} to 8425169689Skanbe emitted for each function. Instead of an integer return the enum 8426169689Skanvalue for the @code{DW_CC_} tag. 8427169689Skan@end deftypefn 8428169689Skan 842990075SobrienTo support optional call frame debugging information, you must also 843090075Sobriendefine @code{INCOMING_RETURN_ADDR_RTX} and either set 843190075Sobrien@code{RTX_FRAME_RELATED_P} on the prologue insns if you use RTL for the 843290075Sobrienprologue, or call @code{dwarf2out_def_cfa} and @code{dwarf2out_reg_save} 843390075Sobrienas appropriate from @code{TARGET_ASM_FUNCTION_PROLOGUE} if you don't. 8434132718Skan@end defmac 843590075Sobrien 8436132718Skan@defmac DWARF2_FRAME_INFO 843790075SobrienDefine this macro to a nonzero value if GCC should always output 843890075SobrienDwarf 2 frame information. If @code{DWARF2_UNWIND_INFO} 843990075Sobrien(@pxref{Exception Region Output} is nonzero, GCC will output this 844090075Sobrieninformation not matter how you define @code{DWARF2_FRAME_INFO}. 8441132718Skan@end defmac 844290075Sobrien 8443132718Skan@defmac DWARF2_ASM_LINE_DEBUG_INFO 844490075SobrienDefine this macro to be a nonzero value if the assembler can generate Dwarf 2 844590075Sobrienline debug info sections. This will result in much more compact line number 844690075Sobrientables, and hence is desirable if it works. 8447132718Skan@end defmac 844890075Sobrien 8449132718Skan@defmac ASM_OUTPUT_DWARF_DELTA (@var{stream}, @var{size}, @var{label1}, @var{label2}) 8450117395SkanA C statement to issue assembly directives that create a difference 8451169689Skan@var{lab1} minus @var{lab2}, using an integer of the given @var{size}. 8452132718Skan@end defmac 8453117395Skan 8454169689Skan@defmac ASM_OUTPUT_DWARF_OFFSET (@var{stream}, @var{size}, @var{label}, @var{section}) 8455117395SkanA C statement to issue assembly directives that create a 8456169689Skansection-relative reference to the given @var{label}, using an integer of the 8457169689Skangiven @var{size}. The label is known to be defined in the given @var{section}. 8458132718Skan@end defmac 8459117395Skan 8460132718Skan@defmac ASM_OUTPUT_DWARF_PCREL (@var{stream}, @var{size}, @var{label}) 8461117395SkanA C statement to issue assembly directives that create a self-relative 8462169689Skanreference to the given @var{label}, using an integer of the given @var{size}. 8463132718Skan@end defmac 8464117395Skan 8465169689Skan@deftypefn {Target Hook} void TARGET_ASM_OUTPUT_DWARF_DTPREL (FILE *@var{FILE}, int @var{size}, rtx @var{x}) 8466169689SkanIf defined, this target hook is a function which outputs a DTP-relative 8467169689Skanreference to the given TLS symbol of the specified size. 8468169689Skan@end deftypefn 8469169689Skan 8470132718Skan@defmac PUT_SDB_@dots{} 847190075SobrienDefine these macros to override the assembler syntax for the special 847290075SobrienSDB assembler directives. See @file{sdbout.c} for a list of these 847390075Sobrienmacros and their arguments. If the standard syntax is used, you need 847490075Sobriennot define them yourself. 8475132718Skan@end defmac 847690075Sobrien 8477132718Skan@defmac SDB_DELIM 847890075SobrienSome assemblers do not support a semicolon as a delimiter, even between 847990075SobrienSDB assembler directives. In that case, define this macro to be the 848090075Sobriendelimiter to use (usually @samp{\n}). It is not necessary to define 848190075Sobriena new set of @code{PUT_SDB_@var{op}} macros if this is the only change 848290075Sobrienrequired. 8483132718Skan@end defmac 848490075Sobrien 8485132718Skan@defmac SDB_ALLOW_UNKNOWN_REFERENCES 848690075SobrienDefine this macro to allow references to unknown structure, 848790075Sobrienunion, or enumeration tags to be emitted. Standard COFF does not 848890075Sobrienallow handling of unknown references, MIPS ECOFF has support for 848990075Sobrienit. 8490132718Skan@end defmac 849190075Sobrien 8492132718Skan@defmac SDB_ALLOW_FORWARD_REFERENCES 849390075SobrienDefine this macro to allow references to structure, union, or 849490075Sobrienenumeration tags that have not yet been seen to be handled. Some 849590075Sobrienassemblers choke if forward tags are used, while some require it. 8496132718Skan@end defmac 849790075Sobrien 8498169689Skan@defmac SDB_OUTPUT_SOURCE_LINE (@var{stream}, @var{line}) 8499169689SkanA C statement to output SDB debugging information before code for line 8500169689Skannumber @var{line} of the current source file to the stdio stream 8501169689Skan@var{stream}. The default is to emit an @code{.ln} directive. 8502169689Skan@end defmac 8503169689Skan 850490075Sobrien@need 2000 850590075Sobrien@node VMS Debug 850690075Sobrien@subsection Macros for VMS Debug Format 850790075Sobrien 850890075Sobrien@c prevent bad page break with this line 850990075SobrienHere are macros for VMS debug format. 851090075Sobrien 8511132718Skan@defmac VMS_DEBUGGING_INFO 851290075SobrienDefine this macro if GCC should produce debugging output for VMS 851390075Sobrienin response to the @option{-g} option. The default behavior for VMS 851490075Sobrienis to generate minimal debug info for a traceback in the absence of 851590075Sobrien@option{-g} unless explicitly overridden with @option{-g0}. This 851690075Sobrienbehavior is controlled by @code{OPTIMIZATION_OPTIONS} and 851790075Sobrien@code{OVERRIDE_OPTIONS}. 8518132718Skan@end defmac 851990075Sobrien 8520117395Skan@node Floating Point 852190075Sobrien@section Cross Compilation and Floating Point 852290075Sobrien@cindex cross compilation and floating point 852390075Sobrien@cindex floating point and cross compilation 852490075Sobrien 8525117395SkanWhile all modern machines use twos-complement representation for integers, 852690075Sobrienthere are a variety of representations for floating point numbers. This 852790075Sobrienmeans that in a cross-compiler the representation of floating point numbers 852890075Sobrienin the compiled program may be different from that used in the machine 852990075Sobriendoing the compilation. 853090075Sobrien 853190075SobrienBecause different representation systems may offer different amounts of 8532117395Skanrange and precision, all floating point constants must be represented in 8533117395Skanthe target machine's format. Therefore, the cross compiler cannot 8534117395Skansafely use the host machine's floating point arithmetic; it must emulate 8535117395Skanthe target's arithmetic. To ensure consistency, GCC always uses 8536117395Skanemulation to work with floating point values, even when the host and 8537117395Skantarget floating point formats are identical. 853890075Sobrien 8539117395SkanThe following macros are provided by @file{real.h} for the compiler to 8540117395Skanuse. All parts of the compiler which generate or optimize 8541117395Skanfloating-point calculations must use these macros. They may evaluate 8542117395Skantheir operands more than once, so operands must not have side effects. 854390075Sobrien 8544117395Skan@defmac REAL_VALUE_TYPE 8545117395SkanThe C data type to be used to hold a floating point value in the target 8546117395Skanmachine's format. Typically this is a @code{struct} containing an 8547117395Skanarray of @code{HOST_WIDE_INT}, but all code should treat it as an opaque 8548117395Skanquantity. 8549117395Skan@end defmac 855090075Sobrien 8551117395Skan@deftypefn Macro int REAL_VALUES_EQUAL (REAL_VALUE_TYPE @var{x}, REAL_VALUE_TYPE @var{y}) 8552117395SkanCompares for equality the two values, @var{x} and @var{y}. If the target 8553117395Skanfloating point format supports negative zeroes and/or NaNs, 8554117395Skan@samp{REAL_VALUES_EQUAL (-0.0, 0.0)} is true, and 8555117395Skan@samp{REAL_VALUES_EQUAL (NaN, NaN)} is false. 8556117395Skan@end deftypefn 855790075Sobrien 8558117395Skan@deftypefn Macro int REAL_VALUES_LESS (REAL_VALUE_TYPE @var{x}, REAL_VALUE_TYPE @var{y}) 8559117395SkanTests whether @var{x} is less than @var{y}. 8560117395Skan@end deftypefn 856190075Sobrien 8562117395Skan@deftypefn Macro HOST_WIDE_INT REAL_VALUE_FIX (REAL_VALUE_TYPE @var{x}) 8563117395SkanTruncates @var{x} to a signed integer, rounding toward zero. 8564117395Skan@end deftypefn 856590075Sobrien 8566117395Skan@deftypefn Macro {unsigned HOST_WIDE_INT} REAL_VALUE_UNSIGNED_FIX (REAL_VALUE_TYPE @var{x}) 8567117395SkanTruncates @var{x} to an unsigned integer, rounding toward zero. If 8568117395Skan@var{x} is negative, returns zero. 8569117395Skan@end deftypefn 857090075Sobrien 8571117395Skan@deftypefn Macro REAL_VALUE_TYPE REAL_VALUE_ATOF (const char *@var{string}, enum machine_mode @var{mode}) 8572117395SkanConverts @var{string} into a floating point number in the target machine's 8573117395Skanrepresentation for mode @var{mode}. This routine can handle both 8574117395Skandecimal and hexadecimal floating point constants, using the syntax 8575117395Skandefined by the C language for both. 8576117395Skan@end deftypefn 857790075Sobrien 8578117395Skan@deftypefn Macro int REAL_VALUE_NEGATIVE (REAL_VALUE_TYPE @var{x}) 8579117395SkanReturns 1 if @var{x} is negative (including negative zero), 0 otherwise. 8580117395Skan@end deftypefn 858190075Sobrien 8582117395Skan@deftypefn Macro int REAL_VALUE_ISINF (REAL_VALUE_TYPE @var{x}) 8583117395SkanDetermines whether @var{x} represents infinity (positive or negative). 8584117395Skan@end deftypefn 858590075Sobrien 8586117395Skan@deftypefn Macro int REAL_VALUE_ISNAN (REAL_VALUE_TYPE @var{x}) 8587117395SkanDetermines whether @var{x} represents a ``NaN'' (not-a-number). 8588117395Skan@end deftypefn 858990075Sobrien 8590117395Skan@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}) 8591117395SkanCalculates an arithmetic operation on the two floating point values 8592117395Skan@var{x} and @var{y}, storing the result in @var{output} (which must be a 8593117395Skanvariable). 859490075Sobrien 8595117395SkanThe operation to be performed is specified by @var{code}. Only the 8596117395Skanfollowing codes are supported: @code{PLUS_EXPR}, @code{MINUS_EXPR}, 8597117395Skan@code{MULT_EXPR}, @code{RDIV_EXPR}, @code{MAX_EXPR}, @code{MIN_EXPR}. 859890075Sobrien 8599117395SkanIf @code{REAL_ARITHMETIC} is asked to evaluate division by zero and the 8600117395Skantarget's floating point format cannot represent infinity, it will call 8601117395Skan@code{abort}. Callers should check for this situation first, using 8602117395Skan@code{MODE_HAS_INFINITIES}. @xref{Storage Layout}. 8603117395Skan@end deftypefn 860490075Sobrien 8605117395Skan@deftypefn Macro REAL_VALUE_TYPE REAL_VALUE_NEGATE (REAL_VALUE_TYPE @var{x}) 8606117395SkanReturns the negative of the floating point value @var{x}. 8607117395Skan@end deftypefn 860890075Sobrien 8609117395Skan@deftypefn Macro REAL_VALUE_TYPE REAL_VALUE_ABS (REAL_VALUE_TYPE @var{x}) 8610117395SkanReturns the absolute value of @var{x}. 8611117395Skan@end deftypefn 861290075Sobrien 8613117395Skan@deftypefn Macro REAL_VALUE_TYPE REAL_VALUE_TRUNCATE (REAL_VALUE_TYPE @var{mode}, enum machine_mode @var{x}) 8614117395SkanTruncates the floating point value @var{x} to fit in @var{mode}. The 8615117395Skanreturn value is still a full-size @code{REAL_VALUE_TYPE}, but it has an 8616117395Skanappropriate bit pattern to be output asa floating constant whose 8617117395Skanprecision accords with mode @var{mode}. 8618117395Skan@end deftypefn 861990075Sobrien 8620117395Skan@deftypefn Macro void REAL_VALUE_TO_INT (HOST_WIDE_INT @var{low}, HOST_WIDE_INT @var{high}, REAL_VALUE_TYPE @var{x}) 8621117395SkanConverts a floating point value @var{x} into a double-precision integer 8622117395Skanwhich is then stored into @var{low} and @var{high}. If the value is not 8623117395Skanintegral, it is truncated. 8624117395Skan@end deftypefn 862590075Sobrien 8626117395Skan@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}) 8627117395SkanConverts a double-precision integer found in @var{low} and @var{high}, 8628117395Skaninto a floating point value which is then stored into @var{x}. The 8629117395Skanvalue is truncated to fit in mode @var{mode}. 8630117395Skan@end deftypefn 863190075Sobrien 863290075Sobrien@node Mode Switching 863390075Sobrien@section Mode Switching Instructions 863490075Sobrien@cindex mode switching 863590075SobrienThe following macros control mode switching optimizations: 863690075Sobrien 8637132718Skan@defmac OPTIMIZE_MODE_SWITCHING (@var{entity}) 863890075SobrienDefine this macro if the port needs extra instructions inserted for mode 863990075Sobrienswitching in an optimizing compilation. 864090075Sobrien 864190075SobrienFor an example, the SH4 can perform both single and double precision 864290075Sobrienfloating point operations, but to perform a single precision operation, 864390075Sobrienthe FPSCR PR bit has to be cleared, while for a double precision 864490075Sobrienoperation, this bit has to be set. Changing the PR bit requires a general 864590075Sobrienpurpose register as a scratch register, hence these FPSCR sets have to 864690075Sobrienbe inserted before reload, i.e.@: you can't put this into instruction emitting 8647132718Skanor @code{TARGET_MACHINE_DEPENDENT_REORG}. 864890075Sobrien 864990075SobrienYou can have multiple entities that are mode-switched, and select at run time 865090075Sobrienwhich entities actually need it. @code{OPTIMIZE_MODE_SWITCHING} should 865190075Sobrienreturn nonzero for any @var{entity} that needs mode-switching. 865290075SobrienIf you define this macro, you also have to define 865390075Sobrien@code{NUM_MODES_FOR_MODE_SWITCHING}, @code{MODE_NEEDED}, 865490075Sobrien@code{MODE_PRIORITY_TO_MODE} and @code{EMIT_MODE_SET}. 8655132718Skan@code{MODE_AFTER}, @code{MODE_ENTRY}, and @code{MODE_EXIT} 8656132718Skanare optional. 8657132718Skan@end defmac 865890075Sobrien 8659132718Skan@defmac NUM_MODES_FOR_MODE_SWITCHING 866090075SobrienIf you define @code{OPTIMIZE_MODE_SWITCHING}, you have to define this as 866190075Sobrieninitializer for an array of integers. Each initializer element 866290075SobrienN refers to an entity that needs mode switching, and specifies the number 866390075Sobrienof different modes that might need to be set for this entity. 8664169689SkanThe position of the initializer in the initializer---starting counting at 8665169689Skanzero---determines the integer that is used to refer to the mode-switched 866690075Sobrienentity in question. 866790075SobrienIn macros that take mode arguments / yield a mode result, modes are 866890075Sobrienrepresented as numbers 0 @dots{} N @minus{} 1. N is used to specify that no mode 866990075Sobrienswitch is needed / supplied. 8670132718Skan@end defmac 867190075Sobrien 8672132718Skan@defmac MODE_NEEDED (@var{entity}, @var{insn}) 867390075Sobrien@var{entity} is an integer specifying a mode-switched entity. If 867490075Sobrien@code{OPTIMIZE_MODE_SWITCHING} is defined, you must define this macro to 867590075Sobrienreturn an integer value not larger than the corresponding element in 867690075Sobrien@code{NUM_MODES_FOR_MODE_SWITCHING}, to denote the mode that @var{entity} must 867790075Sobrienbe switched into prior to the execution of @var{insn}. 8678132718Skan@end defmac 867990075Sobrien 8680132718Skan@defmac MODE_AFTER (@var{mode}, @var{insn}) 8681132718SkanIf this macro is defined, it is evaluated for every @var{insn} during 8682169689Skanmode switching. It determines the mode that an insn results in (if 8683132718Skandifferent from the incoming mode). 8684132718Skan@end defmac 8685132718Skan 8686132718Skan@defmac MODE_ENTRY (@var{entity}) 868790075SobrienIf this macro is defined, it is evaluated for every @var{entity} that needs 8688169689Skanmode switching. It should evaluate to an integer, which is a mode that 8689169689Skan@var{entity} is assumed to be switched to at function entry. If @code{MODE_ENTRY} 8690132718Skanis defined then @code{MODE_EXIT} must be defined. 8691132718Skan@end defmac 869290075Sobrien 8693132718Skan@defmac MODE_EXIT (@var{entity}) 8694132718SkanIf this macro is defined, it is evaluated for every @var{entity} that needs 8695169689Skanmode switching. It should evaluate to an integer, which is a mode that 8696169689Skan@var{entity} is assumed to be switched to at function exit. If @code{MODE_EXIT} 8697132718Skanis defined then @code{MODE_ENTRY} must be defined. 8698132718Skan@end defmac 8699132718Skan 8700132718Skan@defmac MODE_PRIORITY_TO_MODE (@var{entity}, @var{n}) 870190075SobrienThis macro specifies the order in which modes for @var{entity} are processed. 870290075Sobrien0 is the highest priority, @code{NUM_MODES_FOR_MODE_SWITCHING[@var{entity}] - 1} the 870390075Sobrienlowest. The value of the macro should be an integer designating a mode 870490075Sobrienfor @var{entity}. For any fixed @var{entity}, @code{mode_priority_to_mode} 870590075Sobrien(@var{entity}, @var{n}) shall be a bijection in 0 @dots{} 870690075Sobrien@code{num_modes_for_mode_switching[@var{entity}] - 1}. 8707132718Skan@end defmac 870890075Sobrien 8709132718Skan@defmac EMIT_MODE_SET (@var{entity}, @var{mode}, @var{hard_regs_live}) 871090075SobrienGenerate one or more insns to set @var{entity} to @var{mode}. 871190075Sobrien@var{hard_reg_live} is the set of hard registers live at the point where 871290075Sobrienthe insn(s) are to be inserted. 8713132718Skan@end defmac 871490075Sobrien 871590075Sobrien@node Target Attributes 871690075Sobrien@section Defining target-specific uses of @code{__attribute__} 871790075Sobrien@cindex target attributes 871890075Sobrien@cindex machine attributes 871990075Sobrien@cindex attributes, target-specific 872090075Sobrien 872190075SobrienTarget-specific attributes may be defined for functions, data and types. 872290075SobrienThese are described using the following target hooks; they also need to 872390075Sobrienbe documented in @file{extend.texi}. 872490075Sobrien 872590075Sobrien@deftypevr {Target Hook} {const struct attribute_spec *} TARGET_ATTRIBUTE_TABLE 872690075SobrienIf defined, this target hook points to an array of @samp{struct 872790075Sobrienattribute_spec} (defined in @file{tree.h}) specifying the machine 872890075Sobrienspecific attributes for this target and some of the restrictions on the 872990075Sobrienentities to which these attributes are applied and the arguments they 873090075Sobrientake. 873190075Sobrien@end deftypevr 873290075Sobrien 873390075Sobrien@deftypefn {Target Hook} int TARGET_COMP_TYPE_ATTRIBUTES (tree @var{type1}, tree @var{type2}) 873490075SobrienIf defined, this target hook is a function which returns zero if the attributes on 873590075Sobrien@var{type1} and @var{type2} are incompatible, one if they are compatible, 873690075Sobrienand two if they are nearly compatible (which causes a warning to be 873790075Sobriengenerated). If this is not defined, machine-specific attributes are 873890075Sobriensupposed always to be compatible. 873990075Sobrien@end deftypefn 874090075Sobrien 874190075Sobrien@deftypefn {Target Hook} void TARGET_SET_DEFAULT_TYPE_ATTRIBUTES (tree @var{type}) 874290075SobrienIf defined, this target hook is a function which assigns default attributes to 874390075Sobriennewly defined @var{type}. 874490075Sobrien@end deftypefn 874590075Sobrien 874690075Sobrien@deftypefn {Target Hook} tree TARGET_MERGE_TYPE_ATTRIBUTES (tree @var{type1}, tree @var{type2}) 874790075SobrienDefine this target hook if the merging of type attributes needs special 874890075Sobrienhandling. If defined, the result is a list of the combined 874990075Sobrien@code{TYPE_ATTRIBUTES} of @var{type1} and @var{type2}. It is assumed 875090075Sobrienthat @code{comptypes} has already been called and returned 1. This 875190075Sobrienfunction may call @code{merge_attributes} to handle machine-independent 875290075Sobrienmerging. 875390075Sobrien@end deftypefn 875490075Sobrien 875590075Sobrien@deftypefn {Target Hook} tree TARGET_MERGE_DECL_ATTRIBUTES (tree @var{olddecl}, tree @var{newdecl}) 875690075SobrienDefine this target hook if the merging of decl attributes needs special 875790075Sobrienhandling. If defined, the result is a list of the combined 875890075Sobrien@code{DECL_ATTRIBUTES} of @var{olddecl} and @var{newdecl}. 875990075Sobrien@var{newdecl} is a duplicate declaration of @var{olddecl}. Examples of 876090075Sobrienwhen this is needed are when one attribute overrides another, or when an 876190075Sobrienattribute is nullified by a subsequent definition. This function may 876290075Sobriencall @code{merge_attributes} to handle machine-independent merging. 876390075Sobrien 876490075Sobrien@findex TARGET_DLLIMPORT_DECL_ATTRIBUTES 8765169689SkanIf the only target-specific handling you require is @samp{dllimport} 8766169689Skanfor Microsoft Windows targets, you should define the macro 8767169689Skan@code{TARGET_DLLIMPORT_DECL_ATTRIBUTES} to @code{1}. The compiler 8768169689Skanwill then define a function called 8769169689Skan@code{merge_dllimport_decl_attributes} which can then be defined as 8770169689Skanthe expansion of @code{TARGET_MERGE_DECL_ATTRIBUTES}. You can also 8771169689Skanadd @code{handle_dll_attribute} in the attribute table for your port 8772169689Skanto perform initial processing of the @samp{dllimport} and 8773169689Skan@samp{dllexport} attributes. This is done in @file{i386/cygwin.h} and 8774169689Skan@file{i386/i386.c}, for example. 877590075Sobrien@end deftypefn 877690075Sobrien 8777169689Skan@deftypefn {Target Hook} bool TARGET_VALID_DLLIMPORT_ATTRIBUTE_P (tree @var{decl}) 8778169689Skan@var{decl} is a variable or function with @code{__attribute__((dllimport))} 8779169689Skanspecified. Use this hook if the target needs to add extra validation 8780169689Skanchecks to @code{handle_dll_attribute}. 8781169689Skan@end deftypefn 8782169689Skan 8783169689Skan@defmac TARGET_DECLSPEC 8784169689SkanDefine this macro to a nonzero value if you want to treat 8785169689Skan@code{__declspec(X)} as equivalent to @code{__attribute((X))}. By 8786169689Skandefault, this behavior is enabled only for targets that define 8787169689Skan@code{TARGET_DLLIMPORT_DECL_ATTRIBUTES}. The current implementation 8788169689Skanof @code{__declspec} is via a built-in macro, but you should not rely 8789169689Skanon this implementation detail. 8790169689Skan@end defmac 8791169689Skan 879290075Sobrien@deftypefn {Target Hook} void TARGET_INSERT_ATTRIBUTES (tree @var{node}, tree *@var{attr_ptr}) 879390075SobrienDefine this target hook if you want to be able to add attributes to a decl 879490075Sobrienwhen it is being created. This is normally useful for back ends which 879590075Sobrienwish to implement a pragma by using the attributes which correspond to 879690075Sobrienthe pragma's effect. The @var{node} argument is the decl which is being 879790075Sobriencreated. The @var{attr_ptr} argument is a pointer to the attribute list 879890075Sobrienfor this decl. The list itself should not be modified, since it may be 879990075Sobrienshared with other decls, but attributes may be chained on the head of 880090075Sobrienthe list and @code{*@var{attr_ptr}} modified to point to the new 880190075Sobrienattributes, or a copy of the list may be made if further changes are 880290075Sobrienneeded. 880390075Sobrien@end deftypefn 880490075Sobrien 880590075Sobrien@deftypefn {Target Hook} bool TARGET_FUNCTION_ATTRIBUTE_INLINABLE_P (tree @var{fndecl}) 880690075Sobrien@cindex inlining 880790075SobrienThis target hook returns @code{true} if it is ok to inline @var{fndecl} 880890075Sobrieninto the current function, despite its having target-specific 880990075Sobrienattributes, @code{false} otherwise. By default, if a function has a 881090075Sobrientarget specific attribute attached to it, it will not be inlined. 881190075Sobrien@end deftypefn 881290075Sobrien 8813117395Skan@node MIPS Coprocessors 8814117395Skan@section Defining coprocessor specifics for MIPS targets. 8815117395Skan@cindex MIPS coprocessor-definition macros 8816117395Skan 8817117395SkanThe MIPS specification allows MIPS implementations to have as many as 4 8818132718Skancoprocessors, each with as many as 32 private registers. GCC supports 8819117395Skanaccessing these registers and transferring values between the registers 8820117395Skanand memory using asm-ized variables. For example: 8821117395Skan 8822117395Skan@smallexample 8823117395Skan register unsigned int cp0count asm ("c0r1"); 8824117395Skan unsigned int d; 8825117395Skan 8826117395Skan d = cp0count + 3; 8827117395Skan@end smallexample 8828117395Skan 8829117395Skan(``c0r1'' is the default name of register 1 in coprocessor 0; alternate 8830117395Skannames may be added as described below, or the default names may be 8831117395Skanoverridden entirely in @code{SUBTARGET_CONDITIONAL_REGISTER_USAGE}.) 8832117395Skan 8833117395SkanCoprocessor registers are assumed to be epilogue-used; sets to them will 8834117395Skanbe preserved even if it does not appear that the register is used again 8835117395Skanlater in the function. 8836117395Skan 8837117395SkanAnother note: according to the MIPS spec, coprocessor 1 (if present) is 8838169689Skanthe FPU@. One accesses COP1 registers through standard mips 8839117395Skanfloating-point support; they are not included in this mechanism. 8840117395Skan 8841117395SkanThere is one macro used in defining the MIPS coprocessor interface which 8842117395Skanyou may want to override in subtargets; it is described below. 8843117395Skan 8844132718Skan@defmac ALL_COP_ADDITIONAL_REGISTER_NAMES 8845117395SkanA comma-separated list (with leading comma) of pairs describing the 8846117395Skanalternate names of coprocessor registers. The format of each entry should be 8847117395Skan@smallexample 8848117395Skan@{ @var{alternatename}, @var{register_number}@} 8849117395Skan@end smallexample 8850117395SkanDefault: empty. 8851132718Skan@end defmac 8852117395Skan 8853132718Skan@node PCH Target 8854132718Skan@section Parameters for Precompiled Header Validity Checking 8855132718Skan@cindex parameters, precompiled headers 8856117395Skan 8857169689Skan@deftypefn {Target Hook} void *TARGET_GET_PCH_VALIDITY (size_t *@var{sz}) 8858169689SkanThis hook returns the data needed by @code{TARGET_PCH_VALID_P} and sets 8859169689Skan@samp{*@var{sz}} to the size of the data in bytes. 8860132718Skan@end deftypefn 8861132718Skan 8862169689Skan@deftypefn {Target Hook} const char *TARGET_PCH_VALID_P (const void *@var{data}, size_t @var{sz}) 8863169689SkanThis hook checks whether the options used to create a PCH file are 8864169689Skancompatible with the current settings. It returns @code{NULL} 8865169689Skanif so and a suitable error message if not. Error messages will 8866169689Skanbe presented to the user and must be localized using @samp{_(@var{msg})}. 8867169689Skan 8868169689Skan@var{data} is the data that was returned by @code{TARGET_GET_PCH_VALIDITY} 8869169689Skanwhen the PCH file was created and @var{sz} is the size of that data in bytes. 8870169689SkanIt's safe to assume that the data was created by the same version of the 8871169689Skancompiler, so no format checking is needed. 8872169689Skan 8873169689SkanThe default definition of @code{default_pch_valid_p} should be 8874169689Skansuitable for most targets. 8875132718Skan@end deftypefn 8876132718Skan 8877169689Skan@deftypefn {Target Hook} const char *TARGET_CHECK_PCH_TARGET_FLAGS (int @var{pch_flags}) 8878169689SkanIf this hook is nonnull, the default implementation of 8879169689Skan@code{TARGET_PCH_VALID_P} will use it to check for compatible values 8880169689Skanof @code{target_flags}. @var{pch_flags} specifies the value that 8881169689Skan@code{target_flags} had when the PCH file was created. The return 8882169689Skanvalue is the same as for @code{TARGET_PCH_VALID_P}. 8883169689Skan@end deftypefn 8884169689Skan 8885169689Skan@node C++ ABI 8886169689Skan@section C++ ABI parameters 8887169689Skan@cindex parameters, c++ abi 8888169689Skan 8889169689Skan@deftypefn {Target Hook} tree TARGET_CXX_GUARD_TYPE (void) 8890169689SkanDefine this hook to override the integer type used for guard variables. 8891169689SkanThese are used to implement one-time construction of static objects. The 8892169689Skandefault is long_long_integer_type_node. 8893169689Skan@end deftypefn 8894169689Skan 8895169689Skan@deftypefn {Target Hook} bool TARGET_CXX_GUARD_MASK_BIT (void) 8896169689SkanThis hook determines how guard variables are used. It should return 8897169689Skan@code{false} (the default) if first byte should be used. A return value of 8898169689Skan@code{true} indicates the least significant bit should be used. 8899169689Skan@end deftypefn 8900169689Skan 8901169689Skan@deftypefn {Target Hook} tree TARGET_CXX_GET_COOKIE_SIZE (tree @var{type}) 8902169689SkanThis hook returns the size of the cookie to use when allocating an array 8903169689Skanwhose elements have the indicated @var{type}. Assumes that it is already 8904169689Skanknown that a cookie is needed. The default is 8905169689Skan@code{max(sizeof (size_t), alignof(type))}, as defined in section 2.7 of the 8906169689SkanIA64/Generic C++ ABI@. 8907169689Skan@end deftypefn 8908169689Skan 8909169689Skan@deftypefn {Target Hook} bool TARGET_CXX_COOKIE_HAS_SIZE (void) 8910169689SkanThis hook should return @code{true} if the element size should be stored in 8911169689Skanarray cookies. The default is to return @code{false}. 8912169689Skan@end deftypefn 8913169689Skan 8914169689Skan@deftypefn {Target Hook} int TARGET_CXX_IMPORT_EXPORT_CLASS (tree @var{type}, int @var{import_export}) 8915169689SkanIf defined by a backend this hook allows the decision made to export 8916169689Skanclass @var{type} to be overruled. Upon entry @var{import_export} 8917169689Skanwill contain 1 if the class is going to be exported, @minus{}1 if it is going 8918169689Skanto be imported and 0 otherwise. This function should return the 8919169689Skanmodified value and perform any other actions necessary to support the 8920169689Skanbackend's targeted operating system. 8921169689Skan@end deftypefn 8922169689Skan 8923169689Skan@deftypefn {Target Hook} bool TARGET_CXX_CDTOR_RETURNS_THIS (void) 8924169689SkanThis hook should return @code{true} if constructors and destructors return 8925169689Skanthe address of the object created/destroyed. The default is to return 8926169689Skan@code{false}. 8927169689Skan@end deftypefn 8928169689Skan 8929169689Skan@deftypefn {Target Hook} bool TARGET_CXX_KEY_METHOD_MAY_BE_INLINE (void) 8930169689SkanThis hook returns true if the key method for a class (i.e., the method 8931169689Skanwhich, if defined in the current translation unit, causes the virtual 8932169689Skantable to be emitted) may be an inline function. Under the standard 8933169689SkanItanium C++ ABI the key method may be an inline function so long as 8934169689Skanthe function is not declared inline in the class definition. Under 8935169689Skansome variants of the ABI, an inline function can never be the key 8936169689Skanmethod. The default is to return @code{true}. 8937169689Skan@end deftypefn 8938169689Skan 8939169689Skan@deftypefn {Target Hook} void TARGET_CXX_DETERMINE_CLASS_DATA_VISIBILITY (tree @var{decl}) 8940169689Skan@var{decl} is a virtual table, virtual table table, typeinfo object, 8941169689Skanor other similar implicit class data object that will be emitted with 8942169689Skanexternal linkage in this translation unit. No ELF visibility has been 8943169689Skanexplicitly specified. If the target needs to specify a visibility 8944169689Skanother than that of the containing class, use this hook to set 8945169689Skan@code{DECL_VISIBILITY} and @code{DECL_VISIBILITY_SPECIFIED}. 8946169689Skan@end deftypefn 8947169689Skan 8948169689Skan@deftypefn {Target Hook} bool TARGET_CXX_CLASS_DATA_ALWAYS_COMDAT (void) 8949169689SkanThis hook returns true (the default) if virtual tables and other 8950169689Skansimilar implicit class data objects are always COMDAT if they have 8951169689Skanexternal linkage. If this hook returns false, then class data for 8952169689Skanclasses whose virtual table will be emitted in only one translation 8953169689Skanunit will not be COMDAT. 8954169689Skan@end deftypefn 8955169689Skan 8956259947Spfg@deftypefn {Target Hook} bool TARGET_CXX_LIBRARY_RTTI_COMDAT (void) 8957259947SpfgThis hook returns true (the default) if the RTTI information for 8958259947Spfgthe basic types which is defined in the C++ runtime should always 8959259947Spfgbe COMDAT, false if it should not be COMDAT. 8960259947Spfg@end deftypefn 8961259947Spfg 8962169689Skan@deftypefn {Target Hook} bool TARGET_CXX_USE_AEABI_ATEXIT (void) 8963169689SkanThis hook returns true if @code{__aeabi_atexit} (as defined by the ARM EABI) 8964169689Skanshould be used to register static destructors when @option{-fuse-cxa-atexit} 8965169689Skanis in effect. The default is to return false to use @code{__cxa_atexit}. 8966169689Skan@end deftypefn 8967169689Skan 8968169689Skan@deftypefn {Target Hook} void TARGET_CXX_ADJUST_CLASS_AT_DEFINITION (tree @var{type}) 8969169689Skan@var{type} is a C++ class (i.e., RECORD_TYPE or UNION_TYPE) that has just been 8970169689Skandefined. Use this hook to make adjustments to the class (eg, tweak 8971169689Skanvisibility or perform any other required target modifications). 8972169689Skan@end deftypefn 8973169689Skan 897490075Sobrien@node Misc 897590075Sobrien@section Miscellaneous Parameters 897690075Sobrien@cindex parameters, miscellaneous 897790075Sobrien 897890075Sobrien@c prevent bad page break with this line 897990075SobrienHere are several miscellaneous parameters. 898090075Sobrien 8981169689Skan@defmac HAS_LONG_COND_BRANCH 8982169689SkanDefine this boolean macro to indicate whether or not your architecture 8983169689Skanhas conditional branches that can span all of memory. It is used in 8984169689Skanconjunction with an optimization that partitions hot and cold basic 8985169689Skanblocks into separate sections of the executable. If this macro is 8986169689Skanset to false, gcc will convert any conditional branches that attempt 8987169689Skanto cross between sections into unconditional branches or indirect jumps. 8988132718Skan@end defmac 898990075Sobrien 8990169689Skan@defmac HAS_LONG_UNCOND_BRANCH 8991169689SkanDefine this boolean macro to indicate whether or not your architecture 8992169689Skanhas unconditional branches that can span all of memory. It is used in 8993169689Skanconjunction with an optimization that partitions hot and cold basic 8994169689Skanblocks into separate sections of the executable. If this macro is 8995169689Skanset to false, gcc will convert any unconditional branches that attempt 8996169689Skanto cross between sections into indirect jumps. 8997132718Skan@end defmac 899890075Sobrien 8999132718Skan@defmac CASE_VECTOR_MODE 900090075SobrienAn alias for a machine mode name. This is the machine mode that 900190075Sobrienelements of a jump-table should have. 9002132718Skan@end defmac 900390075Sobrien 9004132718Skan@defmac CASE_VECTOR_SHORTEN_MODE (@var{min_offset}, @var{max_offset}, @var{body}) 900590075SobrienOptional: return the preferred mode for an @code{addr_diff_vec} 900690075Sobrienwhen the minimum and maximum offset are known. If you define this, 900790075Sobrienit enables extra code in branch shortening to deal with @code{addr_diff_vec}. 9008117395SkanTo make this work, you also have to define @code{INSN_ALIGN} and 900990075Sobrienmake the alignment for @code{addr_diff_vec} explicit. 901090075SobrienThe @var{body} argument is provided so that the offset_unsigned and scale 901190075Sobrienflags can be updated. 9012132718Skan@end defmac 901390075Sobrien 9014132718Skan@defmac CASE_VECTOR_PC_RELATIVE 901590075SobrienDefine this macro to be a C expression to indicate when jump-tables 9016132718Skanshould contain relative addresses. You need not define this macro if 9017132718Skanjump-tables never contain relative addresses, or jump-tables should 9018132718Skancontain relative addresses only when @option{-fPIC} or @option{-fPIC} 9019132718Skanis in effect. 9020132718Skan@end defmac 902190075Sobrien 9022132718Skan@defmac CASE_VALUES_THRESHOLD 902390075SobrienDefine this to be the smallest number of different values for which it 902490075Sobrienis best to use a jump-table instead of a tree of conditional branches. 902590075SobrienThe default is four for machines with a @code{casesi} instruction and 902690075Sobrienfive otherwise. This is best for most machines. 9027132718Skan@end defmac 902890075Sobrien 9029132718Skan@defmac CASE_USE_BIT_TESTS 9030132718SkanDefine this macro to be a C expression to indicate whether C switch 9031132718Skanstatements may be implemented by a sequence of bit tests. This is 9032132718Skanadvantageous on processors that can efficiently implement left shift 9033132718Skanof 1 by the number of bits held in a register, but inappropriate on 9034132718Skantargets that would require a loop. By default, this macro returns 9035132718Skan@code{true} if the target defines an @code{ashlsi3} pattern, and 9036132718Skan@code{false} otherwise. 9037132718Skan@end defmac 9038132718Skan 9039132718Skan@defmac WORD_REGISTER_OPERATIONS 904090075SobrienDefine this macro if operations between registers with integral mode 904190075Sobriensmaller than a word are always performed on the entire register. 904290075SobrienMost RISC machines have this property and most CISC machines do not. 9043132718Skan@end defmac 904490075Sobrien 9045132718Skan@defmac LOAD_EXTEND_OP (@var{mem_mode}) 904690075SobrienDefine this macro to be a C expression indicating when insns that read 9047132718Skanmemory in @var{mem_mode}, an integral mode narrower than a word, set the 9048132718Skanbits outside of @var{mem_mode} to be either the sign-extension or the 904990075Sobrienzero-extension of the data read. Return @code{SIGN_EXTEND} for values 9050132718Skanof @var{mem_mode} for which the 905190075Sobrieninsn sign-extends, @code{ZERO_EXTEND} for which it zero-extends, and 9052169689Skan@code{UNKNOWN} for other modes. 905390075Sobrien 9054132718SkanThis macro is not called with @var{mem_mode} non-integral or with a width 905590075Sobriengreater than or equal to @code{BITS_PER_WORD}, so you may return any 905690075Sobrienvalue in this case. Do not define this macro if it would always return 9057169689Skan@code{UNKNOWN}. On machines where this macro is defined, you will normally 905890075Sobriendefine it as the constant @code{SIGN_EXTEND} or @code{ZERO_EXTEND}. 905990075Sobrien 9060169689SkanYou may return a non-@code{UNKNOWN} value even if for some hard registers 9061132718Skanthe sign extension is not performed, if for the @code{REGNO_REG_CLASS} 9062132718Skanof these hard registers @code{CANNOT_CHANGE_MODE_CLASS} returns nonzero 9063132718Skanwhen the @var{from} mode is @var{mem_mode} and the @var{to} mode is any 9064132718Skanintegral mode larger than this but not larger than @code{word_mode}. 9065132718Skan 9066169689SkanYou must return @code{UNKNOWN} if for some hard registers that allow this 9067132718Skanmode, @code{CANNOT_CHANGE_MODE_CLASS} says that they cannot change to 9068132718Skan@code{word_mode}, but that they can change to another integral mode that 9069132718Skanis larger then @var{mem_mode} but still smaller than @code{word_mode}. 9070132718Skan@end defmac 9071132718Skan 9072132718Skan@defmac SHORT_IMMEDIATES_SIGN_EXTEND 907390075SobrienDefine this macro if loading short immediate values into registers sign 907490075Sobrienextends. 9075132718Skan@end defmac 907690075Sobrien 9077132718Skan@defmac FIXUNS_TRUNC_LIKE_FIX_TRUNC 907890075SobrienDefine this macro if the same instructions that convert a floating 907990075Sobrienpoint number to a signed fixed point number also convert validly to an 908090075Sobrienunsigned one. 9081132718Skan@end defmac 908290075Sobrien 9083169689Skan@deftypefn {Target Hook} int TARGET_MIN_DIVISIONS_FOR_RECIP_MUL (enum machine_mode @var{mode}) 9084169689SkanWhen @option{-ffast-math} is in effect, GCC tries to optimize 9085169689Skandivisions by the same divisor, by turning them into multiplications by 9086169689Skanthe reciprocal. This target hook specifies the minimum number of divisions 9087169689Skanthat should be there for GCC to perform the optimization for a variable 9088169689Skanof mode @var{mode}. The default implementation returns 3 if the machine 9089169689Skanhas an instruction for the division, and 2 if it does not. 9090169689Skan@end deftypefn 9091169689Skan 9092132718Skan@defmac MOVE_MAX 909390075SobrienThe maximum number of bytes that a single instruction can move quickly 909490075Sobrienbetween memory and registers or between two memory locations. 9095132718Skan@end defmac 909690075Sobrien 9097132718Skan@defmac MAX_MOVE_MAX 909890075SobrienThe maximum number of bytes that a single instruction can move quickly 909990075Sobrienbetween memory and registers or between two memory locations. If this 910090075Sobrienis undefined, the default is @code{MOVE_MAX}. Otherwise, it is the 910190075Sobrienconstant value that is the largest value that @code{MOVE_MAX} can have 910290075Sobrienat run-time. 9103132718Skan@end defmac 910490075Sobrien 9105132718Skan@defmac SHIFT_COUNT_TRUNCATED 910690075SobrienA C expression that is nonzero if on this machine the number of bits 910790075Sobrienactually used for the count of a shift operation is equal to the number 910890075Sobrienof bits needed to represent the size of the object being shifted. When 910990075Sobrienthis macro is nonzero, the compiler will assume that it is safe to omit 911090075Sobriena sign-extend, zero-extend, and certain bitwise `and' instructions that 911190075Sobrientruncates the count of a shift operation. On machines that have 911290075Sobrieninstructions that act on bit-fields at variable positions, which may 911390075Sobrieninclude `bit test' instructions, a nonzero @code{SHIFT_COUNT_TRUNCATED} 911490075Sobrienalso enables deletion of truncations of the values that serve as 911590075Sobrienarguments to bit-field instructions. 911690075Sobrien 911790075SobrienIf both types of instructions truncate the count (for shifts) and 911890075Sobrienposition (for bit-field operations), or if no variable-position bit-field 911990075Sobrieninstructions exist, you should define this macro. 912090075Sobrien 912190075SobrienHowever, on some machines, such as the 80386 and the 680x0, truncation 912290075Sobrienonly applies to shift operations and not the (real or pretended) 912390075Sobrienbit-field operations. Define @code{SHIFT_COUNT_TRUNCATED} to be zero on 912490075Sobriensuch machines. Instead, add patterns to the @file{md} file that include 912590075Sobrienthe implied truncation of the shift instructions. 912690075Sobrien 912790075SobrienYou need not define this macro if it would always have the value of zero. 9128132718Skan@end defmac 912990075Sobrien 9130169689Skan@anchor{TARGET_SHIFT_TRUNCATION_MASK} 9131169689Skan@deftypefn {Target Hook} int TARGET_SHIFT_TRUNCATION_MASK (enum machine_mode @var{mode}) 9132169689SkanThis function describes how the standard shift patterns for @var{mode} 9133169689Skandeal with shifts by negative amounts or by more than the width of the mode. 9134169689Skan@xref{shift patterns}. 9135169689Skan 9136169689SkanOn many machines, the shift patterns will apply a mask @var{m} to the 9137169689Skanshift count, meaning that a fixed-width shift of @var{x} by @var{y} is 9138169689Skanequivalent to an arbitrary-width shift of @var{x} by @var{y & m}. If 9139169689Skanthis is true for mode @var{mode}, the function should return @var{m}, 9140169689Skanotherwise it should return 0. A return value of 0 indicates that no 9141169689Skanparticular behavior is guaranteed. 9142169689Skan 9143169689SkanNote that, unlike @code{SHIFT_COUNT_TRUNCATED}, this function does 9144169689Skan@emph{not} apply to general shift rtxes; it applies only to instructions 9145169689Skanthat are generated by the named shift patterns. 9146169689Skan 9147169689SkanThe default implementation of this function returns 9148169689Skan@code{GET_MODE_BITSIZE (@var{mode}) - 1} if @code{SHIFT_COUNT_TRUNCATED} 9149169689Skanand 0 otherwise. This definition is always safe, but if 9150169689Skan@code{SHIFT_COUNT_TRUNCATED} is false, and some shift patterns 9151169689Skannevertheless truncate the shift count, you may get better code 9152169689Skanby overriding it. 9153169689Skan@end deftypefn 9154169689Skan 9155132718Skan@defmac TRULY_NOOP_TRUNCATION (@var{outprec}, @var{inprec}) 915690075SobrienA C expression which is nonzero if on this machine it is safe to 915790075Sobrien``convert'' an integer of @var{inprec} bits to one of @var{outprec} 915890075Sobrienbits (where @var{outprec} is smaller than @var{inprec}) by merely 915990075Sobrienoperating on it as if it had only @var{outprec} bits. 916090075Sobrien 916190075SobrienOn many machines, this expression can be 1. 916290075Sobrien 916390075Sobrien@c rearranged this, removed the phrase "it is reported that". this was 916490075Sobrien@c to fix an overfull hbox. --mew 10feb93 916590075SobrienWhen @code{TRULY_NOOP_TRUNCATION} returns 1 for a pair of sizes for 916690075Sobrienmodes for which @code{MODES_TIEABLE_P} is 0, suboptimal code can result. 916790075SobrienIf this is the case, making @code{TRULY_NOOP_TRUNCATION} return 0 in 916890075Sobriensuch cases may improve things. 9169132718Skan@end defmac 917090075Sobrien 9171169689Skan@deftypefn {Target Hook} int TARGET_MODE_REP_EXTENDED (enum machine_mode @var{mode}, enum machine_mode @var{rep_mode}) 9172169689SkanThe representation of an integral mode can be such that the values 9173169689Skanare always extended to a wider integral mode. Return 9174169689Skan@code{SIGN_EXTEND} if values of @var{mode} are represented in 9175169689Skansign-extended form to @var{rep_mode}. Return @code{UNKNOWN} 9176169689Skanotherwise. (Currently, none of the targets use zero-extended 9177169689Skanrepresentation this way so unlike @code{LOAD_EXTEND_OP}, 9178169689Skan@code{TARGET_MODE_REP_EXTENDED} is expected to return either 9179169689Skan@code{SIGN_EXTEND} or @code{UNKNOWN}. Also no target extends 9180169689Skan@var{mode} to @var{mode_rep} so that @var{mode_rep} is not the next 9181169689Skanwidest integral mode and currently we take advantage of this fact.) 9182169689Skan 9183169689SkanSimilarly to @code{LOAD_EXTEND_OP} you may return a non-@code{UNKNOWN} 9184169689Skanvalue even if the extension is not performed on certain hard registers 9185169689Skanas long as for the @code{REGNO_REG_CLASS} of these hard registers 9186169689Skan@code{CANNOT_CHANGE_MODE_CLASS} returns nonzero. 9187169689Skan 9188169689SkanNote that @code{TARGET_MODE_REP_EXTENDED} and @code{LOAD_EXTEND_OP} 9189169689Skandescribe two related properties. If you define 9190169689Skan@code{TARGET_MODE_REP_EXTENDED (mode, word_mode)} you probably also want 9191169689Skanto define @code{LOAD_EXTEND_OP (mode)} to return the same type of 9192169689Skanextension. 9193169689Skan 9194169689SkanIn order to enforce the representation of @code{mode}, 9195169689Skan@code{TRULY_NOOP_TRUNCATION} should return false when truncating to 9196169689Skan@code{mode}. 9197169689Skan@end deftypefn 9198169689Skan 9199132718Skan@defmac STORE_FLAG_VALUE 920090075SobrienA C expression describing the value returned by a comparison operator 920190075Sobrienwith an integral mode and stored by a store-flag instruction 920290075Sobrien(@samp{s@var{cond}}) when the condition is true. This description must 920390075Sobrienapply to @emph{all} the @samp{s@var{cond}} patterns and all the 920490075Sobriencomparison operators whose results have a @code{MODE_INT} mode. 920590075Sobrien 920690075SobrienA value of 1 or @minus{}1 means that the instruction implementing the 920790075Sobriencomparison operator returns exactly 1 or @minus{}1 when the comparison is true 920890075Sobrienand 0 when the comparison is false. Otherwise, the value indicates 920990075Sobrienwhich bits of the result are guaranteed to be 1 when the comparison is 921090075Sobrientrue. This value is interpreted in the mode of the comparison 921190075Sobrienoperation, which is given by the mode of the first operand in the 921290075Sobrien@samp{s@var{cond}} pattern. Either the low bit or the sign bit of 921390075Sobrien@code{STORE_FLAG_VALUE} be on. Presently, only those bits are used by 921490075Sobrienthe compiler. 921590075Sobrien 921690075SobrienIf @code{STORE_FLAG_VALUE} is neither 1 or @minus{}1, the compiler will 921790075Sobriengenerate code that depends only on the specified bits. It can also 921890075Sobrienreplace comparison operators with equivalent operations if they cause 921990075Sobrienthe required bits to be set, even if the remaining bits are undefined. 922090075SobrienFor example, on a machine whose comparison operators return an 922190075Sobrien@code{SImode} value and where @code{STORE_FLAG_VALUE} is defined as 922290075Sobrien@samp{0x80000000}, saying that just the sign bit is relevant, the 922390075Sobrienexpression 922490075Sobrien 922590075Sobrien@smallexample 922690075Sobrien(ne:SI (and:SI @var{x} (const_int @var{power-of-2})) (const_int 0)) 922790075Sobrien@end smallexample 922890075Sobrien 922990075Sobrien@noindent 923090075Sobriencan be converted to 923190075Sobrien 923290075Sobrien@smallexample 923390075Sobrien(ashift:SI @var{x} (const_int @var{n})) 923490075Sobrien@end smallexample 923590075Sobrien 923690075Sobrien@noindent 923790075Sobrienwhere @var{n} is the appropriate shift count to move the bit being 923890075Sobrientested into the sign bit. 923990075Sobrien 924090075SobrienThere is no way to describe a machine that always sets the low-order bit 924190075Sobrienfor a true value, but does not guarantee the value of any other bits, 924290075Sobrienbut we do not know of any machine that has such an instruction. If you 924390075Sobrienare trying to port GCC to such a machine, include an instruction to 924490075Sobrienperform a logical-and of the result with 1 in the pattern for the 924590075Sobriencomparison operators and let us know at @email{gcc@@gcc.gnu.org}. 924690075Sobrien 924790075SobrienOften, a machine will have multiple instructions that obtain a value 924890075Sobrienfrom a comparison (or the condition codes). Here are rules to guide the 924990075Sobrienchoice of value for @code{STORE_FLAG_VALUE}, and hence the instructions 925090075Sobriento be used: 925190075Sobrien 925290075Sobrien@itemize @bullet 925390075Sobrien@item 925490075SobrienUse the shortest sequence that yields a valid definition for 925590075Sobrien@code{STORE_FLAG_VALUE}. It is more efficient for the compiler to 925690075Sobrien``normalize'' the value (convert it to, e.g., 1 or 0) than for the 925790075Sobriencomparison operators to do so because there may be opportunities to 925890075Sobriencombine the normalization with other operations. 925990075Sobrien 926090075Sobrien@item 926190075SobrienFor equal-length sequences, use a value of 1 or @minus{}1, with @minus{}1 being 926290075Sobrienslightly preferred on machines with expensive jumps and 1 preferred on 926390075Sobrienother machines. 926490075Sobrien 926590075Sobrien@item 926690075SobrienAs a second choice, choose a value of @samp{0x80000001} if instructions 926790075Sobrienexist that set both the sign and low-order bits but do not define the 926890075Sobrienothers. 926990075Sobrien 927090075Sobrien@item 927190075SobrienOtherwise, use a value of @samp{0x80000000}. 927290075Sobrien@end itemize 927390075Sobrien 927490075SobrienMany machines can produce both the value chosen for 927590075Sobrien@code{STORE_FLAG_VALUE} and its negation in the same number of 927690075Sobrieninstructions. On those machines, you should also define a pattern for 927790075Sobrienthose cases, e.g., one matching 927890075Sobrien 927990075Sobrien@smallexample 928090075Sobrien(set @var{A} (neg:@var{m} (ne:@var{m} @var{B} @var{C}))) 928190075Sobrien@end smallexample 928290075Sobrien 928390075SobrienSome machines can also perform @code{and} or @code{plus} operations on 928490075Sobriencondition code values with less instructions than the corresponding 928590075Sobrien@samp{s@var{cond}} insn followed by @code{and} or @code{plus}. On those 928690075Sobrienmachines, define the appropriate patterns. Use the names @code{incscc} 928790075Sobrienand @code{decscc}, respectively, for the patterns which perform 928890075Sobrien@code{plus} or @code{minus} operations on condition code values. See 928990075Sobrien@file{rs6000.md} for some examples. The GNU Superoptizer can be used to 929090075Sobrienfind such instruction sequences on other machines. 929190075Sobrien 9292132718SkanIf this macro is not defined, the default value, 1, is used. You need 9293132718Skannot define @code{STORE_FLAG_VALUE} if the machine has no store-flag 9294132718Skaninstructions, or if the value generated by these instructions is 1. 9295132718Skan@end defmac 929690075Sobrien 9297132718Skan@defmac FLOAT_STORE_FLAG_VALUE (@var{mode}) 929890075SobrienA C expression that gives a nonzero @code{REAL_VALUE_TYPE} value that is 929990075Sobrienreturned when comparison operators with floating-point results are true. 9300169689SkanDefine this macro on machines that have comparison operations that return 930190075Sobrienfloating-point values. If there are no such operations, do not define 930290075Sobrienthis macro. 9303132718Skan@end defmac 930490075Sobrien 9305169689Skan@defmac VECTOR_STORE_FLAG_VALUE (@var{mode}) 9306169689SkanA C expression that gives a rtx representing the nonzero true element 9307169689Skanfor vector comparisons. The returned rtx should be valid for the inner 9308169689Skanmode of @var{mode} which is guaranteed to be a vector mode. Define 9309169689Skanthis macro on machines that have vector comparison operations that 9310169689Skanreturn a vector result. If there are no such operations, do not define 9311169689Skanthis macro. Typically, this macro is defined as @code{const1_rtx} or 9312169689Skan@code{constm1_rtx}. This macro may return @code{NULL_RTX} to prevent 9313169689Skanthe compiler optimizing such vector comparison operations for the 9314169689Skangiven mode. 9315169689Skan@end defmac 9316169689Skan 9317132718Skan@defmac CLZ_DEFINED_VALUE_AT_ZERO (@var{mode}, @var{value}) 9318132718Skan@defmacx CTZ_DEFINED_VALUE_AT_ZERO (@var{mode}, @var{value}) 9319132718SkanA C expression that evaluates to true if the architecture defines a value 9320132718Skanfor @code{clz} or @code{ctz} with a zero operand. If so, @var{value} 9321132718Skanshould be set to this value. If this macro is not defined, the value of 9322132718Skan@code{clz} or @code{ctz} is assumed to be undefined. 9323132718Skan 9324132718SkanThis macro must be defined if the target's expansion for @code{ffs} 9325132718Skanrelies on a particular value to get correct results. Otherwise it 9326132718Skanis not necessary, though it may be used to optimize some corner cases. 9327132718Skan 9328132718SkanNote that regardless of this macro the ``definedness'' of @code{clz} 9329132718Skanand @code{ctz} at zero do @emph{not} extend to the builtin functions 9330132718Skanvisible to the user. Thus one may be free to adjust the value at will 9331132718Skanto match the target expansion of these operations without fear of 9332169689Skanbreaking the API@. 9333132718Skan@end defmac 9334132718Skan 9335132718Skan@defmac Pmode 933690075SobrienAn alias for the machine mode for pointers. On most machines, define 933790075Sobrienthis to be the integer mode corresponding to the width of a hardware 933890075Sobrienpointer; @code{SImode} on 32-bit machine or @code{DImode} on 64-bit machines. 933990075SobrienOn some machines you must define this to be one of the partial integer 934090075Sobrienmodes, such as @code{PSImode}. 934190075Sobrien 934290075SobrienThe width of @code{Pmode} must be at least as large as the value of 934390075Sobrien@code{POINTER_SIZE}. If it is not equal, you must define the macro 934490075Sobrien@code{POINTERS_EXTEND_UNSIGNED} to specify how pointers are extended 934590075Sobriento @code{Pmode}. 9346132718Skan@end defmac 934790075Sobrien 9348132718Skan@defmac FUNCTION_MODE 934990075SobrienAn alias for the machine mode used for memory references to functions 935090075Sobrienbeing called, in @code{call} RTL expressions. On most machines this 935190075Sobrienshould be @code{QImode}. 9352132718Skan@end defmac 935390075Sobrien 9354132718Skan@defmac STDC_0_IN_SYSTEM_HEADERS 935590075SobrienIn normal operation, the preprocessor expands @code{__STDC__} to the 935690075Sobrienconstant 1, to signify that GCC conforms to ISO Standard C@. On some 935790075Sobrienhosts, like Solaris, the system compiler uses a different convention, 935890075Sobrienwhere @code{__STDC__} is normally 0, but is 1 if the user specifies 935990075Sobrienstrict conformance to the C Standard. 936090075Sobrien 936190075SobrienDefining @code{STDC_0_IN_SYSTEM_HEADERS} makes GNU CPP follows the host 936290075Sobrienconvention when processing system header files, but when processing user 936390075Sobrienfiles @code{__STDC__} will always expand to 1. 9364132718Skan@end defmac 936590075Sobrien 9366132718Skan@defmac NO_IMPLICIT_EXTERN_C 936790075SobrienDefine this macro if the system header files support C++ as well as C@. 936890075SobrienThis macro inhibits the usual method of using system header files in 936990075SobrienC++, which is to pretend that the file's contents are enclosed in 937090075Sobrien@samp{extern "C" @{@dots{}@}}. 9371132718Skan@end defmac 937290075Sobrien 937390075Sobrien@findex #pragma 937490075Sobrien@findex pragma 9375132718Skan@defmac REGISTER_TARGET_PRAGMAS () 937690075SobrienDefine this macro if you want to implement any target-specific pragmas. 937790075SobrienIf defined, it is a C expression which makes a series of calls to 9378169689Skan@code{c_register_pragma} or @code{c_register_pragma_with_expansion} 9379169689Skanfor each pragma. The macro may also do any 938090075Sobriensetup required for the pragmas. 938190075Sobrien 938290075SobrienThe primary reason to define this macro is to provide compatibility with 938390075Sobrienother compilers for the same target. In general, we discourage 938490075Sobriendefinition of target-specific pragmas for GCC@. 938590075Sobrien 938690075SobrienIf the pragma can be implemented by attributes then you should consider 938790075Sobriendefining the target hook @samp{TARGET_INSERT_ATTRIBUTES} as well. 938890075Sobrien 938990075SobrienPreprocessor macros that appear on pragma lines are not expanded. All 939090075Sobrien@samp{#pragma} directives that do not match any registered pragma are 939190075Sobriensilently ignored, unless the user specifies @option{-Wunknown-pragmas}. 9392132718Skan@end defmac 939390075Sobrien 9394132718Skan@deftypefun void c_register_pragma (const char *@var{space}, const char *@var{name}, void (*@var{callback}) (struct cpp_reader *)) 9395169689Skan@deftypefunx void c_register_pragma_with_expansion (const char *@var{space}, const char *@var{name}, void (*@var{callback}) (struct cpp_reader *)) 939690075Sobrien 9397169689SkanEach call to @code{c_register_pragma} or 9398169689Skan@code{c_register_pragma_with_expansion} establishes one pragma. The 939990075Sobrien@var{callback} routine will be called when the preprocessor encounters a 940090075Sobrienpragma of the form 940190075Sobrien 940290075Sobrien@smallexample 940390075Sobrien#pragma [@var{space}] @var{name} @dots{} 940490075Sobrien@end smallexample 940590075Sobrien 940690075Sobrien@var{space} is the case-sensitive namespace of the pragma, or 940790075Sobrien@code{NULL} to put the pragma in the global namespace. The callback 940890075Sobrienroutine receives @var{pfile} as its first argument, which can be passed 940990075Sobrienon to cpplib's functions if necessary. You can lex tokens after the 9410169689Skan@var{name} by calling @code{pragma_lex}. Tokens that are not read by the 941190075Sobriencallback will be silently ignored. The end of the line is indicated by 9412169689Skana token of type @code{CPP_EOF}. Macro expansion occurs on the 9413169689Skanarguments of pragmas registered with 9414169689Skan@code{c_register_pragma_with_expansion} but not on the arguments of 9415169689Skanpragmas registered with @code{c_register_pragma}. 941690075Sobrien 941790075SobrienFor an example use of this routine, see @file{c4x.h} and the callback 941890075Sobrienroutines defined in @file{c4x-c.c}. 941990075Sobrien 9420169689SkanNote that the use of @code{pragma_lex} is specific to the C and C++ 942190075Sobriencompilers. It will not work in the Java or Fortran compilers, or any 9422169689Skanother language compilers for that matter. Thus if @code{pragma_lex} is going 942390075Sobriento be called from target-specific code, it must only be done so when 942490075Sobrienbuilding the C and C++ compilers. This can be done by defining the 942590075Sobrienvariables @code{c_target_objs} and @code{cxx_target_objs} in the 942690075Sobrientarget entry in the @file{config.gcc} file. These variables should name 942790075Sobrienthe target-specific, language-specific object file which contains the 9428169689Skancode that uses @code{pragma_lex}. Note it will also be necessary to add a 942990075Sobrienrule to the makefile fragment pointed to by @code{tmake_file} that shows 943090075Sobrienhow to build this object file. 943190075Sobrien@end deftypefun 943290075Sobrien 943390075Sobrien@findex #pragma 943490075Sobrien@findex pragma 9435132718Skan@defmac HANDLE_SYSV_PRAGMA 943690075SobrienDefine this macro (to a value of 1) if you want the System V style 943790075Sobrienpragmas @samp{#pragma pack(<n>)} and @samp{#pragma weak <name> 943890075Sobrien[=<value>]} to be supported by gcc. 943990075Sobrien 944090075SobrienThe pack pragma specifies the maximum alignment (in bytes) of fields 944190075Sobrienwithin a structure, in much the same way as the @samp{__aligned__} and 944290075Sobrien@samp{__packed__} @code{__attribute__}s do. A pack value of zero resets 944390075Sobrienthe behavior to the default. 944490075Sobrien 9445117395SkanA subtlety for Microsoft Visual C/C++ style bit-field packing 9446169689Skan(e.g.@: -mms-bitfields) for targets that support it: 9447117395SkanWhen a bit-field is inserted into a packed record, the whole size 9448117395Skanof the underlying type is used by one or more same-size adjacent 9449117395Skanbit-fields (that is, if its long:3, 32 bits is used in the record, 9450117395Skanand any additional adjacent long bit-fields are packed into the same 9451169689Skanchunk of 32 bits. However, if the size changes, a new field of that 9452117395Skansize is allocated). 9453117395Skan 9454117395SkanIf both MS bit-fields and @samp{__attribute__((packed))} are used, 9455169689Skanthe latter will take precedence. If @samp{__attribute__((packed))} is 9456117395Skanused on a single field when MS bit-fields are in use, it will take 9457117395Skanprecedence for that field, but the alignment of the rest of the structure 9458117395Skanmay affect its placement. 9459117395Skan 946090075SobrienThe weak pragma only works if @code{SUPPORTS_WEAK} and 946190075Sobrien@code{ASM_WEAKEN_LABEL} are defined. If enabled it allows the creation 946290075Sobrienof specifically named weak labels, optionally with a value. 9463132718Skan@end defmac 946490075Sobrien 946590075Sobrien@findex #pragma 946690075Sobrien@findex pragma 9467132718Skan@defmac HANDLE_PRAGMA_PACK_PUSH_POP 946890075SobrienDefine this macro (to a value of 1) if you want to support the Win32 9469169689Skanstyle pragmas @samp{#pragma pack(push[,@var{n}])} and @samp{#pragma 9470169689Skanpack(pop)}. The @samp{pack(push,[@var{n}])} pragma specifies the maximum 9471169689Skanalignment (in bytes) of fields within a structure, in much the same way as 9472169689Skanthe @samp{__aligned__} and @samp{__packed__} @code{__attribute__}s do. A 947390075Sobrienpack value of zero resets the behavior to the default. Successive 947490075Sobrieninvocations of this pragma cause the previous values to be stacked, so 947590075Sobrienthat invocations of @samp{#pragma pack(pop)} will return to the previous 947690075Sobrienvalue. 9477132718Skan@end defmac 947890075Sobrien 9479169689Skan@defmac HANDLE_PRAGMA_PACK_WITH_EXPANSION 9480169689SkanDefine this macro, as well as 9481169689Skan@code{HANDLE_SYSV_PRAGMA}, if macros should be expanded in the 9482169689Skanarguments of @samp{#pragma pack}. 9483169689Skan@end defmac 9484169689Skan 9485169689Skan@defmac TARGET_DEFAULT_PACK_STRUCT 9486169689SkanIf your target requires a structure packing default other than 0 (meaning 9487169689Skanthe machine default), define this macro to the necessary value (in bytes). 9488169689SkanThis must be a value that would also be valid to use with 9489169689Skan@samp{#pragma pack()} (that is, a small power of two). 9490169689Skan@end defmac 9491169689Skan 9492132718Skan@defmac DOLLARS_IN_IDENTIFIERS 9493132718SkanDefine this macro to control use of the character @samp{$} in 9494132718Skanidentifier names for the C family of languages. 0 means @samp{$} is 9495132718Skannot allowed by default; 1 means it is allowed. 1 is the default; 9496132718Skanthere is no need to define this macro in that case. 9497132718Skan@end defmac 949890075Sobrien 9499132718Skan@defmac NO_DOLLAR_IN_LABEL 950090075SobrienDefine this macro if the assembler does not accept the character 950190075Sobrien@samp{$} in label names. By default constructors and destructors in 950290075SobrienG++ have @samp{$} in the identifiers. If this macro is defined, 950390075Sobrien@samp{.} is used instead. 9504132718Skan@end defmac 950590075Sobrien 9506132718Skan@defmac NO_DOT_IN_LABEL 950790075SobrienDefine this macro if the assembler does not accept the character 950890075Sobrien@samp{.} in label names. By default constructors and destructors in G++ 950990075Sobrienhave names that use @samp{.}. If this macro is defined, these names 951090075Sobrienare rewritten to avoid @samp{.}. 9511132718Skan@end defmac 951290075Sobrien 9513132718Skan@defmac INSN_SETS_ARE_DELAYED (@var{insn}) 951490075SobrienDefine this macro as a C expression that is nonzero if it is safe for the 951590075Sobriendelay slot scheduler to place instructions in the delay slot of @var{insn}, 951690075Sobrieneven if they appear to use a resource set or clobbered in @var{insn}. 951790075Sobrien@var{insn} is always a @code{jump_insn} or an @code{insn}; GCC knows that 951890075Sobrienevery @code{call_insn} has this behavior. On machines where some @code{insn} 951990075Sobrienor @code{jump_insn} is really a function call and hence has this behavior, 952090075Sobrienyou should define this macro. 952190075Sobrien 952290075SobrienYou need not define this macro if it would always return zero. 9523132718Skan@end defmac 952490075Sobrien 9525132718Skan@defmac INSN_REFERENCES_ARE_DELAYED (@var{insn}) 952690075SobrienDefine this macro as a C expression that is nonzero if it is safe for the 952790075Sobriendelay slot scheduler to place instructions in the delay slot of @var{insn}, 952890075Sobrieneven if they appear to set or clobber a resource referenced in @var{insn}. 952990075Sobrien@var{insn} is always a @code{jump_insn} or an @code{insn}. On machines where 953090075Sobriensome @code{insn} or @code{jump_insn} is really a function call and its operands 953190075Sobrienare registers whose use is actually in the subroutine it calls, you should 953290075Sobriendefine this macro. Doing so allows the delay slot scheduler to move 953390075Sobrieninstructions which copy arguments into the argument registers into the delay 953490075Sobrienslot of @var{insn}. 953590075Sobrien 953690075SobrienYou need not define this macro if it would always return zero. 9537132718Skan@end defmac 953890075Sobrien 9539132718Skan@defmac MULTIPLE_SYMBOL_SPACES 9540169689SkanDefine this macro as a C expression that is nonzero if, in some cases, 9541169689Skanglobal symbols from one translation unit may not be bound to undefined 9542169689Skansymbols in another translation unit without user intervention. For 9543169689Skaninstance, under Microsoft Windows symbols must be explicitly imported 9544169689Skanfrom shared libraries (DLLs). 954590075Sobrien 9546169689SkanYou need not define this macro if it would always evaluate to zero. 9547132718Skan@end defmac 954890075Sobrien 9549169689Skan@deftypefn {Target Hook} tree TARGET_MD_ASM_CLOBBERS (tree @var{outputs}, tree @var{inputs}, tree @var{clobbers}) 9550169689SkanThis target hook should add to @var{clobbers} @code{STRING_CST} trees for 9551169689Skanany hard regs the port wishes to automatically clobber for an asm. 9552169689SkanIt should return the result of the last @code{tree_cons} used to add a 9553169689Skanclobber. The @var{outputs}, @var{inputs} and @var{clobber} lists are the 9554169689Skancorresponding parameters to the asm and may be inspected to avoid 9555169689Skanclobbering a register that is an input or output of the asm. You can use 9556169689Skan@code{tree_overlaps_hard_reg_set}, declared in @file{tree.h}, to test 9557169689Skanfor overlap with regards to asm-declared registers. 9558169689Skan@end deftypefn 9559169689Skan 9560132718Skan@defmac MATH_LIBRARY 956190075SobrienDefine this macro as a C string constant for the linker argument to link 956290075Sobrienin the system math library, or @samp{""} if the target does not have a 956390075Sobrienseparate math library. 956490075Sobrien 956590075SobrienYou need only define this macro if the default of @samp{"-lm"} is wrong. 9566132718Skan@end defmac 956790075Sobrien 9568132718Skan@defmac LIBRARY_PATH_ENV 956990075SobrienDefine this macro as a C string constant for the environment variable that 957090075Sobrienspecifies where the linker should look for libraries. 957190075Sobrien 957290075SobrienYou need only define this macro if the default of @samp{"LIBRARY_PATH"} 957390075Sobrienis wrong. 9574132718Skan@end defmac 957590075Sobrien 9576169689Skan@defmac TARGET_POSIX_IO 9577169689SkanDefine this macro if the target supports the following POSIX@ file 9578169689Skanfunctions, access, mkdir and file locking with fcntl / F_SETLKW@. 9579169689SkanDefining @code{TARGET_POSIX_IO} will enable the test coverage code 958090075Sobriento use file locking when exiting a program, which avoids race conditions 9581169689Skanif the program has forked. It will also create directories at run-time 9582169689Skanfor cross-profiling. 9583132718Skan@end defmac 958490075Sobrien 9585132718Skan@defmac MAX_CONDITIONAL_EXECUTE 958690075Sobrien 958790075SobrienA C expression for the maximum number of instructions to execute via 958890075Sobrienconditional execution instructions instead of a branch. A value of 958990075Sobrien@code{BRANCH_COST}+1 is the default if the machine does not use cc0, and 959090075Sobrien1 if it does use cc0. 9591132718Skan@end defmac 959290075Sobrien 9593132718Skan@defmac IFCVT_MODIFY_TESTS (@var{ce_info}, @var{true_expr}, @var{false_expr}) 9594117395SkanUsed if the target needs to perform machine-dependent modifications on the 9595117395Skanconditionals used for turning basic blocks into conditionally executed code. 9596117395Skan@var{ce_info} points to a data structure, @code{struct ce_if_block}, which 9597117395Skancontains information about the currently processed blocks. @var{true_expr} 9598117395Skanand @var{false_expr} are the tests that are used for converting the 9599117395Skanthen-block and the else-block, respectively. Set either @var{true_expr} or 9600117395Skan@var{false_expr} to a null pointer if the tests cannot be converted. 9601132718Skan@end defmac 960290075Sobrien 9603132718Skan@defmac IFCVT_MODIFY_MULTIPLE_TESTS (@var{ce_info}, @var{bb}, @var{true_expr}, @var{false_expr}) 9604117395SkanLike @code{IFCVT_MODIFY_TESTS}, but used when converting more complicated 9605117395Skanif-statements into conditions combined by @code{and} and @code{or} operations. 9606117395Skan@var{bb} contains the basic block that contains the test that is currently 9607117395Skanbeing processed and about to be turned into a condition. 9608132718Skan@end defmac 9609117395Skan 9610132718Skan@defmac IFCVT_MODIFY_INSN (@var{ce_info}, @var{pattern}, @var{insn}) 9611117395SkanA C expression to modify the @var{PATTERN} of an @var{INSN} that is to 9612117395Skanbe converted to conditional execution format. @var{ce_info} points to 9613117395Skana data structure, @code{struct ce_if_block}, which contains information 9614117395Skanabout the currently processed blocks. 9615132718Skan@end defmac 961690075Sobrien 9617132718Skan@defmac IFCVT_MODIFY_FINAL (@var{ce_info}) 961890075SobrienA C expression to perform any final machine dependent modifications in 9619117395Skanconverting code to conditional execution. The involved basic blocks 9620117395Skancan be found in the @code{struct ce_if_block} structure that is pointed 9621117395Skanto by @var{ce_info}. 9622132718Skan@end defmac 962390075Sobrien 9624132718Skan@defmac IFCVT_MODIFY_CANCEL (@var{ce_info}) 962590075SobrienA C expression to cancel any machine dependent modifications in 9626117395Skanconverting code to conditional execution. The involved basic blocks 9627117395Skancan be found in the @code{struct ce_if_block} structure that is pointed 9628117395Skanto by @var{ce_info}. 9629132718Skan@end defmac 9630117395Skan 9631132718Skan@defmac IFCVT_INIT_EXTRA_FIELDS (@var{ce_info}) 9632117395SkanA C expression to initialize any extra fields in a @code{struct ce_if_block} 9633117395Skanstructure, which are defined by the @code{IFCVT_EXTRA_FIELDS} macro. 9634132718Skan@end defmac 9635117395Skan 9636132718Skan@defmac IFCVT_EXTRA_FIELDS 9637117395SkanIf defined, it should expand to a set of field declarations that will be 9638117395Skanadded to the @code{struct ce_if_block} structure. These should be initialized 9639117395Skanby the @code{IFCVT_INIT_EXTRA_FIELDS} macro. 9640132718Skan@end defmac 9641117395Skan 9642132718Skan@deftypefn {Target Hook} void TARGET_MACHINE_DEPENDENT_REORG () 9643132718SkanIf non-null, this hook performs a target-specific pass over the 9644132718Skaninstruction stream. The compiler will run it at all optimization levels, 9645132718Skanjust before the point at which it normally does delayed-branch scheduling. 964690075Sobrien 9647132718SkanThe exact purpose of the hook varies from target to target. Some use 9648132718Skanit to do transformations that are necessary for correctness, such as 9649132718Skanlaying out in-function constant pools or avoiding hardware hazards. 9650132718SkanOthers use it as an opportunity to do some machine-dependent optimizations. 9651132718Skan 9652132718SkanYou need not implement the hook if it has nothing to do. The default 9653132718Skandefinition is null. 9654132718Skan@end deftypefn 9655132718Skan 965690075Sobrien@deftypefn {Target Hook} void TARGET_INIT_BUILTINS () 965790075SobrienDefine this hook if you have any machine-specific built-in functions 965890075Sobrienthat need to be defined. It should be a function that performs the 965990075Sobriennecessary setup. 966090075Sobrien 966190075SobrienMachine specific built-in functions can be useful to expand special machine 966290075Sobrieninstructions that would otherwise not normally be generated because 966390075Sobrienthey have no equivalent in the source language (for example, SIMD vector 966490075Sobrieninstructions or prefetch instructions). 966590075Sobrien 9666169689SkanTo create a built-in function, call the function 9667169689Skan@code{lang_hooks.builtin_function} 966890075Sobrienwhich is defined by the language front end. You can use any type nodes set 966990075Sobrienup by @code{build_common_tree_nodes} and @code{build_common_tree_nodes_2}; 967090075Sobrienonly language front ends that use those two functions will call 967190075Sobrien@samp{TARGET_INIT_BUILTINS}. 967290075Sobrien@end deftypefn 967390075Sobrien 967490075Sobrien@deftypefn {Target Hook} rtx TARGET_EXPAND_BUILTIN (tree @var{exp}, rtx @var{target}, rtx @var{subtarget}, enum machine_mode @var{mode}, int @var{ignore}) 967590075Sobrien 967690075SobrienExpand a call to a machine specific built-in function that was set up by 967790075Sobrien@samp{TARGET_INIT_BUILTINS}. @var{exp} is the expression for the 967890075Sobrienfunction call; the result should go to @var{target} if that is 967990075Sobrienconvenient, and have mode @var{mode} if that is convenient. 968090075Sobrien@var{subtarget} may be used as the target for computing one of 968190075Sobrien@var{exp}'s operands. @var{ignore} is nonzero if the value is to be 968290075Sobrienignored. This function should return the result of the call to the 968390075Sobrienbuilt-in function. 968490075Sobrien@end deftypefn 968590075Sobrien 9686169689Skan@deftypefn {Target Hook} tree TARGET_RESOLVE_OVERLOADED_BUILTIN (tree @var{fndecl}, tree @var{arglist}) 9687169689Skan 9688169689SkanSelect a replacement for a machine specific built-in function that 9689169689Skanwas set up by @samp{TARGET_INIT_BUILTINS}. This is done 9690169689Skan@emph{before} regular type checking, and so allows the target to 9691169689Skanimplement a crude form of function overloading. @var{fndecl} is the 9692169689Skandeclaration of the built-in function. @var{arglist} is the list of 9693169689Skanarguments passed to the built-in function. The result is a 9694169689Skancomplete expression that implements the operation, usually 9695169689Skananother @code{CALL_EXPR}. 9696169689Skan@end deftypefn 9697169689Skan 9698169689Skan@deftypefn {Target Hook} tree TARGET_FOLD_BUILTIN (tree @var{fndecl}, tree @var{arglist}, bool @var{ignore}) 9699169689Skan 9700169689SkanFold a call to a machine specific built-in function that was set up by 9701169689Skan@samp{TARGET_INIT_BUILTINS}. @var{fndecl} is the declaration of the 9702169689Skanbuilt-in function. @var{arglist} is the list of arguments passed to 9703169689Skanthe built-in function. The result is another tree containing a 9704169689Skansimplified expression for the call's result. If @var{ignore} is true 9705169689Skanthe value will be ignored. 9706169689Skan@end deftypefn 9707169689Skan 9708169689Skan@deftypefn {Target Hook} const char * TARGET_INVALID_WITHIN_DOLOOP (rtx @var{insn}) 9709169689Skan 9710169689SkanTake an instruction in @var{insn} and return NULL if it is valid within a 9711169689Skanlow-overhead loop, otherwise return a string why doloop could not be applied. 9712169689Skan 9713169689SkanMany targets use special registers for low-overhead looping. For any 9714169689Skaninstruction that clobbers these this function should return a string indicating 9715169689Skanthe reason why the doloop could not be applied. 9716169689SkanBy default, the RTL loop optimizer does not use a present doloop pattern for 9717169689Skanloops containing function calls or branch on table instructions. 9718169689Skan@end deftypefn 9719169689Skan 9720132718Skan@defmac MD_CAN_REDIRECT_BRANCH (@var{branch1}, @var{branch2}) 972190075Sobrien 972290075SobrienTake a branch insn in @var{branch1} and another in @var{branch2}. 972390075SobrienReturn true if redirecting @var{branch1} to the destination of 972490075Sobrien@var{branch2} is possible. 972590075Sobrien 972690075SobrienOn some targets, branches may have a limited range. Optimizing the 972790075Sobrienfilling of delay slots can result in branches being redirected, and this 972890075Sobrienmay in turn cause a branch offset to overflow. 9729132718Skan@end defmac 973090075Sobrien 9731169689Skan@deftypefn {Target Hook} bool TARGET_COMMUTATIVE_P (rtx @var{x}, @var{outer_code}) 9732169689SkanThis target hook returns @code{true} if @var{x} is considered to be commutative. 9733169689SkanUsually, this is just COMMUTATIVE_P (@var{x}), but the HP PA doesn't consider 9734169689SkanPLUS to be commutative inside a MEM. @var{outer_code} is the rtx code 9735169689Skanof the enclosing rtl, if known, otherwise it is UNKNOWN. 9736169689Skan@end deftypefn 973790075Sobrien 9738169689Skan@deftypefn {Target Hook} rtx TARGET_ALLOCATE_INITIAL_VALUE (rtx @var{hard_reg}) 9739169689Skan 974090075SobrienWhen the initial value of a hard register has been copied in a pseudo 974190075Sobrienregister, it is often not necessary to actually allocate another register 974290075Sobriento this pseudo register, because the original hard register or a stack slot 9743169689Skanit has been saved into can be used. @code{TARGET_ALLOCATE_INITIAL_VALUE} 9744169689Skanis called at the start of register allocation once for each hard register 9745169689Skanthat had its initial value copied by using 974690075Sobrien@code{get_func_hard_reg_initial_val} or @code{get_hard_reg_initial_val}. 974790075SobrienPossible values are @code{NULL_RTX}, if you don't want 974890075Sobriento do any special allocation, a @code{REG} rtx---that would typically be 974990075Sobrienthe hard register itself, if it is known not to be clobbered---or a 975090075Sobrien@code{MEM}. 975190075SobrienIf you are returning a @code{MEM}, this is only a hint for the allocator; 975290075Sobrienit might decide to use another register anyways. 9753169689SkanYou may use @code{current_function_leaf_function} in the hook, functions 9754169689Skanthat use @code{REG_N_SETS}, to determine if the hard 975590075Sobrienregister in question will not be clobbered. 9756169689SkanThe default value of this hook is @code{NULL}, which disables any special 9757169689Skanallocation. 9758169689Skan@end deftypefn 975990075Sobrien 9760132718Skan@defmac TARGET_OBJECT_SUFFIX 976190075SobrienDefine this macro to be a C string representing the suffix for object 976290075Sobrienfiles on your target machine. If you do not define this macro, GCC will 976390075Sobrienuse @samp{.o} as the suffix for object files. 9764132718Skan@end defmac 976590075Sobrien 9766132718Skan@defmac TARGET_EXECUTABLE_SUFFIX 976790075SobrienDefine this macro to be a C string representing the suffix to be 976890075Sobrienautomatically added to executable files on your target machine. If you 976990075Sobriendo not define this macro, GCC will use the null string as the suffix for 977090075Sobrienexecutable files. 9771132718Skan@end defmac 977290075Sobrien 9773132718Skan@defmac COLLECT_EXPORT_LIST 977490075SobrienIf defined, @code{collect2} will scan the individual object files 977590075Sobrienspecified on its command line and create an export list for the linker. 977690075SobrienDefine this macro for systems like AIX, where the linker discards 977790075Sobrienobject files that are not referenced from @code{main} and uses export 977890075Sobrienlists. 9779132718Skan@end defmac 978090075Sobrien 9781132718Skan@defmac MODIFY_JNI_METHOD_CALL (@var{mdecl}) 9782117395SkanDefine this macro to a C expression representing a variant of the 9783117395Skanmethod call @var{mdecl}, if Java Native Interface (JNI) methods 9784117395Skanmust be invoked differently from other methods on your target. 9785132718SkanFor example, on 32-bit Microsoft Windows, JNI methods must be invoked using 9786117395Skanthe @code{stdcall} calling convention and this macro is then 9787117395Skandefined as this expression: 9788117395Skan 9789117395Skan@smallexample 9790117395Skanbuild_type_attribute_variant (@var{mdecl}, 9791117395Skan build_tree_list 9792117395Skan (get_identifier ("stdcall"), 9793117395Skan NULL)) 9794117395Skan@end smallexample 9795132718Skan@end defmac 9796117395Skan 979796263Sobrien@deftypefn {Target Hook} bool TARGET_CANNOT_MODIFY_JUMPS_P (void) 979896263SobrienThis target hook returns @code{true} past the point in which new jump 979996263Sobrieninstructions could be created. On machines that require a register for 980096263Sobrienevery jump such as the SHmedia ISA of SH5, this point would typically be 980196263Sobrienreload, so this target hook should be defined to a function such as: 980296263Sobrien 980396263Sobrien@smallexample 980496263Sobrienstatic bool 980596263Sobriencannot_modify_jumps_past_reload_p () 980696263Sobrien@{ 980796263Sobrien return (reload_completed || reload_in_progress); 980896263Sobrien@} 980996263Sobrien@end smallexample 981096263Sobrien@end deftypefn 9811132718Skan 9812132718Skan@deftypefn {Target Hook} int TARGET_BRANCH_TARGET_REGISTER_CLASS (void) 9813132718SkanThis target hook returns a register class for which branch target register 9814132718Skanoptimizations should be applied. All registers in this class should be 9815132718Skanusable interchangeably. After reload, registers in this class will be 9816132718Skanre-allocated and loads will be hoisted out of loops and be subjected 9817132718Skanto inter-block scheduling. 9818132718Skan@end deftypefn 9819132718Skan 9820132718Skan@deftypefn {Target Hook} bool TARGET_BRANCH_TARGET_REGISTER_CALLEE_SAVED (bool @var{after_prologue_epilogue_gen}) 9821132718SkanBranch target register optimization will by default exclude callee-saved 9822132718Skanregisters 9823132718Skanthat are not already live during the current function; if this target hook 9824132718Skanreturns true, they will be included. The target code must than make sure 9825132718Skanthat all target registers in the class returned by 9826132718Skan@samp{TARGET_BRANCH_TARGET_REGISTER_CLASS} that might need saving are 9827132718Skansaved. @var{after_prologue_epilogue_gen} indicates if prologues and 9828132718Skanepilogues have already been generated. Note, even if you only return 9829132718Skantrue when @var{after_prologue_epilogue_gen} is false, you still are likely 9830132718Skanto have to make special provisions in @code{INITIAL_ELIMINATION_OFFSET} 9831132718Skanto reserve space for caller-saved target registers. 9832132718Skan@end deftypefn 9833132718Skan 9834132718Skan@defmac POWI_MAX_MULTS 9835132718SkanIf defined, this macro is interpreted as a signed integer C expression 9836132718Skanthat specifies the maximum number of floating point multiplications 9837132718Skanthat should be emitted when expanding exponentiation by an integer 9838132718Skanconstant inline. When this value is defined, exponentiation requiring 9839132718Skanmore than this number of multiplications is implemented by calling the 9840132718Skansystem library's @code{pow}, @code{powf} or @code{powl} routines. 9841132718SkanThe default value places no upper bound on the multiplication count. 9842132718Skan@end defmac 9843169689Skan 9844169689Skan@deftypefn Macro void TARGET_EXTRA_INCLUDES (const char *@var{sysroot}, const char *@var{iprefix}, int @var{stdinc}) 9845169689SkanThis target hook should register any extra include files for the 9846169689Skantarget. The parameter @var{stdinc} indicates if normal include files 9847169689Skanare present. The parameter @var{sysroot} is the system root directory. 9848169689SkanThe parameter @var{iprefix} is the prefix for the gcc directory. 9849169689Skan@end deftypefn 9850169689Skan 9851169689Skan@deftypefn Macro void TARGET_EXTRA_PRE_INCLUDES (const char *@var{sysroot}, const char *@var{iprefix}, int @var{stdinc}) 9852169689SkanThis target hook should register any extra include files for the 9853169689Skantarget before any standard headers. The parameter @var{stdinc} 9854169689Skanindicates if normal include files are present. The parameter 9855169689Skan@var{sysroot} is the system root directory. The parameter 9856169689Skan@var{iprefix} is the prefix for the gcc directory. 9857169689Skan@end deftypefn 9858169689Skan 9859169689Skan@deftypefn Macro void TARGET_OPTF (char *@var{path}) 9860169689SkanThis target hook should register special include paths for the target. 9861169689SkanThe parameter @var{path} is the include to register. On Darwin 9862169689Skansystems, this is used for Framework includes, which have semantics 9863169689Skanthat are different from @option{-I}. 9864169689Skan@end deftypefn 9865169689Skan 9866169689Skan@deftypefn {Target Hook} bool TARGET_USE_LOCAL_THUNK_ALIAS_P (tree @var{fndecl}) 9867169689SkanThis target hook returns @code{true} if it is safe to use a local alias 9868169689Skanfor a virtual function @var{fndecl} when constructing thunks, 9869169689Skan@code{false} otherwise. By default, the hook returns @code{true} for all 9870169689Skanfunctions, if a target supports aliases (i.e.@: defines 9871169689Skan@code{ASM_OUTPUT_DEF}), @code{false} otherwise, 9872169689Skan@end deftypefn 9873169689Skan 9874169689Skan@defmac TARGET_FORMAT_TYPES 9875169689SkanIf defined, this macro is the name of a global variable containing 9876169689Skantarget-specific format checking information for the @option{-Wformat} 9877169689Skanoption. The default is to have no target-specific format checks. 9878169689Skan@end defmac 9879169689Skan 9880169689Skan@defmac TARGET_N_FORMAT_TYPES 9881169689SkanIf defined, this macro is the number of entries in 9882169689Skan@code{TARGET_FORMAT_TYPES}. 9883169689Skan@end defmac 9884169689Skan 9885169689Skan@deftypefn {Target Hook} bool TARGET_RELAXED_ORDERING 9886169689SkanIf set to @code{true}, means that the target's memory model does not 9887169689Skanguarantee that loads which do not depend on one another will access 9888169689Skanmain memory in the order of the instruction stream; if ordering is 9889169689Skanimportant, an explicit memory barrier must be used. This is true of 9890169689Skanmany recent processors which implement a policy of ``relaxed,'' 9891169689Skan``weak,'' or ``release'' memory consistency, such as Alpha, PowerPC, 9892169689Skanand ia64. The default is @code{false}. 9893169689Skan@end deftypefn 9894169689Skan 9895169689Skan@deftypefn {Target Hook} const char *TARGET_INVALID_ARG_FOR_UNPROTOTYPED_FN (tree @var{typelist}, tree @var{funcdecl}, tree @var{val}) 9896169689SkanIf defined, this macro returns the diagnostic message when it is 9897169689Skanillegal to pass argument @var{val} to function @var{funcdecl} 9898169689Skanwith prototype @var{typelist}. 9899169689Skan@end deftypefn 9900169689Skan 9901169689Skan@deftypefn {Target Hook} {const char *} TARGET_INVALID_CONVERSION (tree @var{fromtype}, tree @var{totype}) 9902169689SkanIf defined, this macro returns the diagnostic message when it is 9903169689Skaninvalid to convert from @var{fromtype} to @var{totype}, or @code{NULL} 9904169689Skanif validity should be determined by the front end. 9905169689Skan@end deftypefn 9906169689Skan 9907169689Skan@deftypefn {Target Hook} {const char *} TARGET_INVALID_UNARY_OP (int @var{op}, tree @var{type}) 9908169689SkanIf defined, this macro returns the diagnostic message when it is 9909169689Skaninvalid to apply operation @var{op} (where unary plus is denoted by 9910169689Skan@code{CONVERT_EXPR}) to an operand of type @var{type}, or @code{NULL} 9911169689Skanif validity should be determined by the front end. 9912169689Skan@end deftypefn 9913169689Skan 9914169689Skan@deftypefn {Target Hook} {const char *} TARGET_INVALID_BINARY_OP (int @var{op}, tree @var{type1}, tree @var{type2}) 9915169689SkanIf defined, this macro returns the diagnostic message when it is 9916169689Skaninvalid to apply operation @var{op} to operands of types @var{type1} 9917169689Skanand @var{type2}, or @code{NULL} if validity should be determined by 9918169689Skanthe front end. 9919169689Skan@end deftypefn 9920169689Skan 9921169689Skan@defmac TARGET_USE_JCR_SECTION 9922169689SkanThis macro determines whether to use the JCR section to register Java 9923169689Skanclasses. By default, TARGET_USE_JCR_SECTION is defined to 1 if both 9924169689SkanSUPPORTS_WEAK and TARGET_HAVE_NAMED_SECTIONS are true, else 0. 9925169689Skan@end defmac 9926