tm.texi revision 117395
1271440Sjkim@c Copyright (C) 1988,1989,1992,1993,1994,1995,1996,1997,1998,1999,2000,2001,2002,2003 2271440Sjkim@c Free Software Foundation, Inc. 3271440Sjkim@c This is part of the GCC manual. 4306536Sjkim@c For copying conditions, see the file gcc.texi. 5271440Sjkim 6271440Sjkim@node Target Macros 7271440Sjkim@chapter Target Description Macros and Functions 8271440Sjkim@cindex machine description macros 9306536Sjkim@cindex target description macros 10271440Sjkim@cindex macros, target description 11271440Sjkim@cindex @file{tm.h} macros 12271440Sjkim 13271440SjkimIn addition to the file @file{@var{machine}.md}, a machine description 14271440Sjkimincludes a C header file conventionally given the name 15271440Sjkim@file{@var{machine}.h} and a C source file named @file{@var{machine}.c}. 16271440SjkimThe header file defines numerous macros that convey the information 17271440Sjkimabout the target machine that does not fit into the scheme of the 18271440Sjkim@file{.md} file. The file @file{tm.h} should be a link to 19271440Sjkim@file{@var{machine}.h}. The header file @file{config.h} includes 20271440Sjkim@file{tm.h} and most compiler source files include @file{config.h}. The 21271440Sjkimsource file defines a variable @code{targetm}, which is a structure 22271440Sjkimcontaining pointers to functions and data relating to the target 23271440Sjkimmachine. @file{@var{machine}.c} should also contain their definitions, 24271440Sjkimif they are not defined elsewhere in GCC, and other functions called 25271440Sjkimthrough the macros defined in the @file{.h} file. 26271440Sjkim 27271440Sjkim@menu 28271440Sjkim* Target Structure:: The @code{targetm} variable. 29271440Sjkim* Driver:: Controlling how the driver runs the compilation passes. 30271440Sjkim* Run-time Target:: Defining @samp{-m} options like @option{-m68000} and @option{-m68020}. 31271440Sjkim* Per-Function Data:: Defining data structures for per-function information. 32271440Sjkim* Storage Layout:: Defining sizes and alignments of data. 33271440Sjkim* Type Layout:: Defining sizes and properties of basic user data types. 34271440Sjkim* Escape Sequences:: Defining the value of target character escape sequences 35271440Sjkim* Registers:: Naming and describing the hardware registers. 36271440Sjkim* Register Classes:: Defining the classes of hardware registers. 37271440Sjkim* Stack and Calling:: Defining which way the stack grows and by how much. 38271440Sjkim* Varargs:: Defining the varargs macros. 39271440Sjkim* Trampolines:: Code set up at run time to enter a nested function. 40271440Sjkim* Library Calls:: Controlling how library routines are implicitly called. 41271440Sjkim* Addressing Modes:: Defining addressing modes valid for memory operands. 42271440Sjkim* Condition Code:: Defining how insns update the condition code. 43271440Sjkim* Costs:: Defining relative costs of different operations. 44271440Sjkim* Scheduling:: Adjusting the behavior of the instruction scheduler. 45271440Sjkim* Sections:: Dividing storage into text, data, and other sections. 46271440Sjkim* PIC:: Macros for position independent code. 47271440Sjkim* Assembler Format:: Defining how to write insns and pseudo-ops to output. 48271440Sjkim* Debugging Info:: Defining the format of debugging output. 49306536Sjkim* Floating Point:: Handling floating point for cross-compilers. 50271440Sjkim* Mode Switching:: Insertion of mode-switching instructions. 51271440Sjkim* Target Attributes:: Defining target-specific uses of @code{__attribute__}. 52271440Sjkim* MIPS Coprocessors:: MIPS coprocessor support and how to customize it. 53271440Sjkim* Misc:: Everything else. 54306536Sjkim@end menu 55271440Sjkim 56271440Sjkim@node Target Structure 57306536Sjkim@section The Global @code{targetm} Variable 58306536Sjkim@cindex target hooks 59271440Sjkim@cindex target functions 60271440Sjkim 61271440Sjkim@deftypevar {struct gcc_target} targetm 62271440SjkimThe target @file{.c} file must define the global @code{targetm} variable 63271440Sjkimwhich contains pointers to functions and data relating to the target 64271440Sjkimmachine. The variable is declared in @file{target.h}; 65271440Sjkim@file{target-def.h} defines the macro @code{TARGET_INITIALIZER} which is 66271440Sjkimused to initialize the variable, and macros for the default initializers 67271440Sjkimfor elements of the structure. The @file{.c} file should override those 68271440Sjkimmacros for which the default definition is inappropriate. For example: 69271440Sjkim@smallexample 70271440Sjkim#include "target.h" 71271440Sjkim#include "target-def.h" 72271440Sjkim 73271440Sjkim/* @r{Initialize the GCC target structure.} */ 74271440Sjkim 75271440Sjkim#undef TARGET_COMP_TYPE_ATTRIBUTES 76271440Sjkim#define TARGET_COMP_TYPE_ATTRIBUTES @var{machine}_comp_type_attributes 77306536Sjkim 78306536Sjkimstruct gcc_target targetm = TARGET_INITIALIZER; 79306536Sjkim@end smallexample 80306536Sjkim@end deftypevar 81271440Sjkim 82271440SjkimWhere a macro should be defined in the @file{.c} file in this manner to 83306536Sjkimform part of the @code{targetm} structure, it is documented below as a 84271440Sjkim``Target Hook'' with a prototype. Many macros will change in future 85271440Sjkimfrom being defined in the @file{.h} file to being part of the 86271440Sjkim@code{targetm} structure. 87271440Sjkim 88271440Sjkim@node Driver 89271440Sjkim@section Controlling the Compilation Driver, @file{gcc} 90271440Sjkim@cindex driver 91271440Sjkim@cindex controlling the compilation driver 92271440Sjkim 93271440Sjkim@c prevent bad page break with this line 94306536SjkimYou can control the compilation driver. 95306536Sjkim 96306536Sjkim@table @code 97306536Sjkim@findex SWITCH_TAKES_ARG 98306536Sjkim@item SWITCH_TAKES_ARG (@var{char}) 99281075SdimA C expression which determines whether the option @option{-@var{char}} 100306536Sjkimtakes arguments. The value should be the number of arguments that 101306536Sjkimoption takes--zero, for many options. 102306536Sjkim 103306536SjkimBy default, this macro is defined as 104306536Sjkim@code{DEFAULT_SWITCH_TAKES_ARG}, which handles the standard options 105306536Sjkimproperly. You need not define @code{SWITCH_TAKES_ARG} unless you 106281075Sdimwish to add additional options which take arguments. Any redefinition 107306536Sjkimshould call @code{DEFAULT_SWITCH_TAKES_ARG} and then check for 108306536Sjkimadditional options. 109306536Sjkim 110306536Sjkim@findex WORD_SWITCH_TAKES_ARG 111306536Sjkim@item WORD_SWITCH_TAKES_ARG (@var{name}) 112281075SdimA C expression which determines whether the option @option{-@var{name}} 113306536Sjkimtakes arguments. The value should be the number of arguments that 114306536Sjkimoption takes--zero, for many options. This macro rather than 115306536Sjkim@code{SWITCH_TAKES_ARG} is used for multi-character option names. 116306536Sjkim 117306536SjkimBy default, this macro is defined as 118306536Sjkim@code{DEFAULT_WORD_SWITCH_TAKES_ARG}, which handles the standard options 119306536Sjkimproperly. You need not define @code{WORD_SWITCH_TAKES_ARG} unless you 120281075Sdimwish to add additional options which take arguments. Any redefinition 121306536Sjkimshould call @code{DEFAULT_WORD_SWITCH_TAKES_ARG} and then check for 122306536Sjkimadditional options. 123306536Sjkim 124306536Sjkim@findex SWITCH_CURTAILS_COMPILATION 125306536Sjkim@item SWITCH_CURTAILS_COMPILATION (@var{char}) 126306536SjkimA C expression which determines whether the option @option{-@var{char}} 127281075Sdimstops compilation before the generation of an executable. The value is 128306536Sjkimboolean, nonzero if the option does stop an executable from being 129281075Sdimgenerated, zero otherwise. 130306536Sjkim 131306536SjkimBy default, this macro is defined as 132306536Sjkim@code{DEFAULT_SWITCH_CURTAILS_COMPILATION}, which handles the standard 133306536Sjkimoptions properly. You need not define 134281075Sdim@code{SWITCH_CURTAILS_COMPILATION} unless you wish to add additional 135306536Sjkimoptions which affect the generation of an executable. Any redefinition 136281075Sdimshould call @code{DEFAULT_SWITCH_CURTAILS_COMPILATION} and then check 137306536Sjkimfor additional options. 138306536Sjkim 139306536Sjkim@findex SWITCHES_NEED_SPACES 140306536Sjkim@item SWITCHES_NEED_SPACES 141306536SjkimA string-valued C expression which enumerates the options for which 142281075Sdimthe linker needs a space between the option and its argument. 143306536Sjkim 144306536SjkimIf this macro is not defined, the default value is @code{""}. 145306536Sjkim 146306536Sjkim@findex TARGET_OPTION_TRANSLATE_TABLE 147281075Sdim@item TARGET_OPTION_TRANSLATE_TABLE 148281075SdimIf defined, a list of pairs of strings, the first of which is a 149306536Sjkimpotential command line target to the @file{gcc} driver program, and the 150306536Sjkimsecond of which is a space-separated (tabs and other whitespace are not 151306536Sjkimsupported) list of options with which to replace the first option. The 152306536Sjkimtarget defining this list is responsible for assuring that the results 153306536Sjkimare valid. Replacement options may not be the @code{--opt} style, they 154306536Sjkimmust be the @code{-opt} style. It is the intention of this macro to 155306536Sjkimprovide a mechanism for substitution that affects the multilibs chosen, 156306536Sjkimsuch as one option that enables many options, some of which select 157281075Sdimmultilibs. Example nonsensical definition, where @code{-malt-abi}, 158281075Sdim@code{-EB}, and @code{-mspoo} cause different multilibs to be chosen: 159306536Sjkim 160306536Sjkim@smallexample 161306536Sjkim#define TARGET_OPTION_TRANSLATE_TABLE \ 162306536Sjkim@{ "-fast", "-march=fast-foo -malt-abi -I/usr/fast-foo" @}, \ 163306536Sjkim@{ "-compat", "-EB -malign=4 -mspoo" @} 164306536Sjkim@end smallexample 165306536Sjkim 166281075Sdim@findex DRIVER_SELF_SPECS 167306536Sjkim@item DRIVER_SELF_SPECS 168306536SjkimA list of specs for the driver itself. It should be a suitable 169306536Sjkiminitializer for an array of strings, with no surrounding braces. 170306536Sjkim 171306536SjkimThe driver applies these specs to its own command line before choosing 172306536Sjkimthe multilib directory or running any subcommands. It applies them in 173306536Sjkimthe order given, so each spec can depend on the options added by 174281075Sdimearlier ones. It is also possible to remove options using 175306536Sjkim@samp{%<@var{option}} in the usual way. 176306536Sjkim 177306536SjkimThis macro can be useful when a port has several interdependent target 178306536Sjkimoptions. It provides a way of standardizing the command line so 179306536Sjkimthat the other specs are easier to write. 180306536Sjkim 181306536SjkimDo not define this macro if it does not need to do anything. 182281075Sdim 183306536Sjkim@findex CPP_SPEC 184306536Sjkim@item CPP_SPEC 185306536SjkimA C string constant that tells the GCC driver program options to 186306536Sjkimpass to CPP@. It can also specify how to translate options you 187306536Sjkimgive to GCC into options for GCC to pass to the CPP@. 188306536Sjkim 189281075SdimDo not define this macro if it does not need to do anything. 190306536Sjkim 191306536Sjkim@findex CPLUSPLUS_CPP_SPEC 192306536Sjkim@item CPLUSPLUS_CPP_SPEC 193306536SjkimThis macro is just like @code{CPP_SPEC}, but is used for C++, rather 194306536Sjkimthan C@. If you do not define this macro, then the value of 195281075Sdim@code{CPP_SPEC} (if any) will be used instead. 196306536Sjkim 197306536Sjkim@findex CC1_SPEC 198306536Sjkim@item CC1_SPEC 199306536SjkimA C string constant that tells the GCC driver program options to 200306536Sjkimpass to @code{cc1}, @code{cc1plus}, @code{f771}, and the other language 201281075Sdimfront ends. 202306536SjkimIt can also specify how to translate options you give to GCC into options 203306536Sjkimfor GCC to pass to front ends. 204306536Sjkim 205306536SjkimDo not define this macro if it does not need to do anything. 206306536Sjkim 207306536Sjkim@findex CC1PLUS_SPEC 208306536Sjkim@item CC1PLUS_SPEC 209281075SdimA C string constant that tells the GCC driver program options to 210306536Sjkimpass to @code{cc1plus}. It can also specify how to translate options you 211306536Sjkimgive to GCC into options for GCC to pass to the @code{cc1plus}. 212306536Sjkim 213306536SjkimDo not define this macro if it does not need to do anything. 214281075SdimNote that everything defined in CC1_SPEC is already passed to 215306536Sjkim@code{cc1plus} so there is no need to duplicate the contents of 216281075SdimCC1_SPEC in CC1PLUS_SPEC@. 217306536Sjkim 218306536Sjkim@findex ASM_SPEC 219306536Sjkim@item ASM_SPEC 220306536SjkimA C string constant that tells the GCC driver program options to 221306536Sjkimpass to the assembler. It can also specify how to translate options 222306536Sjkimyou give to GCC into options for GCC to pass to the assembler. 223281075SdimSee the file @file{sun3.h} for an example of this. 224306536Sjkim 225306536SjkimDo not define this macro if it does not need to do anything. 226306536Sjkim 227306536Sjkim@findex ASM_FINAL_SPEC 228306536Sjkim@item ASM_FINAL_SPEC 229281075SdimA C string constant that tells the GCC driver program how to 230306536Sjkimrun any programs which cleanup after the normal assembler. 231306536SjkimNormally, this is not needed. See the file @file{mips.h} for 232306536Sjkiman example of this. 233306536Sjkim 234281075SdimDo not define this macro if it does not need to do anything. 235306536Sjkim 236306536Sjkim@findex LINK_SPEC 237306536Sjkim@item LINK_SPEC 238306536SjkimA C string constant that tells the GCC driver program options to 239306536Sjkimpass to the linker. It can also specify how to translate options you 240306536Sjkimgive to GCC into options for GCC to pass to the linker. 241281075Sdim 242281075SdimDo not define this macro if it does not need to do anything. 243306536Sjkim 244306536Sjkim@findex LIB_SPEC 245306536Sjkim@item LIB_SPEC 246306536SjkimAnother C string constant used much like @code{LINK_SPEC}. The difference 247306536Sjkimbetween the two is that @code{LIB_SPEC} is used at the end of the 248281075Sdimcommand given to the linker. 249306536Sjkim 250306536SjkimIf this macro is not defined, a default is provided that 251306536Sjkimloads the standard C library from the usual place. See @file{gcc.c}. 252306536Sjkim 253271440Sjkim@findex LIBGCC_SPEC 254306536Sjkim@item LIBGCC_SPEC 255306536SjkimAnother C string constant that tells the GCC driver program 256271440Sjkimhow and when to place a reference to @file{libgcc.a} into the 257271440Sjkimlinker command line. This constant is placed both before and after 258271440Sjkimthe value of @code{LIB_SPEC}. 259271440Sjkim 260271440SjkimIf this macro is not defined, the GCC driver provides a default that 261271440Sjkimpasses the string @option{-lgcc} to the linker. 262271440Sjkim 263271440Sjkim@findex STARTFILE_SPEC 264271440Sjkim@item STARTFILE_SPEC 265271440SjkimAnother C string constant used much like @code{LINK_SPEC}. The 266271440Sjkimdifference between the two is that @code{STARTFILE_SPEC} is used at 267271440Sjkimthe very beginning of the command given to the linker. 268281687Sjkim 269281687SjkimIf this macro is not defined, a default is provided that loads the 270271440Sjkimstandard C startup file from the usual place. See @file{gcc.c}. 271271440Sjkim 272271440Sjkim@findex ENDFILE_SPEC 273271440Sjkim@item ENDFILE_SPEC 274271440SjkimAnother C string constant used much like @code{LINK_SPEC}. The 275306536Sjkimdifference between the two is that @code{ENDFILE_SPEC} is used at 276306536Sjkimthe very end of the command given to the linker. 277306536Sjkim 278306536SjkimDo not define this macro if it does not need to do anything. 279306536Sjkim 280306536Sjkim@findex THREAD_MODEL_SPEC 281306536Sjkim@item THREAD_MODEL_SPEC 282306536SjkimGCC @code{-v} will print the thread model GCC was configured to use. 283306536SjkimHowever, this doesn't work on platforms that are multilibbed on thread 284306536Sjkimmodels, such as AIX 4.3. On such platforms, define 285306536Sjkim@code{THREAD_MODEL_SPEC} such that it evaluates to a string without 286271440Sjkimblanks that names one of the recognized thread models. @code{%*}, the 287306536Sjkimdefault value of this macro, will expand to the value of 288306536Sjkim@code{thread_file} set in @file{config.gcc}. 289306536Sjkim 290306536Sjkim@findex EXTRA_SPECS 291271440Sjkim@item EXTRA_SPECS 292306536SjkimDefine this macro to provide additional specifications to put in the 293306536Sjkim@file{specs} file that can be used in various specifications like 294306536Sjkim@code{CC1_SPEC}. 295306536Sjkim 296306536SjkimThe definition should be an initializer for an array of structures, 297271440Sjkimcontaining a string constant, that defines the specification name, and a 298271440Sjkimstring constant that provides the specification. 299306536Sjkim 300306536SjkimDo not define this macro if it does not need to do anything. 301306536Sjkim 302306536Sjkim@code{EXTRA_SPECS} is useful when an architecture contains several 303306536Sjkimrelated targets, which have various @code{@dots{}_SPECS} which are similar 304271440Sjkimto each other, and the maintainer would like one central place to keep 305306536Sjkimthese definitions. 306271440Sjkim 307306536SjkimFor example, the PowerPC System V.4 targets use @code{EXTRA_SPECS} to 308306536Sjkimdefine either @code{_CALL_SYSV} when the System V calling sequence is 309306536Sjkimused or @code{_CALL_AIX} when the older AIX-based calling sequence is 310306536Sjkimused. 311306536Sjkim 312306536SjkimThe @file{config/rs6000/rs6000.h} target file defines: 313306536Sjkim 314271440Sjkim@example 315271440Sjkim#define EXTRA_SPECS \ 316271440Sjkim @{ "cpp_sysv_default", CPP_SYSV_DEFAULT @}, 317271440Sjkim 318271440Sjkim#define CPP_SYS_DEFAULT "" 319271440Sjkim@end example 320271440Sjkim 321271440SjkimThe @file{config/rs6000/sysv.h} target file defines: 322271440Sjkim@smallexample 323271440Sjkim#undef CPP_SPEC 324271440Sjkim#define CPP_SPEC \ 325271440Sjkim"%@{posix: -D_POSIX_SOURCE @} \ 326271440Sjkim%@{mcall-sysv: -D_CALL_SYSV @} %@{mcall-aix: -D_CALL_AIX @} \ 327271440Sjkim%@{!mcall-sysv: %@{!mcall-aix: %(cpp_sysv_default) @}@} \ 328271440Sjkim%@{msoft-float: -D_SOFT_FLOAT@} %@{mcpu=403: -D_SOFT_FLOAT@}" 329271440Sjkim 330271440Sjkim#undef CPP_SYSV_DEFAULT 331271440Sjkim#define CPP_SYSV_DEFAULT "-D_CALL_SYSV" 332271440Sjkim@end smallexample 333271440Sjkim 334271440Sjkimwhile the @file{config/rs6000/eabiaix.h} target file defines 335271440Sjkim@code{CPP_SYSV_DEFAULT} as: 336271440Sjkim 337271440Sjkim@smallexample 338271440Sjkim#undef CPP_SYSV_DEFAULT 339271440Sjkim#define CPP_SYSV_DEFAULT "-D_CALL_AIX" 340271440Sjkim@end smallexample 341271440Sjkim 342271440Sjkim@findex LINK_LIBGCC_SPECIAL 343271440Sjkim@item LINK_LIBGCC_SPECIAL 344306536SjkimDefine this macro if the driver program should find the library 345306536Sjkim@file{libgcc.a} itself and should not pass @option{-L} options to the 346306536Sjkimlinker. If you do not define this macro, the driver program will pass 347306536Sjkimthe argument @option{-lgcc} to tell the linker to do the search and will 348306536Sjkimpass @option{-L} options to it. 349306536Sjkim 350306536Sjkim@findex LINK_LIBGCC_SPECIAL_1 351306536Sjkim@item LINK_LIBGCC_SPECIAL_1 352306536SjkimDefine this macro if the driver program should find the library 353306536Sjkim@file{libgcc.a}. If you do not define this macro, the driver program will pass 354306536Sjkimthe argument @option{-lgcc} to tell the linker to do the search. 355306536SjkimThis macro is similar to @code{LINK_LIBGCC_SPECIAL}, except that it does 356306536Sjkimnot affect @option{-L} options. 357306536Sjkim 358306536Sjkim@findex LINK_GCC_C_SEQUENCE_SPEC 359306536Sjkim@item LINK_GCC_C_SEQUENCE_SPEC 360306536SjkimThe sequence in which libgcc and libc are specified to the linker. 361306536SjkimBy default this is @code{%G %L %G}. 362306536Sjkim 363306536Sjkim@findex LINK_COMMAND_SPEC 364306536Sjkim@item LINK_COMMAND_SPEC 365306536SjkimA C string constant giving the complete command line need to execute the 366306536Sjkimlinker. When you do this, you will need to update your port each time a 367306536Sjkimchange is made to the link command line within @file{gcc.c}. Therefore, 368306536Sjkimdefine this macro only if you need to completely redefine the command 369306536Sjkimline for invoking the linker and there is no other way to accomplish 370306536Sjkimthe effect you need. Overriding this macro may be avoidable by overriding 371306536Sjkim@code{LINK_GCC_C_SEQUENCE_SPEC} instead. 372306536Sjkim 373306536Sjkim@findex LINK_ELIMINATE_DUPLICATE_LDIRECTORIES 374306536Sjkim@item LINK_ELIMINATE_DUPLICATE_LDIRECTORIES 375306536SjkimA nonzero value causes @command{collect2} to remove duplicate @option{-L@var{directory}} search 376306536Sjkimdirectories from linking commands. Do not give it a nonzero value if 377306536Sjkimremoving duplicate search directories changes the linker's semantics. 378306536Sjkim 379306536Sjkim@findex MULTILIB_DEFAULTS 380306536Sjkim@item MULTILIB_DEFAULTS 381306536SjkimDefine this macro as a C expression for the initializer of an array of 382306536Sjkimstring to tell the driver program which options are defaults for this 383306536Sjkimtarget and thus do not need to be handled specially when using 384306536Sjkim@code{MULTILIB_OPTIONS}. 385306536Sjkim 386306536SjkimDo not define this macro if @code{MULTILIB_OPTIONS} is not defined in 387306536Sjkimthe target makefile fragment or if none of the options listed in 388306536Sjkim@code{MULTILIB_OPTIONS} are set by default. 389306536Sjkim@xref{Target Fragment}. 390306536Sjkim 391306536Sjkim@findex RELATIVE_PREFIX_NOT_LINKDIR 392306536Sjkim@item RELATIVE_PREFIX_NOT_LINKDIR 393306536SjkimDefine this macro to tell @command{gcc} that it should only translate 394306536Sjkima @option{-B} prefix into a @option{-L} linker option if the prefix 395306536Sjkimindicates an absolute file name. 396306536Sjkim 397306536Sjkim@findex STANDARD_EXEC_PREFIX 398306536Sjkim@item STANDARD_EXEC_PREFIX 399306536SjkimDefine this macro as a C string constant if you wish to override the 400306536Sjkimstandard choice of @file{/usr/local/lib/gcc-lib/} as the default prefix to 401306536Sjkimtry when searching for the executable files of the compiler. 402306536Sjkim 403306536Sjkim@findex MD_EXEC_PREFIX 404306536Sjkim@item MD_EXEC_PREFIX 405306536SjkimIf defined, this macro is an additional prefix to try after 406306536Sjkim@code{STANDARD_EXEC_PREFIX}. @code{MD_EXEC_PREFIX} is not searched 407306536Sjkimwhen the @option{-b} option is used, or the compiler is built as a cross 408306536Sjkimcompiler. If you define @code{MD_EXEC_PREFIX}, then be sure to add it 409306536Sjkimto the list of directories used to find the assembler in @file{configure.in}. 410306536Sjkim 411306536Sjkim@findex STANDARD_STARTFILE_PREFIX 412306536Sjkim@item STANDARD_STARTFILE_PREFIX 413306536SjkimDefine this macro as a C string constant if you wish to override the 414306536Sjkimstandard choice of @file{/usr/local/lib/} as the default prefix to 415306536Sjkimtry when searching for startup files such as @file{crt0.o}. 416306536Sjkim 417306536Sjkim@findex MD_STARTFILE_PREFIX 418306536Sjkim@item MD_STARTFILE_PREFIX 419306536SjkimIf defined, this macro supplies an additional prefix to try after the 420306536Sjkimstandard prefixes. @code{MD_EXEC_PREFIX} is not searched when the 421306536Sjkim@option{-b} option is used, or when the compiler is built as a cross 422306536Sjkimcompiler. 423306536Sjkim 424306536Sjkim@findex MD_STARTFILE_PREFIX_1 425306536Sjkim@item MD_STARTFILE_PREFIX_1 426306536SjkimIf defined, this macro supplies yet another prefix to try after the 427306536Sjkimstandard prefixes. It is not searched when the @option{-b} option is 428306536Sjkimused, or when the compiler is built as a cross compiler. 429306536Sjkim 430306536Sjkim@findex INIT_ENVIRONMENT 431306536Sjkim@item INIT_ENVIRONMENT 432271440SjkimDefine this macro as a C string constant if you wish to set environment 433271440Sjkimvariables for programs called by the driver, such as the assembler and 434271440Sjkimloader. The driver passes the value of this macro to @code{putenv} to 435271440Sjkiminitialize the necessary environment variables. 436271440Sjkim 437271440Sjkim@findex LOCAL_INCLUDE_DIR 438271440Sjkim@item LOCAL_INCLUDE_DIR 439271440SjkimDefine this macro as a C string constant if you wish to override the 440271440Sjkimstandard choice of @file{/usr/local/include} as the default prefix to 441271440Sjkimtry when searching for local header files. @code{LOCAL_INCLUDE_DIR} 442271440Sjkimcomes before @code{SYSTEM_INCLUDE_DIR} in the search order. 443271440Sjkim 444271440SjkimCross compilers do not search either @file{/usr/local/include} or its 445271440Sjkimreplacement. 446271440Sjkim 447271440Sjkim@findex MODIFY_TARGET_NAME 448271440Sjkim@item MODIFY_TARGET_NAME 449271440SjkimDefine this macro if you with to define command-line switches that modify the 450271440Sjkimdefault target name 451271440Sjkim 452271440SjkimFor each switch, you can include a string to be appended to the first 453271440Sjkimpart of the configuration name or a string to be deleted from the 454271440Sjkimconfiguration name, if present. The definition should be an initializer 455271440Sjkimfor an array of structures. Each array element should have three 456271440Sjkimelements: the switch name (a string constant, including the initial 457271440Sjkimdash), one of the enumeration codes @code{ADD} or @code{DELETE} to 458271440Sjkimindicate whether the string should be inserted or deleted, and the string 459271440Sjkimto be inserted or deleted (a string constant). 460306536Sjkim 461271440SjkimFor example, on a machine where @samp{64} at the end of the 462306536Sjkimconfiguration name denotes a 64-bit target and you want the @option{-32} 463306536Sjkimand @option{-64} switches to select between 32- and 64-bit targets, you would 464306536Sjkimcode 465306536Sjkim 466306536Sjkim@smallexample 467306536Sjkim#define MODIFY_TARGET_NAME \ 468306536Sjkim @{ @{ "-32", DELETE, "64"@}, \ 469306536Sjkim @{"-64", ADD, "64"@}@} 470306536Sjkim@end smallexample 471271440Sjkim 472271440Sjkim 473271440Sjkim@findex SYSTEM_INCLUDE_DIR 474271440Sjkim@item SYSTEM_INCLUDE_DIR 475271440SjkimDefine this macro as a C string constant if you wish to specify a 476271440Sjkimsystem-specific directory to search for header files before the standard 477271440Sjkimdirectory. @code{SYSTEM_INCLUDE_DIR} comes before 478271440Sjkim@code{STANDARD_INCLUDE_DIR} in the search order. 479271440Sjkim 480271440SjkimCross compilers do not use this macro and do not search the directory 481271440Sjkimspecified. 482271440Sjkim 483271440Sjkim@findex STANDARD_INCLUDE_DIR 484271440Sjkim@item STANDARD_INCLUDE_DIR 485271440SjkimDefine this macro as a C string constant if you wish to override the 486271440Sjkimstandard choice of @file{/usr/include} as the default prefix to 487271440Sjkimtry when searching for header files. 488271440Sjkim 489271440SjkimCross compilers do not use this macro and do not search either 490306536Sjkim@file{/usr/include} or its replacement. 491306536Sjkim 492271440Sjkim@findex STANDARD_INCLUDE_COMPONENT 493271440Sjkim@item STANDARD_INCLUDE_COMPONENT 494271440SjkimThe ``component'' corresponding to @code{STANDARD_INCLUDE_DIR}. 495271440SjkimSee @code{INCLUDE_DEFAULTS}, below, for the description of components. 496271440SjkimIf you do not define this macro, no component is used. 497271440Sjkim 498271440Sjkim@findex INCLUDE_DEFAULTS 499271440Sjkim@item INCLUDE_DEFAULTS 500271440SjkimDefine this macro if you wish to override the entire default search path 501271440Sjkimfor include files. For a native compiler, the default search path 502271440Sjkimusually consists of @code{GCC_INCLUDE_DIR}, @code{LOCAL_INCLUDE_DIR}, 503271440Sjkim@code{SYSTEM_INCLUDE_DIR}, @code{GPLUSPLUS_INCLUDE_DIR}, and 504271440Sjkim@code{STANDARD_INCLUDE_DIR}. In addition, @code{GPLUSPLUS_INCLUDE_DIR} 505271440Sjkimand @code{GCC_INCLUDE_DIR} are defined automatically by @file{Makefile}, 506271440Sjkimand specify private search areas for GCC@. The directory 507271440Sjkim@code{GPLUSPLUS_INCLUDE_DIR} is used only for C++ programs. 508271440Sjkim 509271440SjkimThe definition should be an initializer for an array of structures. 510271440SjkimEach array element should have four elements: the directory name (a 511271440Sjkimstring constant), the component name (also a string constant), a flag 512271440Sjkimfor C++-only directories, 513271440Sjkimand a flag showing that the includes in the directory don't need to be 514271440Sjkimwrapped in @code{extern @samp{C}} when compiling C++. Mark the end of 515281075Sdimthe array with a null element. 516271440Sjkim 517271440SjkimThe component name denotes what GNU package the include file is part of, 518281687Sjkimif any, in all upper-case letters. For example, it might be @samp{GCC} 519271440Sjkimor @samp{BINUTILS}. If the package is part of a vendor-supplied 520271440Sjkimoperating system, code the component name as @samp{0}. 521271440Sjkim 522271440SjkimFor example, here is the definition used for VAX/VMS: 523271440Sjkim 524271440Sjkim@example 525281687Sjkim#define INCLUDE_DEFAULTS \ 526281687Sjkim@{ \ 527271440Sjkim @{ "GNU_GXX_INCLUDE:", "G++", 1, 1@}, \ 528271440Sjkim @{ "GNU_CC_INCLUDE:", "GCC", 0, 0@}, \ 529271440Sjkim @{ "SYS$SYSROOT:[SYSLIB.]", 0, 0, 0@}, \ 530271440Sjkim @{ ".", 0, 0, 0@}, \ 531271440Sjkim @{ 0, 0, 0, 0@} \ 532271440Sjkim@} 533271440Sjkim@end example 534271440Sjkim@end table 535271440Sjkim 536271440SjkimHere is the order of prefixes tried for exec files: 537271440Sjkim 538271440Sjkim@enumerate 539271440Sjkim@item 540271440SjkimAny prefixes specified by the user with @option{-B}. 541271440Sjkim 542271440Sjkim@item 543271440SjkimThe environment variable @code{GCC_EXEC_PREFIX}, if any. 544271440Sjkim 545271440Sjkim@item 546271440SjkimThe directories specified by the environment variable @code{COMPILER_PATH}. 547271440Sjkim 548271440Sjkim@item 549271440SjkimThe macro @code{STANDARD_EXEC_PREFIX}. 550271440Sjkim 551271440Sjkim@item 552271440Sjkim@file{/usr/lib/gcc/}. 553271440Sjkim 554271440Sjkim@item 555271440SjkimThe macro @code{MD_EXEC_PREFIX}, if any. 556271440Sjkim@end enumerate 557271440Sjkim 558271440SjkimHere is the order of prefixes tried for startfiles: 559271440Sjkim 560271440Sjkim@enumerate 561271440Sjkim@item 562271440SjkimAny prefixes specified by the user with @option{-B}. 563271440Sjkim 564271440Sjkim@item 565271440SjkimThe environment variable @code{GCC_EXEC_PREFIX}, if any. 566271440Sjkim 567271440Sjkim@item 568271440SjkimThe directories specified by the environment variable @code{LIBRARY_PATH} 569271440Sjkim(or port-specific name; native only, cross compilers do not use this). 570271440Sjkim 571271440Sjkim@item 572281687SjkimThe macro @code{STANDARD_EXEC_PREFIX}. 573281075Sdim 574281075Sdim@item 575271440Sjkim@file{/usr/lib/gcc/}. 576271440Sjkim 577271440Sjkim@item 578271440SjkimThe macro @code{MD_EXEC_PREFIX}, if any. 579271440Sjkim 580271440Sjkim@item 581271440SjkimThe macro @code{MD_STARTFILE_PREFIX}, if any. 582271440Sjkim 583271440Sjkim@item 584271440SjkimThe macro @code{STANDARD_STARTFILE_PREFIX}. 585271440Sjkim 586271440Sjkim@item 587271440Sjkim@file{/lib/}. 588271440Sjkim 589271440Sjkim@item 590271440Sjkim@file{/usr/lib/}. 591271440Sjkim@end enumerate 592271440Sjkim 593271440Sjkim@node Run-time Target 594271440Sjkim@section Run-time Target Specification 595271440Sjkim@cindex run-time target specification 596271440Sjkim@cindex predefined macros 597271440Sjkim@cindex target specifications 598281075Sdim 599271440Sjkim@c prevent bad page break with this line 600271440SjkimHere are run-time target specifications. 601271440Sjkim 602271440Sjkim@table @code 603271440Sjkim@findex TARGET_CPU_CPP_BUILTINS 604271440Sjkim@item TARGET_CPU_CPP_BUILTINS() 605271440SjkimThis function-like macro expands to a block of code that defines 606306536Sjkimbuilt-in preprocessor macros and assertions for the target cpu, using 607281687Sjkimthe functions @code{builtin_define}, @code{builtin_define_std} and 608271440Sjkim@code{builtin_assert} defined in @file{c-common.c}. When the front end 609271440Sjkimcalls this macro it provides a trailing semicolon, and since it has 610306536Sjkimfinished command line option processing your code can use those 611306536Sjkimresults freely. 612306536Sjkim 613306536Sjkim@code{builtin_assert} takes a string in the form you pass to the 614306536Sjkimcommand-line option @option{-A}, such as @code{cpu=mips}, and creates 615306536Sjkimthe assertion. @code{builtin_define} takes a string in the form 616306536Sjkimaccepted by option @option{-D} and unconditionally defines the macro. 617306536Sjkim 618306536Sjkim@code{builtin_define_std} takes a string representing the name of an 619306536Sjkimobject-like macro. If it doesn't lie in the user's namespace, 620306536Sjkim@code{builtin_define_std} defines it unconditionally. Otherwise, it 621306536Sjkimdefines a version with two leading underscores, and another version 622306536Sjkimwith two leading and trailing underscores, and defines the original 623306536Sjkimonly if an ISO standard was not requested on the command line. For 624271440Sjkimexample, passing @code{unix} defines @code{__unix}, @code{__unix__} 625271440Sjkimand possibly @code{unix}; passing @code{_mips} defines @code{__mips}, 626306536Sjkim@code{__mips__} and possibly @code{_mips}, and passing @code{_ABI64} 627306536Sjkimdefines only @code{_ABI64}. 628306536Sjkim 629306536SjkimYou can also test for the C dialect being compiled. The variable 630306536Sjkim@code{c_language} is set to one of @code{clk_c}, @code{clk_cplusplus} 631306536Sjkimor @code{clk_objective_c}. Note that if we are preprocessing 632306536Sjkimassembler, this variable will be @code{clk_c} but the function-like 633271440Sjkimmacro @code{preprocessing_asm_p()} will return true, so you might want 634271440Sjkimto check for that first. If you need to check for strict ANSI, the 635306536Sjkimvariable @code{flag_iso} can be used. The function-like macro 636306536Sjkim@code{preprocessing_trad_p()} can be used to check for traditional 637306536Sjkimpreprocessing. 638306536Sjkim 639306536SjkimWith @code{TARGET_OS_CPP_BUILTINS} this macro obsoletes the 640306536Sjkim@code{CPP_PREDEFINES} target macro. 641306536Sjkim 642306536Sjkim@findex TARGET_OS_CPP_BUILTINS 643306536Sjkim@item TARGET_OS_CPP_BUILTINS() 644306536SjkimSimilarly to @code{TARGET_CPU_CPP_BUILTINS} but this macro is optional 645306536Sjkimand is used for the target operating system instead. 646306536Sjkim 647271440SjkimWith @code{TARGET_CPU_CPP_BUILTINS} this macro obsoletes the 648306536Sjkim@code{CPP_PREDEFINES} target macro. 649306536Sjkim 650306536Sjkim@findex CPP_PREDEFINES 651306536Sjkim@item CPP_PREDEFINES 652271440SjkimDefine this to be a string constant containing @option{-D} options to 653271440Sjkimdefine the predefined macros that identify this machine and system. 654271440SjkimThese macros will be predefined unless the @option{-ansi} option (or a 655306536Sjkim@option{-std} option for strict ISO C conformance) is specified. 656306536Sjkim 657306536SjkimIn addition, a parallel set of macros are predefined, whose names are 658306536Sjkimmade by appending @samp{__} at the beginning and at the end. These 659306536Sjkim@samp{__} macros are permitted by the ISO standard, so they are 660306536Sjkimpredefined regardless of whether @option{-ansi} or a @option{-std} option 661306536Sjkimis specified. 662306536Sjkim 663306536SjkimFor example, on the Sun, one can use the following value: 664271440Sjkim 665306536Sjkim@smallexample 666306536Sjkim"-Dmc68000 -Dsun -Dunix" 667306536Sjkim@end smallexample 668306536Sjkim 669306536SjkimThe result is to define the macros @code{__mc68000__}, @code{__sun__} 670306536Sjkimand @code{__unix__} unconditionally, and the macros @code{mc68000}, 671306536Sjkim@code{sun} and @code{unix} provided @option{-ansi} is not specified. 672306536Sjkim 673306536Sjkim@findex extern int target_flags 674271440Sjkim@item extern int target_flags; 675271440SjkimThis declaration should be present. 676271440Sjkim 677271440Sjkim@cindex optional hardware or system features 678271440Sjkim@cindex features, optional, in system conventions 679271440Sjkim@item TARGET_@dots{} 680271440SjkimThis series of macros is to allow compiler command arguments to 681271440Sjkimenable or disable the use of optional features of the target machine. 682271440SjkimFor example, one machine description serves both the 68000 and 683271440Sjkimthe 68020; a command argument tells the compiler whether it should 684271440Sjkimuse 68020-only instructions or not. This command argument works 685271440Sjkimby means of a macro @code{TARGET_68020} that tests a bit in 686271440Sjkim@code{target_flags}. 687271440Sjkim 688271440SjkimDefine a macro @code{TARGET_@var{featurename}} for each such option. 689306536SjkimIts definition should test a bit in @code{target_flags}. It is 690306536Sjkimrecommended that a helper macro @code{TARGET_MASK_@var{featurename}} 691271440Sjkimis defined for each bit-value to test, and used in 692271440Sjkim@code{TARGET_@var{featurename}} and @code{TARGET_SWITCHES}. For 693306536Sjkimexample: 694306536Sjkim 695271440Sjkim@smallexample 696271440Sjkim#define TARGET_MASK_68020 1 697306536Sjkim#define TARGET_68020 (target_flags & TARGET_MASK_68020) 698306536Sjkim@end smallexample 699306536Sjkim 700306536SjkimOne place where these macros are used is in the condition-expressions 701306536Sjkimof instruction patterns. Note how @code{TARGET_68020} appears 702306536Sjkimfrequently in the 68000 machine description file, @file{m68k.md}. 703306536SjkimAnother place they are used is in the definitions of the other 704271440Sjkimmacros in the @file{@var{machine}.h} file. 705271440Sjkim 706306536Sjkim@findex TARGET_SWITCHES 707306536Sjkim@item TARGET_SWITCHES 708306536SjkimThis macro defines names of command options to set and clear 709306536Sjkimbits in @code{target_flags}. Its definition is an initializer 710306536Sjkimwith a subgrouping for each command option. 711306536Sjkim 712306536SjkimEach subgrouping contains a string constant, that defines the option 713306536Sjkimname, a number, which contains the bits to set in 714306536Sjkim@code{target_flags}, and a second string which is the description 715306536Sjkimdisplayed by @option{--help}. If the number is negative then the bits specified 716306536Sjkimby the number are cleared instead of being set. If the description 717271440Sjkimstring is present but empty, then no help information will be displayed 718271440Sjkimfor that option, but it will not count as an undocumented option. The 719271440Sjkimactual option name is made by appending @samp{-m} to the specified name. 720306536SjkimNon-empty description strings should be marked with @code{N_(@dots{})} for 721306536Sjkim@command{xgettext}. Please do not mark empty strings because the empty 722306536Sjkimstring is reserved by GNU gettext. @code{gettext("")} returns the header entry 723306536Sjkimof the message catalog with meta information, not the empty string. 724306536Sjkim 725306536SjkimIn addition to the description for @option{--help}, 726306536Sjkimmore detailed documentation for each option should be added to 727271440Sjkim@file{invoke.texi}. 728271440Sjkim 729271440SjkimOne of the subgroupings should have a null string. The number in 730306536Sjkimthis grouping is the default value for @code{target_flags}. Any 731306536Sjkimtarget options act starting with that value. 732306536Sjkim 733306536SjkimHere is an example which defines @option{-m68000} and @option{-m68020} 734306536Sjkimwith opposite meanings, and picks the latter as the default: 735306536Sjkim 736306536Sjkim@smallexample 737306536Sjkim#define TARGET_SWITCHES \ 738306536Sjkim @{ @{ "68020", TARGET_MASK_68020, "" @}, \ 739306536Sjkim @{ "68000", -TARGET_MASK_68020, \ 740271440Sjkim N_("Compile for the 68000") @}, \ 741271440Sjkim @{ "", TARGET_MASK_68020, "" @}@} 742271440Sjkim@end smallexample 743271440Sjkim 744271440Sjkim@findex TARGET_OPTIONS 745271440Sjkim@item TARGET_OPTIONS 746271440SjkimThis macro is similar to @code{TARGET_SWITCHES} but defines names of command 747271440Sjkimoptions that have values. Its definition is an initializer with a 748271440Sjkimsubgrouping for each command option. 749271440Sjkim 750271440SjkimEach subgrouping contains a string constant, that defines the fixed part 751271440Sjkimof the option name, the address of a variable, and a description string. 752271440SjkimNon-empty description strings should be marked with @code{N_(@dots{})} for 753271440Sjkim@command{xgettext}. Please do not mark empty strings because the empty 754271440Sjkimstring is reserved by GNU gettext. @code{gettext("")} returns the header entry 755306536Sjkimof the message catalog with meta information, not the empty string. 756306536Sjkim 757306536SjkimThe variable, type @code{char *}, is set to the variable part of the 758306536Sjkimgiven option if the fixed part matches. The actual option name is made 759306536Sjkimby appending @samp{-m} to the specified name. Again, each option should 760306536Sjkimalso be documented in @file{invoke.texi}. 761306536Sjkim 762306536SjkimHere is an example which defines @option{-mshort-data-@var{number}}. If the 763306536Sjkimgiven option is @option{-mshort-data-512}, the variable @code{m88k_short_data} 764306536Sjkimwill be set to the string @code{"512"}. 765306536Sjkim 766306536Sjkim@smallexample 767306536Sjkimextern char *m88k_short_data; 768306536Sjkim#define TARGET_OPTIONS \ 769306536Sjkim @{ @{ "short-data-", &m88k_short_data, \ 770306536Sjkim N_("Specify the size of the short data section") @} @} 771306536Sjkim@end smallexample 772306536Sjkim 773306536Sjkim@findex TARGET_VERSION 774306536Sjkim@item TARGET_VERSION 775306536SjkimThis macro is a C statement to print on @code{stderr} a string 776306536Sjkimdescribing the particular machine description choice. Every machine 777271440Sjkimdescription should define @code{TARGET_VERSION}. For example: 778271440Sjkim 779271440Sjkim@smallexample 780271440Sjkim#ifdef MOTOROLA 781271440Sjkim#define TARGET_VERSION \ 782271440Sjkim fprintf (stderr, " (68k, Motorola syntax)"); 783271440Sjkim#else 784271440Sjkim#define TARGET_VERSION \ 785271440Sjkim fprintf (stderr, " (68k, MIT syntax)"); 786271440Sjkim#endif 787271440Sjkim@end smallexample 788271440Sjkim 789271440Sjkim@findex OVERRIDE_OPTIONS 790271440Sjkim@item OVERRIDE_OPTIONS 791271440SjkimSometimes certain combinations of command options do not make sense on 792271440Sjkima particular target machine. You can define a macro 793271440Sjkim@code{OVERRIDE_OPTIONS} to take account of this. This macro, if 794271440Sjkimdefined, is executed once just after all the command options have been 795271440Sjkimparsed. 796271440Sjkim 797271440SjkimDon't use this macro to turn on various extra optimizations for 798271440Sjkim@option{-O}. That is what @code{OPTIMIZATION_OPTIONS} is for. 799271440Sjkim 800271440Sjkim@findex OPTIMIZATION_OPTIONS 801271440Sjkim@item OPTIMIZATION_OPTIONS (@var{level}, @var{size}) 802271440SjkimSome machines may desire to change what optimizations are performed for 803271440Sjkimvarious optimization levels. This macro, if defined, is executed once 804271440Sjkimjust after the optimization level is determined and before the remainder 805271440Sjkimof the command options have been parsed. Values set in this macro are 806271440Sjkimused as the default values for the other command line options. 807271440Sjkim 808271440Sjkim@var{level} is the optimization level specified; 2 if @option{-O2} is 809271440Sjkimspecified, 1 if @option{-O} is specified, and 0 if neither is specified. 810271440Sjkim 811271440Sjkim@var{size} is nonzero if @option{-Os} is specified and zero otherwise. 812271440Sjkim 813271440SjkimYou should not use this macro to change options that are not 814271440Sjkimmachine-specific. These should uniformly selected by the same 815271440Sjkimoptimization level on all supported machines. Use this macro to enable 816271440Sjkimmachine-specific optimizations. 817271440Sjkim 818271440Sjkim@strong{Do not examine @code{write_symbols} in 819271440Sjkimthis macro!} The debugging options are not supposed to alter the 820271440Sjkimgenerated code. 821271440Sjkim 822271440Sjkim@findex CAN_DEBUG_WITHOUT_FP 823271440Sjkim@item CAN_DEBUG_WITHOUT_FP 824271440SjkimDefine this macro if debugging can be performed even without a frame 825271440Sjkimpointer. If this macro is defined, GCC will turn on the 826271440Sjkim@option{-fomit-frame-pointer} option whenever @option{-O} is specified. 827271440Sjkim@end table 828271440Sjkim 829271440Sjkim@node Per-Function Data 830271440Sjkim@section Defining data structures for per-function information. 831271440Sjkim@cindex per-function data 832271440Sjkim@cindex data structures 833271440Sjkim 834271440SjkimIf the target needs to store information on a per-function basis, GCC 835271440Sjkimprovides a macro and a couple of variables to allow this. Note, just 836271440Sjkimusing statics to store the information is a bad idea, since GCC supports 837271440Sjkimnested functions, so you can be halfway through encoding one function 838271440Sjkimwhen another one comes along. 839271440Sjkim 840271440SjkimGCC defines a data structure called @code{struct function} which 841271440Sjkimcontains all of the data specific to an individual function. This 842271440Sjkimstructure contains a field called @code{machine} whose type is 843271440Sjkim@code{struct machine_function *}, which can be used by targets to point 844271440Sjkimto their own specific data. 845271440Sjkim 846271440SjkimIf a target needs per-function specific data it should define the type 847271440Sjkim@code{struct machine_function} and also the macro @code{INIT_EXPANDERS}. 848271440SjkimThis macro should be used to initialize the function pointer 849306536Sjkim@code{init_machine_status}. This pointer is explained below. 850306536Sjkim 851271440SjkimOne typical use of per-function, target specific data is to create an 852271440SjkimRTX to hold the register containing the function's return address. This 853306536SjkimRTX can then be used to implement the @code{__builtin_return_address} 854306536Sjkimfunction, for level 0. 855306536Sjkim 856306536SjkimNote---earlier implementations of GCC used a single data area to hold 857306536Sjkimall of the per-function information. Thus when processing of a nested 858271440Sjkimfunction began the old per-function data had to be pushed onto a 859271440Sjkimstack, and when the processing was finished, it had to be popped off the 860271440Sjkimstack. GCC used to provide function pointers called 861306536Sjkim@code{save_machine_status} and @code{restore_machine_status} to handle 862306536Sjkimthe saving and restoring of the target specific information. Since the 863306536Sjkimsingle data area approach is no longer used, these pointers are no 864306536Sjkimlonger supported. 865306536Sjkim 866271440SjkimThe macro and function pointers are described below. 867271440Sjkim 868306536Sjkim@table @code 869306536Sjkim@findex INIT_EXPANDERS 870306536Sjkim@item INIT_EXPANDERS 871306536SjkimMacro called to initialize any target specific information. This macro 872306536Sjkimis called once per function, before generation of any RTL has begun. 873271440SjkimThe intention of this macro is to allow the initialization of the 874271440Sjkimfunction pointers below. 875271440Sjkim 876306536Sjkim@findex init_machine_status 877306536Sjkim@item init_machine_status 878271440SjkimThis is a @code{void (*)(struct function *)} function pointer. If this 879271440Sjkimpointer is non-@code{NULL} it will be called once per function, before function 880306536Sjkimcompilation starts, in order to allow the target to perform any target 881306536Sjkimspecific initialization of the @code{struct function} structure. It is 882271440Sjkimintended that this would be used to initialize the @code{machine} of 883271440Sjkimthat structure. 884271440Sjkim 885306536Sjkim@code{struct machine_function} structures are expected to be freed by GC. 886306536SjkimGenerally, any memory that they reference must be allocated by using 887306536Sjkim@code{ggc_alloc}, including the structure itself. 888271440Sjkim 889306536Sjkim@end table 890306536Sjkim 891306536Sjkim@node Storage Layout 892306536Sjkim@section Storage Layout 893271440Sjkim@cindex storage layout 894271440Sjkim 895271440SjkimNote that the definitions of the macros in this table which are sizes or 896306536Sjkimalignments measured in bits do not need to be constant. They can be C 897306536Sjkimexpressions that refer to static variables, such as the @code{target_flags}. 898306536Sjkim@xref{Run-time Target}. 899306536Sjkim 900271440Sjkim@table @code 901271440Sjkim@findex BITS_BIG_ENDIAN 902271440Sjkim@item BITS_BIG_ENDIAN 903306536SjkimDefine this macro to have the value 1 if the most significant bit in a 904271440Sjkimbyte has the lowest number; otherwise define it to have the value zero. 905271440SjkimThis means that bit-field instructions count from the most significant 906271440Sjkimbit. If the machine has no bit-field instructions, then this must still 907271440Sjkimbe defined, but it doesn't matter which value it is defined to. This 908271440Sjkimmacro need not be a constant. 909271440Sjkim 910271440SjkimThis macro does not affect the way structure fields are packed into 911271440Sjkimbytes or words; that is controlled by @code{BYTES_BIG_ENDIAN}. 912271440Sjkim 913271440Sjkim@findex BYTES_BIG_ENDIAN 914271440Sjkim@item BYTES_BIG_ENDIAN 915271440SjkimDefine this macro to have the value 1 if the most significant byte in a 916271440Sjkimword has the lowest number. This macro need not be a constant. 917271440Sjkim 918271440Sjkim@findex WORDS_BIG_ENDIAN 919271440Sjkim@item WORDS_BIG_ENDIAN 920271440SjkimDefine this macro to have the value 1 if, in a multiword object, the 921271440Sjkimmost significant word has the lowest number. This applies to both 922271440Sjkimmemory locations and registers; GCC fundamentally assumes that the 923271440Sjkimorder of words in memory is the same as the order in registers. This 924271440Sjkimmacro need not be a constant. 925271440Sjkim 926271440Sjkim@findex LIBGCC2_WORDS_BIG_ENDIAN 927271440Sjkim@item LIBGCC2_WORDS_BIG_ENDIAN 928271440SjkimDefine this macro if @code{WORDS_BIG_ENDIAN} is not constant. This must be a 929271440Sjkimconstant value with the same meaning as @code{WORDS_BIG_ENDIAN}, which will be 930271440Sjkimused only when compiling @file{libgcc2.c}. Typically the value will be set 931271440Sjkimbased on preprocessor defines. 932306536Sjkim 933306536Sjkim@findex FLOAT_WORDS_BIG_ENDIAN 934271440Sjkim@item FLOAT_WORDS_BIG_ENDIAN 935306536SjkimDefine this macro to have the value 1 if @code{DFmode}, @code{XFmode} or 936306536Sjkim@code{TFmode} floating point numbers are stored in memory with the word 937271440Sjkimcontaining the sign bit at the lowest address; otherwise define it to 938271440Sjkimhave the value 0. This macro need not be a constant. 939271440Sjkim 940306536SjkimYou need not define this macro if the ordering is the same as for 941306536Sjkimmulti-word integers. 942306536Sjkim 943306536Sjkim@findex BITS_PER_UNIT 944306536Sjkim@item BITS_PER_UNIT 945306536SjkimDefine this macro to be the number of bits in an addressable storage 946306536Sjkimunit (byte). If you do not define this macro the default is 8. 947306536Sjkim 948306536Sjkim@findex BITS_PER_WORD 949271440Sjkim@item BITS_PER_WORD 950271440SjkimNumber of bits in a word. If you do not define this macro, the default 951306536Sjkimis @code{BITS_PER_UNIT * UNITS_PER_WORD}. 952306536Sjkim 953306536Sjkim@findex MAX_BITS_PER_WORD 954306536Sjkim@item MAX_BITS_PER_WORD 955271440SjkimMaximum number of bits in a word. If this is undefined, the default is 956306536Sjkim@code{BITS_PER_WORD}. Otherwise, it is the constant value that is the 957306536Sjkimlargest value that @code{BITS_PER_WORD} can have at run-time. 958271440Sjkim 959271440Sjkim@findex UNITS_PER_WORD 960271440Sjkim@item UNITS_PER_WORD 961306536SjkimNumber of storage units in a word; normally 4. 962306536Sjkim 963306536Sjkim@findex MIN_UNITS_PER_WORD 964306536Sjkim@item MIN_UNITS_PER_WORD 965306536SjkimMinimum number of units in a word. If this is undefined, the default is 966306536Sjkim@code{UNITS_PER_WORD}. Otherwise, it is the constant value that is the 967271440Sjkimsmallest value that @code{UNITS_PER_WORD} can have at run-time. 968306536Sjkim 969306536Sjkim@findex POINTER_SIZE 970306536Sjkim@item POINTER_SIZE 971271440SjkimWidth of a pointer, in bits. You must specify a value no wider than the 972271440Sjkimwidth of @code{Pmode}. If it is not equal to the width of @code{Pmode}, 973306536Sjkimyou must define @code{POINTERS_EXTEND_UNSIGNED}. If you do not specify 974306536Sjkima value the default is @code{BITS_PER_WORD}. 975271440Sjkim 976306536Sjkim@findex POINTERS_EXTEND_UNSIGNED 977306536Sjkim@item POINTERS_EXTEND_UNSIGNED 978306536SjkimA C expression whose value is greater than zero if pointers that need to be 979271440Sjkimextended from being @code{POINTER_SIZE} bits wide to @code{Pmode} are to 980271440Sjkimbe zero-extended and zero if they are to be sign-extended. If the value 981271440Sjkimis less then zero then there must be an "ptr_extend" instruction that 982306536Sjkimextends a pointer from @code{POINTER_SIZE} to @code{Pmode}. 983306536Sjkim 984271440SjkimYou need not define this macro if the @code{POINTER_SIZE} is equal 985271440Sjkimto the width of @code{Pmode}. 986306536Sjkim 987306536Sjkim@findex PROMOTE_MODE 988271440Sjkim@item PROMOTE_MODE (@var{m}, @var{unsignedp}, @var{type}) 989271440SjkimA macro to update @var{m} and @var{unsignedp} when an object whose type 990271440Sjkimis @var{type} and which has the specified mode and signedness is to be 991306536Sjkimstored in a register. This macro is only called when @var{type} is a 992306536Sjkimscalar type. 993306536Sjkim 994306536SjkimOn most RISC machines, which only have operations that operate on a full 995306536Sjkimregister, define this macro to set @var{m} to @code{word_mode} if 996306536Sjkim@var{m} is an integer mode narrower than @code{BITS_PER_WORD}. In most 997306536Sjkimcases, only integer modes should be widened because wider-precision 998306536Sjkimfloating-point operations are usually more expensive than their narrower 999306536Sjkimcounterparts. 1000306536Sjkim 1001271440SjkimFor most machines, the macro definition does not change @var{unsignedp}. 1002271440SjkimHowever, some machines, have instructions that preferentially handle 1003306536Sjkimeither signed or unsigned quantities of certain modes. For example, on 1004306536Sjkimthe DEC Alpha, 32-bit loads from memory and 32-bit add instructions 1005306536Sjkimsign-extend the result to 64 bits. On such machines, set 1006271440Sjkim@var{unsignedp} according to which kind of extension is more efficient. 1007271440Sjkim 1008306536SjkimDo not define this macro if it would never modify @var{m}. 1009306536Sjkim 1010306536Sjkim@findex PROMOTE_FUNCTION_ARGS 1011306536Sjkim@item PROMOTE_FUNCTION_ARGS 1012306536SjkimDefine this macro if the promotion described by @code{PROMOTE_MODE} 1013306536Sjkimshould also be done for outgoing function arguments. 1014306536Sjkim 1015271440Sjkim@findex PROMOTE_FUNCTION_RETURN 1016271440Sjkim@item PROMOTE_FUNCTION_RETURN 1017271440SjkimDefine this macro if the promotion described by @code{PROMOTE_MODE} 1018306536Sjkimshould also be done for the return value of functions. 1019306536Sjkim 1020306536SjkimIf this macro is defined, @code{FUNCTION_VALUE} must perform the same 1021271440Sjkimpromotions done by @code{PROMOTE_MODE}. 1022271440Sjkim 1023306536Sjkim@findex PROMOTE_FOR_CALL_ONLY 1024271440Sjkim@item PROMOTE_FOR_CALL_ONLY 1025271440SjkimDefine this macro if the promotion described by @code{PROMOTE_MODE} 1026271440Sjkimshould @emph{only} be performed for outgoing function arguments or 1027306536Sjkimfunction return values, as specified by @code{PROMOTE_FUNCTION_ARGS} 1028306536Sjkimand @code{PROMOTE_FUNCTION_RETURN}, respectively. 1029306536Sjkim 1030306536Sjkim@findex PARM_BOUNDARY 1031306536Sjkim@item PARM_BOUNDARY 1032306536SjkimNormal alignment required for function parameters on the stack, in 1033306536Sjkimbits. All stack parameters receive at least this much alignment 1034306536Sjkimregardless of data type. On most machines, this is the same as the 1035306536Sjkimsize of an integer. 1036306536Sjkim 1037306536Sjkim@findex STACK_BOUNDARY 1038271440Sjkim@item STACK_BOUNDARY 1039271440SjkimDefine this macro to the minimum alignment enforced by hardware for the 1040271440Sjkimstack pointer on this machine. The definition is a C expression for the 1041306536Sjkimdesired alignment (measured in bits). This value is used as a default 1042306536Sjkimif @code{PREFERRED_STACK_BOUNDARY} is not defined. On most machines, 1043271440Sjkimthis should be the same as @code{PARM_BOUNDARY}. 1044306536Sjkim 1045306536Sjkim@findex PREFERRED_STACK_BOUNDARY 1046271440Sjkim@item PREFERRED_STACK_BOUNDARY 1047306536SjkimDefine this macro if you wish to preserve a certain alignment for the 1048271440Sjkimstack pointer, greater than what the hardware enforces. The definition 1049271440Sjkimis a C expression for the desired alignment (measured in bits). This 1050271440Sjkimmacro must evaluate to a value equal to or larger than 1051306536Sjkim@code{STACK_BOUNDARY}. 1052306536Sjkim 1053306536Sjkim@findex FORCE_PREFERRED_STACK_BOUNDARY_IN_MAIN 1054306536Sjkim@item FORCE_PREFERRED_STACK_BOUNDARY_IN_MAIN 1055271440SjkimA C expression that evaluates true if @code{PREFERRED_STACK_BOUNDARY} is 1056271440Sjkimnot guaranteed by the runtime and we should emit code to align the stack 1057306536Sjkimat the beginning of @code{main}. 1058306536Sjkim 1059271440Sjkim@cindex @code{PUSH_ROUNDING}, interaction with @code{PREFERRED_STACK_BOUNDARY} 1060271440SjkimIf @code{PUSH_ROUNDING} is not defined, the stack will always be aligned 1061271440Sjkimto the specified boundary. If @code{PUSH_ROUNDING} is defined and specifies 1062271440Sjkima less strict alignment than @code{PREFERRED_STACK_BOUNDARY}, the stack may 1063271440Sjkimbe momentarily unaligned while pushing arguments. 1064271440Sjkim 1065271440Sjkim@findex FUNCTION_BOUNDARY 1066271440Sjkim@item FUNCTION_BOUNDARY 1067271440SjkimAlignment required for a function entry point, in bits. 1068271440Sjkim 1069306536Sjkim@findex BIGGEST_ALIGNMENT 1070306536Sjkim@item BIGGEST_ALIGNMENT 1071306536SjkimBiggest alignment that any data type can require on this machine, in bits. 1072306536Sjkim 1073306536Sjkim@findex MINIMUM_ATOMIC_ALIGNMENT 1074306536Sjkim@item MINIMUM_ATOMIC_ALIGNMENT 1075306536SjkimIf defined, the smallest alignment, in bits, that can be given to an 1076306536Sjkimobject that can be referenced in one operation, without disturbing any 1077306536Sjkimnearby object. Normally, this is @code{BITS_PER_UNIT}, but may be larger 1078306536Sjkimon machines that don't have byte or half-word store operations. 1079306536Sjkim 1080306536Sjkim@findex BIGGEST_FIELD_ALIGNMENT 1081306536Sjkim@item BIGGEST_FIELD_ALIGNMENT 1082271440SjkimBiggest alignment that any structure or union field can require on this 1083271440Sjkimmachine, in bits. If defined, this overrides @code{BIGGEST_ALIGNMENT} for 1084271440Sjkimstructure and union fields only, unless the field alignment has been set 1085271440Sjkimby the @code{__attribute__ ((aligned (@var{n})))} construct. 1086271440Sjkim 1087271440Sjkim@findex ADJUST_FIELD_ALIGN 1088271440Sjkim@item ADJUST_FIELD_ALIGN (@var{field}, @var{computed}) 1089271440SjkimAn expression for the alignment of a structure field @var{field} if the 1090271440Sjkimalignment computed in the usual way (including applying of 1091271440Sjkim@code{BIGGEST_ALIGNMENT} and @code{BIGGEST_FIELD_ALIGNMENT} to the 1092271440Sjkimalignment) is @var{computed}. It overrides alignment only if the 1093271440Sjkimfield alignment has not been set by the 1094271440Sjkim@code{__attribute__ ((aligned (@var{n})))} construct. 1095271440Sjkim 1096271440Sjkim@findex MAX_OFILE_ALIGNMENT 1097271440Sjkim@item MAX_OFILE_ALIGNMENT 1098271440SjkimBiggest alignment supported by the object file format of this machine. 1099271440SjkimUse this macro to limit the alignment which can be specified using the 1100271440Sjkim@code{__attribute__ ((aligned (@var{n})))} construct. If not defined, 1101271440Sjkimthe default value is @code{BIGGEST_ALIGNMENT}. 1102271440Sjkim 1103271440Sjkim@findex DATA_ALIGNMENT 1104271440Sjkim@item DATA_ALIGNMENT (@var{type}, @var{basic-align}) 1105271440SjkimIf defined, a C expression to compute the alignment for a variable in 1106271440Sjkimthe static store. @var{type} is the data type, and @var{basic-align} is 1107271440Sjkimthe alignment that the object would ordinarily have. The value of this 1108271440Sjkimmacro is used instead of that alignment to align the object. 1109271440Sjkim 1110306536SjkimIf this macro is not defined, then @var{basic-align} is used. 1111306536Sjkim 1112306536Sjkim@findex strcpy 1113306536SjkimOne use of this macro is to increase alignment of medium-size data to 1114306536Sjkimmake it all fit in fewer cache lines. Another is to cause character 1115306536Sjkimarrays to be word-aligned so that @code{strcpy} calls that copy 1116306536Sjkimconstants to character arrays can be done inline. 1117306536Sjkim 1118306536Sjkim@findex CONSTANT_ALIGNMENT 1119271440Sjkim@item CONSTANT_ALIGNMENT (@var{constant}, @var{basic-align}) 1120271440SjkimIf defined, a C expression to compute the alignment given to a constant 1121271440Sjkimthat is being placed in memory. @var{constant} is the constant and 1122271440Sjkim@var{basic-align} is the alignment that the object would ordinarily 1123271440Sjkimhave. The value of this macro is used instead of that alignment to 1124271440Sjkimalign the object. 1125271440Sjkim 1126271440SjkimIf this macro is not defined, then @var{basic-align} is used. 1127271440Sjkim 1128306536SjkimThe typical use of this macro is to increase alignment for string 1129306536Sjkimconstants to be word aligned so that @code{strcpy} calls that copy 1130271440Sjkimconstants can be done inline. 1131271440Sjkim 1132271440Sjkim@findex LOCAL_ALIGNMENT 1133306536Sjkim@item LOCAL_ALIGNMENT (@var{type}, @var{basic-align}) 1134271440SjkimIf defined, a C expression to compute the alignment for a variable in 1135271440Sjkimthe local store. @var{type} is the data type, and @var{basic-align} is 1136271440Sjkimthe alignment that the object would ordinarily have. The value of this 1137271440Sjkimmacro is used instead of that alignment to align the object. 1138271440Sjkim 1139271440SjkimIf this macro is not defined, then @var{basic-align} is used. 1140271440Sjkim 1141271440SjkimOne use of this macro is to increase alignment of medium-size data to 1142271440Sjkimmake it all fit in fewer cache lines. 1143271440Sjkim 1144271440Sjkim@findex EMPTY_FIELD_BOUNDARY 1145271440Sjkim@item EMPTY_FIELD_BOUNDARY 1146306536SjkimAlignment in bits to be given to a structure bit-field that follows an 1147306536Sjkimempty field such as @code{int : 0;}. 1148271440Sjkim 1149271440SjkimNote that @code{PCC_BITFIELD_TYPE_MATTERS} also affects the alignment 1150271440Sjkimthat results from an empty field. 1151306536Sjkim 1152271440Sjkim@findex STRUCTURE_SIZE_BOUNDARY 1153271440Sjkim@item STRUCTURE_SIZE_BOUNDARY 1154271440SjkimNumber of bits which any structure or union's size must be a multiple of. 1155271440SjkimEach structure or union's size is rounded up to a multiple of this. 1156271440Sjkim 1157271440SjkimIf you do not define this macro, the default is the same as 1158271440Sjkim@code{BITS_PER_UNIT}. 1159271440Sjkim 1160271440Sjkim@findex STRICT_ALIGNMENT 1161271440Sjkim@item STRICT_ALIGNMENT 1162271440SjkimDefine this macro to be the value 1 if instructions will fail to work 1163271440Sjkimif given data not on the nominal alignment. If instructions will merely 1164271440Sjkimgo slower in that case, define this macro as 0. 1165271440Sjkim 1166271440Sjkim@findex PCC_BITFIELD_TYPE_MATTERS 1167271440Sjkim@item PCC_BITFIELD_TYPE_MATTERS 1168271440SjkimDefine this if you wish to imitate the way many other C compilers handle 1169271440Sjkimalignment of bit-fields and the structures that contain them. 1170271440Sjkim 1171271440SjkimThe behavior is that the type written for a bit-field (@code{int}, 1172271440Sjkim@code{short}, or other integer type) imposes an alignment for the 1173271440Sjkimentire structure, as if the structure really did contain an ordinary 1174271440Sjkimfield of that type. In addition, the bit-field is placed within the 1175271440Sjkimstructure so that it would fit within such a field, not crossing a 1176306536Sjkimboundary for it. 1177306536Sjkim 1178306536SjkimThus, on most machines, a bit-field whose type is written as @code{int} 1179306536Sjkimwould not cross a four-byte boundary, and would force four-byte 1180306536Sjkimalignment for the whole structure. (The alignment used may not be four 1181306536Sjkimbytes; it is controlled by the other alignment parameters.) 1182306536Sjkim 1183306536SjkimIf the macro is defined, its definition should be a C expression; 1184306536Sjkima nonzero value for the expression enables this behavior. 1185306536Sjkim 1186306536SjkimNote that if this macro is not defined, or its value is zero, some 1187306536Sjkimbit-fields may cross more than one alignment boundary. The compiler can 1188306536Sjkimsupport such references if there are @samp{insv}, @samp{extv}, and 1189306536Sjkim@samp{extzv} insns that can directly reference memory. 1190306536Sjkim 1191306536SjkimThe other known way of making bit-fields work is to define 1192306536Sjkim@code{STRUCTURE_SIZE_BOUNDARY} as large as @code{BIGGEST_ALIGNMENT}. 1193306536SjkimThen every structure can be accessed with fullwords. 1194306536Sjkim 1195306536SjkimUnless the machine has bit-field instructions or you define 1196271440Sjkim@code{STRUCTURE_SIZE_BOUNDARY} that way, you must define 1197271440Sjkim@code{PCC_BITFIELD_TYPE_MATTERS} to have a nonzero value. 1198271440Sjkim 1199271440SjkimIf your aim is to make GCC use the same conventions for laying out 1200271440Sjkimbit-fields as are used by another compiler, here is how to investigate 1201271440Sjkimwhat the other compiler does. Compile and run this program: 1202271440Sjkim 1203271440Sjkim@example 1204271440Sjkimstruct foo1 1205271440Sjkim@{ 1206271440Sjkim char x; 1207271440Sjkim char :0; 1208271440Sjkim char y; 1209271440Sjkim@}; 1210271440Sjkim 1211271440Sjkimstruct foo2 1212271440Sjkim@{ 1213271440Sjkim char x; 1214271440Sjkim int :0; 1215271440Sjkim char y; 1216271440Sjkim@}; 1217271440Sjkim 1218306536Sjkimmain () 1219306536Sjkim@{ 1220306536Sjkim printf ("Size of foo1 is %d\n", 1221306536Sjkim sizeof (struct foo1)); 1222306536Sjkim printf ("Size of foo2 is %d\n", 1223306536Sjkim sizeof (struct foo2)); 1224306536Sjkim exit (0); 1225306536Sjkim@} 1226306536Sjkim@end example 1227306536Sjkim 1228306536SjkimIf this prints 2 and 5, then the compiler's behavior is what you would 1229306536Sjkimget from @code{PCC_BITFIELD_TYPE_MATTERS}. 1230306536Sjkim 1231306536Sjkim@findex BITFIELD_NBYTES_LIMITED 1232271440Sjkim@item BITFIELD_NBYTES_LIMITED 1233271440SjkimLike @code{PCC_BITFIELD_TYPE_MATTERS} except that its effect is limited 1234271440Sjkimto aligning a bit-field within the structure. 1235271440Sjkim 1236271440Sjkim@findex MEMBER_TYPE_FORCES_BLK 1237271440Sjkim@item MEMBER_TYPE_FORCES_BLK (@var{field}, @var{mode}) 1238271440SjkimReturn 1 if a structure or array containing @var{field} should be accessed using 1239271440Sjkim@code{BLKMODE}. 1240271440Sjkim 1241271440SjkimIf @var{field} is the only field in the structure, @var{mode} is its 1242271440Sjkimmode, otherwise @var{mode} is VOIDmode. @var{mode} is provided in the 1243271440Sjkimcase where structures of one field would require the structure's mode to 1244271440Sjkimretain the field's mode. 1245271440Sjkim 1246271440SjkimNormally, this is not needed. See the file @file{c4x.h} for an example 1247271440Sjkimof how to use this macro to prevent a structure having a floating point 1248271440Sjkimfield from being accessed in an integer mode. 1249271440Sjkim 1250271440Sjkim@findex ROUND_TYPE_SIZE 1251271440Sjkim@item ROUND_TYPE_SIZE (@var{type}, @var{computed}, @var{specified}) 1252271440SjkimDefine this macro as an expression for the overall size of a type 1253271440Sjkim(given by @var{type} as a tree node) when the size computed in the 1254271440Sjkimusual way is @var{computed} and the alignment is @var{specified}. 1255271440Sjkim 1256271440SjkimThe default is to round @var{computed} up to a multiple of @var{specified}. 1257271440Sjkim 1258271440Sjkim@findex ROUND_TYPE_SIZE_UNIT 1259271440Sjkim@item ROUND_TYPE_SIZE_UNIT (@var{type}, @var{computed}, @var{specified}) 1260271440SjkimSimilar to @code{ROUND_TYPE_SIZE}, but sizes and alignments are 1261271440Sjkimspecified in units (bytes). If you define @code{ROUND_TYPE_SIZE}, 1262271440Sjkimyou must also define this macro and they must be defined consistently 1263306536Sjkimwith each other. 1264306536Sjkim 1265306536Sjkim@findex ROUND_TYPE_ALIGN 1266306536Sjkim@item ROUND_TYPE_ALIGN (@var{type}, @var{computed}, @var{specified}) 1267306536SjkimDefine this macro as an expression for the alignment of a type (given 1268306536Sjkimby @var{type} as a tree node) if the alignment computed in the usual 1269306536Sjkimway is @var{computed} and the alignment explicitly specified was 1270306536Sjkim@var{specified}. 1271306536Sjkim 1272306536SjkimThe default is to use @var{specified} if it is larger; otherwise, use 1273306536Sjkimthe smaller of @var{computed} and @code{BIGGEST_ALIGNMENT} 1274306536Sjkim 1275306536Sjkim@findex MAX_FIXED_MODE_SIZE 1276306536Sjkim@item MAX_FIXED_MODE_SIZE 1277306536SjkimAn integer expression for the size in bits of the largest integer 1278306536Sjkimmachine mode that should actually be used. All integer machine modes of 1279306536Sjkimthis size or smaller can be used for structures and unions with the 1280306536Sjkimappropriate sizes. If this macro is undefined, @code{GET_MODE_BITSIZE 1281271440Sjkim(DImode)} is assumed. 1282271440Sjkim 1283271440Sjkim@findex VECTOR_MODE_SUPPORTED_P 1284271440Sjkim@item VECTOR_MODE_SUPPORTED_P(@var{mode}) 1285271440SjkimDefine this macro to be nonzero if the port is prepared to handle insns 1286271440Sjkiminvolving vector mode @var{mode}. At the very least, it must have move 1287271440Sjkimpatterns for this mode. 1288271440Sjkim 1289271440Sjkim@findex STACK_SAVEAREA_MODE 1290271440Sjkim@item STACK_SAVEAREA_MODE (@var{save_level}) 1291306536SjkimIf defined, an expression of type @code{enum machine_mode} that 1292306536Sjkimspecifies the mode of the save area operand of a 1293306536Sjkim@code{save_stack_@var{level}} named pattern (@pxref{Standard Names}). 1294306536Sjkim@var{save_level} is one of @code{SAVE_BLOCK}, @code{SAVE_FUNCTION}, or 1295271440Sjkim@code{SAVE_NONLOCAL} and selects which of the three named patterns is 1296271440Sjkimhaving its mode specified. 1297271440Sjkim 1298271440SjkimYou need not define this macro if it always returns @code{Pmode}. You 1299271440Sjkimwould most commonly define this macro if the 1300271440Sjkim@code{save_stack_@var{level}} patterns need to support both a 32- and a 1301271440Sjkim64-bit mode. 1302271440Sjkim 1303271440Sjkim@findex STACK_SIZE_MODE 1304271440Sjkim@item STACK_SIZE_MODE 1305306536SjkimIf defined, an expression of type @code{enum machine_mode} that 1306306536Sjkimspecifies the mode of the size increment operand of an 1307306536Sjkim@code{allocate_stack} named pattern (@pxref{Standard Names}). 1308306536Sjkim 1309306536SjkimYou need not define this macro if it always returns @code{word_mode}. 1310306536SjkimYou would most commonly define this macro if the @code{allocate_stack} 1311306536Sjkimpattern needs to support both a 32- and a 64-bit mode. 1312306536Sjkim 1313306536Sjkim@findex TARGET_FLOAT_FORMAT 1314271440Sjkim@item TARGET_FLOAT_FORMAT 1315271440SjkimA code distinguishing the floating point format of the target machine. 1316271440SjkimThere are five defined values: 1317271440Sjkim 1318271440Sjkim@table @code 1319271440Sjkim@findex IEEE_FLOAT_FORMAT 1320271440Sjkim@item IEEE_FLOAT_FORMAT 1321271440SjkimThis code indicates IEEE floating point. It is the default; there is no 1322271440Sjkimneed to define this macro when the format is IEEE@. 1323271440Sjkim 1324271440Sjkim@findex VAX_FLOAT_FORMAT 1325271440Sjkim@item VAX_FLOAT_FORMAT 1326271440SjkimThis code indicates the ``F float'' (for @code{float}) and ``D float'' 1327271440Sjkimor ``G float'' formats (for @code{double}) used on the VAX and PDP-11@. 1328271440Sjkim 1329271440Sjkim@findex IBM_FLOAT_FORMAT 1330271440Sjkim@item IBM_FLOAT_FORMAT 1331306536SjkimThis code indicates the format used on the IBM System/370. 1332306536Sjkim 1333306536Sjkim@findex C4X_FLOAT_FORMAT 1334306536Sjkim@item C4X_FLOAT_FORMAT 1335306536SjkimThis code indicates the format used on the TMS320C3x/C4x. 1336306536Sjkim 1337306536Sjkim@findex UNKNOWN_FLOAT_FORMAT 1338306536Sjkim@item UNKNOWN_FLOAT_FORMAT 1339306536SjkimThis code indicates any other format. 1340306536Sjkim@end table 1341306536Sjkim 1342306536SjkimIf any other 1343306536Sjkimformats are actually in use on supported machines, new codes should be 1344306536Sjkimdefined for them. 1345306536Sjkim 1346306536SjkimThe ordering of the component words of floating point values stored in 1347306536Sjkimmemory is controlled by @code{FLOAT_WORDS_BIG_ENDIAN}. 1348306536Sjkim 1349306536Sjkim@findex MODE_HAS_NANS 1350306536Sjkim@item MODE_HAS_NANS (@var{mode}) 1351306536SjkimWhen defined, this macro should be true if @var{mode} has a NaN 1352306536Sjkimrepresentation. The compiler assumes that NaNs are not equal to 1353306536Sjkimanything (including themselves) and that addition, subtraction, 1354306536Sjkimmultiplication and division all return NaNs when one operand is 1355271440SjkimNaN@. 1356271440Sjkim 1357271440SjkimBy default, this macro is true if @var{mode} is a floating-point 1358271440Sjkimmode and the target floating-point format is IEEE@. 1359271440Sjkim 1360271440Sjkim@findex MODE_HAS_INFINITIES 1361271440Sjkim@item MODE_HAS_INFINITIES (@var{mode}) 1362271440SjkimThis macro should be true if @var{mode} can represent infinity. At 1363271440Sjkimpresent, the compiler uses this macro to decide whether @samp{x - x} 1364271440Sjkimis always defined. By default, the macro is true when @var{mode} 1365306536Sjkimis a floating-point mode and the target format is IEEE@. 1366306536Sjkim 1367306536Sjkim@findex MODE_HAS_SIGNED_ZEROS 1368306536Sjkim@item MODE_HAS_SIGNED_ZEROS (@var{mode}) 1369306536SjkimTrue if @var{mode} distinguishes between positive and negative zero. 1370306536SjkimThe rules are expected to follow the IEEE standard: 1371306536Sjkim 1372306536Sjkim@itemize @bullet 1373306536Sjkim@item 1374306536Sjkim@samp{x + x} has the same sign as @samp{x}. 1375306536Sjkim 1376306536Sjkim@item 1377306536SjkimIf the sum of two values with opposite sign is zero, the result is 1378306536Sjkimpositive for all rounding modes expect towards @minus{}infinity, for 1379306536Sjkimwhich it is negative. 1380306536Sjkim 1381306536Sjkim@item 1382306536SjkimThe sign of a product or quotient is negative when exactly one 1383306536Sjkimof the operands is negative. 1384306536Sjkim@end itemize 1385306536Sjkim 1386306536SjkimThe default definition is true if @var{mode} is a floating-point 1387306536Sjkimmode and the target format is IEEE@. 1388306536Sjkim 1389306536Sjkim@findex MODE_HAS_SIGN_DEPENDENT_ROUNDING 1390306536Sjkim@item MODE_HAS_SIGN_DEPENDENT_ROUNDING (@var{mode}) 1391306536SjkimIf defined, this macro should be true for @var{mode} if it has at 1392306536Sjkimleast one rounding mode in which @samp{x} and @samp{-x} can be 1393306536Sjkimrounded to numbers of different magnitude. Two such modes are 1394306536Sjkimtowards @minus{}infinity and towards +infinity. 1395306536Sjkim 1396306536SjkimThe default definition of this macro is true if @var{mode} is 1397306536Sjkima floating-point mode and the target format is IEEE@. 1398306536Sjkim 1399306536Sjkim@findex ROUND_TOWARDS_ZERO 1400306536Sjkim@item ROUND_TOWARDS_ZERO 1401306536SjkimIf defined, this macro should be true if the prevailing rounding 1402306536Sjkimmode is towards zero. A true value has the following effects: 1403306536Sjkim 1404306536Sjkim@itemize @bullet 1405306536Sjkim@item 1406306536Sjkim@code{MODE_HAS_SIGN_DEPENDENT_ROUNDING} will be false for all modes. 1407306536Sjkim 1408306536Sjkim@item 1409306536Sjkim@file{libgcc.a}'s floating-point emulator will round towards zero 1410306536Sjkimrather than towards nearest. 1411306536Sjkim 1412306536Sjkim@item 1413306536SjkimThe compiler's floating-point emulator will round towards zero after 1414306536Sjkimdoing arithmetic, and when converting from the internal float format to 1415306536Sjkimthe target format. 1416306536Sjkim@end itemize 1417306536Sjkim 1418306536SjkimThe macro does not affect the parsing of string literals. When the 1419306536Sjkimprimary rounding mode is towards zero, library functions like 1420306536Sjkim@code{strtod} might still round towards nearest, and the compiler's 1421306536Sjkimparser should behave like the target's @code{strtod} where possible. 1422271440Sjkim 1423271440SjkimNot defining this macro is equivalent to returning zero. 1424271440Sjkim 1425271440Sjkim@findex LARGEST_EXPONENT_IS_NORMAL 1426271440Sjkim@item LARGEST_EXPONENT_IS_NORMAL (@var{size}) 1427271440SjkimThis macro should return true if floats with @var{size} 1428271440Sjkimbits do not have a NaN or infinity representation, but use the largest 1429271440Sjkimexponent for normal numbers instead. 1430271440Sjkim 1431271440SjkimDefining this macro to true for @var{size} causes @code{MODE_HAS_NANS} 1432271440Sjkimand @code{MODE_HAS_INFINITIES} to be false for @var{size}-bit modes. 1433271440SjkimIt also affects the way @file{libgcc.a} and @file{real.c} emulate 1434306536Sjkimfloating-point arithmetic. 1435306536Sjkim 1436306536SjkimThe default definition of this macro returns false for all sizes. 1437306536Sjkim@end table 1438306536Sjkim 1439306536Sjkim@deftypefn {Target Hook} bool TARGET_MS_BITFIELD_LAYOUT_P (tree @var{record_type}) 1440306536SjkimThis target hook returns @code{true} if bit-fields in the given 1441306536Sjkim@var{record_type} are to be laid out following the rules of Microsoft 1442306536SjkimVisual C/C++, namely: (i) a bit-field won't share the same storage 1443306536Sjkimunit with the previous bit-field if their underlying types have 1444306536Sjkimdifferent sizes, and the bit-field will be aligned to the highest 1445306536Sjkimalignment of the underlying types of itself and of the previous 1446306536Sjkimbit-field; (ii) a zero-sized bit-field will affect the alignment of 1447306536Sjkimthe whole enclosing structure, even if it is unnamed; except that 1448306536Sjkim(iii) a zero-sized bit-field will be disregarded unless it follows 1449306536Sjkimanother bit-field of nonzero size. If this hook returns @code{true}, 1450306536Sjkimother macros that control bit-field layout are ignored. 1451306536Sjkim 1452306536SjkimWhen a bit-field is inserted into a packed record, the whole size 1453306536Sjkimof the underlying type is used by one or more same-size adjacent 1454306536Sjkimbit-fields (that is, if its long:3, 32 bits is used in the record, 1455306536Sjkimand any additional adjacent long bit-fields are packed into the same 1456306536Sjkimchunk of 32 bits. However, if the size changes, a new field of that 1457306536Sjkimsize is allocated). In an unpacked record, this is the same as using 1458306536Sjkimalignment, but not equivalent when packing. 1459306536Sjkim 1460306536SjkimIf both MS bit-fields and @samp{__attribute__((packed))} are used, 1461306536Sjkimthe latter will take precedence. If @samp{__attribute__((packed))} is 1462306536Sjkimused on a single field when MS bit-fields are in use, it will take 1463306536Sjkimprecedence for that field, but the alignment of the rest of the structure 1464306536Sjkimmay affect its placement. 1465306536Sjkim@end deftypefn 1466306536Sjkim 1467306536Sjkim@node Type Layout 1468271440Sjkim@section Layout of Source Language Data Types 1469271440Sjkim 1470271440SjkimThese macros define the sizes and other characteristics of the standard 1471271440Sjkimbasic data types used in programs being compiled. Unlike the macros in 1472271440Sjkimthe previous section, these apply to specific features of C and related 1473271440Sjkimlanguages, rather than to fundamental aspects of storage layout. 1474271440Sjkim 1475271440Sjkim@table @code 1476271440Sjkim@findex INT_TYPE_SIZE 1477271440Sjkim@item INT_TYPE_SIZE 1478271440SjkimA C expression for the size in bits of the type @code{int} on the 1479271440Sjkimtarget machine. If you don't define this, the default is one word. 1480271440Sjkim 1481271440Sjkim@findex SHORT_TYPE_SIZE 1482271440Sjkim@item SHORT_TYPE_SIZE 1483271440SjkimA C expression for the size in bits of the type @code{short} on the 1484271440Sjkimtarget machine. If you don't define this, the default is half a word. 1485271440Sjkim(If this would be less than one storage unit, it is rounded up to one 1486271440Sjkimunit.) 1487271440Sjkim 1488306536Sjkim@findex LONG_TYPE_SIZE 1489306536Sjkim@item LONG_TYPE_SIZE 1490306536SjkimA C expression for the size in bits of the type @code{long} on the 1491306536Sjkimtarget machine. If you don't define this, the default is one word. 1492306536Sjkim 1493306536Sjkim@findex ADA_LONG_TYPE_SIZE 1494306536Sjkim@item ADA_LONG_TYPE_SIZE 1495306536SjkimOn some machines, the size used for the Ada equivalent of the type 1496271440Sjkim@code{long} by a native Ada compiler differs from that used by C. In 1497271440Sjkimthat situation, define this macro to be a C expression to be used for 1498271440Sjkimthe size of that type. If you don't define this, the default is the 1499271440Sjkimvalue of @code{LONG_TYPE_SIZE}. 1500271440Sjkim 1501271440Sjkim@findex MAX_LONG_TYPE_SIZE 1502271440Sjkim@item MAX_LONG_TYPE_SIZE 1503271440SjkimMaximum number for the size in bits of the type @code{long} on the 1504306536Sjkimtarget machine. If this is undefined, the default is 1505306536Sjkim@code{LONG_TYPE_SIZE}. Otherwise, it is the constant value that is the 1506306536Sjkimlargest value that @code{LONG_TYPE_SIZE} can have at run-time. This is 1507306536Sjkimused in @code{cpp}. 1508306536Sjkim 1509306536Sjkim@findex LONG_LONG_TYPE_SIZE 1510306536Sjkim@item LONG_LONG_TYPE_SIZE 1511306536SjkimA C expression for the size in bits of the type @code{long long} on the 1512306536Sjkimtarget machine. If you don't define this, the default is two 1513306536Sjkimwords. If you want to support GNU Ada on your machine, the value of this 1514306536Sjkimmacro must be at least 64. 1515306536Sjkim 1516306536Sjkim@findex CHAR_TYPE_SIZE 1517306536Sjkim@item CHAR_TYPE_SIZE 1518306536SjkimA C expression for the size in bits of the type @code{char} on the 1519306536Sjkimtarget machine. If you don't define this, the default is 1520271440Sjkim@code{BITS_PER_UNIT}. 1521271440Sjkim 1522271440Sjkim@findex BOOL_TYPE_SIZE 1523271440Sjkim@item BOOL_TYPE_SIZE 1524271440SjkimA C expression for the size in bits of the C++ type @code{bool} and 1525271440SjkimC99 type @code{_Bool} on the target machine. If you don't define 1526271440Sjkimthis, and you probably shouldn't, the default is @code{CHAR_TYPE_SIZE}. 1527271440Sjkim 1528271440Sjkim@findex FLOAT_TYPE_SIZE 1529271440Sjkim@item FLOAT_TYPE_SIZE 1530271440SjkimA C expression for the size in bits of the type @code{float} on the 1531271440Sjkimtarget machine. If you don't define this, the default is one word. 1532271440Sjkim 1533271440Sjkim@findex DOUBLE_TYPE_SIZE 1534271440Sjkim@item DOUBLE_TYPE_SIZE 1535271440SjkimA C expression for the size in bits of the type @code{double} on the 1536271440Sjkimtarget machine. If you don't define this, the default is two 1537271440Sjkimwords. 1538306536Sjkim 1539306536Sjkim@findex LONG_DOUBLE_TYPE_SIZE 1540306536Sjkim@item LONG_DOUBLE_TYPE_SIZE 1541306536SjkimA C expression for the size in bits of the type @code{long double} on 1542306536Sjkimthe target machine. If you don't define this, the default is two 1543306536Sjkimwords. 1544306536Sjkim 1545306536Sjkim@findex MAX_LONG_DOUBLE_TYPE_SIZE 1546306536SjkimMaximum number for the size in bits of the type @code{long double} on the 1547271440Sjkimtarget machine. If this is undefined, the default is 1548306536Sjkim@code{LONG_DOUBLE_TYPE_SIZE}. Otherwise, it is the constant value that is 1549306536Sjkimthe largest value that @code{LONG_DOUBLE_TYPE_SIZE} can have at run-time. 1550306536SjkimThis is used in @code{cpp}. 1551306536Sjkim 1552306536Sjkim@findex TARGET_FLT_EVAL_METHOD 1553306536Sjkim@item TARGET_FLT_EVAL_METHOD 1554306536SjkimA C expression for the value for @code{FLT_EVAL_METHOD} in @file{float.h}, 1555306536Sjkimassuming, if applicable, that the floating-point control word is in its 1556306536Sjkimdefault state. If you do not define this macro the value of 1557271440Sjkim@code{FLT_EVAL_METHOD} will be zero. 1558271440Sjkim 1559271440Sjkim@findex WIDEST_HARDWARE_FP_SIZE 1560271440Sjkim@item WIDEST_HARDWARE_FP_SIZE 1561271440SjkimA C expression for the size in bits of the widest floating-point format 1562271440Sjkimsupported by the hardware. If you define this macro, you must specify a 1563271440Sjkimvalue less than or equal to the value of @code{LONG_DOUBLE_TYPE_SIZE}. 1564271440SjkimIf you do not define this macro, the value of @code{LONG_DOUBLE_TYPE_SIZE} 1565271440Sjkimis the default. 1566271440Sjkim 1567271440Sjkim@findex DEFAULT_SIGNED_CHAR 1568271440Sjkim@item DEFAULT_SIGNED_CHAR 1569271440SjkimAn expression whose value is 1 or 0, according to whether the type 1570271440Sjkim@code{char} should be signed or unsigned by default. The user can 1571271440Sjkimalways override this default with the options @option{-fsigned-char} 1572271440Sjkimand @option{-funsigned-char}. 1573271440Sjkim 1574271440Sjkim@findex DEFAULT_SHORT_ENUMS 1575271440Sjkim@item DEFAULT_SHORT_ENUMS 1576271440SjkimA C expression to determine whether to give an @code{enum} type 1577271440Sjkimonly as many bytes as it takes to represent the range of possible values 1578271440Sjkimof that type. A nonzero value means to do that; a zero value means all 1579271440Sjkim@code{enum} types should be allocated like @code{int}. 1580271440Sjkim 1581271440SjkimIf you don't define the macro, the default is 0. 1582271440Sjkim 1583271440Sjkim@findex SIZE_TYPE 1584271440Sjkim@item SIZE_TYPE 1585271440SjkimA C expression for a string describing the name of the data type to use 1586271440Sjkimfor size values. The typedef name @code{size_t} is defined using the 1587271440Sjkimcontents of the string. 1588271440Sjkim 1589271440SjkimThe string can contain more than one keyword. If so, separate them with 1590271440Sjkimspaces, and write first any length keyword, then @code{unsigned} if 1591271440Sjkimappropriate, and finally @code{int}. The string must exactly match one 1592271440Sjkimof the data type names defined in the function 1593271440Sjkim@code{init_decl_processing} in the file @file{c-decl.c}. You may not 1594271440Sjkimomit @code{int} or change the order---that would cause the compiler to 1595271440Sjkimcrash on startup. 1596271440Sjkim 1597271440SjkimIf you don't define this macro, the default is @code{"long unsigned 1598271440Sjkimint"}. 1599271440Sjkim 1600271440Sjkim@findex PTRDIFF_TYPE 1601271440Sjkim@item PTRDIFF_TYPE 1602271440SjkimA C expression for a string describing the name of the data type to use 1603271440Sjkimfor the result of subtracting two pointers. The typedef name 1604271440Sjkim@code{ptrdiff_t} is defined using the contents of the string. See 1605271440Sjkim@code{SIZE_TYPE} above for more information. 1606271440Sjkim 1607271440SjkimIf you don't define this macro, the default is @code{"long int"}. 1608271440Sjkim 1609271440Sjkim@findex WCHAR_TYPE 1610306536Sjkim@item WCHAR_TYPE 1611306536SjkimA C expression for a string describing the name of the data type to use 1612306536Sjkimfor wide characters. The typedef name @code{wchar_t} is defined using 1613306536Sjkimthe contents of the string. See @code{SIZE_TYPE} above for more 1614306536Sjkiminformation. 1615306536Sjkim 1616281075SdimIf you don't define this macro, the default is @code{"int"}. 1617281075Sdim 1618281075Sdim@findex WCHAR_TYPE_SIZE 1619281075Sdim@item WCHAR_TYPE_SIZE 1620281075SdimA C expression for the size in bits of the data type for wide 1621281075Sdimcharacters. This is used in @code{cpp}, which cannot make use of 1622281075Sdim@code{WCHAR_TYPE}. 1623281075Sdim 1624281075Sdim@findex MAX_WCHAR_TYPE_SIZE 1625281075Sdim@item MAX_WCHAR_TYPE_SIZE 1626281075SdimMaximum number for the size in bits of the data type for wide 1627281075Sdimcharacters. If this is undefined, the default is 1628281075Sdim@code{WCHAR_TYPE_SIZE}. Otherwise, it is the constant value that is the 1629281075Sdimlargest value that @code{WCHAR_TYPE_SIZE} can have at run-time. This is 1630281075Sdimused in @code{cpp}. 1631281075Sdim 1632281075Sdim@findex GCOV_TYPE_SIZE 1633281075Sdim@item GCOV_TYPE_SIZE 1634271440SjkimA C expression for the size in bits of the type used for gcov counters on the 1635271440Sjkimtarget machine. If you don't define this, the default is one 1636271440Sjkim@code{LONG_TYPE_SIZE} in case it is greater or equal to 64-bit and 1637271440Sjkim@code{LONG_LONG_TYPE_SIZE} otherwise. You may want to re-define the type to 1638271440Sjkimensure atomicity for counters in multithreaded programs. 1639271440Sjkim 1640271440Sjkim@findex WINT_TYPE 1641271440Sjkim@item WINT_TYPE 1642271440SjkimA C expression for a string describing the name of the data type to 1643271440Sjkimuse for wide characters passed to @code{printf} and returned from 1644271440Sjkim@code{getwc}. The typedef name @code{wint_t} is defined using the 1645271440Sjkimcontents of the string. See @code{SIZE_TYPE} above for more 1646271440Sjkiminformation. 1647271440Sjkim 1648271440SjkimIf you don't define this macro, the default is @code{"unsigned int"}. 1649271440Sjkim 1650271440Sjkim@findex INTMAX_TYPE 1651306536Sjkim@item INTMAX_TYPE 1652306536SjkimA C expression for a string describing the name of the data type that 1653306536Sjkimcan represent any value of any standard or extended signed integer type. 1654306536SjkimThe typedef name @code{intmax_t} is defined using the contents of the 1655306536Sjkimstring. See @code{SIZE_TYPE} above for more information. 1656306536Sjkim 1657306536SjkimIf you don't define this macro, the default is the first of 1658306536Sjkim@code{"int"}, @code{"long int"}, or @code{"long long int"} that has as 1659306536Sjkimmuch precision as @code{long long int}. 1660306536Sjkim 1661306536Sjkim@findex UINTMAX_TYPE 1662306536Sjkim@item UINTMAX_TYPE 1663306536SjkimA C expression for a string describing the name of the data type that 1664306536Sjkimcan represent any value of any standard or extended unsigned integer 1665306536Sjkimtype. The typedef name @code{uintmax_t} is defined using the contents 1666306536Sjkimof the string. See @code{SIZE_TYPE} above for more information. 1667271440Sjkim 1668271440SjkimIf you don't define this macro, the default is the first of 1669271440Sjkim@code{"unsigned int"}, @code{"long unsigned int"}, or @code{"long long 1670271440Sjkimunsigned int"} that has as much precision as @code{long long unsigned 1671271440Sjkimint}. 1672271440Sjkim 1673271440Sjkim@findex TARGET_PTRMEMFUNC_VBIT_LOCATION 1674271440Sjkim@item TARGET_PTRMEMFUNC_VBIT_LOCATION 1675271440SjkimThe C++ compiler represents a pointer-to-member-function with a struct 1676271440Sjkimthat looks like: 1677271440Sjkim 1678271440Sjkim@example 1679271440Sjkim struct @{ 1680271440Sjkim union @{ 1681271440Sjkim void (*fn)(); 1682271440Sjkim ptrdiff_t vtable_index; 1683271440Sjkim @}; 1684271440Sjkim ptrdiff_t delta; 1685271440Sjkim @}; 1686306536Sjkim@end example 1687306536Sjkim 1688306536Sjkim@noindent 1689306536SjkimThe C++ compiler must use one bit to indicate whether the function that 1690306536Sjkimwill be called through a pointer-to-member-function is virtual. 1691306536SjkimNormally, we assume that the low-order bit of a function pointer must 1692271440Sjkimalways be zero. Then, by ensuring that the vtable_index is odd, we can 1693271440Sjkimdistinguish which variant of the union is in use. But, on some 1694271440Sjkimplatforms function pointers can be odd, and so this doesn't work. In 1695271440Sjkimthat case, we use the low-order bit of the @code{delta} field, and shift 1696306536Sjkimthe remainder of the @code{delta} field to the left. 1697306536Sjkim 1698306536SjkimGCC will automatically make the right selection about where to store 1699306536Sjkimthis bit using the @code{FUNCTION_BOUNDARY} setting for your platform. 1700306536SjkimHowever, some platforms such as ARM/Thumb have @code{FUNCTION_BOUNDARY} 1701271440Sjkimset such that functions always start at even addresses, but the lowest 1702271440Sjkimbit of pointers to functions indicate whether the function at that 1703271440Sjkimaddress is in ARM or Thumb mode. If this is the case of your 1704271440Sjkimarchitecture, you should define this macro to 1705271440Sjkim@code{ptrmemfunc_vbit_in_delta}. 1706271440Sjkim 1707271440SjkimIn general, you should not have to define this macro. On architectures 1708271440Sjkimin which function addresses are always even, according to 1709271440Sjkim@code{FUNCTION_BOUNDARY}, GCC will automatically define this macro to 1710271440Sjkim@code{ptrmemfunc_vbit_in_pfn}. 1711271440Sjkim 1712271440Sjkim@findex TARGET_VTABLE_USES_DESCRIPTORS 1713271440Sjkim@item TARGET_VTABLE_USES_DESCRIPTORS 1714271440SjkimNormally, the C++ compiler uses function pointers in vtables. This 1715271440Sjkimmacro allows the target to change to use ``function descriptors'' 1716271440Sjkiminstead. Function descriptors are found on targets for whom a 1717271440Sjkimfunction pointer is actually a small data structure. Normally the 1718271440Sjkimdata structure consists of the actual code address plus a data 1719271440Sjkimpointer to which the function's data is relative. 1720271440Sjkim 1721271440SjkimIf vtables are used, the value of this macro should be the number 1722271440Sjkimof words that the function descriptor occupies. 1723271440Sjkim 1724271440Sjkim@findex TARGET_VTABLE_ENTRY_ALIGN 1725271440Sjkim@item TARGET_VTABLE_ENTRY_ALIGN 1726271440SjkimBy default, the vtable entries are void pointers, the so the alignment 1727271440Sjkimis the same as pointer alignment. The value of this macro specifies 1728271440Sjkimthe alignment of the vtable entry in bits. It should be defined only 1729271440Sjkimwhen special alignment is necessary. */ 1730271440Sjkim 1731271440Sjkim@findex TARGET_VTABLE_DATA_ENTRY_DISTANCE 1732271440Sjkim@item TARGET_VTABLE_DATA_ENTRY_DISTANCE 1733271440SjkimThere are a few non-descriptor entries in the vtable at offsets below 1734306536Sjkimzero. If these entries must be padded (say, to preserve the alignment 1735271440Sjkimspecified by @code{TARGET_VTABLE_ENTRY_ALIGN}), set this to the number 1736271440Sjkimof words in each data entry. 1737271440Sjkim@end table 1738306536Sjkim 1739271440Sjkim@node Escape Sequences 1740306536Sjkim@section Target Character Escape Sequences 1741271440Sjkim@cindex escape sequences 1742271440Sjkim 1743271440SjkimBy default, GCC assumes that the C character escape sequences take on 1744271440Sjkimtheir ASCII values for the target. If this is not correct, you must 1745271440Sjkimexplicitly define all of the macros below. 1746271440Sjkim 1747@table @code 1748@findex TARGET_BELL 1749@item TARGET_BELL 1750A C constant expression for the integer value for escape sequence 1751@samp{\a}. 1752 1753@findex TARGET_ESC 1754@item TARGET_ESC 1755A C constant expression for the integer value of the target escape 1756character. As an extension, GCC evaluates the escape sequences 1757@samp{\e} and @samp{\E} to this. 1758 1759@findex TARGET_TAB 1760@findex TARGET_BS 1761@findex TARGET_NEWLINE 1762@item TARGET_BS 1763@itemx TARGET_TAB 1764@itemx TARGET_NEWLINE 1765C constant expressions for the integer values for escape sequences 1766@samp{\b}, @samp{\t} and @samp{\n}. 1767 1768@findex TARGET_VT 1769@findex TARGET_FF 1770@findex TARGET_CR 1771@item TARGET_VT 1772@itemx TARGET_FF 1773@itemx TARGET_CR 1774C constant expressions for the integer values for escape sequences 1775@samp{\v}, @samp{\f} and @samp{\r}. 1776@end table 1777 1778@node Registers 1779@section Register Usage 1780@cindex register usage 1781 1782This section explains how to describe what registers the target machine 1783has, and how (in general) they can be used. 1784 1785The description of which registers a specific instruction can use is 1786done with register classes; see @ref{Register Classes}. For information 1787on using registers to access a stack frame, see @ref{Frame Registers}. 1788For passing values in registers, see @ref{Register Arguments}. 1789For returning values in registers, see @ref{Scalar Return}. 1790 1791@menu 1792* Register Basics:: Number and kinds of registers. 1793* Allocation Order:: Order in which registers are allocated. 1794* Values in Registers:: What kinds of values each reg can hold. 1795* Leaf Functions:: Renumbering registers for leaf functions. 1796* Stack Registers:: Handling a register stack such as 80387. 1797@end menu 1798 1799@node Register Basics 1800@subsection Basic Characteristics of Registers 1801 1802@c prevent bad page break with this line 1803Registers have various characteristics. 1804 1805@table @code 1806@findex FIRST_PSEUDO_REGISTER 1807@item FIRST_PSEUDO_REGISTER 1808Number of hardware registers known to the compiler. They receive 1809numbers 0 through @code{FIRST_PSEUDO_REGISTER-1}; thus, the first 1810pseudo register's number really is assigned the number 1811@code{FIRST_PSEUDO_REGISTER}. 1812 1813@item FIXED_REGISTERS 1814@findex FIXED_REGISTERS 1815@cindex fixed register 1816An initializer that says which registers are used for fixed purposes 1817all throughout the compiled code and are therefore not available for 1818general allocation. These would include the stack pointer, the frame 1819pointer (except on machines where that can be used as a general 1820register when no frame pointer is needed), the program counter on 1821machines where that is considered one of the addressable registers, 1822and any other numbered register with a standard use. 1823 1824This information is expressed as a sequence of numbers, separated by 1825commas and surrounded by braces. The @var{n}th number is 1 if 1826register @var{n} is fixed, 0 otherwise. 1827 1828The table initialized from this macro, and the table initialized by 1829the following one, may be overridden at run time either automatically, 1830by the actions of the macro @code{CONDITIONAL_REGISTER_USAGE}, or by 1831the user with the command options @option{-ffixed-@var{reg}}, 1832@option{-fcall-used-@var{reg}} and @option{-fcall-saved-@var{reg}}. 1833 1834@findex CALL_USED_REGISTERS 1835@item CALL_USED_REGISTERS 1836@cindex call-used register 1837@cindex call-clobbered register 1838@cindex call-saved register 1839Like @code{FIXED_REGISTERS} but has 1 for each register that is 1840clobbered (in general) by function calls as well as for fixed 1841registers. This macro therefore identifies the registers that are not 1842available for general allocation of values that must live across 1843function calls. 1844 1845If a register has 0 in @code{CALL_USED_REGISTERS}, the compiler 1846automatically saves it on function entry and restores it on function 1847exit, if the register is used within the function. 1848 1849@findex CALL_REALLY_USED_REGISTERS 1850@item CALL_REALLY_USED_REGISTERS 1851@cindex call-used register 1852@cindex call-clobbered register 1853@cindex call-saved register 1854Like @code{CALL_USED_REGISTERS} except this macro doesn't require 1855that the entire set of @code{FIXED_REGISTERS} be included. 1856(@code{CALL_USED_REGISTERS} must be a superset of @code{FIXED_REGISTERS}). 1857This macro is optional. If not specified, it defaults to the value 1858of @code{CALL_USED_REGISTERS}. 1859 1860@findex HARD_REGNO_CALL_PART_CLOBBERED 1861@item HARD_REGNO_CALL_PART_CLOBBERED (@var{regno}, @var{mode}) 1862@cindex call-used register 1863@cindex call-clobbered register 1864@cindex call-saved register 1865A C expression that is nonzero if it is not permissible to store a 1866value of mode @var{mode} in hard register number @var{regno} across a 1867call without some part of it being clobbered. For most machines this 1868macro need not be defined. It is only required for machines that do not 1869preserve the entire contents of a register across a call. 1870 1871@findex CONDITIONAL_REGISTER_USAGE 1872@findex fixed_regs 1873@findex call_used_regs 1874@item CONDITIONAL_REGISTER_USAGE 1875Zero or more C statements that may conditionally modify five variables 1876@code{fixed_regs}, @code{call_used_regs}, @code{global_regs}, 1877@code{reg_names}, and @code{reg_class_contents}, to take into account 1878any dependence of these register sets on target flags. The first three 1879of these are of type @code{char []} (interpreted as Boolean vectors). 1880@code{global_regs} is a @code{const char *[]}, and 1881@code{reg_class_contents} is a @code{HARD_REG_SET}. Before the macro is 1882called, @code{fixed_regs}, @code{call_used_regs}, 1883@code{reg_class_contents}, and @code{reg_names} have been initialized 1884from @code{FIXED_REGISTERS}, @code{CALL_USED_REGISTERS}, 1885@code{REG_CLASS_CONTENTS}, and @code{REGISTER_NAMES}, respectively. 1886@code{global_regs} has been cleared, and any @option{-ffixed-@var{reg}}, 1887@option{-fcall-used-@var{reg}} and @option{-fcall-saved-@var{reg}} 1888command options have been applied. 1889 1890You need not define this macro if it has no work to do. 1891 1892@cindex disabling certain registers 1893@cindex controlling register usage 1894If the usage of an entire class of registers depends on the target 1895flags, you may indicate this to GCC by using this macro to modify 1896@code{fixed_regs} and @code{call_used_regs} to 1 for each of the 1897registers in the classes which should not be used by GCC@. Also define 1898the macro @code{REG_CLASS_FROM_LETTER} to return @code{NO_REGS} if it 1899is called with a letter for a class that shouldn't be used. 1900 1901(However, if this class is not included in @code{GENERAL_REGS} and all 1902of the insn patterns whose constraints permit this class are 1903controlled by target switches, then GCC will automatically avoid using 1904these registers when the target switches are opposed to them.) 1905 1906@findex NON_SAVING_SETJMP 1907@item NON_SAVING_SETJMP 1908If this macro is defined and has a nonzero value, it means that 1909@code{setjmp} and related functions fail to save the registers, or that 1910@code{longjmp} fails to restore them. To compensate, the compiler 1911avoids putting variables in registers in functions that use 1912@code{setjmp}. 1913 1914@findex INCOMING_REGNO 1915@item INCOMING_REGNO (@var{out}) 1916Define this macro if the target machine has register windows. This C 1917expression returns the register number as seen by the called function 1918corresponding to the register number @var{out} as seen by the calling 1919function. Return @var{out} if register number @var{out} is not an 1920outbound register. 1921 1922@findex OUTGOING_REGNO 1923@item OUTGOING_REGNO (@var{in}) 1924Define this macro if the target machine has register windows. This C 1925expression returns the register number as seen by the calling function 1926corresponding to the register number @var{in} as seen by the called 1927function. Return @var{in} if register number @var{in} is not an inbound 1928register. 1929 1930@findex LOCAL_REGNO 1931@item LOCAL_REGNO (@var{regno}) 1932Define this macro if the target machine has register windows. This C 1933expression returns true if the register is call-saved but is in the 1934register window. Unlike most call-saved registers, such registers 1935need not be explicitly restored on function exit or during non-local 1936gotos. 1937 1938@ignore 1939@findex PC_REGNUM 1940@item PC_REGNUM 1941If the program counter has a register number, define this as that 1942register number. Otherwise, do not define it. 1943@end ignore 1944@end table 1945 1946@node Allocation Order 1947@subsection Order of Allocation of Registers 1948@cindex order of register allocation 1949@cindex register allocation order 1950 1951@c prevent bad page break with this line 1952Registers are allocated in order. 1953 1954@table @code 1955@findex REG_ALLOC_ORDER 1956@item REG_ALLOC_ORDER 1957If defined, an initializer for a vector of integers, containing the 1958numbers of hard registers in the order in which GCC should prefer 1959to use them (from most preferred to least). 1960 1961If this macro is not defined, registers are used lowest numbered first 1962(all else being equal). 1963 1964One use of this macro is on machines where the highest numbered 1965registers must always be saved and the save-multiple-registers 1966instruction supports only sequences of consecutive registers. On such 1967machines, define @code{REG_ALLOC_ORDER} to be an initializer that lists 1968the highest numbered allocable register first. 1969 1970@findex ORDER_REGS_FOR_LOCAL_ALLOC 1971@item ORDER_REGS_FOR_LOCAL_ALLOC 1972A C statement (sans semicolon) to choose the order in which to allocate 1973hard registers for pseudo-registers local to a basic block. 1974 1975Store the desired register order in the array @code{reg_alloc_order}. 1976Element 0 should be the register to allocate first; element 1, the next 1977register; and so on. 1978 1979The macro body should not assume anything about the contents of 1980@code{reg_alloc_order} before execution of the macro. 1981 1982On most machines, it is not necessary to define this macro. 1983@end table 1984 1985@node Values in Registers 1986@subsection How Values Fit in Registers 1987 1988This section discusses the macros that describe which kinds of values 1989(specifically, which machine modes) each register can hold, and how many 1990consecutive registers are needed for a given mode. 1991 1992@table @code 1993@findex HARD_REGNO_NREGS 1994@item HARD_REGNO_NREGS (@var{regno}, @var{mode}) 1995A C expression for the number of consecutive hard registers, starting 1996at register number @var{regno}, required to hold a value of mode 1997@var{mode}. 1998 1999On a machine where all registers are exactly one word, a suitable 2000definition of this macro is 2001 2002@smallexample 2003#define HARD_REGNO_NREGS(REGNO, MODE) \ 2004 ((GET_MODE_SIZE (MODE) + UNITS_PER_WORD - 1) \ 2005 / UNITS_PER_WORD) 2006@end smallexample 2007 2008@findex HARD_REGNO_MODE_OK 2009@item HARD_REGNO_MODE_OK (@var{regno}, @var{mode}) 2010A C expression that is nonzero if it is permissible to store a value 2011of mode @var{mode} in hard register number @var{regno} (or in several 2012registers starting with that one). For a machine where all registers 2013are equivalent, a suitable definition is 2014 2015@smallexample 2016#define HARD_REGNO_MODE_OK(REGNO, MODE) 1 2017@end smallexample 2018 2019You need not include code to check for the numbers of fixed registers, 2020because the allocation mechanism considers them to be always occupied. 2021 2022@cindex register pairs 2023On some machines, double-precision values must be kept in even/odd 2024register pairs. You can implement that by defining this macro to reject 2025odd register numbers for such modes. 2026 2027The minimum requirement for a mode to be OK in a register is that the 2028@samp{mov@var{mode}} instruction pattern support moves between the 2029register and other hard register in the same class and that moving a 2030value into the register and back out not alter it. 2031 2032Since the same instruction used to move @code{word_mode} will work for 2033all narrower integer modes, it is not necessary on any machine for 2034@code{HARD_REGNO_MODE_OK} to distinguish between these modes, provided 2035you define patterns @samp{movhi}, etc., to take advantage of this. This 2036is useful because of the interaction between @code{HARD_REGNO_MODE_OK} 2037and @code{MODES_TIEABLE_P}; it is very desirable for all integer modes 2038to be tieable. 2039 2040Many machines have special registers for floating point arithmetic. 2041Often people assume that floating point machine modes are allowed only 2042in floating point registers. This is not true. Any registers that 2043can hold integers can safely @emph{hold} a floating point machine 2044mode, whether or not floating arithmetic can be done on it in those 2045registers. Integer move instructions can be used to move the values. 2046 2047On some machines, though, the converse is true: fixed-point machine 2048modes may not go in floating registers. This is true if the floating 2049registers normalize any value stored in them, because storing a 2050non-floating value there would garble it. In this case, 2051@code{HARD_REGNO_MODE_OK} should reject fixed-point machine modes in 2052floating registers. But if the floating registers do not automatically 2053normalize, if you can store any bit pattern in one and retrieve it 2054unchanged without a trap, then any machine mode may go in a floating 2055register, so you can define this macro to say so. 2056 2057The primary significance of special floating registers is rather that 2058they are the registers acceptable in floating point arithmetic 2059instructions. However, this is of no concern to 2060@code{HARD_REGNO_MODE_OK}. You handle it by writing the proper 2061constraints for those instructions. 2062 2063On some machines, the floating registers are especially slow to access, 2064so that it is better to store a value in a stack frame than in such a 2065register if floating point arithmetic is not being done. As long as the 2066floating registers are not in class @code{GENERAL_REGS}, they will not 2067be used unless some pattern's constraint asks for one. 2068 2069@findex MODES_TIEABLE_P 2070@item MODES_TIEABLE_P (@var{mode1}, @var{mode2}) 2071A C expression that is nonzero if a value of mode 2072@var{mode1} is accessible in mode @var{mode2} without copying. 2073 2074If @code{HARD_REGNO_MODE_OK (@var{r}, @var{mode1})} and 2075@code{HARD_REGNO_MODE_OK (@var{r}, @var{mode2})} are always the same for 2076any @var{r}, then @code{MODES_TIEABLE_P (@var{mode1}, @var{mode2})} 2077should be nonzero. If they differ for any @var{r}, you should define 2078this macro to return zero unless some other mechanism ensures the 2079accessibility of the value in a narrower mode. 2080 2081You should define this macro to return nonzero in as many cases as 2082possible since doing so will allow GCC to perform better register 2083allocation. 2084 2085@findex AVOID_CCMODE_COPIES 2086@item AVOID_CCMODE_COPIES 2087Define this macro if the compiler should avoid copies to/from @code{CCmode} 2088registers. You should only define this macro if support for copying to/from 2089@code{CCmode} is incomplete. 2090@end table 2091 2092@node Leaf Functions 2093@subsection Handling Leaf Functions 2094 2095@cindex leaf functions 2096@cindex functions, leaf 2097On some machines, a leaf function (i.e., one which makes no calls) can run 2098more efficiently if it does not make its own register window. Often this 2099means it is required to receive its arguments in the registers where they 2100are passed by the caller, instead of the registers where they would 2101normally arrive. 2102 2103The special treatment for leaf functions generally applies only when 2104other conditions are met; for example, often they may use only those 2105registers for its own variables and temporaries. We use the term ``leaf 2106function'' to mean a function that is suitable for this special 2107handling, so that functions with no calls are not necessarily ``leaf 2108functions''. 2109 2110GCC assigns register numbers before it knows whether the function is 2111suitable for leaf function treatment. So it needs to renumber the 2112registers in order to output a leaf function. The following macros 2113accomplish this. 2114 2115@table @code 2116@findex LEAF_REGISTERS 2117@item LEAF_REGISTERS 2118Name of a char vector, indexed by hard register number, which 2119contains 1 for a register that is allowable in a candidate for leaf 2120function treatment. 2121 2122If leaf function treatment involves renumbering the registers, then the 2123registers marked here should be the ones before renumbering---those that 2124GCC would ordinarily allocate. The registers which will actually be 2125used in the assembler code, after renumbering, should not be marked with 1 2126in this vector. 2127 2128Define this macro only if the target machine offers a way to optimize 2129the treatment of leaf functions. 2130 2131@findex LEAF_REG_REMAP 2132@item LEAF_REG_REMAP (@var{regno}) 2133A C expression whose value is the register number to which @var{regno} 2134should be renumbered, when a function is treated as a leaf function. 2135 2136If @var{regno} is a register number which should not appear in a leaf 2137function before renumbering, then the expression should yield @minus{}1, which 2138will cause the compiler to abort. 2139 2140Define this macro only if the target machine offers a way to optimize the 2141treatment of leaf functions, and registers need to be renumbered to do 2142this. 2143@end table 2144 2145@findex current_function_is_leaf 2146@findex current_function_uses_only_leaf_regs 2147@code{TARGET_ASM_FUNCTION_PROLOGUE} and 2148@code{TARGET_ASM_FUNCTION_EPILOGUE} must usually treat leaf functions 2149specially. They can test the C variable @code{current_function_is_leaf} 2150which is nonzero for leaf functions. @code{current_function_is_leaf} is 2151set prior to local register allocation and is valid for the remaining 2152compiler passes. They can also test the C variable 2153@code{current_function_uses_only_leaf_regs} which is nonzero for leaf 2154functions which only use leaf registers. 2155@code{current_function_uses_only_leaf_regs} is valid after reload and is 2156only useful if @code{LEAF_REGISTERS} is defined. 2157@c changed this to fix overfull. ALSO: why the "it" at the beginning 2158@c of the next paragraph?! --mew 2feb93 2159 2160@node Stack Registers 2161@subsection Registers That Form a Stack 2162 2163There are special features to handle computers where some of the 2164``registers'' form a stack, as in the 80387 coprocessor for the 80386. 2165Stack registers are normally written by pushing onto the stack, and are 2166numbered relative to the top of the stack. 2167 2168Currently, GCC can only handle one group of stack-like registers, and 2169they must be consecutively numbered. 2170 2171@table @code 2172@findex STACK_REGS 2173@item STACK_REGS 2174Define this if the machine has any stack-like registers. 2175 2176@findex FIRST_STACK_REG 2177@item FIRST_STACK_REG 2178The number of the first stack-like register. This one is the top 2179of the stack. 2180 2181@findex LAST_STACK_REG 2182@item LAST_STACK_REG 2183The number of the last stack-like register. This one is the bottom of 2184the stack. 2185@end table 2186 2187@node Register Classes 2188@section Register Classes 2189@cindex register class definitions 2190@cindex class definitions, register 2191 2192On many machines, the numbered registers are not all equivalent. 2193For example, certain registers may not be allowed for indexed addressing; 2194certain registers may not be allowed in some instructions. These machine 2195restrictions are described to the compiler using @dfn{register classes}. 2196 2197You define a number of register classes, giving each one a name and saying 2198which of the registers belong to it. Then you can specify register classes 2199that are allowed as operands to particular instruction patterns. 2200 2201@findex ALL_REGS 2202@findex NO_REGS 2203In general, each register will belong to several classes. In fact, one 2204class must be named @code{ALL_REGS} and contain all the registers. Another 2205class must be named @code{NO_REGS} and contain no registers. Often the 2206union of two classes will be another class; however, this is not required. 2207 2208@findex GENERAL_REGS 2209One of the classes must be named @code{GENERAL_REGS}. There is nothing 2210terribly special about the name, but the operand constraint letters 2211@samp{r} and @samp{g} specify this class. If @code{GENERAL_REGS} is 2212the same as @code{ALL_REGS}, just define it as a macro which expands 2213to @code{ALL_REGS}. 2214 2215Order the classes so that if class @var{x} is contained in class @var{y} 2216then @var{x} has a lower class number than @var{y}. 2217 2218The way classes other than @code{GENERAL_REGS} are specified in operand 2219constraints is through machine-dependent operand constraint letters. 2220You can define such letters to correspond to various classes, then use 2221them in operand constraints. 2222 2223You should define a class for the union of two classes whenever some 2224instruction allows both classes. For example, if an instruction allows 2225either a floating point (coprocessor) register or a general register for a 2226certain operand, you should define a class @code{FLOAT_OR_GENERAL_REGS} 2227which includes both of them. Otherwise you will get suboptimal code. 2228 2229You must also specify certain redundant information about the register 2230classes: for each class, which classes contain it and which ones are 2231contained in it; for each pair of classes, the largest class contained 2232in their union. 2233 2234When a value occupying several consecutive registers is expected in a 2235certain class, all the registers used must belong to that class. 2236Therefore, register classes cannot be used to enforce a requirement for 2237a register pair to start with an even-numbered register. The way to 2238specify this requirement is with @code{HARD_REGNO_MODE_OK}. 2239 2240Register classes used for input-operands of bitwise-and or shift 2241instructions have a special requirement: each such class must have, for 2242each fixed-point machine mode, a subclass whose registers can transfer that 2243mode to or from memory. For example, on some machines, the operations for 2244single-byte values (@code{QImode}) are limited to certain registers. When 2245this is so, each register class that is used in a bitwise-and or shift 2246instruction must have a subclass consisting of registers from which 2247single-byte values can be loaded or stored. This is so that 2248@code{PREFERRED_RELOAD_CLASS} can always have a possible value to return. 2249 2250@table @code 2251@findex enum reg_class 2252@item enum reg_class 2253An enumeral type that must be defined with all the register class names 2254as enumeral values. @code{NO_REGS} must be first. @code{ALL_REGS} 2255must be the last register class, followed by one more enumeral value, 2256@code{LIM_REG_CLASSES}, which is not a register class but rather 2257tells how many classes there are. 2258 2259Each register class has a number, which is the value of casting 2260the class name to type @code{int}. The number serves as an index 2261in many of the tables described below. 2262 2263@findex N_REG_CLASSES 2264@item N_REG_CLASSES 2265The number of distinct register classes, defined as follows: 2266 2267@example 2268#define N_REG_CLASSES (int) LIM_REG_CLASSES 2269@end example 2270 2271@findex REG_CLASS_NAMES 2272@item REG_CLASS_NAMES 2273An initializer containing the names of the register classes as C string 2274constants. These names are used in writing some of the debugging dumps. 2275 2276@findex REG_CLASS_CONTENTS 2277@item REG_CLASS_CONTENTS 2278An initializer containing the contents of the register classes, as integers 2279which are bit masks. The @var{n}th integer specifies the contents of class 2280@var{n}. The way the integer @var{mask} is interpreted is that 2281register @var{r} is in the class if @code{@var{mask} & (1 << @var{r})} is 1. 2282 2283When the machine has more than 32 registers, an integer does not suffice. 2284Then the integers are replaced by sub-initializers, braced groupings containing 2285several integers. Each sub-initializer must be suitable as an initializer 2286for the type @code{HARD_REG_SET} which is defined in @file{hard-reg-set.h}. 2287In this situation, the first integer in each sub-initializer corresponds to 2288registers 0 through 31, the second integer to registers 32 through 63, and 2289so on. 2290 2291@findex REGNO_REG_CLASS 2292@item REGNO_REG_CLASS (@var{regno}) 2293A C expression whose value is a register class containing hard register 2294@var{regno}. In general there is more than one such class; choose a class 2295which is @dfn{minimal}, meaning that no smaller class also contains the 2296register. 2297 2298@findex BASE_REG_CLASS 2299@item BASE_REG_CLASS 2300A macro whose definition is the name of the class to which a valid 2301base register must belong. A base register is one used in an address 2302which is the register value plus a displacement. 2303 2304@findex MODE_BASE_REG_CLASS 2305@item MODE_BASE_REG_CLASS (@var{mode}) 2306This is a variation of the @code{BASE_REG_CLASS} macro which allows 2307the selection of a base register in a mode dependent manner. If 2308@var{mode} is VOIDmode then it should return the same value as 2309@code{BASE_REG_CLASS}. 2310 2311@findex INDEX_REG_CLASS 2312@item INDEX_REG_CLASS 2313A macro whose definition is the name of the class to which a valid 2314index register must belong. An index register is one used in an 2315address where its value is either multiplied by a scale factor or 2316added to another register (as well as added to a displacement). 2317 2318@findex REG_CLASS_FROM_LETTER 2319@item REG_CLASS_FROM_LETTER (@var{char}) 2320A C expression which defines the machine-dependent operand constraint 2321letters for register classes. If @var{char} is such a letter, the 2322value should be the register class corresponding to it. Otherwise, 2323the value should be @code{NO_REGS}. The register letter @samp{r}, 2324corresponding to class @code{GENERAL_REGS}, will not be passed 2325to this macro; you do not need to handle it. 2326 2327@findex REGNO_OK_FOR_BASE_P 2328@item REGNO_OK_FOR_BASE_P (@var{num}) 2329A C expression which is nonzero if register number @var{num} is 2330suitable for use as a base register in operand addresses. It may be 2331either a suitable hard register or a pseudo register that has been 2332allocated such a hard register. 2333 2334@findex REGNO_MODE_OK_FOR_BASE_P 2335@item REGNO_MODE_OK_FOR_BASE_P (@var{num}, @var{mode}) 2336A C expression that is just like @code{REGNO_OK_FOR_BASE_P}, except that 2337that expression may examine the mode of the memory reference in 2338@var{mode}. You should define this macro if the mode of the memory 2339reference affects whether a register may be used as a base register. If 2340you define this macro, the compiler will use it instead of 2341@code{REGNO_OK_FOR_BASE_P}. 2342 2343@findex REGNO_OK_FOR_INDEX_P 2344@item REGNO_OK_FOR_INDEX_P (@var{num}) 2345A C expression which is nonzero if register number @var{num} is 2346suitable for use as an index register in operand addresses. It may be 2347either a suitable hard register or a pseudo register that has been 2348allocated such a hard register. 2349 2350The difference between an index register and a base register is that 2351the index register may be scaled. If an address involves the sum of 2352two registers, neither one of them scaled, then either one may be 2353labeled the ``base'' and the other the ``index''; but whichever 2354labeling is used must fit the machine's constraints of which registers 2355may serve in each capacity. The compiler will try both labelings, 2356looking for one that is valid, and will reload one or both registers 2357only if neither labeling works. 2358 2359@findex PREFERRED_RELOAD_CLASS 2360@item PREFERRED_RELOAD_CLASS (@var{x}, @var{class}) 2361A C expression that places additional restrictions on the register class 2362to use when it is necessary to copy value @var{x} into a register in class 2363@var{class}. The value is a register class; perhaps @var{class}, or perhaps 2364another, smaller class. On many machines, the following definition is 2365safe: 2366 2367@example 2368#define PREFERRED_RELOAD_CLASS(X,CLASS) CLASS 2369@end example 2370 2371Sometimes returning a more restrictive class makes better code. For 2372example, on the 68000, when @var{x} is an integer constant that is in range 2373for a @samp{moveq} instruction, the value of this macro is always 2374@code{DATA_REGS} as long as @var{class} includes the data registers. 2375Requiring a data register guarantees that a @samp{moveq} will be used. 2376 2377If @var{x} is a @code{const_double}, by returning @code{NO_REGS} 2378you can force @var{x} into a memory constant. This is useful on 2379certain machines where immediate floating values cannot be loaded into 2380certain kinds of registers. 2381 2382@findex PREFERRED_OUTPUT_RELOAD_CLASS 2383@item PREFERRED_OUTPUT_RELOAD_CLASS (@var{x}, @var{class}) 2384Like @code{PREFERRED_RELOAD_CLASS}, but for output reloads instead of 2385input reloads. If you don't define this macro, the default is to use 2386@var{class}, unchanged. 2387 2388@findex LIMIT_RELOAD_CLASS 2389@item LIMIT_RELOAD_CLASS (@var{mode}, @var{class}) 2390A C expression that places additional restrictions on the register class 2391to use when it is necessary to be able to hold a value of mode 2392@var{mode} in a reload register for which class @var{class} would 2393ordinarily be used. 2394 2395Unlike @code{PREFERRED_RELOAD_CLASS}, this macro should be used when 2396there are certain modes that simply can't go in certain reload classes. 2397 2398The value is a register class; perhaps @var{class}, or perhaps another, 2399smaller class. 2400 2401Don't define this macro unless the target machine has limitations which 2402require the macro to do something nontrivial. 2403 2404@findex SECONDARY_RELOAD_CLASS 2405@findex SECONDARY_INPUT_RELOAD_CLASS 2406@findex SECONDARY_OUTPUT_RELOAD_CLASS 2407@item SECONDARY_RELOAD_CLASS (@var{class}, @var{mode}, @var{x}) 2408@itemx SECONDARY_INPUT_RELOAD_CLASS (@var{class}, @var{mode}, @var{x}) 2409@itemx SECONDARY_OUTPUT_RELOAD_CLASS (@var{class}, @var{mode}, @var{x}) 2410Many machines have some registers that cannot be copied directly to or 2411from memory or even from other types of registers. An example is the 2412@samp{MQ} register, which on most machines, can only be copied to or 2413from general registers, but not memory. Some machines allow copying all 2414registers to and from memory, but require a scratch register for stores 2415to some memory locations (e.g., those with symbolic address on the RT, 2416and those with certain symbolic address on the SPARC when compiling 2417PIC)@. In some cases, both an intermediate and a scratch register are 2418required. 2419 2420You should define these macros to indicate to the reload phase that it may 2421need to allocate at least one register for a reload in addition to the 2422register to contain the data. Specifically, if copying @var{x} to a 2423register @var{class} in @var{mode} requires an intermediate register, 2424you should define @code{SECONDARY_INPUT_RELOAD_CLASS} to return the 2425largest register class all of whose registers can be used as 2426intermediate registers or scratch registers. 2427 2428If copying a register @var{class} in @var{mode} to @var{x} requires an 2429intermediate or scratch register, @code{SECONDARY_OUTPUT_RELOAD_CLASS} 2430should be defined to return the largest register class required. If the 2431requirements for input and output reloads are the same, the macro 2432@code{SECONDARY_RELOAD_CLASS} should be used instead of defining both 2433macros identically. 2434 2435The values returned by these macros are often @code{GENERAL_REGS}. 2436Return @code{NO_REGS} if no spare register is needed; i.e., if @var{x} 2437can be directly copied to or from a register of @var{class} in 2438@var{mode} without requiring a scratch register. Do not define this 2439macro if it would always return @code{NO_REGS}. 2440 2441If a scratch register is required (either with or without an 2442intermediate register), you should define patterns for 2443@samp{reload_in@var{m}} or @samp{reload_out@var{m}}, as required 2444(@pxref{Standard Names}. These patterns, which will normally be 2445implemented with a @code{define_expand}, should be similar to the 2446@samp{mov@var{m}} patterns, except that operand 2 is the scratch 2447register. 2448 2449Define constraints for the reload register and scratch register that 2450contain a single register class. If the original reload register (whose 2451class is @var{class}) can meet the constraint given in the pattern, the 2452value returned by these macros is used for the class of the scratch 2453register. Otherwise, two additional reload registers are required. 2454Their classes are obtained from the constraints in the insn pattern. 2455 2456@var{x} might be a pseudo-register or a @code{subreg} of a 2457pseudo-register, which could either be in a hard register or in memory. 2458Use @code{true_regnum} to find out; it will return @minus{}1 if the pseudo is 2459in memory and the hard register number if it is in a register. 2460 2461These macros should not be used in the case where a particular class of 2462registers can only be copied to memory and not to another class of 2463registers. In that case, secondary reload registers are not needed and 2464would not be helpful. Instead, a stack location must be used to perform 2465the copy and the @code{mov@var{m}} pattern should use memory as an 2466intermediate storage. This case often occurs between floating-point and 2467general registers. 2468 2469@findex SECONDARY_MEMORY_NEEDED 2470@item SECONDARY_MEMORY_NEEDED (@var{class1}, @var{class2}, @var{m}) 2471Certain machines have the property that some registers cannot be copied 2472to some other registers without using memory. Define this macro on 2473those machines to be a C expression that is nonzero if objects of mode 2474@var{m} in registers of @var{class1} can only be copied to registers of 2475class @var{class2} by storing a register of @var{class1} into memory 2476and loading that memory location into a register of @var{class2}. 2477 2478Do not define this macro if its value would always be zero. 2479 2480@findex SECONDARY_MEMORY_NEEDED_RTX 2481@item SECONDARY_MEMORY_NEEDED_RTX (@var{mode}) 2482Normally when @code{SECONDARY_MEMORY_NEEDED} is defined, the compiler 2483allocates a stack slot for a memory location needed for register copies. 2484If this macro is defined, the compiler instead uses the memory location 2485defined by this macro. 2486 2487Do not define this macro if you do not define 2488@code{SECONDARY_MEMORY_NEEDED}. 2489 2490@findex SECONDARY_MEMORY_NEEDED_MODE 2491@item SECONDARY_MEMORY_NEEDED_MODE (@var{mode}) 2492When the compiler needs a secondary memory location to copy between two 2493registers of mode @var{mode}, it normally allocates sufficient memory to 2494hold a quantity of @code{BITS_PER_WORD} bits and performs the store and 2495load operations in a mode that many bits wide and whose class is the 2496same as that of @var{mode}. 2497 2498This is right thing to do on most machines because it ensures that all 2499bits of the register are copied and prevents accesses to the registers 2500in a narrower mode, which some machines prohibit for floating-point 2501registers. 2502 2503However, this default behavior is not correct on some machines, such as 2504the DEC Alpha, that store short integers in floating-point registers 2505differently than in integer registers. On those machines, the default 2506widening will not work correctly and you must define this macro to 2507suppress that widening in some cases. See the file @file{alpha.h} for 2508details. 2509 2510Do not define this macro if you do not define 2511@code{SECONDARY_MEMORY_NEEDED} or if widening @var{mode} to a mode that 2512is @code{BITS_PER_WORD} bits wide is correct for your machine. 2513 2514@findex SMALL_REGISTER_CLASSES 2515@item SMALL_REGISTER_CLASSES 2516On some machines, it is risky to let hard registers live across arbitrary 2517insns. Typically, these machines have instructions that require values 2518to be in specific registers (like an accumulator), and reload will fail 2519if the required hard register is used for another purpose across such an 2520insn. 2521 2522Define @code{SMALL_REGISTER_CLASSES} to be an expression with a nonzero 2523value on these machines. When this macro has a nonzero value, the 2524compiler will try to minimize the lifetime of hard registers. 2525 2526It is always safe to define this macro with a nonzero value, but if you 2527unnecessarily define it, you will reduce the amount of optimizations 2528that can be performed in some cases. If you do not define this macro 2529with a nonzero value when it is required, the compiler will run out of 2530spill registers and print a fatal error message. For most machines, you 2531should not define this macro at all. 2532 2533@findex CLASS_LIKELY_SPILLED_P 2534@item CLASS_LIKELY_SPILLED_P (@var{class}) 2535A C expression whose value is nonzero if pseudos that have been assigned 2536to registers of class @var{class} would likely be spilled because 2537registers of @var{class} are needed for spill registers. 2538 2539The default value of this macro returns 1 if @var{class} has exactly one 2540register and zero otherwise. On most machines, this default should be 2541used. Only define this macro to some other expression if pseudos 2542allocated by @file{local-alloc.c} end up in memory because their hard 2543registers were needed for spill registers. If this macro returns nonzero 2544for those classes, those pseudos will only be allocated by 2545@file{global.c}, which knows how to reallocate the pseudo to another 2546register. If there would not be another register available for 2547reallocation, you should not change the definition of this macro since 2548the only effect of such a definition would be to slow down register 2549allocation. 2550 2551@findex CLASS_MAX_NREGS 2552@item CLASS_MAX_NREGS (@var{class}, @var{mode}) 2553A C expression for the maximum number of consecutive registers 2554of class @var{class} needed to hold a value of mode @var{mode}. 2555 2556This is closely related to the macro @code{HARD_REGNO_NREGS}. In fact, 2557the value of the macro @code{CLASS_MAX_NREGS (@var{class}, @var{mode})} 2558should be the maximum value of @code{HARD_REGNO_NREGS (@var{regno}, 2559@var{mode})} for all @var{regno} values in the class @var{class}. 2560 2561This macro helps control the handling of multiple-word values 2562in the reload pass. 2563 2564@item CANNOT_CHANGE_MODE_CLASS(@var{from}, @var{to}, @var{class}) 2565If defined, a C expression that returns nonzero for a @var{class} for which 2566a change from mode @var{from} to mode @var{to} is invalid. 2567 2568For the example, loading 32-bit integer or floating-point objects into 2569floating-point registers on the Alpha extends them to 64 bits. 2570Therefore loading a 64-bit object and then storing it as a 32-bit object 2571does not store the low-order 32 bits, as would be the case for a normal 2572register. Therefore, @file{alpha.h} defines @code{CANNOT_CHANGE_MODE_CLASS} 2573as below: 2574 2575@example 2576#define CANNOT_CHANGE_MODE_CLASS(FROM, TO, CLASS) \ 2577 (GET_MODE_SIZE (FROM) != GET_MODE_SIZE (TO) \ 2578 ? reg_classes_intersect_p (FLOAT_REGS, (CLASS)) : 0) 2579@end example 2580@end table 2581 2582Three other special macros describe which operands fit which constraint 2583letters. 2584 2585@table @code 2586@findex CONST_OK_FOR_LETTER_P 2587@item CONST_OK_FOR_LETTER_P (@var{value}, @var{c}) 2588A C expression that defines the machine-dependent operand constraint 2589letters (@samp{I}, @samp{J}, @samp{K}, @dots{} @samp{P}) that specify 2590particular ranges of integer values. If @var{c} is one of those 2591letters, the expression should check that @var{value}, an integer, is in 2592the appropriate range and return 1 if so, 0 otherwise. If @var{c} is 2593not one of those letters, the value should be 0 regardless of 2594@var{value}. 2595 2596@findex CONST_DOUBLE_OK_FOR_LETTER_P 2597@item CONST_DOUBLE_OK_FOR_LETTER_P (@var{value}, @var{c}) 2598A C expression that defines the machine-dependent operand constraint 2599letters that specify particular ranges of @code{const_double} values 2600(@samp{G} or @samp{H}). 2601 2602If @var{c} is one of those letters, the expression should check that 2603@var{value}, an RTX of code @code{const_double}, is in the appropriate 2604range and return 1 if so, 0 otherwise. If @var{c} is not one of those 2605letters, the value should be 0 regardless of @var{value}. 2606 2607@code{const_double} is used for all floating-point constants and for 2608@code{DImode} fixed-point constants. A given letter can accept either 2609or both kinds of values. It can use @code{GET_MODE} to distinguish 2610between these kinds. 2611 2612@findex EXTRA_CONSTRAINT 2613@item EXTRA_CONSTRAINT (@var{value}, @var{c}) 2614A C expression that defines the optional machine-dependent constraint 2615letters that can be used to segregate specific types of operands, usually 2616memory references, for the target machine. Any letter that is not 2617elsewhere defined and not matched by @code{REG_CLASS_FROM_LETTER} 2618may be used. Normally this macro will not be defined. 2619 2620If it is required for a particular target machine, it should return 1 2621if @var{value} corresponds to the operand type represented by the 2622constraint letter @var{c}. If @var{c} is not defined as an extra 2623constraint, the value returned should be 0 regardless of @var{value}. 2624 2625For example, on the ROMP, load instructions cannot have their output 2626in r0 if the memory reference contains a symbolic address. Constraint 2627letter @samp{Q} is defined as representing a memory address that does 2628@emph{not} contain a symbolic address. An alternative is specified with 2629a @samp{Q} constraint on the input and @samp{r} on the output. The next 2630alternative specifies @samp{m} on the input and a register class that 2631does not include r0 on the output. 2632 2633@findex EXTRA_MEMORY_CONSTRAINT 2634@item EXTRA_MEMORY_CONSTRAINT (@var{c}) 2635A C expression that defines the optional machine-dependent constraint 2636letters, amongst those accepted by @code{EXTRA_CONSTRAINT}, that should 2637be treated like memory constraints by the reload pass. 2638 2639It should return 1 if the operand type represented by the constraint 2640letter @var{c} comprises a subset of all memory references including 2641all those whose address is simply a base register. This allows the reload 2642pass to reload an operand, if it does not directly correspond to the operand 2643type of @var{c}, by copying its address into a base register. 2644 2645For example, on the S/390, some instructions do not accept arbitrary 2646memory references, but only those that do not make use of an index 2647register. The constraint letter @samp{Q} is defined via 2648@code{EXTRA_CONSTRAINT} as representing a memory address of this type. 2649If the letter @samp{Q} is marked as @code{EXTRA_MEMORY_CONSTRAINT}, 2650a @samp{Q} constraint can handle any memory operand, because the 2651reload pass knows it can be reloaded by copying the memory address 2652into a base register if required. This is analogous to the way 2653a @samp{o} constraint can handle any memory operand. 2654 2655@findex EXTRA_ADDRESS_CONSTRAINT 2656@item EXTRA_ADDRESS_CONSTRAINT (@var{c}) 2657A C expression that defines the optional machine-dependent constraint 2658letters, amongst those accepted by @code{EXTRA_CONSTRAINT}, that should 2659be treated like address constraints by the reload pass. 2660 2661It should return 1 if the operand type represented by the constraint 2662letter @var{c} comprises a subset of all memory addresses including 2663all those that consist of just a base register. This allows the reload 2664pass to reload an operand, if it does not directly correspond to the operand 2665type of @var{c}, by copying it into a base register. 2666 2667Any constraint marked as @code{EXTRA_ADDRESS_CONSTRAINT} can only 2668be used with the @code{address_operand} predicate. It is treated 2669analogously to the @samp{p} constraint. 2670@end table 2671 2672@node Stack and Calling 2673@section Stack Layout and Calling Conventions 2674@cindex calling conventions 2675 2676@c prevent bad page break with this line 2677This describes the stack layout and calling conventions. 2678 2679@menu 2680* Frame Layout:: 2681* Exception Handling:: 2682* Stack Checking:: 2683* Frame Registers:: 2684* Elimination:: 2685* Stack Arguments:: 2686* Register Arguments:: 2687* Scalar Return:: 2688* Aggregate Return:: 2689* Caller Saves:: 2690* Function Entry:: 2691* Profiling:: 2692* Tail Calls:: 2693@end menu 2694 2695@node Frame Layout 2696@subsection Basic Stack Layout 2697@cindex stack frame layout 2698@cindex frame layout 2699 2700@c prevent bad page break with this line 2701Here is the basic stack layout. 2702 2703@table @code 2704@findex STACK_GROWS_DOWNWARD 2705@item STACK_GROWS_DOWNWARD 2706Define this macro if pushing a word onto the stack moves the stack 2707pointer to a smaller address. 2708 2709When we say, ``define this macro if @dots{},'' it means that the 2710compiler checks this macro only with @code{#ifdef} so the precise 2711definition used does not matter. 2712 2713@findex STACK_PUSH_CODE 2714@item STACK_PUSH_CODE 2715 2716This macro defines the operation used when something is pushed 2717on the stack. In RTL, a push operation will be 2718@code{(set (mem (STACK_PUSH_CODE (reg sp))) @dots{})} 2719 2720The choices are @code{PRE_DEC}, @code{POST_DEC}, @code{PRE_INC}, 2721and @code{POST_INC}. Which of these is correct depends on 2722the stack direction and on whether the stack pointer points 2723to the last item on the stack or whether it points to the 2724space for the next item on the stack. 2725 2726The default is @code{PRE_DEC} when @code{STACK_GROWS_DOWNWARD} is 2727defined, which is almost always right, and @code{PRE_INC} otherwise, 2728which is often wrong. 2729 2730@findex FRAME_GROWS_DOWNWARD 2731@item FRAME_GROWS_DOWNWARD 2732Define this macro if the addresses of local variable slots are at negative 2733offsets from the frame pointer. 2734 2735@findex ARGS_GROW_DOWNWARD 2736@item ARGS_GROW_DOWNWARD 2737Define this macro if successive arguments to a function occupy decreasing 2738addresses on the stack. 2739 2740@findex STARTING_FRAME_OFFSET 2741@item STARTING_FRAME_OFFSET 2742Offset from the frame pointer to the first local variable slot to be allocated. 2743 2744If @code{FRAME_GROWS_DOWNWARD}, find the next slot's offset by 2745subtracting the first slot's length from @code{STARTING_FRAME_OFFSET}. 2746Otherwise, it is found by adding the length of the first slot to the 2747value @code{STARTING_FRAME_OFFSET}. 2748@c i'm not sure if the above is still correct.. had to change it to get 2749@c rid of an overfull. --mew 2feb93 2750 2751@findex STACK_POINTER_OFFSET 2752@item STACK_POINTER_OFFSET 2753Offset from the stack pointer register to the first location at which 2754outgoing arguments are placed. If not specified, the default value of 2755zero is used. This is the proper value for most machines. 2756 2757If @code{ARGS_GROW_DOWNWARD}, this is the offset to the location above 2758the first location at which outgoing arguments are placed. 2759 2760@findex FIRST_PARM_OFFSET 2761@item FIRST_PARM_OFFSET (@var{fundecl}) 2762Offset from the argument pointer register to the first argument's 2763address. On some machines it may depend on the data type of the 2764function. 2765 2766If @code{ARGS_GROW_DOWNWARD}, this is the offset to the location above 2767the first argument's address. 2768 2769@findex STACK_DYNAMIC_OFFSET 2770@item STACK_DYNAMIC_OFFSET (@var{fundecl}) 2771Offset from the stack pointer register to an item dynamically allocated 2772on the stack, e.g., by @code{alloca}. 2773 2774The default value for this macro is @code{STACK_POINTER_OFFSET} plus the 2775length of the outgoing arguments. The default is correct for most 2776machines. See @file{function.c} for details. 2777 2778@findex DYNAMIC_CHAIN_ADDRESS 2779@item DYNAMIC_CHAIN_ADDRESS (@var{frameaddr}) 2780A C expression whose value is RTL representing the address in a stack 2781frame where the pointer to the caller's frame is stored. Assume that 2782@var{frameaddr} is an RTL expression for the address of the stack frame 2783itself. 2784 2785If you don't define this macro, the default is to return the value 2786of @var{frameaddr}---that is, the stack frame address is also the 2787address of the stack word that points to the previous frame. 2788 2789@findex SETUP_FRAME_ADDRESSES 2790@item SETUP_FRAME_ADDRESSES 2791If defined, a C expression that produces the machine-specific code to 2792setup the stack so that arbitrary frames can be accessed. For example, 2793on the SPARC, we must flush all of the register windows to the stack 2794before we can access arbitrary stack frames. You will seldom need to 2795define this macro. 2796 2797@findex BUILTIN_SETJMP_FRAME_VALUE 2798@item BUILTIN_SETJMP_FRAME_VALUE 2799If defined, a C expression that contains an rtx that is used to store 2800the address of the current frame into the built in @code{setjmp} buffer. 2801The default value, @code{virtual_stack_vars_rtx}, is correct for most 2802machines. One reason you may need to define this macro is if 2803@code{hard_frame_pointer_rtx} is the appropriate value on your machine. 2804 2805@findex RETURN_ADDR_RTX 2806@item RETURN_ADDR_RTX (@var{count}, @var{frameaddr}) 2807A C expression whose value is RTL representing the value of the return 2808address for the frame @var{count} steps up from the current frame, after 2809the prologue. @var{frameaddr} is the frame pointer of the @var{count} 2810frame, or the frame pointer of the @var{count} @minus{} 1 frame if 2811@code{RETURN_ADDR_IN_PREVIOUS_FRAME} is defined. 2812 2813The value of the expression must always be the correct address when 2814@var{count} is zero, but may be @code{NULL_RTX} if there is not way to 2815determine the return address of other frames. 2816 2817@findex RETURN_ADDR_IN_PREVIOUS_FRAME 2818@item RETURN_ADDR_IN_PREVIOUS_FRAME 2819Define this if the return address of a particular stack frame is accessed 2820from the frame pointer of the previous stack frame. 2821 2822@findex INCOMING_RETURN_ADDR_RTX 2823@item INCOMING_RETURN_ADDR_RTX 2824A C expression whose value is RTL representing the location of the 2825incoming return address at the beginning of any function, before the 2826prologue. This RTL is either a @code{REG}, indicating that the return 2827value is saved in @samp{REG}, or a @code{MEM} representing a location in 2828the stack. 2829 2830You only need to define this macro if you want to support call frame 2831debugging information like that provided by DWARF 2. 2832 2833If this RTL is a @code{REG}, you should also define 2834@code{DWARF_FRAME_RETURN_COLUMN} to @code{DWARF_FRAME_REGNUM (REGNO)}. 2835 2836@findex INCOMING_FRAME_SP_OFFSET 2837@item INCOMING_FRAME_SP_OFFSET 2838A C expression whose value is an integer giving the offset, in bytes, 2839from the value of the stack pointer register to the top of the stack 2840frame at the beginning of any function, before the prologue. The top of 2841the frame is defined to be the value of the stack pointer in the 2842previous frame, just before the call instruction. 2843 2844You only need to define this macro if you want to support call frame 2845debugging information like that provided by DWARF 2. 2846 2847@findex ARG_POINTER_CFA_OFFSET 2848@item ARG_POINTER_CFA_OFFSET (@var{fundecl}) 2849A C expression whose value is an integer giving the offset, in bytes, 2850from the argument pointer to the canonical frame address (cfa). The 2851final value should coincide with that calculated by 2852@code{INCOMING_FRAME_SP_OFFSET}. Which is unfortunately not usable 2853during virtual register instantiation. 2854 2855The default value for this macro is @code{FIRST_PARM_OFFSET (fundecl)}, 2856which is correct for most machines; in general, the arguments are found 2857immediately before the stack frame. Note that this is not the case on 2858some targets that save registers into the caller's frame, such as SPARC 2859and rs6000, and so such targets need to define this macro. 2860 2861You only need to define this macro if the default is incorrect, and you 2862want to support call frame debugging information like that provided by 2863DWARF 2. 2864 2865@findex SMALL_STACK 2866@item SMALL_STACK 2867Define this macro if the stack size for the target is very small. This 2868has the effect of disabling gcc's built-in @samp{alloca}, though 2869@samp{__builtin_alloca} is not affected. 2870@end table 2871 2872@node Exception Handling 2873@subsection Exception Handling Support 2874@cindex exception handling 2875 2876@table @code 2877@findex EH_RETURN_DATA_REGNO 2878@item EH_RETURN_DATA_REGNO (@var{N}) 2879A C expression whose value is the @var{N}th register number used for 2880data by exception handlers, or @code{INVALID_REGNUM} if fewer than 2881@var{N} registers are usable. 2882 2883The exception handling library routines communicate with the exception 2884handlers via a set of agreed upon registers. Ideally these registers 2885should be call-clobbered; it is possible to use call-saved registers, 2886but may negatively impact code size. The target must support at least 28872 data registers, but should define 4 if there are enough free registers. 2888 2889You must define this macro if you want to support call frame exception 2890handling like that provided by DWARF 2. 2891 2892@findex EH_RETURN_STACKADJ_RTX 2893@item EH_RETURN_STACKADJ_RTX 2894A C expression whose value is RTL representing a location in which 2895to store a stack adjustment to be applied before function return. 2896This is used to unwind the stack to an exception handler's call frame. 2897It will be assigned zero on code paths that return normally. 2898 2899Typically this is a call-clobbered hard register that is otherwise 2900untouched by the epilogue, but could also be a stack slot. 2901 2902Do not define this macro if the stack pointer is saved and restored 2903by the regular prolog and epilog code in the call frame itself; in 2904this case, the exception handling library routines will update the 2905stack location to be restored in place. Otherwise, you must define 2906this macro if you want to support call frame exception handling like 2907that provided by DWARF 2. 2908 2909@findex EH_RETURN_HANDLER_RTX 2910@item EH_RETURN_HANDLER_RTX 2911A C expression whose value is RTL representing a location in which 2912to store the address of an exception handler to which we should 2913return. It will not be assigned on code paths that return normally. 2914 2915Typically this is the location in the call frame at which the normal 2916return address is stored. For targets that return by popping an 2917address off the stack, this might be a memory address just below 2918the @emph{target} call frame rather than inside the current call 2919frame. If defined, @code{EH_RETURN_STACKADJ_RTX} will have already 2920been assigned, so it may be used to calculate the location of the 2921target call frame. 2922 2923Some targets have more complex requirements than storing to an 2924address calculable during initial code generation. In that case 2925the @code{eh_return} instruction pattern should be used instead. 2926 2927If you want to support call frame exception handling, you must 2928define either this macro or the @code{eh_return} instruction pattern. 2929 2930@findex ASM_PREFERRED_EH_DATA_FORMAT 2931@item ASM_PREFERRED_EH_DATA_FORMAT(@var{code}, @var{global}) 2932This macro chooses the encoding of pointers embedded in the exception 2933handling sections. If at all possible, this should be defined such 2934that the exception handling section will not require dynamic relocations, 2935and so may be read-only. 2936 2937@var{code} is 0 for data, 1 for code labels, 2 for function pointers. 2938@var{global} is true if the symbol may be affected by dynamic relocations. 2939The macro should return a combination of the @code{DW_EH_PE_*} defines 2940as found in @file{dwarf2.h}. 2941 2942If this macro is not defined, pointers will not be encoded but 2943represented directly. 2944 2945@findex ASM_MAYBE_OUTPUT_ENCODED_ADDR_RTX 2946@item ASM_MAYBE_OUTPUT_ENCODED_ADDR_RTX(@var{file}, @var{encoding}, @var{size}, @var{addr}, @var{done}) 2947This macro allows the target to emit whatever special magic is required 2948to represent the encoding chosen by @code{ASM_PREFERRED_EH_DATA_FORMAT}. 2949Generic code takes care of pc-relative and indirect encodings; this must 2950be defined if the target uses text-relative or data-relative encodings. 2951 2952This is a C statement that branches to @var{done} if the format was 2953handled. @var{encoding} is the format chosen, @var{size} is the number 2954of bytes that the format occupies, @var{addr} is the @code{SYMBOL_REF} 2955to be emitted. 2956 2957@findex MD_FALLBACK_FRAME_STATE_FOR 2958@item MD_FALLBACK_FRAME_STATE_FOR(@var{context}, @var{fs}, @var{success}) 2959This macro allows the target to add cpu and operating system specific 2960code to the call-frame unwinder for use when there is no unwind data 2961available. The most common reason to implement this macro is to unwind 2962through signal frames. 2963 2964This macro is called from @code{uw_frame_state_for} in @file{unwind-dw2.c} 2965and @file{unwind-ia64.c}. @var{context} is an @code{_Unwind_Context}; 2966@var{fs} is an @code{_Unwind_FrameState}. Examine @code{context->ra} 2967for the address of the code being executed and @code{context->cfa} for 2968the stack pointer value. If the frame can be decoded, the register save 2969addresses should be updated in @var{fs} and the macro should branch to 2970@var{success}. If the frame cannot be decoded, the macro should do 2971nothing. 2972@end table 2973 2974@node Stack Checking 2975@subsection Specifying How Stack Checking is Done 2976 2977GCC will check that stack references are within the boundaries of 2978the stack, if the @option{-fstack-check} is specified, in one of three ways: 2979 2980@enumerate 2981@item 2982If the value of the @code{STACK_CHECK_BUILTIN} macro is nonzero, GCC 2983will assume that you have arranged for stack checking to be done at 2984appropriate places in the configuration files, e.g., in 2985@code{TARGET_ASM_FUNCTION_PROLOGUE}. GCC will do not other special 2986processing. 2987 2988@item 2989If @code{STACK_CHECK_BUILTIN} is zero and you defined a named pattern 2990called @code{check_stack} in your @file{md} file, GCC will call that 2991pattern with one argument which is the address to compare the stack 2992value against. You must arrange for this pattern to report an error if 2993the stack pointer is out of range. 2994 2995@item 2996If neither of the above are true, GCC will generate code to periodically 2997``probe'' the stack pointer using the values of the macros defined below. 2998@end enumerate 2999 3000Normally, you will use the default values of these macros, so GCC 3001will use the third approach. 3002 3003@table @code 3004@findex STACK_CHECK_BUILTIN 3005@item STACK_CHECK_BUILTIN 3006A nonzero value if stack checking is done by the configuration files in a 3007machine-dependent manner. You should define this macro if stack checking 3008is require by the ABI of your machine or if you would like to have to stack 3009checking in some more efficient way than GCC's portable approach. 3010The default value of this macro is zero. 3011 3012@findex STACK_CHECK_PROBE_INTERVAL 3013@item STACK_CHECK_PROBE_INTERVAL 3014An integer representing the interval at which GCC must generate stack 3015probe instructions. You will normally define this macro to be no larger 3016than the size of the ``guard pages'' at the end of a stack area. The 3017default value of 4096 is suitable for most systems. 3018 3019@findex STACK_CHECK_PROBE_LOAD 3020@item STACK_CHECK_PROBE_LOAD 3021A integer which is nonzero if GCC should perform the stack probe 3022as a load instruction and zero if GCC should use a store instruction. 3023The default is zero, which is the most efficient choice on most systems. 3024 3025@findex STACK_CHECK_PROTECT 3026@item STACK_CHECK_PROTECT 3027The number of bytes of stack needed to recover from a stack overflow, 3028for languages where such a recovery is supported. The default value of 302975 words should be adequate for most machines. 3030 3031@findex STACK_CHECK_MAX_FRAME_SIZE 3032@item STACK_CHECK_MAX_FRAME_SIZE 3033The maximum size of a stack frame, in bytes. GCC will generate probe 3034instructions in non-leaf functions to ensure at least this many bytes of 3035stack are available. If a stack frame is larger than this size, stack 3036checking will not be reliable and GCC will issue a warning. The 3037default is chosen so that GCC only generates one instruction on most 3038systems. You should normally not change the default value of this macro. 3039 3040@findex STACK_CHECK_FIXED_FRAME_SIZE 3041@item STACK_CHECK_FIXED_FRAME_SIZE 3042GCC uses this value to generate the above warning message. It 3043represents the amount of fixed frame used by a function, not including 3044space for any callee-saved registers, temporaries and user variables. 3045You need only specify an upper bound for this amount and will normally 3046use the default of four words. 3047 3048@findex STACK_CHECK_MAX_VAR_SIZE 3049@item STACK_CHECK_MAX_VAR_SIZE 3050The maximum size, in bytes, of an object that GCC will place in the 3051fixed area of the stack frame when the user specifies 3052@option{-fstack-check}. 3053GCC computed the default from the values of the above macros and you will 3054normally not need to override that default. 3055@end table 3056 3057@need 2000 3058@node Frame Registers 3059@subsection Registers That Address the Stack Frame 3060 3061@c prevent bad page break with this line 3062This discusses registers that address the stack frame. 3063 3064@table @code 3065@findex STACK_POINTER_REGNUM 3066@item STACK_POINTER_REGNUM 3067The register number of the stack pointer register, which must also be a 3068fixed register according to @code{FIXED_REGISTERS}. On most machines, 3069the hardware determines which register this is. 3070 3071@findex FRAME_POINTER_REGNUM 3072@item FRAME_POINTER_REGNUM 3073The register number of the frame pointer register, which is used to 3074access automatic variables in the stack frame. On some machines, the 3075hardware determines which register this is. On other machines, you can 3076choose any register you wish for this purpose. 3077 3078@findex HARD_FRAME_POINTER_REGNUM 3079@item HARD_FRAME_POINTER_REGNUM 3080On some machines the offset between the frame pointer and starting 3081offset of the automatic variables is not known until after register 3082allocation has been done (for example, because the saved registers are 3083between these two locations). On those machines, define 3084@code{FRAME_POINTER_REGNUM} the number of a special, fixed register to 3085be used internally until the offset is known, and define 3086@code{HARD_FRAME_POINTER_REGNUM} to be the actual hard register number 3087used for the frame pointer. 3088 3089You should define this macro only in the very rare circumstances when it 3090is not possible to calculate the offset between the frame pointer and 3091the automatic variables until after register allocation has been 3092completed. When this macro is defined, you must also indicate in your 3093definition of @code{ELIMINABLE_REGS} how to eliminate 3094@code{FRAME_POINTER_REGNUM} into either @code{HARD_FRAME_POINTER_REGNUM} 3095or @code{STACK_POINTER_REGNUM}. 3096 3097Do not define this macro if it would be the same as 3098@code{FRAME_POINTER_REGNUM}. 3099 3100@findex ARG_POINTER_REGNUM 3101@item ARG_POINTER_REGNUM 3102The register number of the arg pointer register, which is used to access 3103the function's argument list. On some machines, this is the same as the 3104frame pointer register. On some machines, the hardware determines which 3105register this is. On other machines, you can choose any register you 3106wish for this purpose. If this is not the same register as the frame 3107pointer register, then you must mark it as a fixed register according to 3108@code{FIXED_REGISTERS}, or arrange to be able to eliminate it 3109(@pxref{Elimination}). 3110 3111@findex RETURN_ADDRESS_POINTER_REGNUM 3112@item RETURN_ADDRESS_POINTER_REGNUM 3113The register number of the return address pointer register, which is used to 3114access the current function's return address from the stack. On some 3115machines, the return address is not at a fixed offset from the frame 3116pointer or stack pointer or argument pointer. This register can be defined 3117to point to the return address on the stack, and then be converted by 3118@code{ELIMINABLE_REGS} into either the frame pointer or stack pointer. 3119 3120Do not define this macro unless there is no other way to get the return 3121address from the stack. 3122 3123@findex STATIC_CHAIN_REGNUM 3124@findex STATIC_CHAIN_INCOMING_REGNUM 3125@item STATIC_CHAIN_REGNUM 3126@itemx STATIC_CHAIN_INCOMING_REGNUM 3127Register numbers used for passing a function's static chain pointer. If 3128register windows are used, the register number as seen by the called 3129function is @code{STATIC_CHAIN_INCOMING_REGNUM}, while the register 3130number as seen by the calling function is @code{STATIC_CHAIN_REGNUM}. If 3131these registers are the same, @code{STATIC_CHAIN_INCOMING_REGNUM} need 3132not be defined. 3133 3134The static chain register need not be a fixed register. 3135 3136If the static chain is passed in memory, these macros should not be 3137defined; instead, the next two macros should be defined. 3138 3139@findex STATIC_CHAIN 3140@findex STATIC_CHAIN_INCOMING 3141@item STATIC_CHAIN 3142@itemx STATIC_CHAIN_INCOMING 3143If the static chain is passed in memory, these macros provide rtx giving 3144@code{mem} expressions that denote where they are stored. 3145@code{STATIC_CHAIN} and @code{STATIC_CHAIN_INCOMING} give the locations 3146as seen by the calling and called functions, respectively. Often the former 3147will be at an offset from the stack pointer and the latter at an offset from 3148the frame pointer. 3149 3150@findex stack_pointer_rtx 3151@findex frame_pointer_rtx 3152@findex arg_pointer_rtx 3153The variables @code{stack_pointer_rtx}, @code{frame_pointer_rtx}, and 3154@code{arg_pointer_rtx} will have been initialized prior to the use of these 3155macros and should be used to refer to those items. 3156 3157If the static chain is passed in a register, the two previous macros should 3158be defined instead. 3159 3160@findex DWARF_FRAME_REGISTERS 3161@item DWARF_FRAME_REGISTERS 3162This macro specifies the maximum number of hard registers that can be 3163saved in a call frame. This is used to size data structures used in 3164DWARF2 exception handling. 3165 3166Prior to GCC 3.0, this macro was needed in order to establish a stable 3167exception handling ABI in the face of adding new hard registers for ISA 3168extensions. In GCC 3.0 and later, the EH ABI is insulated from changes 3169in the number of hard registers. Nevertheless, this macro can still be 3170used to reduce the runtime memory requirements of the exception handling 3171routines, which can be substantial if the ISA contains a lot of 3172registers that are not call-saved. 3173 3174If this macro is not defined, it defaults to 3175@code{FIRST_PSEUDO_REGISTER}. 3176 3177@findex PRE_GCC3_DWARF_FRAME_REGISTERS 3178@item PRE_GCC3_DWARF_FRAME_REGISTERS 3179 3180This macro is similar to @code{DWARF_FRAME_REGISTERS}, but is provided 3181for backward compatibility in pre GCC 3.0 compiled code. 3182 3183If this macro is not defined, it defaults to 3184@code{DWARF_FRAME_REGISTERS}. 3185 3186@end table 3187 3188@node Elimination 3189@subsection Eliminating Frame Pointer and Arg Pointer 3190 3191@c prevent bad page break with this line 3192This is about eliminating the frame pointer and arg pointer. 3193 3194@table @code 3195@findex FRAME_POINTER_REQUIRED 3196@item FRAME_POINTER_REQUIRED 3197A C expression which is nonzero if a function must have and use a frame 3198pointer. This expression is evaluated in the reload pass. If its value is 3199nonzero the function will have a frame pointer. 3200 3201The expression can in principle examine the current function and decide 3202according to the facts, but on most machines the constant 0 or the 3203constant 1 suffices. Use 0 when the machine allows code to be generated 3204with no frame pointer, and doing so saves some time or space. Use 1 3205when there is no possible advantage to avoiding a frame pointer. 3206 3207In certain cases, the compiler does not know how to produce valid code 3208without a frame pointer. The compiler recognizes those cases and 3209automatically gives the function a frame pointer regardless of what 3210@code{FRAME_POINTER_REQUIRED} says. You don't need to worry about 3211them. 3212 3213In a function that does not require a frame pointer, the frame pointer 3214register can be allocated for ordinary usage, unless you mark it as a 3215fixed register. See @code{FIXED_REGISTERS} for more information. 3216 3217@findex INITIAL_FRAME_POINTER_OFFSET 3218@findex get_frame_size 3219@item INITIAL_FRAME_POINTER_OFFSET (@var{depth-var}) 3220A C statement to store in the variable @var{depth-var} the difference 3221between the frame pointer and the stack pointer values immediately after 3222the function prologue. The value would be computed from information 3223such as the result of @code{get_frame_size ()} and the tables of 3224registers @code{regs_ever_live} and @code{call_used_regs}. 3225 3226If @code{ELIMINABLE_REGS} is defined, this macro will be not be used and 3227need not be defined. Otherwise, it must be defined even if 3228@code{FRAME_POINTER_REQUIRED} is defined to always be true; in that 3229case, you may set @var{depth-var} to anything. 3230 3231@findex ELIMINABLE_REGS 3232@item ELIMINABLE_REGS 3233If defined, this macro specifies a table of register pairs used to 3234eliminate unneeded registers that point into the stack frame. If it is not 3235defined, the only elimination attempted by the compiler is to replace 3236references to the frame pointer with references to the stack pointer. 3237 3238The definition of this macro is a list of structure initializations, each 3239of which specifies an original and replacement register. 3240 3241On some machines, the position of the argument pointer is not known until 3242the compilation is completed. In such a case, a separate hard register 3243must be used for the argument pointer. This register can be eliminated by 3244replacing it with either the frame pointer or the argument pointer, 3245depending on whether or not the frame pointer has been eliminated. 3246 3247In this case, you might specify: 3248@example 3249#define ELIMINABLE_REGS \ 3250@{@{ARG_POINTER_REGNUM, STACK_POINTER_REGNUM@}, \ 3251 @{ARG_POINTER_REGNUM, FRAME_POINTER_REGNUM@}, \ 3252 @{FRAME_POINTER_REGNUM, STACK_POINTER_REGNUM@}@} 3253@end example 3254 3255Note that the elimination of the argument pointer with the stack pointer is 3256specified first since that is the preferred elimination. 3257 3258@findex CAN_ELIMINATE 3259@item CAN_ELIMINATE (@var{from-reg}, @var{to-reg}) 3260A C expression that returns nonzero if the compiler is allowed to try 3261to replace register number @var{from-reg} with register number 3262@var{to-reg}. This macro need only be defined if @code{ELIMINABLE_REGS} 3263is defined, and will usually be the constant 1, since most of the cases 3264preventing register elimination are things that the compiler already 3265knows about. 3266 3267@findex INITIAL_ELIMINATION_OFFSET 3268@item INITIAL_ELIMINATION_OFFSET (@var{from-reg}, @var{to-reg}, @var{offset-var}) 3269This macro is similar to @code{INITIAL_FRAME_POINTER_OFFSET}. It 3270specifies the initial difference between the specified pair of 3271registers. This macro must be defined if @code{ELIMINABLE_REGS} is 3272defined. 3273@end table 3274 3275@node Stack Arguments 3276@subsection Passing Function Arguments on the Stack 3277@cindex arguments on stack 3278@cindex stack arguments 3279 3280The macros in this section control how arguments are passed 3281on the stack. See the following section for other macros that 3282control passing certain arguments in registers. 3283 3284@table @code 3285@findex PROMOTE_PROTOTYPES 3286@item PROMOTE_PROTOTYPES 3287A C expression whose value is nonzero if an argument declared in 3288a prototype as an integral type smaller than @code{int} should 3289actually be passed as an @code{int}. In addition to avoiding 3290errors in certain cases of mismatch, it also makes for better 3291code on certain machines. If the macro is not defined in target 3292header files, it defaults to 0. 3293 3294@findex PUSH_ARGS 3295@item PUSH_ARGS 3296A C expression. If nonzero, push insns will be used to pass 3297outgoing arguments. 3298If the target machine does not have a push instruction, set it to zero. 3299That directs GCC to use an alternate strategy: to 3300allocate the entire argument block and then store the arguments into 3301it. When @code{PUSH_ARGS} is nonzero, @code{PUSH_ROUNDING} must be defined too. 3302 3303@findex PUSH_ROUNDING 3304@item PUSH_ROUNDING (@var{npushed}) 3305A C expression that is the number of bytes actually pushed onto the 3306stack when an instruction attempts to push @var{npushed} bytes. 3307 3308On some machines, the definition 3309 3310@example 3311#define PUSH_ROUNDING(BYTES) (BYTES) 3312@end example 3313 3314@noindent 3315will suffice. But on other machines, instructions that appear 3316to push one byte actually push two bytes in an attempt to maintain 3317alignment. Then the definition should be 3318 3319@example 3320#define PUSH_ROUNDING(BYTES) (((BYTES) + 1) & ~1) 3321@end example 3322 3323@findex ACCUMULATE_OUTGOING_ARGS 3324@findex current_function_outgoing_args_size 3325@item ACCUMULATE_OUTGOING_ARGS 3326A C expression. If nonzero, the maximum amount of space required for outgoing arguments 3327will be computed and placed into the variable 3328@code{current_function_outgoing_args_size}. No space will be pushed 3329onto the stack for each call; instead, the function prologue should 3330increase the stack frame size by this amount. 3331 3332Setting both @code{PUSH_ARGS} and @code{ACCUMULATE_OUTGOING_ARGS} 3333is not proper. 3334 3335@findex REG_PARM_STACK_SPACE 3336@item REG_PARM_STACK_SPACE (@var{fndecl}) 3337Define this macro if functions should assume that stack space has been 3338allocated for arguments even when their values are passed in 3339registers. 3340 3341The value of this macro is the size, in bytes, of the area reserved for 3342arguments passed in registers for the function represented by @var{fndecl}, 3343which can be zero if GCC is calling a library function. 3344 3345This space can be allocated by the caller, or be a part of the 3346machine-dependent stack frame: @code{OUTGOING_REG_PARM_STACK_SPACE} says 3347which. 3348@c above is overfull. not sure what to do. --mew 5feb93 did 3349@c something, not sure if it looks good. --mew 10feb93 3350 3351@findex MAYBE_REG_PARM_STACK_SPACE 3352@findex FINAL_REG_PARM_STACK_SPACE 3353@item MAYBE_REG_PARM_STACK_SPACE 3354@itemx FINAL_REG_PARM_STACK_SPACE (@var{const_size}, @var{var_size}) 3355Define these macros in addition to the one above if functions might 3356allocate stack space for arguments even when their values are passed 3357in registers. These should be used when the stack space allocated 3358for arguments in registers is not a simple constant independent of the 3359function declaration. 3360 3361The value of the first macro is the size, in bytes, of the area that 3362we should initially assume would be reserved for arguments passed in registers. 3363 3364The value of the second macro is the actual size, in bytes, of the area 3365that will be reserved for arguments passed in registers. This takes two 3366arguments: an integer representing the number of bytes of fixed sized 3367arguments on the stack, and a tree representing the number of bytes of 3368variable sized arguments on the stack. 3369 3370When these macros are defined, @code{REG_PARM_STACK_SPACE} will only be 3371called for libcall functions, the current function, or for a function 3372being called when it is known that such stack space must be allocated. 3373In each case this value can be easily computed. 3374 3375When deciding whether a called function needs such stack space, and how 3376much space to reserve, GCC uses these two macros instead of 3377@code{REG_PARM_STACK_SPACE}. 3378 3379@findex OUTGOING_REG_PARM_STACK_SPACE 3380@item OUTGOING_REG_PARM_STACK_SPACE 3381Define this if it is the responsibility of the caller to allocate the area 3382reserved for arguments passed in registers. 3383 3384If @code{ACCUMULATE_OUTGOING_ARGS} is defined, this macro controls 3385whether the space for these arguments counts in the value of 3386@code{current_function_outgoing_args_size}. 3387 3388@findex STACK_PARMS_IN_REG_PARM_AREA 3389@item STACK_PARMS_IN_REG_PARM_AREA 3390Define this macro if @code{REG_PARM_STACK_SPACE} is defined, but the 3391stack parameters don't skip the area specified by it. 3392@c i changed this, makes more sens and it should have taken care of the 3393@c overfull.. not as specific, tho. --mew 5feb93 3394 3395Normally, when a parameter is not passed in registers, it is placed on the 3396stack beyond the @code{REG_PARM_STACK_SPACE} area. Defining this macro 3397suppresses this behavior and causes the parameter to be passed on the 3398stack in its natural location. 3399 3400@findex RETURN_POPS_ARGS 3401@item RETURN_POPS_ARGS (@var{fundecl}, @var{funtype}, @var{stack-size}) 3402A C expression that should indicate the number of bytes of its own 3403arguments that a function pops on returning, or 0 if the 3404function pops no arguments and the caller must therefore pop them all 3405after the function returns. 3406 3407@var{fundecl} is a C variable whose value is a tree node that describes 3408the function in question. Normally it is a node of type 3409@code{FUNCTION_DECL} that describes the declaration of the function. 3410From this you can obtain the @code{DECL_ATTRIBUTES} of the function. 3411 3412@var{funtype} is a C variable whose value is a tree node that 3413describes the function in question. Normally it is a node of type 3414@code{FUNCTION_TYPE} that describes the data type of the function. 3415From this it is possible to obtain the data types of the value and 3416arguments (if known). 3417 3418When a call to a library function is being considered, @var{fundecl} 3419will contain an identifier node for the library function. Thus, if 3420you need to distinguish among various library functions, you can do so 3421by their names. Note that ``library function'' in this context means 3422a function used to perform arithmetic, whose name is known specially 3423in the compiler and was not mentioned in the C code being compiled. 3424 3425@var{stack-size} is the number of bytes of arguments passed on the 3426stack. If a variable number of bytes is passed, it is zero, and 3427argument popping will always be the responsibility of the calling function. 3428 3429On the VAX, all functions always pop their arguments, so the definition 3430of this macro is @var{stack-size}. On the 68000, using the standard 3431calling convention, no functions pop their arguments, so the value of 3432the macro is always 0 in this case. But an alternative calling 3433convention is available in which functions that take a fixed number of 3434arguments pop them but other functions (such as @code{printf}) pop 3435nothing (the caller pops all). When this convention is in use, 3436@var{funtype} is examined to determine whether a function takes a fixed 3437number of arguments. 3438 3439@findex CALL_POPS_ARGS 3440@item CALL_POPS_ARGS (@var{cum}) 3441A C expression that should indicate the number of bytes a call sequence 3442pops off the stack. It is added to the value of @code{RETURN_POPS_ARGS} 3443when compiling a function call. 3444 3445@var{cum} is the variable in which all arguments to the called function 3446have been accumulated. 3447 3448On certain architectures, such as the SH5, a call trampoline is used 3449that pops certain registers off the stack, depending on the arguments 3450that have been passed to the function. Since this is a property of the 3451call site, not of the called function, @code{RETURN_POPS_ARGS} is not 3452appropriate. 3453 3454@end table 3455 3456@node Register Arguments 3457@subsection Passing Arguments in Registers 3458@cindex arguments in registers 3459@cindex registers arguments 3460 3461This section describes the macros which let you control how various 3462types of arguments are passed in registers or how they are arranged in 3463the stack. 3464 3465@table @code 3466@findex FUNCTION_ARG 3467@item FUNCTION_ARG (@var{cum}, @var{mode}, @var{type}, @var{named}) 3468A C expression that controls whether a function argument is passed 3469in a register, and which register. 3470 3471The arguments are @var{cum}, which summarizes all the previous 3472arguments; @var{mode}, the machine mode of the argument; @var{type}, 3473the data type of the argument as a tree node or 0 if that is not known 3474(which happens for C support library functions); and @var{named}, 3475which is 1 for an ordinary argument and 0 for nameless arguments that 3476correspond to @samp{@dots{}} in the called function's prototype. 3477@var{type} can be an incomplete type if a syntax error has previously 3478occurred. 3479 3480The value of the expression is usually either a @code{reg} RTX for the 3481hard register in which to pass the argument, or zero to pass the 3482argument on the stack. 3483 3484For machines like the VAX and 68000, where normally all arguments are 3485pushed, zero suffices as a definition. 3486 3487The value of the expression can also be a @code{parallel} RTX@. This is 3488used when an argument is passed in multiple locations. The mode of the 3489of the @code{parallel} should be the mode of the entire argument. The 3490@code{parallel} holds any number of @code{expr_list} pairs; each one 3491describes where part of the argument is passed. In each 3492@code{expr_list} the first operand must be a @code{reg} RTX for the hard 3493register in which to pass this part of the argument, and the mode of the 3494register RTX indicates how large this part of the argument is. The 3495second operand of the @code{expr_list} is a @code{const_int} which gives 3496the offset in bytes into the entire argument of where this part starts. 3497As a special exception the first @code{expr_list} in the @code{parallel} 3498RTX may have a first operand of zero. This indicates that the entire 3499argument is also stored on the stack. 3500 3501The last time this macro is called, it is called with @code{MODE == 3502VOIDmode}, and its result is passed to the @code{call} or @code{call_value} 3503pattern as operands 2 and 3 respectively. 3504 3505@cindex @file{stdarg.h} and register arguments 3506The usual way to make the ISO library @file{stdarg.h} work on a machine 3507where some arguments are usually passed in registers, is to cause 3508nameless arguments to be passed on the stack instead. This is done 3509by making @code{FUNCTION_ARG} return 0 whenever @var{named} is 0. 3510 3511@cindex @code{MUST_PASS_IN_STACK}, and @code{FUNCTION_ARG} 3512@cindex @code{REG_PARM_STACK_SPACE}, and @code{FUNCTION_ARG} 3513You may use the macro @code{MUST_PASS_IN_STACK (@var{mode}, @var{type})} 3514in the definition of this macro to determine if this argument is of a 3515type that must be passed in the stack. If @code{REG_PARM_STACK_SPACE} 3516is not defined and @code{FUNCTION_ARG} returns nonzero for such an 3517argument, the compiler will abort. If @code{REG_PARM_STACK_SPACE} is 3518defined, the argument will be computed in the stack and then loaded into 3519a register. 3520 3521@findex MUST_PASS_IN_STACK 3522@item MUST_PASS_IN_STACK (@var{mode}, @var{type}) 3523Define as a C expression that evaluates to nonzero if we do not know how 3524to pass TYPE solely in registers. The file @file{expr.h} defines a 3525definition that is usually appropriate, refer to @file{expr.h} for additional 3526documentation. 3527 3528@findex FUNCTION_INCOMING_ARG 3529@item FUNCTION_INCOMING_ARG (@var{cum}, @var{mode}, @var{type}, @var{named}) 3530Define this macro if the target machine has ``register windows'', so 3531that the register in which a function sees an arguments is not 3532necessarily the same as the one in which the caller passed the 3533argument. 3534 3535For such machines, @code{FUNCTION_ARG} computes the register in which 3536the caller passes the value, and @code{FUNCTION_INCOMING_ARG} should 3537be defined in a similar fashion to tell the function being called 3538where the arguments will arrive. 3539 3540If @code{FUNCTION_INCOMING_ARG} is not defined, @code{FUNCTION_ARG} 3541serves both purposes. 3542 3543@findex FUNCTION_ARG_PARTIAL_NREGS 3544@item FUNCTION_ARG_PARTIAL_NREGS (@var{cum}, @var{mode}, @var{type}, @var{named}) 3545A C expression for the number of words, at the beginning of an 3546argument, that must be put in registers. The value must be zero for 3547arguments that are passed entirely in registers or that are entirely 3548pushed on the stack. 3549 3550On some machines, certain arguments must be passed partially in 3551registers and partially in memory. On these machines, typically the 3552first @var{n} words of arguments are passed in registers, and the rest 3553on the stack. If a multi-word argument (a @code{double} or a 3554structure) crosses that boundary, its first few words must be passed 3555in registers and the rest must be pushed. This macro tells the 3556compiler when this occurs, and how many of the words should go in 3557registers. 3558 3559@code{FUNCTION_ARG} for these arguments should return the first 3560register to be used by the caller for this argument; likewise 3561@code{FUNCTION_INCOMING_ARG}, for the called function. 3562 3563@findex FUNCTION_ARG_PASS_BY_REFERENCE 3564@item FUNCTION_ARG_PASS_BY_REFERENCE (@var{cum}, @var{mode}, @var{type}, @var{named}) 3565A C expression that indicates when an argument must be passed by reference. 3566If nonzero for an argument, a copy of that argument is made in memory and a 3567pointer to the argument is passed instead of the argument itself. 3568The pointer is passed in whatever way is appropriate for passing a pointer 3569to that type. 3570 3571On machines where @code{REG_PARM_STACK_SPACE} is not defined, a suitable 3572definition of this macro might be 3573@smallexample 3574#define FUNCTION_ARG_PASS_BY_REFERENCE\ 3575(CUM, MODE, TYPE, NAMED) \ 3576 MUST_PASS_IN_STACK (MODE, TYPE) 3577@end smallexample 3578@c this is *still* too long. --mew 5feb93 3579 3580@findex FUNCTION_ARG_CALLEE_COPIES 3581@item FUNCTION_ARG_CALLEE_COPIES (@var{cum}, @var{mode}, @var{type}, @var{named}) 3582If defined, a C expression that indicates when it is the called function's 3583responsibility to make a copy of arguments passed by invisible reference. 3584Normally, the caller makes a copy and passes the address of the copy to the 3585routine being called. When @code{FUNCTION_ARG_CALLEE_COPIES} is defined and is 3586nonzero, the caller does not make a copy. Instead, it passes a pointer to the 3587``live'' value. The called function must not modify this value. If it can be 3588determined that the value won't be modified, it need not make a copy; 3589otherwise a copy must be made. 3590 3591@findex CUMULATIVE_ARGS 3592@item CUMULATIVE_ARGS 3593A C type for declaring a variable that is used as the first argument of 3594@code{FUNCTION_ARG} and other related values. For some target machines, 3595the type @code{int} suffices and can hold the number of bytes of 3596argument so far. 3597 3598There is no need to record in @code{CUMULATIVE_ARGS} anything about the 3599arguments that have been passed on the stack. The compiler has other 3600variables to keep track of that. For target machines on which all 3601arguments are passed on the stack, there is no need to store anything in 3602@code{CUMULATIVE_ARGS}; however, the data structure must exist and 3603should not be empty, so use @code{int}. 3604 3605@findex INIT_CUMULATIVE_ARGS 3606@item INIT_CUMULATIVE_ARGS (@var{cum}, @var{fntype}, @var{libname}, @var{indirect}) 3607A C statement (sans semicolon) for initializing the variable @var{cum} 3608for the state at the beginning of the argument list. The variable has 3609type @code{CUMULATIVE_ARGS}. The value of @var{fntype} is the tree node 3610for the data type of the function which will receive the args, or 0 3611if the args are to a compiler support library function. The value of 3612@var{indirect} is nonzero when processing an indirect call, for example 3613a call through a function pointer. The value of @var{indirect} is zero 3614for a call to an explicitly named function, a library function call, or when 3615@code{INIT_CUMULATIVE_ARGS} is used to find arguments for the function 3616being compiled. 3617 3618When processing a call to a compiler support library function, 3619@var{libname} identifies which one. It is a @code{symbol_ref} rtx which 3620contains the name of the function, as a string. @var{libname} is 0 when 3621an ordinary C function call is being processed. Thus, each time this 3622macro is called, either @var{libname} or @var{fntype} is nonzero, but 3623never both of them at once. 3624 3625@findex INIT_CUMULATIVE_LIBCALL_ARGS 3626@item INIT_CUMULATIVE_LIBCALL_ARGS (@var{cum}, @var{mode}, @var{libname}) 3627Like @code{INIT_CUMULATIVE_ARGS} but only used for outgoing libcalls, 3628it gets a @code{MODE} argument instead of @var{fntype}, that would be 3629@code{NULL}. @var{indirect} would always be zero, too. If this macro 3630is not defined, @code{INIT_CUMULATIVE_ARGS (cum, NULL_RTX, libname, 36310)} is used instead. 3632 3633@findex INIT_CUMULATIVE_INCOMING_ARGS 3634@item INIT_CUMULATIVE_INCOMING_ARGS (@var{cum}, @var{fntype}, @var{libname}) 3635Like @code{INIT_CUMULATIVE_ARGS} but overrides it for the purposes of 3636finding the arguments for the function being compiled. If this macro is 3637undefined, @code{INIT_CUMULATIVE_ARGS} is used instead. 3638 3639The value passed for @var{libname} is always 0, since library routines 3640with special calling conventions are never compiled with GCC@. The 3641argument @var{libname} exists for symmetry with 3642@code{INIT_CUMULATIVE_ARGS}. 3643@c could use "this macro" in place of @code{INIT_CUMULATIVE_ARGS}, maybe. 3644@c --mew 5feb93 i switched the order of the sentences. --mew 10feb93 3645 3646@findex FUNCTION_ARG_ADVANCE 3647@item FUNCTION_ARG_ADVANCE (@var{cum}, @var{mode}, @var{type}, @var{named}) 3648A C statement (sans semicolon) to update the summarizer variable 3649@var{cum} to advance past an argument in the argument list. The 3650values @var{mode}, @var{type} and @var{named} describe that argument. 3651Once this is done, the variable @var{cum} is suitable for analyzing 3652the @emph{following} argument with @code{FUNCTION_ARG}, etc. 3653 3654This macro need not do anything if the argument in question was passed 3655on the stack. The compiler knows how to track the amount of stack space 3656used for arguments without any special help. 3657 3658@findex FUNCTION_ARG_PADDING 3659@item FUNCTION_ARG_PADDING (@var{mode}, @var{type}) 3660If defined, a C expression which determines whether, and in which direction, 3661to pad out an argument with extra space. The value should be of type 3662@code{enum direction}: either @code{upward} to pad above the argument, 3663@code{downward} to pad below, or @code{none} to inhibit padding. 3664 3665The @emph{amount} of padding is always just enough to reach the next 3666multiple of @code{FUNCTION_ARG_BOUNDARY}; this macro does not control 3667it. 3668 3669This macro has a default definition which is right for most systems. 3670For little-endian machines, the default is to pad upward. For 3671big-endian machines, the default is to pad downward for an argument of 3672constant size shorter than an @code{int}, and upward otherwise. 3673 3674@findex PAD_VARARGS_DOWN 3675@item PAD_VARARGS_DOWN 3676If defined, a C expression which determines whether the default 3677implementation of va_arg will attempt to pad down before reading the 3678next argument, if that argument is smaller than its aligned space as 3679controlled by @code{PARM_BOUNDARY}. If this macro is not defined, all such 3680arguments are padded down if @code{BYTES_BIG_ENDIAN} is true. 3681 3682@findex FUNCTION_ARG_BOUNDARY 3683@item FUNCTION_ARG_BOUNDARY (@var{mode}, @var{type}) 3684If defined, a C expression that gives the alignment boundary, in bits, 3685of an argument with the specified mode and type. If it is not defined, 3686@code{PARM_BOUNDARY} is used for all arguments. 3687 3688@findex FUNCTION_ARG_REGNO_P 3689@item FUNCTION_ARG_REGNO_P (@var{regno}) 3690A C expression that is nonzero if @var{regno} is the number of a hard 3691register in which function arguments are sometimes passed. This does 3692@emph{not} include implicit arguments such as the static chain and 3693the structure-value address. On many machines, no registers can be 3694used for this purpose since all function arguments are pushed on the 3695stack. 3696 3697@findex LOAD_ARGS_REVERSED 3698@item LOAD_ARGS_REVERSED 3699If defined, the order in which arguments are loaded into their 3700respective argument registers is reversed so that the last 3701argument is loaded first. This macro only affects arguments 3702passed in registers. 3703 3704@end table 3705 3706@node Scalar Return 3707@subsection How Scalar Function Values Are Returned 3708@cindex return values in registers 3709@cindex values, returned by functions 3710@cindex scalars, returned as values 3711 3712This section discusses the macros that control returning scalars as 3713values---values that can fit in registers. 3714 3715@table @code 3716@findex FUNCTION_VALUE 3717@item FUNCTION_VALUE (@var{valtype}, @var{func}) 3718A C expression to create an RTX representing the place where a 3719function returns a value of data type @var{valtype}. @var{valtype} is 3720a tree node representing a data type. Write @code{TYPE_MODE 3721(@var{valtype})} to get the machine mode used to represent that type. 3722On many machines, only the mode is relevant. (Actually, on most 3723machines, scalar values are returned in the same place regardless of 3724mode). 3725 3726The value of the expression is usually a @code{reg} RTX for the hard 3727register where the return value is stored. The value can also be a 3728@code{parallel} RTX, if the return value is in multiple places. See 3729@code{FUNCTION_ARG} for an explanation of the @code{parallel} form. 3730 3731If @code{PROMOTE_FUNCTION_RETURN} is defined, you must apply the same 3732promotion rules specified in @code{PROMOTE_MODE} if @var{valtype} is a 3733scalar type. 3734 3735If the precise function being called is known, @var{func} is a tree 3736node (@code{FUNCTION_DECL}) for it; otherwise, @var{func} is a null 3737pointer. This makes it possible to use a different value-returning 3738convention for specific functions when all their calls are 3739known. 3740 3741@code{FUNCTION_VALUE} is not used for return vales with aggregate data 3742types, because these are returned in another way. See 3743@code{STRUCT_VALUE_REGNUM} and related macros, below. 3744 3745@findex FUNCTION_OUTGOING_VALUE 3746@item FUNCTION_OUTGOING_VALUE (@var{valtype}, @var{func}) 3747Define this macro if the target machine has ``register windows'' 3748so that the register in which a function returns its value is not 3749the same as the one in which the caller sees the value. 3750 3751For such machines, @code{FUNCTION_VALUE} computes the register in which 3752the caller will see the value. @code{FUNCTION_OUTGOING_VALUE} should be 3753defined in a similar fashion to tell the function where to put the 3754value. 3755 3756If @code{FUNCTION_OUTGOING_VALUE} is not defined, 3757@code{FUNCTION_VALUE} serves both purposes. 3758 3759@code{FUNCTION_OUTGOING_VALUE} is not used for return vales with 3760aggregate data types, because these are returned in another way. See 3761@code{STRUCT_VALUE_REGNUM} and related macros, below. 3762 3763@findex LIBCALL_VALUE 3764@item LIBCALL_VALUE (@var{mode}) 3765A C expression to create an RTX representing the place where a library 3766function returns a value of mode @var{mode}. If the precise function 3767being called is known, @var{func} is a tree node 3768(@code{FUNCTION_DECL}) for it; otherwise, @var{func} is a null 3769pointer. This makes it possible to use a different value-returning 3770convention for specific functions when all their calls are 3771known. 3772 3773Note that ``library function'' in this context means a compiler 3774support routine, used to perform arithmetic, whose name is known 3775specially by the compiler and was not mentioned in the C code being 3776compiled. 3777 3778The definition of @code{LIBRARY_VALUE} need not be concerned aggregate 3779data types, because none of the library functions returns such types. 3780 3781@findex FUNCTION_VALUE_REGNO_P 3782@item FUNCTION_VALUE_REGNO_P (@var{regno}) 3783A C expression that is nonzero if @var{regno} is the number of a hard 3784register in which the values of called function may come back. 3785 3786A register whose use for returning values is limited to serving as the 3787second of a pair (for a value of type @code{double}, say) need not be 3788recognized by this macro. So for most machines, this definition 3789suffices: 3790 3791@example 3792#define FUNCTION_VALUE_REGNO_P(N) ((N) == 0) 3793@end example 3794 3795If the machine has register windows, so that the caller and the called 3796function use different registers for the return value, this macro 3797should recognize only the caller's register numbers. 3798 3799@findex APPLY_RESULT_SIZE 3800@item APPLY_RESULT_SIZE 3801Define this macro if @samp{untyped_call} and @samp{untyped_return} 3802need more space than is implied by @code{FUNCTION_VALUE_REGNO_P} for 3803saving and restoring an arbitrary return value. 3804@end table 3805 3806@node Aggregate Return 3807@subsection How Large Values Are Returned 3808@cindex aggregates as return values 3809@cindex large return values 3810@cindex returning aggregate values 3811@cindex structure value address 3812 3813When a function value's mode is @code{BLKmode} (and in some other 3814cases), the value is not returned according to @code{FUNCTION_VALUE} 3815(@pxref{Scalar Return}). Instead, the caller passes the address of a 3816block of memory in which the value should be stored. This address 3817is called the @dfn{structure value address}. 3818 3819This section describes how to control returning structure values in 3820memory. 3821 3822@table @code 3823@findex RETURN_IN_MEMORY 3824@item RETURN_IN_MEMORY (@var{type}) 3825A C expression which can inhibit the returning of certain function 3826values in registers, based on the type of value. A nonzero value says 3827to return the function value in memory, just as large structures are 3828always returned. Here @var{type} will be a C expression of type 3829@code{tree}, representing the data type of the value. 3830 3831Note that values of mode @code{BLKmode} must be explicitly handled 3832by this macro. Also, the option @option{-fpcc-struct-return} 3833takes effect regardless of this macro. On most systems, it is 3834possible to leave the macro undefined; this causes a default 3835definition to be used, whose value is the constant 1 for @code{BLKmode} 3836values, and 0 otherwise. 3837 3838Do not use this macro to indicate that structures and unions should always 3839be returned in memory. You should instead use @code{DEFAULT_PCC_STRUCT_RETURN} 3840to indicate this. 3841 3842@findex DEFAULT_PCC_STRUCT_RETURN 3843@item DEFAULT_PCC_STRUCT_RETURN 3844Define this macro to be 1 if all structure and union return values must be 3845in memory. Since this results in slower code, this should be defined 3846only if needed for compatibility with other compilers or with an ABI@. 3847If you define this macro to be 0, then the conventions used for structure 3848and union return values are decided by the @code{RETURN_IN_MEMORY} macro. 3849 3850If not defined, this defaults to the value 1. 3851 3852@findex STRUCT_VALUE_REGNUM 3853@item STRUCT_VALUE_REGNUM 3854If the structure value address is passed in a register, then 3855@code{STRUCT_VALUE_REGNUM} should be the number of that register. 3856 3857@findex STRUCT_VALUE 3858@item STRUCT_VALUE 3859If the structure value address is not passed in a register, define 3860@code{STRUCT_VALUE} as an expression returning an RTX for the place 3861where the address is passed. If it returns 0, the address is passed as 3862an ``invisible'' first argument. 3863 3864@findex STRUCT_VALUE_INCOMING_REGNUM 3865@item STRUCT_VALUE_INCOMING_REGNUM 3866On some architectures the place where the structure value address 3867is found by the called function is not the same place that the 3868caller put it. This can be due to register windows, or it could 3869be because the function prologue moves it to a different place. 3870 3871If the incoming location of the structure value address is in a 3872register, define this macro as the register number. 3873 3874@findex STRUCT_VALUE_INCOMING 3875@item STRUCT_VALUE_INCOMING 3876If the incoming location is not a register, then you should define 3877@code{STRUCT_VALUE_INCOMING} as an expression for an RTX for where the 3878called function should find the value. If it should find the value on 3879the stack, define this to create a @code{mem} which refers to the frame 3880pointer. A definition of 0 means that the address is passed as an 3881``invisible'' first argument. 3882 3883@findex PCC_STATIC_STRUCT_RETURN 3884@item PCC_STATIC_STRUCT_RETURN 3885Define this macro if the usual system convention on the target machine 3886for returning structures and unions is for the called function to return 3887the address of a static variable containing the value. 3888 3889Do not define this if the usual system convention is for the caller to 3890pass an address to the subroutine. 3891 3892This macro has effect in @option{-fpcc-struct-return} mode, but it does 3893nothing when you use @option{-freg-struct-return} mode. 3894@end table 3895 3896@node Caller Saves 3897@subsection Caller-Saves Register Allocation 3898 3899If you enable it, GCC can save registers around function calls. This 3900makes it possible to use call-clobbered registers to hold variables that 3901must live across calls. 3902 3903@table @code 3904@findex DEFAULT_CALLER_SAVES 3905@item DEFAULT_CALLER_SAVES 3906Define this macro if function calls on the target machine do not preserve 3907any registers; in other words, if @code{CALL_USED_REGISTERS} has 1 3908for all registers. When defined, this macro enables @option{-fcaller-saves} 3909by default for all optimization levels. It has no effect for optimization 3910levels 2 and higher, where @option{-fcaller-saves} is the default. 3911 3912@findex CALLER_SAVE_PROFITABLE 3913@item CALLER_SAVE_PROFITABLE (@var{refs}, @var{calls}) 3914A C expression to determine whether it is worthwhile to consider placing 3915a pseudo-register in a call-clobbered hard register and saving and 3916restoring it around each function call. The expression should be 1 when 3917this is worth doing, and 0 otherwise. 3918 3919If you don't define this macro, a default is used which is good on most 3920machines: @code{4 * @var{calls} < @var{refs}}. 3921 3922@findex HARD_REGNO_CALLER_SAVE_MODE 3923@item HARD_REGNO_CALLER_SAVE_MODE (@var{regno}, @var{nregs}) 3924A C expression specifying which mode is required for saving @var{nregs} 3925of a pseudo-register in call-clobbered hard register @var{regno}. If 3926@var{regno} is unsuitable for caller save, @code{VOIDmode} should be 3927returned. For most machines this macro need not be defined since GCC 3928will select the smallest suitable mode. 3929@end table 3930 3931@node Function Entry 3932@subsection Function Entry and Exit 3933@cindex function entry and exit 3934@cindex prologue 3935@cindex epilogue 3936 3937This section describes the macros that output function entry 3938(@dfn{prologue}) and exit (@dfn{epilogue}) code. 3939 3940@deftypefn {Target Hook} void TARGET_ASM_FUNCTION_PROLOGUE (FILE *@var{file}, HOST_WIDE_INT @var{size}) 3941If defined, a function that outputs the assembler code for entry to a 3942function. The prologue is responsible for setting up the stack frame, 3943initializing the frame pointer register, saving registers that must be 3944saved, and allocating @var{size} additional bytes of storage for the 3945local variables. @var{size} is an integer. @var{file} is a stdio 3946stream to which the assembler code should be output. 3947 3948The label for the beginning of the function need not be output by this 3949macro. That has already been done when the macro is run. 3950 3951@findex regs_ever_live 3952To determine which registers to save, the macro can refer to the array 3953@code{regs_ever_live}: element @var{r} is nonzero if hard register 3954@var{r} is used anywhere within the function. This implies the function 3955prologue should save register @var{r}, provided it is not one of the 3956call-used registers. (@code{TARGET_ASM_FUNCTION_EPILOGUE} must likewise use 3957@code{regs_ever_live}.) 3958 3959On machines that have ``register windows'', the function entry code does 3960not save on the stack the registers that are in the windows, even if 3961they are supposed to be preserved by function calls; instead it takes 3962appropriate steps to ``push'' the register stack, if any non-call-used 3963registers are used in the function. 3964 3965@findex frame_pointer_needed 3966On machines where functions may or may not have frame-pointers, the 3967function entry code must vary accordingly; it must set up the frame 3968pointer if one is wanted, and not otherwise. To determine whether a 3969frame pointer is in wanted, the macro can refer to the variable 3970@code{frame_pointer_needed}. The variable's value will be 1 at run 3971time in a function that needs a frame pointer. @xref{Elimination}. 3972 3973The function entry code is responsible for allocating any stack space 3974required for the function. This stack space consists of the regions 3975listed below. In most cases, these regions are allocated in the 3976order listed, with the last listed region closest to the top of the 3977stack (the lowest address if @code{STACK_GROWS_DOWNWARD} is defined, and 3978the highest address if it is not defined). You can use a different order 3979for a machine if doing so is more convenient or required for 3980compatibility reasons. Except in cases where required by standard 3981or by a debugger, there is no reason why the stack layout used by GCC 3982need agree with that used by other compilers for a machine. 3983@end deftypefn 3984 3985@deftypefn {Target Hook} void TARGET_ASM_FUNCTION_END_PROLOGUE (FILE *@var{file}) 3986If defined, a function that outputs assembler code at the end of a 3987prologue. This should be used when the function prologue is being 3988emitted as RTL, and you have some extra assembler that needs to be 3989emitted. @xref{prologue instruction pattern}. 3990@end deftypefn 3991 3992@deftypefn {Target Hook} void TARGET_ASM_FUNCTION_BEGIN_EPILOGUE (FILE *@var{file}) 3993If defined, a function that outputs assembler code at the start of an 3994epilogue. This should be used when the function epilogue is being 3995emitted as RTL, and you have some extra assembler that needs to be 3996emitted. @xref{epilogue instruction pattern}. 3997@end deftypefn 3998 3999@deftypefn {Target Hook} void TARGET_ASM_FUNCTION_EPILOGUE (FILE *@var{file}, HOST_WIDE_INT @var{size}) 4000If defined, a function that outputs the assembler code for exit from a 4001function. The epilogue is responsible for restoring the saved 4002registers and stack pointer to their values when the function was 4003called, and returning control to the caller. This macro takes the 4004same arguments as the macro @code{TARGET_ASM_FUNCTION_PROLOGUE}, and the 4005registers to restore are determined from @code{regs_ever_live} and 4006@code{CALL_USED_REGISTERS} in the same way. 4007 4008On some machines, there is a single instruction that does all the work 4009of returning from the function. On these machines, give that 4010instruction the name @samp{return} and do not define the macro 4011@code{TARGET_ASM_FUNCTION_EPILOGUE} at all. 4012 4013Do not define a pattern named @samp{return} if you want the 4014@code{TARGET_ASM_FUNCTION_EPILOGUE} to be used. If you want the target 4015switches to control whether return instructions or epilogues are used, 4016define a @samp{return} pattern with a validity condition that tests the 4017target switches appropriately. If the @samp{return} pattern's validity 4018condition is false, epilogues will be used. 4019 4020On machines where functions may or may not have frame-pointers, the 4021function exit code must vary accordingly. Sometimes the code for these 4022two cases is completely different. To determine whether a frame pointer 4023is wanted, the macro can refer to the variable 4024@code{frame_pointer_needed}. The variable's value will be 1 when compiling 4025a function that needs a frame pointer. 4026 4027Normally, @code{TARGET_ASM_FUNCTION_PROLOGUE} and 4028@code{TARGET_ASM_FUNCTION_EPILOGUE} must treat leaf functions specially. 4029The C variable @code{current_function_is_leaf} is nonzero for such a 4030function. @xref{Leaf Functions}. 4031 4032On some machines, some functions pop their arguments on exit while 4033others leave that for the caller to do. For example, the 68020 when 4034given @option{-mrtd} pops arguments in functions that take a fixed 4035number of arguments. 4036 4037@findex current_function_pops_args 4038Your definition of the macro @code{RETURN_POPS_ARGS} decides which 4039functions pop their own arguments. @code{TARGET_ASM_FUNCTION_EPILOGUE} 4040needs to know what was decided. The variable that is called 4041@code{current_function_pops_args} is the number of bytes of its 4042arguments that a function should pop. @xref{Scalar Return}. 4043@c what is the "its arguments" in the above sentence referring to, pray 4044@c tell? --mew 5feb93 4045@end deftypefn 4046 4047@table @code 4048 4049@itemize @bullet 4050@item 4051@findex current_function_pretend_args_size 4052A region of @code{current_function_pretend_args_size} bytes of 4053uninitialized space just underneath the first argument arriving on the 4054stack. (This may not be at the very start of the allocated stack region 4055if the calling sequence has pushed anything else since pushing the stack 4056arguments. But usually, on such machines, nothing else has been pushed 4057yet, because the function prologue itself does all the pushing.) This 4058region is used on machines where an argument may be passed partly in 4059registers and partly in memory, and, in some cases to support the 4060features in @code{<stdarg.h>}. 4061 4062@item 4063An area of memory used to save certain registers used by the function. 4064The size of this area, which may also include space for such things as 4065the return address and pointers to previous stack frames, is 4066machine-specific and usually depends on which registers have been used 4067in the function. Machines with register windows often do not require 4068a save area. 4069 4070@item 4071A region of at least @var{size} bytes, possibly rounded up to an allocation 4072boundary, to contain the local variables of the function. On some machines, 4073this region and the save area may occur in the opposite order, with the 4074save area closer to the top of the stack. 4075 4076@item 4077@cindex @code{ACCUMULATE_OUTGOING_ARGS} and stack frames 4078Optionally, when @code{ACCUMULATE_OUTGOING_ARGS} is defined, a region of 4079@code{current_function_outgoing_args_size} bytes to be used for outgoing 4080argument lists of the function. @xref{Stack Arguments}. 4081@end itemize 4082 4083Normally, it is necessary for the macros 4084@code{TARGET_ASM_FUNCTION_PROLOGUE} and 4085@code{TARGET_ASM_FUNCTION_EPILOGUE} to treat leaf functions specially. 4086The C variable @code{current_function_is_leaf} is nonzero for such a 4087function. 4088 4089@findex EXIT_IGNORE_STACK 4090@item EXIT_IGNORE_STACK 4091Define this macro as a C expression that is nonzero if the return 4092instruction or the function epilogue ignores the value of the stack 4093pointer; in other words, if it is safe to delete an instruction to 4094adjust the stack pointer before a return from the function. 4095 4096Note that this macro's value is relevant only for functions for which 4097frame pointers are maintained. It is never safe to delete a final 4098stack adjustment in a function that has no frame pointer, and the 4099compiler knows this regardless of @code{EXIT_IGNORE_STACK}. 4100 4101@findex EPILOGUE_USES 4102@item EPILOGUE_USES (@var{regno}) 4103Define this macro as a C expression that is nonzero for registers that are 4104used by the epilogue or the @samp{return} pattern. The stack and frame 4105pointer registers are already be assumed to be used as needed. 4106 4107@findex EH_USES 4108@item EH_USES (@var{regno}) 4109Define this macro as a C expression that is nonzero for registers that are 4110used by the exception handling mechanism, and so should be considered live 4111on entry to an exception edge. 4112 4113@findex DELAY_SLOTS_FOR_EPILOGUE 4114@item DELAY_SLOTS_FOR_EPILOGUE 4115Define this macro if the function epilogue contains delay slots to which 4116instructions from the rest of the function can be ``moved''. The 4117definition should be a C expression whose value is an integer 4118representing the number of delay slots there. 4119 4120@findex ELIGIBLE_FOR_EPILOGUE_DELAY 4121@item ELIGIBLE_FOR_EPILOGUE_DELAY (@var{insn}, @var{n}) 4122A C expression that returns 1 if @var{insn} can be placed in delay 4123slot number @var{n} of the epilogue. 4124 4125The argument @var{n} is an integer which identifies the delay slot now 4126being considered (since different slots may have different rules of 4127eligibility). It is never negative and is always less than the number 4128of epilogue delay slots (what @code{DELAY_SLOTS_FOR_EPILOGUE} returns). 4129If you reject a particular insn for a given delay slot, in principle, it 4130may be reconsidered for a subsequent delay slot. Also, other insns may 4131(at least in principle) be considered for the so far unfilled delay 4132slot. 4133 4134@findex current_function_epilogue_delay_list 4135@findex final_scan_insn 4136The insns accepted to fill the epilogue delay slots are put in an RTL 4137list made with @code{insn_list} objects, stored in the variable 4138@code{current_function_epilogue_delay_list}. The insn for the first 4139delay slot comes first in the list. Your definition of the macro 4140@code{TARGET_ASM_FUNCTION_EPILOGUE} should fill the delay slots by 4141outputting the insns in this list, usually by calling 4142@code{final_scan_insn}. 4143 4144You need not define this macro if you did not define 4145@code{DELAY_SLOTS_FOR_EPILOGUE}. 4146 4147@end table 4148 4149@findex TARGET_ASM_OUTPUT_MI_THUNK 4150@deftypefn {Target Hook} void TARGET_ASM_OUTPUT_MI_THUNK (FILE *@var{file}, tree @var{thunk_fndecl}, HOST_WIDE_INT @var{delta}, tree @var{function}) 4151A function that outputs the assembler code for a thunk 4152function, used to implement C++ virtual function calls with multiple 4153inheritance. The thunk acts as a wrapper around a virtual function, 4154adjusting the implicit object parameter before handing control off to 4155the real function. 4156 4157First, emit code to add the integer @var{delta} to the location that 4158contains the incoming first argument. Assume that this argument 4159contains a pointer, and is the one used to pass the @code{this} pointer 4160in C++. This is the incoming argument @emph{before} the function prologue, 4161e.g.@: @samp{%o0} on a sparc. The addition must preserve the values of 4162all other incoming arguments. 4163 4164After the addition, emit code to jump to @var{function}, which is a 4165@code{FUNCTION_DECL}. This is a direct pure jump, not a call, and does 4166not touch the return address. Hence returning from @var{FUNCTION} will 4167return to whoever called the current @samp{thunk}. 4168 4169The effect must be as if @var{function} had been called directly with 4170the adjusted first argument. This macro is responsible for emitting all 4171of the code for a thunk function; @code{TARGET_ASM_FUNCTION_PROLOGUE} 4172and @code{TARGET_ASM_FUNCTION_EPILOGUE} are not invoked. 4173 4174The @var{thunk_fndecl} is redundant. (@var{delta} and @var{function} 4175have already been extracted from it.) It might possibly be useful on 4176some targets, but probably not. 4177 4178If you do not define this macro, the target-independent code in the C++ 4179front end will generate a less efficient heavyweight thunk that calls 4180@var{function} instead of jumping to it. The generic approach does 4181not support varargs. 4182@end deftypefn 4183 4184@findex TARGET_ASM_OUTPUT_MI_VCALL_THUNK 4185@deftypefn {Target Hook} void TARGET_ASM_OUTPUT_MI_VCALL_THUNK (FILE *@var{file}, tree @var{thunk_fndecl}, HOST_WIDE_INT @var{delta}, int @var{vcall_offset}, tree @var{function}) 4186A function like @code{TARGET_ASM_OUTPUT_MI_THUNK}, except that if 4187@var{vcall_offset} is nonzero, an additional adjustment should be made 4188after adding @code{delta}. In particular, if @var{p} is the 4189adjusted pointer, the following adjustment should be made: 4190 4191@example 4192p += (*((ptrdiff_t **)p))[vcall_offset/sizeof(ptrdiff_t)] 4193@end example 4194 4195@noindent 4196If this function is defined, it will always be used in place of 4197@code{TARGET_ASM_OUTPUT_MI_THUNK}. 4198 4199@end deftypefn 4200 4201@node Profiling 4202@subsection Generating Code for Profiling 4203@cindex profiling, code generation 4204 4205These macros will help you generate code for profiling. 4206 4207@table @code 4208@findex FUNCTION_PROFILER 4209@item FUNCTION_PROFILER (@var{file}, @var{labelno}) 4210A C statement or compound statement to output to @var{file} some 4211assembler code to call the profiling subroutine @code{mcount}. 4212 4213@findex mcount 4214The details of how @code{mcount} expects to be called are determined by 4215your operating system environment, not by GCC@. To figure them out, 4216compile a small program for profiling using the system's installed C 4217compiler and look at the assembler code that results. 4218 4219Older implementations of @code{mcount} expect the address of a counter 4220variable to be loaded into some register. The name of this variable is 4221@samp{LP} followed by the number @var{labelno}, so you would generate 4222the name using @samp{LP%d} in a @code{fprintf}. 4223 4224@findex PROFILE_HOOK 4225@item PROFILE_HOOK 4226A C statement or compound statement to output to @var{file} some assembly 4227code to call the profiling subroutine @code{mcount} even the target does 4228not support profiling. 4229 4230@findex NO_PROFILE_COUNTERS 4231@item NO_PROFILE_COUNTERS 4232Define this macro if the @code{mcount} subroutine on your system does 4233not need a counter variable allocated for each function. This is true 4234for almost all modern implementations. If you define this macro, you 4235must not use the @var{labelno} argument to @code{FUNCTION_PROFILER}. 4236 4237@findex PROFILE_BEFORE_PROLOGUE 4238@item PROFILE_BEFORE_PROLOGUE 4239Define this macro if the code for function profiling should come before 4240the function prologue. Normally, the profiling code comes after. 4241@end table 4242 4243@node Tail Calls 4244@subsection Permitting tail calls 4245@cindex tail calls 4246 4247@table @code 4248@findex FUNCTION_OK_FOR_SIBCALL 4249@item FUNCTION_OK_FOR_SIBCALL (@var{decl}) 4250A C expression that evaluates to true if it is ok to perform a sibling 4251call to @var{decl} from the current function. 4252 4253It is not uncommon for limitations of calling conventions to prevent 4254tail calls to functions outside the current unit of translation, or 4255during PIC compilation. Use this macro to enforce these restrictions, 4256as the @code{sibcall} md pattern can not fail, or fall over to a 4257``normal'' call. 4258@end table 4259 4260@node Varargs 4261@section Implementing the Varargs Macros 4262@cindex varargs implementation 4263 4264GCC comes with an implementation of @code{<varargs.h>} and 4265@code{<stdarg.h>} that work without change on machines that pass arguments 4266on the stack. Other machines require their own implementations of 4267varargs, and the two machine independent header files must have 4268conditionals to include it. 4269 4270ISO @code{<stdarg.h>} differs from traditional @code{<varargs.h>} mainly in 4271the calling convention for @code{va_start}. The traditional 4272implementation takes just one argument, which is the variable in which 4273to store the argument pointer. The ISO implementation of 4274@code{va_start} takes an additional second argument. The user is 4275supposed to write the last named argument of the function here. 4276 4277However, @code{va_start} should not use this argument. The way to find 4278the end of the named arguments is with the built-in functions described 4279below. 4280 4281@table @code 4282@findex __builtin_saveregs 4283@item __builtin_saveregs () 4284Use this built-in function to save the argument registers in memory so 4285that the varargs mechanism can access them. Both ISO and traditional 4286versions of @code{va_start} must use @code{__builtin_saveregs}, unless 4287you use @code{SETUP_INCOMING_VARARGS} (see below) instead. 4288 4289On some machines, @code{__builtin_saveregs} is open-coded under the 4290control of the macro @code{EXPAND_BUILTIN_SAVEREGS}. On other machines, 4291it calls a routine written in assembler language, found in 4292@file{libgcc2.c}. 4293 4294Code generated for the call to @code{__builtin_saveregs} appears at the 4295beginning of the function, as opposed to where the call to 4296@code{__builtin_saveregs} is written, regardless of what the code is. 4297This is because the registers must be saved before the function starts 4298to use them for its own purposes. 4299@c i rewrote the first sentence above to fix an overfull hbox. --mew 4300@c 10feb93 4301 4302@findex __builtin_args_info 4303@item __builtin_args_info (@var{category}) 4304Use this built-in function to find the first anonymous arguments in 4305registers. 4306 4307In general, a machine may have several categories of registers used for 4308arguments, each for a particular category of data types. (For example, 4309on some machines, floating-point registers are used for floating-point 4310arguments while other arguments are passed in the general registers.) 4311To make non-varargs functions use the proper calling convention, you 4312have defined the @code{CUMULATIVE_ARGS} data type to record how many 4313registers in each category have been used so far 4314 4315@code{__builtin_args_info} accesses the same data structure of type 4316@code{CUMULATIVE_ARGS} after the ordinary argument layout is finished 4317with it, with @var{category} specifying which word to access. Thus, the 4318value indicates the first unused register in a given category. 4319 4320Normally, you would use @code{__builtin_args_info} in the implementation 4321of @code{va_start}, accessing each category just once and storing the 4322value in the @code{va_list} object. This is because @code{va_list} will 4323have to update the values, and there is no way to alter the 4324values accessed by @code{__builtin_args_info}. 4325 4326@findex __builtin_next_arg 4327@item __builtin_next_arg (@var{lastarg}) 4328This is the equivalent of @code{__builtin_args_info}, for stack 4329arguments. It returns the address of the first anonymous stack 4330argument, as type @code{void *}. If @code{ARGS_GROW_DOWNWARD}, it 4331returns the address of the location above the first anonymous stack 4332argument. Use it in @code{va_start} to initialize the pointer for 4333fetching arguments from the stack. Also use it in @code{va_start} to 4334verify that the second parameter @var{lastarg} is the last named argument 4335of the current function. 4336 4337@findex __builtin_classify_type 4338@item __builtin_classify_type (@var{object}) 4339Since each machine has its own conventions for which data types are 4340passed in which kind of register, your implementation of @code{va_arg} 4341has to embody these conventions. The easiest way to categorize the 4342specified data type is to use @code{__builtin_classify_type} together 4343with @code{sizeof} and @code{__alignof__}. 4344 4345@code{__builtin_classify_type} ignores the value of @var{object}, 4346considering only its data type. It returns an integer describing what 4347kind of type that is---integer, floating, pointer, structure, and so on. 4348 4349The file @file{typeclass.h} defines an enumeration that you can use to 4350interpret the values of @code{__builtin_classify_type}. 4351@end table 4352 4353These machine description macros help implement varargs: 4354 4355@table @code 4356@findex EXPAND_BUILTIN_SAVEREGS 4357@item EXPAND_BUILTIN_SAVEREGS () 4358If defined, is a C expression that produces the machine-specific code 4359for a call to @code{__builtin_saveregs}. This code will be moved to the 4360very beginning of the function, before any parameter access are made. 4361The return value of this function should be an RTX that contains the 4362value to use as the return of @code{__builtin_saveregs}. 4363 4364@findex SETUP_INCOMING_VARARGS 4365@item SETUP_INCOMING_VARARGS (@var{args_so_far}, @var{mode}, @var{type}, @var{pretend_args_size}, @var{second_time}) 4366This macro offers an alternative to using @code{__builtin_saveregs} and 4367defining the macro @code{EXPAND_BUILTIN_SAVEREGS}. Use it to store the 4368anonymous register arguments into the stack so that all the arguments 4369appear to have been passed consecutively on the stack. Once this is 4370done, you can use the standard implementation of varargs that works for 4371machines that pass all their arguments on the stack. 4372 4373The argument @var{args_so_far} is the @code{CUMULATIVE_ARGS} data 4374structure, containing the values that are obtained after processing the 4375named arguments. The arguments @var{mode} and @var{type} describe the 4376last named argument---its machine mode and its data type as a tree node. 4377 4378The macro implementation should do two things: first, push onto the 4379stack all the argument registers @emph{not} used for the named 4380arguments, and second, store the size of the data thus pushed into the 4381@code{int}-valued variable whose name is supplied as the argument 4382@var{pretend_args_size}. The value that you store here will serve as 4383additional offset for setting up the stack frame. 4384 4385Because you must generate code to push the anonymous arguments at 4386compile time without knowing their data types, 4387@code{SETUP_INCOMING_VARARGS} is only useful on machines that have just 4388a single category of argument register and use it uniformly for all data 4389types. 4390 4391If the argument @var{second_time} is nonzero, it means that the 4392arguments of the function are being analyzed for the second time. This 4393happens for an inline function, which is not actually compiled until the 4394end of the source file. The macro @code{SETUP_INCOMING_VARARGS} should 4395not generate any instructions in this case. 4396 4397@findex STRICT_ARGUMENT_NAMING 4398@item STRICT_ARGUMENT_NAMING 4399Define this macro to be a nonzero value if the location where a function 4400argument is passed depends on whether or not it is a named argument. 4401 4402This macro controls how the @var{named} argument to @code{FUNCTION_ARG} 4403is set for varargs and stdarg functions. If this macro returns a 4404nonzero value, the @var{named} argument is always true for named 4405arguments, and false for unnamed arguments. If it returns a value of 4406zero, but @code{SETUP_INCOMING_VARARGS} is defined, then all arguments 4407are treated as named. Otherwise, all named arguments except the last 4408are treated as named. 4409 4410You need not define this macro if it always returns zero. 4411 4412@findex PRETEND_OUTGOING_VARARGS_NAMED 4413@item PRETEND_OUTGOING_VARARGS_NAMED 4414If you need to conditionally change ABIs so that one works with 4415@code{SETUP_INCOMING_VARARGS}, but the other works like neither 4416@code{SETUP_INCOMING_VARARGS} nor @code{STRICT_ARGUMENT_NAMING} was 4417defined, then define this macro to return nonzero if 4418@code{SETUP_INCOMING_VARARGS} is used, zero otherwise. 4419Otherwise, you should not define this macro. 4420@end table 4421 4422@node Trampolines 4423@section Trampolines for Nested Functions 4424@cindex trampolines for nested functions 4425@cindex nested functions, trampolines for 4426 4427A @dfn{trampoline} is a small piece of code that is created at run time 4428when the address of a nested function is taken. It normally resides on 4429the stack, in the stack frame of the containing function. These macros 4430tell GCC how to generate code to allocate and initialize a 4431trampoline. 4432 4433The instructions in the trampoline must do two things: load a constant 4434address into the static chain register, and jump to the real address of 4435the nested function. On CISC machines such as the m68k, this requires 4436two instructions, a move immediate and a jump. Then the two addresses 4437exist in the trampoline as word-long immediate operands. On RISC 4438machines, it is often necessary to load each address into a register in 4439two parts. Then pieces of each address form separate immediate 4440operands. 4441 4442The code generated to initialize the trampoline must store the variable 4443parts---the static chain value and the function address---into the 4444immediate operands of the instructions. On a CISC machine, this is 4445simply a matter of copying each address to a memory reference at the 4446proper offset from the start of the trampoline. On a RISC machine, it 4447may be necessary to take out pieces of the address and store them 4448separately. 4449 4450@table @code 4451@findex TRAMPOLINE_TEMPLATE 4452@item TRAMPOLINE_TEMPLATE (@var{file}) 4453A C statement to output, on the stream @var{file}, assembler code for a 4454block of data that contains the constant parts of a trampoline. This 4455code should not include a label---the label is taken care of 4456automatically. 4457 4458If you do not define this macro, it means no template is needed 4459for the target. Do not define this macro on systems where the block move 4460code to copy the trampoline into place would be larger than the code 4461to generate it on the spot. 4462 4463@findex TRAMPOLINE_SECTION 4464@item TRAMPOLINE_SECTION 4465The name of a subroutine to switch to the section in which the 4466trampoline template is to be placed (@pxref{Sections}). The default is 4467a value of @samp{readonly_data_section}, which places the trampoline in 4468the section containing read-only data. 4469 4470@findex TRAMPOLINE_SIZE 4471@item TRAMPOLINE_SIZE 4472A C expression for the size in bytes of the trampoline, as an integer. 4473 4474@findex TRAMPOLINE_ALIGNMENT 4475@item TRAMPOLINE_ALIGNMENT 4476Alignment required for trampolines, in bits. 4477 4478If you don't define this macro, the value of @code{BIGGEST_ALIGNMENT} 4479is used for aligning trampolines. 4480 4481@findex INITIALIZE_TRAMPOLINE 4482@item INITIALIZE_TRAMPOLINE (@var{addr}, @var{fnaddr}, @var{static_chain}) 4483A C statement to initialize the variable parts of a trampoline. 4484@var{addr} is an RTX for the address of the trampoline; @var{fnaddr} is 4485an RTX for the address of the nested function; @var{static_chain} is an 4486RTX for the static chain value that should be passed to the function 4487when it is called. 4488 4489@findex TRAMPOLINE_ADJUST_ADDRESS 4490@item TRAMPOLINE_ADJUST_ADDRESS (@var{addr}) 4491A C statement that should perform any machine-specific adjustment in 4492the address of the trampoline. Its argument contains the address that 4493was passed to @code{INITIALIZE_TRAMPOLINE}. In case the address to be 4494used for a function call should be different from the address in which 4495the template was stored, the different address should be assigned to 4496@var{addr}. If this macro is not defined, @var{addr} will be used for 4497function calls. 4498 4499@findex ALLOCATE_TRAMPOLINE 4500@item ALLOCATE_TRAMPOLINE (@var{fp}) 4501A C expression to allocate run-time space for a trampoline. The 4502expression value should be an RTX representing a memory reference to the 4503space for the trampoline. 4504 4505@cindex @code{TARGET_ASM_FUNCTION_EPILOGUE} and trampolines 4506@cindex @code{TARGET_ASM_FUNCTION_PROLOGUE} and trampolines 4507If this macro is not defined, by default the trampoline is allocated as 4508a stack slot. This default is right for most machines. The exceptions 4509are machines where it is impossible to execute instructions in the stack 4510area. On such machines, you may have to implement a separate stack, 4511using this macro in conjunction with @code{TARGET_ASM_FUNCTION_PROLOGUE} 4512and @code{TARGET_ASM_FUNCTION_EPILOGUE}. 4513 4514@var{fp} points to a data structure, a @code{struct function}, which 4515describes the compilation status of the immediate containing function of 4516the function which the trampoline is for. Normally (when 4517@code{ALLOCATE_TRAMPOLINE} is not defined), the stack slot for the 4518trampoline is in the stack frame of this containing function. Other 4519allocation strategies probably must do something analogous with this 4520information. 4521@end table 4522 4523Implementing trampolines is difficult on many machines because they have 4524separate instruction and data caches. Writing into a stack location 4525fails to clear the memory in the instruction cache, so when the program 4526jumps to that location, it executes the old contents. 4527 4528Here are two possible solutions. One is to clear the relevant parts of 4529the instruction cache whenever a trampoline is set up. The other is to 4530make all trampolines identical, by having them jump to a standard 4531subroutine. The former technique makes trampoline execution faster; the 4532latter makes initialization faster. 4533 4534To clear the instruction cache when a trampoline is initialized, define 4535the following macros which describe the shape of the cache. 4536 4537@table @code 4538@findex INSN_CACHE_SIZE 4539@item INSN_CACHE_SIZE 4540The total size in bytes of the cache. 4541 4542@findex INSN_CACHE_LINE_WIDTH 4543@item INSN_CACHE_LINE_WIDTH 4544The length in bytes of each cache line. The cache is divided into cache 4545lines which are disjoint slots, each holding a contiguous chunk of data 4546fetched from memory. Each time data is brought into the cache, an 4547entire line is read at once. The data loaded into a cache line is 4548always aligned on a boundary equal to the line size. 4549 4550@findex INSN_CACHE_DEPTH 4551@item INSN_CACHE_DEPTH 4552The number of alternative cache lines that can hold any particular memory 4553location. 4554@end table 4555 4556Alternatively, if the machine has system calls or instructions to clear 4557the instruction cache directly, you can define the following macro. 4558 4559@table @code 4560@findex CLEAR_INSN_CACHE 4561@item CLEAR_INSN_CACHE (@var{beg}, @var{end}) 4562If defined, expands to a C expression clearing the @emph{instruction 4563cache} in the specified interval. If it is not defined, and the macro 4564@code{INSN_CACHE_SIZE} is defined, some generic code is generated to clear the 4565cache. The definition of this macro would typically be a series of 4566@code{asm} statements. Both @var{beg} and @var{end} are both pointer 4567expressions. 4568@end table 4569 4570To use a standard subroutine, define the following macro. In addition, 4571you must make sure that the instructions in a trampoline fill an entire 4572cache line with identical instructions, or else ensure that the 4573beginning of the trampoline code is always aligned at the same point in 4574its cache line. Look in @file{m68k.h} as a guide. 4575 4576@table @code 4577@findex TRANSFER_FROM_TRAMPOLINE 4578@item TRANSFER_FROM_TRAMPOLINE 4579Define this macro if trampolines need a special subroutine to do their 4580work. The macro should expand to a series of @code{asm} statements 4581which will be compiled with GCC@. They go in a library function named 4582@code{__transfer_from_trampoline}. 4583 4584If you need to avoid executing the ordinary prologue code of a compiled 4585C function when you jump to the subroutine, you can do so by placing a 4586special label of your own in the assembler code. Use one @code{asm} 4587statement to generate an assembler label, and another to make the label 4588global. Then trampolines can use that label to jump directly to your 4589special assembler code. 4590@end table 4591 4592@node Library Calls 4593@section Implicit Calls to Library Routines 4594@cindex library subroutine names 4595@cindex @file{libgcc.a} 4596 4597@c prevent bad page break with this line 4598Here is an explanation of implicit calls to library routines. 4599 4600@table @code 4601@findex MULSI3_LIBCALL 4602@item MULSI3_LIBCALL 4603A C string constant giving the name of the function to call for 4604multiplication of one signed full-word by another. If you do not 4605define this macro, the default name is used, which is @code{__mulsi3}, 4606a function defined in @file{libgcc.a}. 4607 4608@findex DIVSI3_LIBCALL 4609@item DIVSI3_LIBCALL 4610A C string constant giving the name of the function to call for 4611division of one signed full-word by another. If you do not define 4612this macro, the default name is used, which is @code{__divsi3}, a 4613function defined in @file{libgcc.a}. 4614 4615@findex UDIVSI3_LIBCALL 4616@item UDIVSI3_LIBCALL 4617A C string constant giving the name of the function to call for 4618division of one unsigned full-word by another. If you do not define 4619this macro, the default name is used, which is @code{__udivsi3}, a 4620function defined in @file{libgcc.a}. 4621 4622@findex MODSI3_LIBCALL 4623@item MODSI3_LIBCALL 4624A C string constant giving the name of the function to call for the 4625remainder in division of one signed full-word by another. If you do 4626not define this macro, the default name is used, which is 4627@code{__modsi3}, a function defined in @file{libgcc.a}. 4628 4629@findex UMODSI3_LIBCALL 4630@item UMODSI3_LIBCALL 4631A C string constant giving the name of the function to call for the 4632remainder in division of one unsigned full-word by another. If you do 4633not define this macro, the default name is used, which is 4634@code{__umodsi3}, a function defined in @file{libgcc.a}. 4635 4636@findex MULDI3_LIBCALL 4637@item MULDI3_LIBCALL 4638A C string constant giving the name of the function to call for 4639multiplication of one signed double-word by another. If you do not 4640define this macro, the default name is used, which is @code{__muldi3}, 4641a function defined in @file{libgcc.a}. 4642 4643@findex DIVDI3_LIBCALL 4644@item DIVDI3_LIBCALL 4645A C string constant giving the name of the function to call for 4646division of one signed double-word by another. If you do not define 4647this macro, the default name is used, which is @code{__divdi3}, a 4648function defined in @file{libgcc.a}. 4649 4650@findex UDIVDI3_LIBCALL 4651@item UDIVDI3_LIBCALL 4652A C string constant giving the name of the function to call for 4653division of one unsigned full-word by another. If you do not define 4654this macro, the default name is used, which is @code{__udivdi3}, a 4655function defined in @file{libgcc.a}. 4656 4657@findex MODDI3_LIBCALL 4658@item MODDI3_LIBCALL 4659A C string constant giving the name of the function to call for the 4660remainder in division of one signed double-word by another. If you do 4661not define this macro, the default name is used, which is 4662@code{__moddi3}, a function defined in @file{libgcc.a}. 4663 4664@findex UMODDI3_LIBCALL 4665@item UMODDI3_LIBCALL 4666A C string constant giving the name of the function to call for the 4667remainder in division of one unsigned full-word by another. If you do 4668not define this macro, the default name is used, which is 4669@code{__umoddi3}, a function defined in @file{libgcc.a}. 4670 4671@findex DECLARE_LIBRARY_RENAMES 4672@item DECLARE_LIBRARY_RENAMES 4673This macro, if defined, should expand to a piece of C code that will get 4674expanded when compiling functions for libgcc.a. It can be used to 4675provide alternate names for gcc's internal library functions if there 4676are ABI-mandated names that the compiler should provide. 4677 4678@findex INIT_TARGET_OPTABS 4679@item INIT_TARGET_OPTABS 4680Define this macro as a C statement that declares additional library 4681routines renames existing ones. @code{init_optabs} calls this macro after 4682initializing all the normal library routines. 4683 4684@findex FLOAT_LIB_COMPARE_RETURNS_BOOL (@var{mode}, @var{comparison}) 4685@item FLOAT_LIB_COMPARE_RETURNS_BOOL 4686Define this macro as a C statement that returns nonzero if a call to 4687the floating point comparison library function will return a boolean 4688value that indicates the result of the comparison. It should return 4689zero if one of gcc's own libgcc functions is called. 4690 4691Most ports don't need to define this macro. 4692 4693@findex TARGET_EDOM 4694@cindex @code{EDOM}, implicit usage 4695@item TARGET_EDOM 4696The value of @code{EDOM} on the target machine, as a C integer constant 4697expression. If you don't define this macro, GCC does not attempt to 4698deposit the value of @code{EDOM} into @code{errno} directly. Look in 4699@file{/usr/include/errno.h} to find the value of @code{EDOM} on your 4700system. 4701 4702If you do not define @code{TARGET_EDOM}, then compiled code reports 4703domain errors by calling the library function and letting it report the 4704error. If mathematical functions on your system use @code{matherr} when 4705there is an error, then you should leave @code{TARGET_EDOM} undefined so 4706that @code{matherr} is used normally. 4707 4708@findex GEN_ERRNO_RTX 4709@cindex @code{errno}, implicit usage 4710@item GEN_ERRNO_RTX 4711Define this macro as a C expression to create an rtl expression that 4712refers to the global ``variable'' @code{errno}. (On certain systems, 4713@code{errno} may not actually be a variable.) If you don't define this 4714macro, a reasonable default is used. 4715 4716@findex TARGET_MEM_FUNCTIONS 4717@cindex @code{bcopy}, implicit usage 4718@cindex @code{memcpy}, implicit usage 4719@cindex @code{memmove}, implicit usage 4720@cindex @code{bzero}, implicit usage 4721@cindex @code{memset}, implicit usage 4722@item TARGET_MEM_FUNCTIONS 4723Define this macro if GCC should generate calls to the ISO C 4724(and System V) library functions @code{memcpy}, @code{memmove} and 4725@code{memset} rather than the BSD functions @code{bcopy} and @code{bzero}. 4726 4727@findex LIBGCC_NEEDS_DOUBLE 4728@item LIBGCC_NEEDS_DOUBLE 4729Define this macro if @code{float} arguments cannot be passed to library 4730routines (so they must be converted to @code{double}). This macro 4731affects both how library calls are generated and how the library 4732routines in @file{libgcc.a} accept their arguments. It is useful on 4733machines where floating and fixed point arguments are passed 4734differently, such as the i860. 4735 4736@findex NEXT_OBJC_RUNTIME 4737@item NEXT_OBJC_RUNTIME 4738Define this macro to generate code for Objective-C message sending using 4739the calling convention of the NeXT system. This calling convention 4740involves passing the object, the selector and the method arguments all 4741at once to the method-lookup library function. 4742 4743The default calling convention passes just the object and the selector 4744to the lookup function, which returns a pointer to the method. 4745@end table 4746 4747@node Addressing Modes 4748@section Addressing Modes 4749@cindex addressing modes 4750 4751@c prevent bad page break with this line 4752This is about addressing modes. 4753 4754@table @code 4755@findex HAVE_PRE_INCREMENT 4756@findex HAVE_PRE_DECREMENT 4757@findex HAVE_POST_INCREMENT 4758@findex HAVE_POST_DECREMENT 4759@item HAVE_PRE_INCREMENT 4760@itemx HAVE_PRE_DECREMENT 4761@itemx HAVE_POST_INCREMENT 4762@itemx HAVE_POST_DECREMENT 4763A C expression that is nonzero if the machine supports pre-increment, 4764pre-decrement, post-increment, or post-decrement addressing respectively. 4765 4766@findex HAVE_POST_MODIFY_DISP 4767@findex HAVE_PRE_MODIFY_DISP 4768@item HAVE_PRE_MODIFY_DISP 4769@itemx HAVE_POST_MODIFY_DISP 4770A C expression that is nonzero if the machine supports pre- or 4771post-address side-effect generation involving constants other than 4772the size of the memory operand. 4773 4774@findex HAVE_POST_MODIFY_REG 4775@findex HAVE_PRE_MODIFY_REG 4776@item HAVE_PRE_MODIFY_REG 4777@itemx HAVE_POST_MODIFY_REG 4778A C expression that is nonzero if the machine supports pre- or 4779post-address side-effect generation involving a register displacement. 4780 4781@findex CONSTANT_ADDRESS_P 4782@item CONSTANT_ADDRESS_P (@var{x}) 4783A C expression that is 1 if the RTX @var{x} is a constant which 4784is a valid address. On most machines, this can be defined as 4785@code{CONSTANT_P (@var{x})}, but a few machines are more restrictive 4786in which constant addresses are supported. 4787 4788@findex CONSTANT_P 4789@code{CONSTANT_P} accepts integer-values expressions whose values are 4790not explicitly known, such as @code{symbol_ref}, @code{label_ref}, and 4791@code{high} expressions and @code{const} arithmetic expressions, in 4792addition to @code{const_int} and @code{const_double} expressions. 4793 4794@findex MAX_REGS_PER_ADDRESS 4795@item MAX_REGS_PER_ADDRESS 4796A number, the maximum number of registers that can appear in a valid 4797memory address. Note that it is up to you to specify a value equal to 4798the maximum number that @code{GO_IF_LEGITIMATE_ADDRESS} would ever 4799accept. 4800 4801@findex GO_IF_LEGITIMATE_ADDRESS 4802@item GO_IF_LEGITIMATE_ADDRESS (@var{mode}, @var{x}, @var{label}) 4803A C compound statement with a conditional @code{goto @var{label};} 4804executed if @var{x} (an RTX) is a legitimate memory address on the 4805target machine for a memory operand of mode @var{mode}. 4806 4807It usually pays to define several simpler macros to serve as 4808subroutines for this one. Otherwise it may be too complicated to 4809understand. 4810 4811This macro must exist in two variants: a strict variant and a 4812non-strict one. The strict variant is used in the reload pass. It 4813must be defined so that any pseudo-register that has not been 4814allocated a hard register is considered a memory reference. In 4815contexts where some kind of register is required, a pseudo-register 4816with no hard register must be rejected. 4817 4818The non-strict variant is used in other passes. It must be defined to 4819accept all pseudo-registers in every context where some kind of 4820register is required. 4821 4822@findex REG_OK_STRICT 4823Compiler source files that want to use the strict variant of this 4824macro define the macro @code{REG_OK_STRICT}. You should use an 4825@code{#ifdef REG_OK_STRICT} conditional to define the strict variant 4826in that case and the non-strict variant otherwise. 4827 4828Subroutines to check for acceptable registers for various purposes (one 4829for base registers, one for index registers, and so on) are typically 4830among the subroutines used to define @code{GO_IF_LEGITIMATE_ADDRESS}. 4831Then only these subroutine macros need have two variants; the higher 4832levels of macros may be the same whether strict or not. 4833 4834Normally, constant addresses which are the sum of a @code{symbol_ref} 4835and an integer are stored inside a @code{const} RTX to mark them as 4836constant. Therefore, there is no need to recognize such sums 4837specifically as legitimate addresses. Normally you would simply 4838recognize any @code{const} as legitimate. 4839 4840Usually @code{PRINT_OPERAND_ADDRESS} is not prepared to handle constant 4841sums that are not marked with @code{const}. It assumes that a naked 4842@code{plus} indicates indexing. If so, then you @emph{must} reject such 4843naked constant sums as illegitimate addresses, so that none of them will 4844be given to @code{PRINT_OPERAND_ADDRESS}. 4845 4846@cindex @code{TARGET_ENCODE_SECTION_INFO} and address validation 4847On some machines, whether a symbolic address is legitimate depends on 4848the section that the address refers to. On these machines, define the 4849target hook @code{TARGET_ENCODE_SECTION_INFO} to store the information 4850into the @code{symbol_ref}, and then check for it here. When you see a 4851@code{const}, you will have to look inside it to find the 4852@code{symbol_ref} in order to determine the section. @xref{Assembler 4853Format}. 4854 4855@findex saveable_obstack 4856The best way to modify the name string is by adding text to the 4857beginning, with suitable punctuation to prevent any ambiguity. Allocate 4858the new name in @code{saveable_obstack}. You will have to modify 4859@code{ASM_OUTPUT_LABELREF} to remove and decode the added text and 4860output the name accordingly, and define @code{TARGET_STRIP_NAME_ENCODING} 4861to access the original name string. 4862 4863You can check the information stored here into the @code{symbol_ref} in 4864the definitions of the macros @code{GO_IF_LEGITIMATE_ADDRESS} and 4865@code{PRINT_OPERAND_ADDRESS}. 4866 4867@findex REG_OK_FOR_BASE_P 4868@item REG_OK_FOR_BASE_P (@var{x}) 4869A C expression that is nonzero if @var{x} (assumed to be a @code{reg} 4870RTX) is valid for use as a base register. For hard registers, it 4871should always accept those which the hardware permits and reject the 4872others. Whether the macro accepts or rejects pseudo registers must be 4873controlled by @code{REG_OK_STRICT} as described above. This usually 4874requires two variant definitions, of which @code{REG_OK_STRICT} 4875controls the one actually used. 4876 4877@findex REG_MODE_OK_FOR_BASE_P 4878@item REG_MODE_OK_FOR_BASE_P (@var{x}, @var{mode}) 4879A C expression that is just like @code{REG_OK_FOR_BASE_P}, except that 4880that expression may examine the mode of the memory reference in 4881@var{mode}. You should define this macro if the mode of the memory 4882reference affects whether a register may be used as a base register. If 4883you define this macro, the compiler will use it instead of 4884@code{REG_OK_FOR_BASE_P}. 4885 4886@findex REG_OK_FOR_INDEX_P 4887@item REG_OK_FOR_INDEX_P (@var{x}) 4888A C expression that is nonzero if @var{x} (assumed to be a @code{reg} 4889RTX) is valid for use as an index register. 4890 4891The difference between an index register and a base register is that 4892the index register may be scaled. If an address involves the sum of 4893two registers, neither one of them scaled, then either one may be 4894labeled the ``base'' and the other the ``index''; but whichever 4895labeling is used must fit the machine's constraints of which registers 4896may serve in each capacity. The compiler will try both labelings, 4897looking for one that is valid, and will reload one or both registers 4898only if neither labeling works. 4899 4900@findex FIND_BASE_TERM 4901@item FIND_BASE_TERM (@var{x}) 4902A C expression to determine the base term of address @var{x}. 4903This macro is used in only one place: `find_base_term' in alias.c. 4904 4905It is always safe for this macro to not be defined. It exists so 4906that alias analysis can understand machine-dependent addresses. 4907 4908The typical use of this macro is to handle addresses containing 4909a label_ref or symbol_ref within an UNSPEC@. 4910 4911@findex LEGITIMIZE_ADDRESS 4912@item LEGITIMIZE_ADDRESS (@var{x}, @var{oldx}, @var{mode}, @var{win}) 4913A C compound statement that attempts to replace @var{x} with a valid 4914memory address for an operand of mode @var{mode}. @var{win} will be a 4915C statement label elsewhere in the code; the macro definition may use 4916 4917@example 4918GO_IF_LEGITIMATE_ADDRESS (@var{mode}, @var{x}, @var{win}); 4919@end example 4920 4921@noindent 4922to avoid further processing if the address has become legitimate. 4923 4924@findex break_out_memory_refs 4925@var{x} will always be the result of a call to @code{break_out_memory_refs}, 4926and @var{oldx} will be the operand that was given to that function to produce 4927@var{x}. 4928 4929The code generated by this macro should not alter the substructure of 4930@var{x}. If it transforms @var{x} into a more legitimate form, it 4931should assign @var{x} (which will always be a C variable) a new value. 4932 4933It is not necessary for this macro to come up with a legitimate 4934address. The compiler has standard ways of doing so in all cases. In 4935fact, it is safe for this macro to do nothing. But often a 4936machine-dependent strategy can generate better code. 4937 4938@findex LEGITIMIZE_RELOAD_ADDRESS 4939@item LEGITIMIZE_RELOAD_ADDRESS (@var{x}, @var{mode}, @var{opnum}, @var{type}, @var{ind_levels}, @var{win}) 4940A C compound statement that attempts to replace @var{x}, which is an address 4941that needs reloading, with a valid memory address for an operand of mode 4942@var{mode}. @var{win} will be a C statement label elsewhere in the code. 4943It is not necessary to define this macro, but it might be useful for 4944performance reasons. 4945 4946For example, on the i386, it is sometimes possible to use a single 4947reload register instead of two by reloading a sum of two pseudo 4948registers into a register. On the other hand, for number of RISC 4949processors offsets are limited so that often an intermediate address 4950needs to be generated in order to address a stack slot. By defining 4951@code{LEGITIMIZE_RELOAD_ADDRESS} appropriately, the intermediate addresses 4952generated for adjacent some stack slots can be made identical, and thus 4953be shared. 4954 4955@emph{Note}: This macro should be used with caution. It is necessary 4956to know something of how reload works in order to effectively use this, 4957and it is quite easy to produce macros that build in too much knowledge 4958of reload internals. 4959 4960@emph{Note}: This macro must be able to reload an address created by a 4961previous invocation of this macro. If it fails to handle such addresses 4962then the compiler may generate incorrect code or abort. 4963 4964@findex push_reload 4965The macro definition should use @code{push_reload} to indicate parts that 4966need reloading; @var{opnum}, @var{type} and @var{ind_levels} are usually 4967suitable to be passed unaltered to @code{push_reload}. 4968 4969The code generated by this macro must not alter the substructure of 4970@var{x}. If it transforms @var{x} into a more legitimate form, it 4971should assign @var{x} (which will always be a C variable) a new value. 4972This also applies to parts that you change indirectly by calling 4973@code{push_reload}. 4974 4975@findex strict_memory_address_p 4976The macro definition may use @code{strict_memory_address_p} to test if 4977the address has become legitimate. 4978 4979@findex copy_rtx 4980If you want to change only a part of @var{x}, one standard way of doing 4981this is to use @code{copy_rtx}. Note, however, that is unshares only a 4982single level of rtl. Thus, if the part to be changed is not at the 4983top level, you'll need to replace first the top level. 4984It is not necessary for this macro to come up with a legitimate 4985address; but often a machine-dependent strategy can generate better code. 4986 4987@findex GO_IF_MODE_DEPENDENT_ADDRESS 4988@item GO_IF_MODE_DEPENDENT_ADDRESS (@var{addr}, @var{label}) 4989A C statement or compound statement with a conditional @code{goto 4990@var{label};} executed if memory address @var{x} (an RTX) can have 4991different meanings depending on the machine mode of the memory 4992reference it is used for or if the address is valid for some modes 4993but not others. 4994 4995Autoincrement and autodecrement addresses typically have mode-dependent 4996effects because the amount of the increment or decrement is the size 4997of the operand being addressed. Some machines have other mode-dependent 4998addresses. Many RISC machines have no mode-dependent addresses. 4999 5000You may assume that @var{addr} is a valid address for the machine. 5001 5002@findex LEGITIMATE_CONSTANT_P 5003@item LEGITIMATE_CONSTANT_P (@var{x}) 5004A C expression that is nonzero if @var{x} is a legitimate constant for 5005an immediate operand on the target machine. You can assume that 5006@var{x} satisfies @code{CONSTANT_P}, so you need not check this. In fact, 5007@samp{1} is a suitable definition for this macro on machines where 5008anything @code{CONSTANT_P} is valid. 5009@end table 5010 5011@node Condition Code 5012@section Condition Code Status 5013@cindex condition code status 5014 5015@c prevent bad page break with this line 5016This describes the condition code status. 5017 5018@findex cc_status 5019The file @file{conditions.h} defines a variable @code{cc_status} to 5020describe how the condition code was computed (in case the interpretation of 5021the condition code depends on the instruction that it was set by). This 5022variable contains the RTL expressions on which the condition code is 5023currently based, and several standard flags. 5024 5025Sometimes additional machine-specific flags must be defined in the machine 5026description header file. It can also add additional machine-specific 5027information by defining @code{CC_STATUS_MDEP}. 5028 5029@table @code 5030@findex CC_STATUS_MDEP 5031@item CC_STATUS_MDEP 5032C code for a data type which is used for declaring the @code{mdep} 5033component of @code{cc_status}. It defaults to @code{int}. 5034 5035This macro is not used on machines that do not use @code{cc0}. 5036 5037@findex CC_STATUS_MDEP_INIT 5038@item CC_STATUS_MDEP_INIT 5039A C expression to initialize the @code{mdep} field to ``empty''. 5040The default definition does nothing, since most machines don't use 5041the field anyway. If you want to use the field, you should probably 5042define this macro to initialize it. 5043 5044This macro is not used on machines that do not use @code{cc0}. 5045 5046@findex NOTICE_UPDATE_CC 5047@item NOTICE_UPDATE_CC (@var{exp}, @var{insn}) 5048A C compound statement to set the components of @code{cc_status} 5049appropriately for an insn @var{insn} whose body is @var{exp}. It is 5050this macro's responsibility to recognize insns that set the condition 5051code as a byproduct of other activity as well as those that explicitly 5052set @code{(cc0)}. 5053 5054This macro is not used on machines that do not use @code{cc0}. 5055 5056If there are insns that do not set the condition code but do alter 5057other machine registers, this macro must check to see whether they 5058invalidate the expressions that the condition code is recorded as 5059reflecting. For example, on the 68000, insns that store in address 5060registers do not set the condition code, which means that usually 5061@code{NOTICE_UPDATE_CC} can leave @code{cc_status} unaltered for such 5062insns. But suppose that the previous insn set the condition code 5063based on location @samp{a4@@(102)} and the current insn stores a new 5064value in @samp{a4}. Although the condition code is not changed by 5065this, it will no longer be true that it reflects the contents of 5066@samp{a4@@(102)}. Therefore, @code{NOTICE_UPDATE_CC} must alter 5067@code{cc_status} in this case to say that nothing is known about the 5068condition code value. 5069 5070The definition of @code{NOTICE_UPDATE_CC} must be prepared to deal 5071with the results of peephole optimization: insns whose patterns are 5072@code{parallel} RTXs containing various @code{reg}, @code{mem} or 5073constants which are just the operands. The RTL structure of these 5074insns is not sufficient to indicate what the insns actually do. What 5075@code{NOTICE_UPDATE_CC} should do when it sees one is just to run 5076@code{CC_STATUS_INIT}. 5077 5078A possible definition of @code{NOTICE_UPDATE_CC} is to call a function 5079that looks at an attribute (@pxref{Insn Attributes}) named, for example, 5080@samp{cc}. This avoids having detailed information about patterns in 5081two places, the @file{md} file and in @code{NOTICE_UPDATE_CC}. 5082 5083@findex EXTRA_CC_MODES 5084@item EXTRA_CC_MODES 5085Condition codes are represented in registers by machine modes of class 5086@code{MODE_CC}. By default, there is just one mode, @code{CCmode}, with 5087this class. If you need more such modes, create a file named 5088@file{@var{machine}-modes.def} in your @file{config/@var{machine}} 5089directory (@pxref{Back End, , Anatomy of a Target Back End}), containing 5090a list of these modes. Each entry in the list should be a call to the 5091macro @code{CC}. This macro takes one argument, which is the name of 5092the mode: it should begin with @samp{CC}. Do not put quotation marks 5093around the name, or include the trailing @samp{mode}; these are 5094automatically added. There should not be anything else in the file 5095except comments. 5096 5097A sample @file{@var{machine}-modes.def} file might look like this: 5098 5099@smallexample 5100CC (CC_NOOV) /* @r{Comparison only valid if there was no overflow.} */ 5101CC (CCFP) /* @r{Floating point comparison that cannot trap.} */ 5102CC (CCFPE) /* @r{Floating point comparison that may trap.} */ 5103@end smallexample 5104 5105When you create this file, the macro @code{EXTRA_CC_MODES} is 5106automatically defined by @command{configure}, with value @samp{1}. 5107 5108@findex SELECT_CC_MODE 5109@item SELECT_CC_MODE (@var{op}, @var{x}, @var{y}) 5110Returns a mode from class @code{MODE_CC} to be used when comparison 5111operation code @var{op} is applied to rtx @var{x} and @var{y}. For 5112example, on the SPARC, @code{SELECT_CC_MODE} is defined as (see 5113@pxref{Jump Patterns} for a description of the reason for this 5114definition) 5115 5116@smallexample 5117#define SELECT_CC_MODE(OP,X,Y) \ 5118 (GET_MODE_CLASS (GET_MODE (X)) == MODE_FLOAT \ 5119 ? ((OP == EQ || OP == NE) ? CCFPmode : CCFPEmode) \ 5120 : ((GET_CODE (X) == PLUS || GET_CODE (X) == MINUS \ 5121 || GET_CODE (X) == NEG) \ 5122 ? CC_NOOVmode : CCmode)) 5123@end smallexample 5124 5125You need not define this macro if @code{EXTRA_CC_MODES} is not defined. 5126 5127@findex CANONICALIZE_COMPARISON 5128@item CANONICALIZE_COMPARISON (@var{code}, @var{op0}, @var{op1}) 5129On some machines not all possible comparisons are defined, but you can 5130convert an invalid comparison into a valid one. For example, the Alpha 5131does not have a @code{GT} comparison, but you can use an @code{LT} 5132comparison instead and swap the order of the operands. 5133 5134On such machines, define this macro to be a C statement to do any 5135required conversions. @var{code} is the initial comparison code 5136and @var{op0} and @var{op1} are the left and right operands of the 5137comparison, respectively. You should modify @var{code}, @var{op0}, and 5138@var{op1} as required. 5139 5140GCC will not assume that the comparison resulting from this macro is 5141valid but will see if the resulting insn matches a pattern in the 5142@file{md} file. 5143 5144You need not define this macro if it would never change the comparison 5145code or operands. 5146 5147@findex REVERSIBLE_CC_MODE 5148@item REVERSIBLE_CC_MODE (@var{mode}) 5149A C expression whose value is one if it is always safe to reverse a 5150comparison whose mode is @var{mode}. If @code{SELECT_CC_MODE} 5151can ever return @var{mode} for a floating-point inequality comparison, 5152then @code{REVERSIBLE_CC_MODE (@var{mode})} must be zero. 5153 5154You need not define this macro if it would always returns zero or if the 5155floating-point format is anything other than @code{IEEE_FLOAT_FORMAT}. 5156For example, here is the definition used on the SPARC, where floating-point 5157inequality comparisons are always given @code{CCFPEmode}: 5158 5159@smallexample 5160#define REVERSIBLE_CC_MODE(MODE) ((MODE) != CCFPEmode) 5161@end smallexample 5162 5163@findex REVERSE_CONDITION (@var{code}, @var{mode}) 5164A C expression whose value is reversed condition code of the @var{code} for 5165comparison done in CC_MODE @var{mode}. The macro is used only in case 5166@code{REVERSIBLE_CC_MODE (@var{mode})} is nonzero. Define this macro in case 5167machine has some non-standard way how to reverse certain conditionals. For 5168instance in case all floating point conditions are non-trapping, compiler may 5169freely convert unordered compares to ordered one. Then definition may look 5170like: 5171 5172@smallexample 5173#define REVERSE_CONDITION(CODE, MODE) \ 5174 ((MODE) != CCFPmode ? reverse_condition (CODE) \ 5175 : reverse_condition_maybe_unordered (CODE)) 5176@end smallexample 5177 5178@findex REVERSE_CONDEXEC_PREDICATES_P 5179@item REVERSE_CONDEXEC_PREDICATES_P (@var{code1}, @var{code2}) 5180A C expression that returns true if the conditional execution predicate 5181@var{code1} is the inverse of @var{code2} and vice versa. Define this to 5182return 0 if the target has conditional execution predicates that cannot be 5183reversed safely. If no expansion is specified, this macro is defined as 5184follows: 5185 5186@smallexample 5187#define REVERSE_CONDEXEC_PREDICATES_P (x, y) \ 5188 ((x) == reverse_condition (y)) 5189@end smallexample 5190 5191@end table 5192 5193@node Costs 5194@section Describing Relative Costs of Operations 5195@cindex costs of instructions 5196@cindex relative costs 5197@cindex speed of instructions 5198 5199These macros let you describe the relative speed of various operations 5200on the target machine. 5201 5202@table @code 5203@findex CONST_COSTS 5204@item CONST_COSTS (@var{x}, @var{code}, @var{outer_code}) 5205A part of a C @code{switch} statement that describes the relative costs 5206of constant RTL expressions. It must contain @code{case} labels for 5207expression codes @code{const_int}, @code{const}, @code{symbol_ref}, 5208@code{label_ref} and @code{const_double}. Each case must ultimately 5209reach a @code{return} statement to return the relative cost of the use 5210of that kind of constant value in an expression. The cost may depend on 5211the precise value of the constant, which is available for examination in 5212@var{x}, and the rtx code of the expression in which it is contained, 5213found in @var{outer_code}. 5214 5215@var{code} is the expression code---redundant, since it can be 5216obtained with @code{GET_CODE (@var{x})}. 5217 5218@findex RTX_COSTS 5219@findex COSTS_N_INSNS 5220@item RTX_COSTS (@var{x}, @var{code}, @var{outer_code}) 5221Like @code{CONST_COSTS} but applies to nonconstant RTL expressions. 5222This can be used, for example, to indicate how costly a multiply 5223instruction is. In writing this macro, you can use the construct 5224@code{COSTS_N_INSNS (@var{n})} to specify a cost equal to @var{n} fast 5225instructions. @var{outer_code} is the code of the expression in which 5226@var{x} is contained. 5227 5228This macro is optional; do not define it if the default cost assumptions 5229are adequate for the target machine. 5230 5231@findex DEFAULT_RTX_COSTS 5232@item DEFAULT_RTX_COSTS (@var{x}, @var{code}, @var{outer_code}) 5233This macro, if defined, is called for any case not handled by the 5234@code{RTX_COSTS} or @code{CONST_COSTS} macros. This eliminates the need 5235to put case labels into the macro, but the code, or any functions it 5236calls, must assume that the RTL in @var{x} could be of any type that has 5237not already been handled. The arguments are the same as for 5238@code{RTX_COSTS}, and the macro should execute a return statement giving 5239the cost of any RTL expressions that it can handle. The default cost 5240calculation is used for any RTL for which this macro does not return a 5241value. 5242 5243This macro is optional; do not define it if the default cost assumptions 5244are adequate for the target machine. 5245 5246@findex ADDRESS_COST 5247@item ADDRESS_COST (@var{address}) 5248An expression giving the cost of an addressing mode that contains 5249@var{address}. If not defined, the cost is computed from 5250the @var{address} expression and the @code{CONST_COSTS} values. 5251 5252For most CISC machines, the default cost is a good approximation of the 5253true cost of the addressing mode. However, on RISC machines, all 5254instructions normally have the same length and execution time. Hence 5255all addresses will have equal costs. 5256 5257In cases where more than one form of an address is known, the form with 5258the lowest cost will be used. If multiple forms have the same, lowest, 5259cost, the one that is the most complex will be used. 5260 5261For example, suppose an address that is equal to the sum of a register 5262and a constant is used twice in the same basic block. When this macro 5263is not defined, the address will be computed in a register and memory 5264references will be indirect through that register. On machines where 5265the cost of the addressing mode containing the sum is no higher than 5266that of a simple indirect reference, this will produce an additional 5267instruction and possibly require an additional register. Proper 5268specification of this macro eliminates this overhead for such machines. 5269 5270Similar use of this macro is made in strength reduction of loops. 5271 5272@var{address} need not be valid as an address. In such a case, the cost 5273is not relevant and can be any value; invalid addresses need not be 5274assigned a different cost. 5275 5276On machines where an address involving more than one register is as 5277cheap as an address computation involving only one register, defining 5278@code{ADDRESS_COST} to reflect this can cause two registers to be live 5279over a region of code where only one would have been if 5280@code{ADDRESS_COST} were not defined in that manner. This effect should 5281be considered in the definition of this macro. Equivalent costs should 5282probably only be given to addresses with different numbers of registers 5283on machines with lots of registers. 5284 5285This macro will normally either not be defined or be defined as a 5286constant. 5287 5288@findex REGISTER_MOVE_COST 5289@item REGISTER_MOVE_COST (@var{mode}, @var{from}, @var{to}) 5290A C expression for the cost of moving data of mode @var{mode} from a 5291register in class @var{from} to one in class @var{to}. The classes are 5292expressed using the enumeration values such as @code{GENERAL_REGS}. A 5293value of 2 is the default; other values are interpreted relative to 5294that. 5295 5296It is not required that the cost always equal 2 when @var{from} is the 5297same as @var{to}; on some machines it is expensive to move between 5298registers if they are not general registers. 5299 5300If reload sees an insn consisting of a single @code{set} between two 5301hard registers, and if @code{REGISTER_MOVE_COST} applied to their 5302classes returns a value of 2, reload does not check to ensure that the 5303constraints of the insn are met. Setting a cost of other than 2 will 5304allow reload to verify that the constraints are met. You should do this 5305if the @samp{mov@var{m}} pattern's constraints do not allow such copying. 5306 5307@findex MEMORY_MOVE_COST 5308@item MEMORY_MOVE_COST (@var{mode}, @var{class}, @var{in}) 5309A C expression for the cost of moving data of mode @var{mode} between a 5310register of class @var{class} and memory; @var{in} is zero if the value 5311is to be written to memory, nonzero if it is to be read in. This cost 5312is relative to those in @code{REGISTER_MOVE_COST}. If moving between 5313registers and memory is more expensive than between two registers, you 5314should define this macro to express the relative cost. 5315 5316If you do not define this macro, GCC uses a default cost of 4 plus 5317the cost of copying via a secondary reload register, if one is 5318needed. If your machine requires a secondary reload register to copy 5319between memory and a register of @var{class} but the reload mechanism is 5320more complex than copying via an intermediate, define this macro to 5321reflect the actual cost of the move. 5322 5323GCC defines the function @code{memory_move_secondary_cost} if 5324secondary reloads are needed. It computes the costs due to copying via 5325a secondary register. If your machine copies from memory using a 5326secondary register in the conventional way but the default base value of 53274 is not correct for your machine, define this macro to add some other 5328value to the result of that function. The arguments to that function 5329are the same as to this macro. 5330 5331@findex BRANCH_COST 5332@item BRANCH_COST 5333A C expression for the cost of a branch instruction. A value of 1 is 5334the default; other values are interpreted relative to that. 5335@end table 5336 5337Here are additional macros which do not specify precise relative costs, 5338but only that certain actions are more expensive than GCC would 5339ordinarily expect. 5340 5341@table @code 5342@findex SLOW_BYTE_ACCESS 5343@item SLOW_BYTE_ACCESS 5344Define this macro as a C expression which is nonzero if accessing less 5345than a word of memory (i.e.@: a @code{char} or a @code{short}) is no 5346faster than accessing a word of memory, i.e., if such access 5347require more than one instruction or if there is no difference in cost 5348between byte and (aligned) word loads. 5349 5350When this macro is not defined, the compiler will access a field by 5351finding the smallest containing object; when it is defined, a fullword 5352load will be used if alignment permits. Unless bytes accesses are 5353faster than word accesses, using word accesses is preferable since it 5354may eliminate subsequent memory access if subsequent accesses occur to 5355other fields in the same word of the structure, but to different bytes. 5356 5357@findex SLOW_UNALIGNED_ACCESS 5358@item SLOW_UNALIGNED_ACCESS (@var{mode}, @var{alignment}) 5359Define this macro to be the value 1 if memory accesses described by the 5360@var{mode} and @var{alignment} parameters have a cost many times greater 5361than aligned accesses, for example if they are emulated in a trap 5362handler. 5363 5364When this macro is nonzero, the compiler will act as if 5365@code{STRICT_ALIGNMENT} were nonzero when generating code for block 5366moves. This can cause significantly more instructions to be produced. 5367Therefore, do not set this macro nonzero if unaligned accesses only add a 5368cycle or two to the time for a memory access. 5369 5370If the value of this macro is always zero, it need not be defined. If 5371this macro is defined, it should produce a nonzero value when 5372@code{STRICT_ALIGNMENT} is nonzero. 5373 5374@findex DONT_REDUCE_ADDR 5375@item DONT_REDUCE_ADDR 5376Define this macro to inhibit strength reduction of memory addresses. 5377(On some machines, such strength reduction seems to do harm rather 5378than good.) 5379 5380@findex MOVE_RATIO 5381@item MOVE_RATIO 5382The threshold of number of scalar memory-to-memory move insns, @emph{below} 5383which a sequence of insns should be generated instead of a 5384string move insn or a library call. Increasing the value will always 5385make code faster, but eventually incurs high cost in increased code size. 5386 5387Note that on machines where the corresponding move insn is a 5388@code{define_expand} that emits a sequence of insns, this macro counts 5389the number of such sequences. 5390 5391If you don't define this, a reasonable default is used. 5392 5393@findex MOVE_BY_PIECES_P 5394@item MOVE_BY_PIECES_P (@var{size}, @var{alignment}) 5395A C expression used to determine whether @code{move_by_pieces} will be used to 5396copy a chunk of memory, or whether some other block move mechanism 5397will be used. Defaults to 1 if @code{move_by_pieces_ninsns} returns less 5398than @code{MOVE_RATIO}. 5399 5400@findex MOVE_MAX_PIECES 5401@item MOVE_MAX_PIECES 5402A C expression used by @code{move_by_pieces} to determine the largest unit 5403a load or store used to copy memory is. Defaults to @code{MOVE_MAX}. 5404 5405@findex CLEAR_RATIO 5406@item CLEAR_RATIO 5407The threshold of number of scalar move insns, @emph{below} which a sequence 5408of insns should be generated to clear memory instead of a string clear insn 5409or a library call. Increasing the value will always make code faster, but 5410eventually incurs high cost in increased code size. 5411 5412If you don't define this, a reasonable default is used. 5413 5414@findex CLEAR_BY_PIECES_P 5415@item CLEAR_BY_PIECES_P (@var{size}, @var{alignment}) 5416A C expression used to determine whether @code{clear_by_pieces} will be used 5417to clear a chunk of memory, or whether some other block clear mechanism 5418will be used. Defaults to 1 if @code{move_by_pieces_ninsns} returns less 5419than @code{CLEAR_RATIO}. 5420 5421@findex USE_LOAD_POST_INCREMENT 5422@item USE_LOAD_POST_INCREMENT (@var{mode}) 5423A C expression used to determine whether a load postincrement is a good 5424thing to use for a given mode. Defaults to the value of 5425@code{HAVE_POST_INCREMENT}. 5426 5427@findex USE_LOAD_POST_DECREMENT 5428@item USE_LOAD_POST_DECREMENT (@var{mode}) 5429A C expression used to determine whether a load postdecrement is a good 5430thing to use for a given mode. Defaults to the value of 5431@code{HAVE_POST_DECREMENT}. 5432 5433@findex USE_LOAD_PRE_INCREMENT 5434@item USE_LOAD_PRE_INCREMENT (@var{mode}) 5435A C expression used to determine whether a load preincrement is a good 5436thing to use for a given mode. Defaults to the value of 5437@code{HAVE_PRE_INCREMENT}. 5438 5439@findex USE_LOAD_PRE_DECREMENT 5440@item USE_LOAD_PRE_DECREMENT (@var{mode}) 5441A C expression used to determine whether a load predecrement is a good 5442thing to use for a given mode. Defaults to the value of 5443@code{HAVE_PRE_DECREMENT}. 5444 5445@findex USE_STORE_POST_INCREMENT 5446@item USE_STORE_POST_INCREMENT (@var{mode}) 5447A C expression used to determine whether a store postincrement is a good 5448thing to use for a given mode. Defaults to the value of 5449@code{HAVE_POST_INCREMENT}. 5450 5451@findex USE_STORE_POST_DECREMENT 5452@item USE_STORE_POST_DECREMENT (@var{mode}) 5453A C expression used to determine whether a store postdecrement is a good 5454thing to use for a given mode. Defaults to the value of 5455@code{HAVE_POST_DECREMENT}. 5456 5457@findex USE_STORE_PRE_INCREMENT 5458@item USE_STORE_PRE_INCREMENT (@var{mode}) 5459This macro is used to determine whether a store preincrement is a good 5460thing to use for a given mode. Defaults to the value of 5461@code{HAVE_PRE_INCREMENT}. 5462 5463@findex USE_STORE_PRE_DECREMENT 5464@item USE_STORE_PRE_DECREMENT (@var{mode}) 5465This macro is used to determine whether a store predecrement is a good 5466thing to use for a given mode. Defaults to the value of 5467@code{HAVE_PRE_DECREMENT}. 5468 5469@findex NO_FUNCTION_CSE 5470@item NO_FUNCTION_CSE 5471Define this macro if it is as good or better to call a constant 5472function address than to call an address kept in a register. 5473 5474@findex NO_RECURSIVE_FUNCTION_CSE 5475@item NO_RECURSIVE_FUNCTION_CSE 5476Define this macro if it is as good or better for a function to call 5477itself with an explicit address than to call an address kept in a 5478register. 5479@end table 5480 5481@node Scheduling 5482@section Adjusting the Instruction Scheduler 5483 5484The instruction scheduler may need a fair amount of machine-specific 5485adjustment in order to produce good code. GCC provides several target 5486hooks for this purpose. It is usually enough to define just a few of 5487them: try the first ones in this list first. 5488 5489@deftypefn {Target Hook} int TARGET_SCHED_ISSUE_RATE (void) 5490This hook returns the maximum number of instructions that can ever 5491issue at the same time on the target machine. The default is one. 5492Although the insn scheduler can define itself the possibility of issue 5493an insn on the same cycle, the value can serve as an additional 5494constraint to issue insns on the same simulated processor cycle (see 5495hooks @samp{TARGET_SCHED_REORDER} and @samp{TARGET_SCHED_REORDER2}). 5496This value must be constant over the entire compilation. If you need 5497it to vary depending on what the instructions are, you must use 5498@samp{TARGET_SCHED_VARIABLE_ISSUE}. 5499 5500For the automaton based pipeline interface, you could define this hook 5501to return the value of the macro @code{MAX_DFA_ISSUE_RATE}. 5502@end deftypefn 5503 5504@deftypefn {Target Hook} int TARGET_SCHED_VARIABLE_ISSUE (FILE *@var{file}, int @var{verbose}, rtx @var{insn}, int @var{more}) 5505This hook is executed by the scheduler after it has scheduled an insn 5506from the ready list. It should return the number of insns which can 5507still be issued in the current cycle. Normally this is 5508@samp{@w{@var{more} - 1}}. You should define this hook if some insns 5509take more machine resources than others, so that fewer insns can follow 5510them in the same cycle. @var{file} is either a null pointer, or a stdio 5511stream to write any debug output to. @var{verbose} is the verbose level 5512provided by @option{-fsched-verbose-@var{n}}. @var{insn} is the 5513instruction that was scheduled. 5514@end deftypefn 5515 5516@deftypefn {Target Hook} int TARGET_SCHED_ADJUST_COST (rtx @var{insn}, rtx @var{link}, rtx @var{dep_insn}, int @var{cost}) 5517This function corrects the value of @var{cost} based on the 5518relationship between @var{insn} and @var{dep_insn} through the 5519dependence @var{link}. It should return the new value. The default 5520is to make no adjustment to @var{cost}. This can be used for example 5521to specify to the scheduler using the traditional pipeline description 5522that an output- or anti-dependence does not incur the same cost as a 5523data-dependence. If the scheduler using the automaton based pipeline 5524description, the cost of anti-dependence is zero and the cost of 5525output-dependence is maximum of one and the difference of latency 5526times of the first and the second insns. If these values are not 5527acceptable, you could use the hook to modify them too. See also 5528@pxref{Automaton pipeline description}. 5529@end deftypefn 5530 5531@deftypefn {Target Hook} int TARGET_SCHED_ADJUST_PRIORITY (rtx @var{insn}, int @var{priority}) 5532This hook adjusts the integer scheduling priority @var{priority} of 5533@var{insn}. It should return the new priority. Reduce the priority to 5534execute @var{insn} earlier, increase the priority to execute @var{insn} 5535later. Do not define this hook if you do not need to adjust the 5536scheduling priorities of insns. 5537@end deftypefn 5538 5539@deftypefn {Target Hook} int TARGET_SCHED_REORDER (FILE *@var{file}, int @var{verbose}, rtx *@var{ready}, int *@var{n_readyp}, int @var{clock}) 5540This hook is executed by the scheduler after it has scheduled the ready 5541list, to allow the machine description to reorder it (for example to 5542combine two small instructions together on @samp{VLIW} machines). 5543@var{file} is either a null pointer, or a stdio stream to write any 5544debug output to. @var{verbose} is the verbose level provided by 5545@option{-fsched-verbose-@var{n}}. @var{ready} is a pointer to the ready 5546list of instructions that are ready to be scheduled. @var{n_readyp} is 5547a pointer to the number of elements in the ready list. The scheduler 5548reads the ready list in reverse order, starting with 5549@var{ready}[@var{*n_readyp}-1] and going to @var{ready}[0]. @var{clock} 5550is the timer tick of the scheduler. You may modify the ready list and 5551the number of ready insns. The return value is the number of insns that 5552can issue this cycle; normally this is just @code{issue_rate}. See also 5553@samp{TARGET_SCHED_REORDER2}. 5554@end deftypefn 5555 5556@deftypefn {Target Hook} int TARGET_SCHED_REORDER2 (FILE *@var{file}, int @var{verbose}, rtx *@var{ready}, int *@var{n_ready}, @var{clock}) 5557Like @samp{TARGET_SCHED_REORDER}, but called at a different time. That 5558function is called whenever the scheduler starts a new cycle. This one 5559is called once per iteration over a cycle, immediately after 5560@samp{TARGET_SCHED_VARIABLE_ISSUE}; it can reorder the ready list and 5561return the number of insns to be scheduled in the same cycle. Defining 5562this hook can be useful if there are frequent situations where 5563scheduling one insn causes other insns to become ready in the same 5564cycle. These other insns can then be taken into account properly. 5565@end deftypefn 5566 5567@deftypefn {Target Hook} void TARGET_SCHED_INIT (FILE *@var{file}, int @var{verbose}, int @var{max_ready}) 5568This hook is executed by the scheduler at the beginning of each block of 5569instructions that are to be scheduled. @var{file} is either a null 5570pointer, or a stdio stream to write any debug output to. @var{verbose} 5571is the verbose level provided by @option{-fsched-verbose-@var{n}}. 5572@var{max_ready} is the maximum number of insns in the current scheduling 5573region that can be live at the same time. This can be used to allocate 5574scratch space if it is needed, e.g. by @samp{TARGET_SCHED_REORDER}. 5575@end deftypefn 5576 5577@deftypefn {Target Hook} void TARGET_SCHED_FINISH (FILE *@var{file}, int @var{verbose}) 5578This hook is executed by the scheduler at the end of each block of 5579instructions that are to be scheduled. It can be used to perform 5580cleanup of any actions done by the other scheduling hooks. @var{file} 5581is either a null pointer, or a stdio stream to write any debug output 5582to. @var{verbose} is the verbose level provided by 5583@option{-fsched-verbose-@var{n}}. 5584@end deftypefn 5585 5586@deftypefn {Target Hook} int TARGET_SCHED_USE_DFA_PIPELINE_INTERFACE (void) 5587This hook is called many times during insn scheduling. If the hook 5588returns nonzero, the automaton based pipeline description is used for 5589insn scheduling. Otherwise the traditional pipeline description is 5590used. The default is usage of the traditional pipeline description. 5591 5592You should also remember that to simplify the insn scheduler sources 5593an empty traditional pipeline description interface is generated even 5594if there is no a traditional pipeline description in the @file{.md} 5595file. The same is true for the automaton based pipeline description. 5596That means that you should be accurate in defining the hook. 5597@end deftypefn 5598 5599@deftypefn {Target Hook} int TARGET_SCHED_DFA_PRE_CYCLE_INSN (void) 5600The hook returns an RTL insn. The automaton state used in the 5601pipeline hazard recognizer is changed as if the insn were scheduled 5602when the new simulated processor cycle starts. Usage of the hook may 5603simplify the automaton pipeline description for some @acronym{VLIW} 5604processors. If the hook is defined, it is used only for the automaton 5605based pipeline description. The default is not to change the state 5606when the new simulated processor cycle starts. 5607@end deftypefn 5608 5609@deftypefn {Target Hook} void TARGET_SCHED_INIT_DFA_PRE_CYCLE_INSN (void) 5610The hook can be used to initialize data used by the previous hook. 5611@end deftypefn 5612 5613@deftypefn {Target Hook} int TARGET_SCHED_DFA_POST_CYCLE_INSN (void) 5614The hook is analogous to @samp{TARGET_SCHED_DFA_PRE_CYCLE_INSN} but used 5615to changed the state as if the insn were scheduled when the new 5616simulated processor cycle finishes. 5617@end deftypefn 5618 5619@deftypefn {Target Hook} void TARGET_SCHED_INIT_DFA_POST_CYCLE_INSN (void) 5620The hook is analogous to @samp{TARGET_SCHED_INIT_DFA_PRE_CYCLE_INSN} but 5621used to initialize data used by the previous hook. 5622@end deftypefn 5623 5624@deftypefn {Target Hook} int TARGET_SCHED_FIRST_CYCLE_MULTIPASS_DFA_LOOKAHEAD (void) 5625This hook controls better choosing an insn from the ready insn queue 5626for the @acronym{DFA}-based insn scheduler. Usually the scheduler 5627chooses the first insn from the queue. If the hook returns a positive 5628value, an additional scheduler code tries all permutations of 5629@samp{TARGET_SCHED_FIRST_CYCLE_MULTIPASS_DFA_LOOKAHEAD ()} 5630subsequent ready insns to choose an insn whose issue will result in 5631maximal number of issued insns on the same cycle. For the 5632@acronym{VLIW} processor, the code could actually solve the problem of 5633packing simple insns into the @acronym{VLIW} insn. Of course, if the 5634rules of @acronym{VLIW} packing are described in the automaton. 5635 5636This code also could be used for superscalar @acronym{RISC} 5637processors. Let us consider a superscalar @acronym{RISC} processor 5638with 3 pipelines. Some insns can be executed in pipelines @var{A} or 5639@var{B}, some insns can be executed only in pipelines @var{B} or 5640@var{C}, and one insn can be executed in pipeline @var{B}. The 5641processor may issue the 1st insn into @var{A} and the 2nd one into 5642@var{B}. In this case, the 3rd insn will wait for freeing @var{B} 5643until the next cycle. If the scheduler issues the 3rd insn the first, 5644the processor could issue all 3 insns per cycle. 5645 5646Actually this code demonstrates advantages of the automaton based 5647pipeline hazard recognizer. We try quickly and easy many insn 5648schedules to choose the best one. 5649 5650The default is no multipass scheduling. 5651@end deftypefn 5652 5653@deftypefn {Target Hook} void TARGET_SCHED_INIT_DFA_BUBBLES (void) 5654The @acronym{DFA}-based scheduler could take the insertion of nop 5655operations for better insn scheduling into account. It can be done 5656only if the multi-pass insn scheduling works (see hook 5657@samp{TARGET_SCHED_FIRST_CYCLE_MULTIPASS_DFA_LOOKAHEAD}). 5658 5659Let us consider a @acronym{VLIW} processor insn with 3 slots. Each 5660insn can be placed only in one of the three slots. We have 3 ready 5661insns @var{A}, @var{B}, and @var{C}. @var{A} and @var{C} can be 5662placed only in the 1st slot, @var{B} can be placed only in the 3rd 5663slot. We described the automaton which does not permit empty slot 5664gaps between insns (usually such description is simpler). Without 5665this code the scheduler would place each insn in 3 separate 5666@acronym{VLIW} insns. If the scheduler places a nop insn into the 2nd 5667slot, it could place the 3 insns into 2 @acronym{VLIW} insns. What is 5668the nop insn is returned by hook @samp{TARGET_SCHED_DFA_BUBBLE}. Hook 5669@samp{TARGET_SCHED_INIT_DFA_BUBBLES} can be used to initialize or 5670create the nop insns. 5671 5672You should remember that the scheduler does not insert the nop insns. 5673It is not wise because of the following optimizations. The scheduler 5674only considers such possibility to improve the result schedule. The 5675nop insns should be inserted lately, e.g. on the final phase. 5676@end deftypefn 5677 5678@deftypefn {Target Hook} rtx TARGET_SCHED_DFA_BUBBLE (int @var{index}) 5679This hook @samp{FIRST_CYCLE_MULTIPASS_SCHEDULING} is used to insert 5680nop operations for better insn scheduling when @acronym{DFA}-based 5681scheduler makes multipass insn scheduling (see also description of 5682hook @samp{TARGET_SCHED_INIT_DFA_BUBBLES}). This hook 5683returns a nop insn with given @var{index}. The indexes start with 5684zero. The hook should return @code{NULL} if there are no more nop 5685insns with indexes greater than given index. 5686@end deftypefn 5687 5688Macros in the following table are generated by the program 5689@file{genattr} and can be useful for writing the hooks. 5690 5691@table @code 5692@findex TRADITIONAL_PIPELINE_INTERFACE 5693@item TRADITIONAL_PIPELINE_INTERFACE 5694The macro definition is generated if there is a traditional pipeline 5695description in @file{.md} file. You should also remember that to 5696simplify the insn scheduler sources an empty traditional pipeline 5697description interface is generated even if there is no a traditional 5698pipeline description in the @file{.md} file. The macro can be used to 5699distinguish the two types of the traditional interface. 5700 5701@findex DFA_PIPELINE_INTERFACE 5702@item DFA_PIPELINE_INTERFACE 5703The macro definition is generated if there is an automaton pipeline 5704description in @file{.md} file. You should also remember that to 5705simplify the insn scheduler sources an empty automaton pipeline 5706description interface is generated even if there is no an automaton 5707pipeline description in the @file{.md} file. The macro can be used to 5708distinguish the two types of the automaton interface. 5709 5710@findex MAX_DFA_ISSUE_RATE 5711@item MAX_DFA_ISSUE_RATE 5712The macro definition is generated in the automaton based pipeline 5713description interface. Its value is calculated from the automaton 5714based pipeline description and is equal to maximal number of all insns 5715described in constructions @samp{define_insn_reservation} which can be 5716issued on the same processor cycle. 5717 5718@end table 5719 5720@node Sections 5721@section Dividing the Output into Sections (Texts, Data, @dots{}) 5722@c the above section title is WAY too long. maybe cut the part between 5723@c the (...)? --mew 10feb93 5724 5725An object file is divided into sections containing different types of 5726data. In the most common case, there are three sections: the @dfn{text 5727section}, which holds instructions and read-only data; the @dfn{data 5728section}, which holds initialized writable data; and the @dfn{bss 5729section}, which holds uninitialized data. Some systems have other kinds 5730of sections. 5731 5732The compiler must tell the assembler when to switch sections. These 5733macros control what commands to output to tell the assembler this. You 5734can also define additional sections. 5735 5736@table @code 5737@findex TEXT_SECTION_ASM_OP 5738@item TEXT_SECTION_ASM_OP 5739A C expression whose value is a string, including spacing, containing the 5740assembler operation that should precede instructions and read-only data. 5741Normally @code{"\t.text"} is right. 5742 5743@findex TEXT_SECTION 5744@item TEXT_SECTION 5745A C statement that switches to the default section containing instructions. 5746Normally this is not needed, as simply defining @code{TEXT_SECTION_ASM_OP} 5747is enough. The MIPS port uses this to sort all functions after all data 5748declarations. 5749 5750@findex HOT_TEXT_SECTION_NAME 5751@item HOT_TEXT_SECTION_NAME 5752If defined, a C string constant for the name of the section containing most 5753frequently executed functions of the program. If not defined, GCC will provide 5754a default definition if the target supports named sections. 5755 5756@findex UNLIKELY_EXECUTED_TEXT_SECTION_NAME 5757@item UNLIKELY_EXECUTED_TEXT_SECTION_NAME 5758If defined, a C string constant for the name of the section containing unlikely 5759executed functions in the program. 5760 5761@findex DATA_SECTION_ASM_OP 5762@item DATA_SECTION_ASM_OP 5763A C expression whose value is a string, including spacing, containing the 5764assembler operation to identify the following data as writable initialized 5765data. Normally @code{"\t.data"} is right. 5766 5767@findex READONLY_DATA_SECTION_ASM_OP 5768@item READONLY_DATA_SECTION_ASM_OP 5769A C expression whose value is a string, including spacing, containing the 5770assembler operation to identify the following data as read-only initialized 5771data. 5772 5773@findex READONLY_DATA_SECTION 5774@item READONLY_DATA_SECTION 5775A macro naming a function to call to switch to the proper section for 5776read-only data. The default is to use @code{READONLY_DATA_SECTION_ASM_OP} 5777if defined, else fall back to @code{text_section}. 5778 5779The most common definition will be @code{data_section}, if the target 5780does not have a special read-only data section, and does not put data 5781in the text section. 5782 5783@findex SHARED_SECTION_ASM_OP 5784@item SHARED_SECTION_ASM_OP 5785If defined, a C expression whose value is a string, including spacing, 5786containing the assembler operation to identify the following data as 5787shared data. If not defined, @code{DATA_SECTION_ASM_OP} will be used. 5788 5789@findex BSS_SECTION_ASM_OP 5790@item BSS_SECTION_ASM_OP 5791If defined, a C expression whose value is a string, including spacing, 5792containing the assembler operation to identify the following data as 5793uninitialized global data. If not defined, and neither 5794@code{ASM_OUTPUT_BSS} nor @code{ASM_OUTPUT_ALIGNED_BSS} are defined, 5795uninitialized global data will be output in the data section if 5796@option{-fno-common} is passed, otherwise @code{ASM_OUTPUT_COMMON} will be 5797used. 5798 5799@findex SHARED_BSS_SECTION_ASM_OP 5800@item SHARED_BSS_SECTION_ASM_OP 5801If defined, a C expression whose value is a string, including spacing, 5802containing the assembler operation to identify the following data as 5803uninitialized global shared data. If not defined, and 5804@code{BSS_SECTION_ASM_OP} is, the latter will be used. 5805 5806@findex INIT_SECTION_ASM_OP 5807@item INIT_SECTION_ASM_OP 5808If defined, a C expression whose value is a string, including spacing, 5809containing the assembler operation to identify the following data as 5810initialization code. If not defined, GCC will assume such a section does 5811not exist. 5812 5813@findex FINI_SECTION_ASM_OP 5814@item FINI_SECTION_ASM_OP 5815If defined, a C expression whose value is a string, including spacing, 5816containing the assembler operation to identify the following data as 5817finalization code. If not defined, GCC will assume such a section does 5818not exist. 5819 5820@findex CRT_CALL_STATIC_FUNCTION 5821@item CRT_CALL_STATIC_FUNCTION (@var{section_op}, @var{function}) 5822If defined, an ASM statement that switches to a different section 5823via @var{section_op}, calls @var{function}, and switches back to 5824the text section. This is used in @file{crtstuff.c} if 5825@code{INIT_SECTION_ASM_OP} or @code{FINI_SECTION_ASM_OP} to calls 5826to initialization and finalization functions from the init and fini 5827sections. By default, this macro uses a simple function call. Some 5828ports need hand-crafted assembly code to avoid dependencies on 5829registers initialized in the function prologue or to ensure that 5830constant pools don't end up too far way in the text section. 5831 5832@findex FORCE_CODE_SECTION_ALIGN 5833@item FORCE_CODE_SECTION_ALIGN 5834If defined, an ASM statement that aligns a code section to some 5835arbitrary boundary. This is used to force all fragments of the 5836@code{.init} and @code{.fini} sections to have to same alignment 5837and thus prevent the linker from having to add any padding. 5838 5839@findex EXTRA_SECTIONS 5840@findex in_text 5841@findex in_data 5842@item EXTRA_SECTIONS 5843A list of names for sections other than the standard two, which are 5844@code{in_text} and @code{in_data}. You need not define this macro 5845on a system with no other sections (that GCC needs to use). 5846 5847@findex EXTRA_SECTION_FUNCTIONS 5848@findex text_section 5849@findex data_section 5850@item EXTRA_SECTION_FUNCTIONS 5851One or more functions to be defined in @file{varasm.c}. These 5852functions should do jobs analogous to those of @code{text_section} and 5853@code{data_section}, for your additional sections. Do not define this 5854macro if you do not define @code{EXTRA_SECTIONS}. 5855 5856@findex JUMP_TABLES_IN_TEXT_SECTION 5857@item JUMP_TABLES_IN_TEXT_SECTION 5858Define this macro to be an expression with a nonzero value if jump 5859tables (for @code{tablejump} insns) should be output in the text 5860section, along with the assembler instructions. Otherwise, the 5861readonly data section is used. 5862 5863This macro is irrelevant if there is no separate readonly data section. 5864@end table 5865 5866@deftypefn {Target Hook} void TARGET_ASM_SELECT_SECTION (tree @var{exp}, int @var{reloc}, unsigned HOST_WIDE_INT @var{align}) 5867Switches to the appropriate section for output of @var{exp}. You can 5868assume that @var{exp} is either a @code{VAR_DECL} node or a constant of 5869some sort. @var{reloc} indicates whether the initial value of @var{exp} 5870requires link-time relocations. Bit 0 is set when variable contains 5871local relocations only, while bit 1 is set for global relocations. 5872Select the section by calling @code{data_section} or one of the 5873alternatives for other sections. @var{align} is the constant alignment 5874in bits. 5875 5876The default version of this function takes care of putting read-only 5877variables in @code{readonly_data_section}. 5878@end deftypefn 5879 5880@deftypefn {Target Hook} void TARGET_ASM_UNIQUE_SECTION (tree @var{decl}, int @var{reloc}) 5881Build up a unique section name, expressed as a @code{STRING_CST} node, 5882and assign it to @samp{DECL_SECTION_NAME (@var{decl})}. 5883As with @code{TARGET_ASM_SELECT_SECTION}, @var{reloc} indicates whether 5884the initial value of @var{exp} requires link-time relocations. 5885 5886The default version of this function appends the symbol name to the 5887ELF section name that would normally be used for the symbol. For 5888example, the function @code{foo} would be placed in @code{.text.foo}. 5889Whatever the actual target object format, this is often good enough. 5890@end deftypefn 5891 5892@deftypefn {Target Hook} void TARGET_ASM_SELECT_RTX_SECTION (enum machine_mode @var{mode}, rtx @var{x}, unsigned HOST_WIDE_INT @var{align}) 5893Switches to the appropriate section for output of constant pool entry 5894@var{x} in @var{mode}. You can assume that @var{x} is some kind of 5895constant in RTL@. The argument @var{mode} is redundant except in the 5896case of a @code{const_int} rtx. Select the section by calling 5897@code{readonly_data_section} or one of the alternatives for other 5898sections. @var{align} is the constant alignment in bits. 5899 5900The default version of this function takes care of putting symbolic 5901constants in @code{flag_pic} mode in @code{data_section} and everything 5902else in @code{readonly_data_section}. 5903@end deftypefn 5904 5905@deftypefn {Target Hook} void TARGET_ENCODE_SECTION_INFO (tree @var{decl}, int @var{new_decl_p}) 5906Define this hook if references to a symbol or a constant must be 5907treated differently depending on something about the variable or 5908function named by the symbol (such as what section it is in). 5909 5910The hook is executed under two circumstances. One is immediately after 5911the rtl for @var{decl} that represents a variable or a function has been 5912created and stored in @code{DECL_RTL(@var{decl})}. The value of the rtl 5913will be a @code{mem} whose address is a @code{symbol_ref}. The other is 5914immediately after the rtl for @var{decl} that represents a constant has 5915been created and stored in @code{TREE_CST_RTL (@var{decl})}. The macro 5916is called once for each distinct constant in a source file. 5917 5918The @var{new_decl_p} argument will be true if this is the first time 5919that @code{ENCODE_SECTION_INFO} has been invoked on this decl. It will 5920be false for subsequent invocations, which will happen for duplicate 5921declarations. Whether or not anything must be done for the duplicate 5922declaration depends on whether the hook examines @code{DECL_ATTRIBUTES}. 5923 5924@cindex @code{SYMBOL_REF_FLAG}, in @code{TARGET_ENCODE_SECTION_INFO} 5925The usual thing for this hook to do is to record a flag in the 5926@code{symbol_ref} (such as @code{SYMBOL_REF_FLAG}) or to store a 5927modified name string in the @code{symbol_ref} (if one bit is not 5928enough information). 5929@end deftypefn 5930 5931@deftypefn {Target Hook} const char *TARGET_STRIP_NAME_ENCODING (const char *name) 5932Decode @var{name} and return the real name part, sans 5933the characters that @code{TARGET_ENCODE_SECTION_INFO} 5934may have added. 5935@end deftypefn 5936 5937@deftypefn {Target Hook} bool TARGET_IN_SMALL_DATA_P (tree @var{exp}) 5938Returns true if @var{exp} should be placed into a ``small data'' section. 5939The default version of this hook always returns false. 5940@end deftypefn 5941 5942@deftypevar {Target Hook} bool TARGET_HAVE_SRODATA_SECTION 5943Contains the value true if the target places read-only 5944``small data'' into a separate section. The default value is false. 5945@end deftypevar 5946 5947@deftypefn {Target Hook} bool TARGET_BINDS_LOCAL_P (tree @var{exp}) 5948Returns true if @var{exp} names an object for which name resolution 5949rules must resolve to the current ``module'' (dynamic shared library 5950or executable image). 5951 5952The default version of this hook implements the name resolution rules 5953for ELF, which has a looser model of global name binding than other 5954currently supported object file formats. 5955@end deftypefn 5956 5957@deftypevar {Target Hook} bool TARGET_HAVE_TLS 5958Contains the value true if the target supports thread-local storage. 5959The default value is false. 5960@end deftypevar 5961 5962 5963@node PIC 5964@section Position Independent Code 5965@cindex position independent code 5966@cindex PIC 5967 5968This section describes macros that help implement generation of position 5969independent code. Simply defining these macros is not enough to 5970generate valid PIC; you must also add support to the macros 5971@code{GO_IF_LEGITIMATE_ADDRESS} and @code{PRINT_OPERAND_ADDRESS}, as 5972well as @code{LEGITIMIZE_ADDRESS}. You must modify the definition of 5973@samp{movsi} to do something appropriate when the source operand 5974contains a symbolic address. You may also need to alter the handling of 5975switch statements so that they use relative addresses. 5976@c i rearranged the order of the macros above to try to force one of 5977@c them to the next line, to eliminate an overfull hbox. --mew 10feb93 5978 5979@table @code 5980@findex PIC_OFFSET_TABLE_REGNUM 5981@item PIC_OFFSET_TABLE_REGNUM 5982The register number of the register used to address a table of static 5983data addresses in memory. In some cases this register is defined by a 5984processor's ``application binary interface'' (ABI)@. When this macro 5985is defined, RTL is generated for this register once, as with the stack 5986pointer and frame pointer registers. If this macro is not defined, it 5987is up to the machine-dependent files to allocate such a register (if 5988necessary). Note that this register must be fixed when in use (e.g.@: 5989when @code{flag_pic} is true). 5990 5991@findex PIC_OFFSET_TABLE_REG_CALL_CLOBBERED 5992@item PIC_OFFSET_TABLE_REG_CALL_CLOBBERED 5993Define this macro if the register defined by 5994@code{PIC_OFFSET_TABLE_REGNUM} is clobbered by calls. Do not define 5995this macro if @code{PIC_OFFSET_TABLE_REGNUM} is not defined. 5996 5997@findex FINALIZE_PIC 5998@item FINALIZE_PIC 5999By generating position-independent code, when two different programs (A 6000and B) share a common library (libC.a), the text of the library can be 6001shared whether or not the library is linked at the same address for both 6002programs. In some of these environments, position-independent code 6003requires not only the use of different addressing modes, but also 6004special code to enable the use of these addressing modes. 6005 6006The @code{FINALIZE_PIC} macro serves as a hook to emit these special 6007codes once the function is being compiled into assembly code, but not 6008before. (It is not done before, because in the case of compiling an 6009inline function, it would lead to multiple PIC prologues being 6010included in functions which used inline functions and were compiled to 6011assembly language.) 6012 6013@findex LEGITIMATE_PIC_OPERAND_P 6014@item LEGITIMATE_PIC_OPERAND_P (@var{x}) 6015A C expression that is nonzero if @var{x} is a legitimate immediate 6016operand on the target machine when generating position independent code. 6017You can assume that @var{x} satisfies @code{CONSTANT_P}, so you need not 6018check this. You can also assume @var{flag_pic} is true, so you need not 6019check it either. You need not define this macro if all constants 6020(including @code{SYMBOL_REF}) can be immediate operands when generating 6021position independent code. 6022@end table 6023 6024@node Assembler Format 6025@section Defining the Output Assembler Language 6026 6027This section describes macros whose principal purpose is to describe how 6028to write instructions in assembler language---rather than what the 6029instructions do. 6030 6031@menu 6032* File Framework:: Structural information for the assembler file. 6033* Data Output:: Output of constants (numbers, strings, addresses). 6034* Uninitialized Data:: Output of uninitialized variables. 6035* Label Output:: Output and generation of labels. 6036* Initialization:: General principles of initialization 6037 and termination routines. 6038* Macros for Initialization:: 6039 Specific macros that control the handling of 6040 initialization and termination routines. 6041* Instruction Output:: Output of actual instructions. 6042* Dispatch Tables:: Output of jump tables. 6043* Exception Region Output:: Output of exception region code. 6044* Alignment Output:: Pseudo ops for alignment and skipping data. 6045@end menu 6046 6047@node File Framework 6048@subsection The Overall Framework of an Assembler File 6049@cindex assembler format 6050@cindex output of assembler code 6051 6052@c prevent bad page break with this line 6053This describes the overall framework of an assembler file. 6054 6055@table @code 6056@findex ASM_FILE_START 6057@item ASM_FILE_START (@var{stream}) 6058A C expression which outputs to the stdio stream @var{stream} 6059some appropriate text to go at the start of an assembler file. 6060 6061Normally this macro is defined to output a line containing 6062@samp{#NO_APP}, which is a comment that has no effect on most 6063assemblers but tells the GNU assembler that it can save time by not 6064checking for certain assembler constructs. 6065 6066On systems that use SDB, it is necessary to output certain commands; 6067see @file{attasm.h}. 6068 6069@findex ASM_FILE_END 6070@item ASM_FILE_END (@var{stream}) 6071A C expression which outputs to the stdio stream @var{stream} 6072some appropriate text to go at the end of an assembler file. 6073 6074If this macro is not defined, the default is to output nothing 6075special at the end of the file. Most systems don't require any 6076definition. 6077 6078On systems that use SDB, it is necessary to output certain commands; 6079see @file{attasm.h}. 6080 6081@findex ASM_COMMENT_START 6082@item ASM_COMMENT_START 6083A C string constant describing how to begin a comment in the target 6084assembler language. The compiler assumes that the comment will end at 6085the end of the line. 6086 6087@findex ASM_APP_ON 6088@item ASM_APP_ON 6089A C string constant for text to be output before each @code{asm} 6090statement or group of consecutive ones. Normally this is 6091@code{"#APP"}, which is a comment that has no effect on most 6092assemblers but tells the GNU assembler that it must check the lines 6093that follow for all valid assembler constructs. 6094 6095@findex ASM_APP_OFF 6096@item ASM_APP_OFF 6097A C string constant for text to be output after each @code{asm} 6098statement or group of consecutive ones. Normally this is 6099@code{"#NO_APP"}, which tells the GNU assembler to resume making the 6100time-saving assumptions that are valid for ordinary compiler output. 6101 6102@findex ASM_OUTPUT_SOURCE_FILENAME 6103@item ASM_OUTPUT_SOURCE_FILENAME (@var{stream}, @var{name}) 6104A C statement to output COFF information or DWARF debugging information 6105which indicates that filename @var{name} is the current source file to 6106the stdio stream @var{stream}. 6107 6108This macro need not be defined if the standard form of output 6109for the file format in use is appropriate. 6110 6111@findex OUTPUT_QUOTED_STRING 6112@item OUTPUT_QUOTED_STRING (@var{stream}, @var{string}) 6113A C statement to output the string @var{string} to the stdio stream 6114@var{stream}. If you do not call the function @code{output_quoted_string} 6115in your config files, GCC will only call it to output filenames to 6116the assembler source. So you can use it to canonicalize the format 6117of the filename using this macro. 6118 6119@findex ASM_OUTPUT_SOURCE_LINE 6120@item ASM_OUTPUT_SOURCE_LINE (@var{stream}, @var{line}) 6121A C statement to output DBX or SDB debugging information before code 6122for line number @var{line} of the current source file to the 6123stdio stream @var{stream}. 6124 6125This macro need not be defined if the standard form of debugging 6126information for the debugger in use is appropriate. 6127 6128@findex ASM_OUTPUT_IDENT 6129@item ASM_OUTPUT_IDENT (@var{stream}, @var{string}) 6130A C statement to output something to the assembler file to handle a 6131@samp{#ident} directive containing the text @var{string}. If this 6132macro is not defined, nothing is output for a @samp{#ident} directive. 6133 6134@findex OBJC_PROLOGUE 6135@item OBJC_PROLOGUE 6136A C statement to output any assembler statements which are required to 6137precede any Objective-C object definitions or message sending. The 6138statement is executed only when compiling an Objective-C program. 6139@end table 6140 6141@deftypefn {Target Hook} void TARGET_ASM_NAMED_SECTION (const char *@var{name}, unsigned int @var{flags}, unsigned int @var{align}) 6142Output assembly directives to switch to section @var{name}. The section 6143should have attributes as specified by @var{flags}, which is a bit mask 6144of the @code{SECTION_*} flags defined in @file{output.h}. If @var{align} 6145is nonzero, it contains an alignment in bytes to be used for the section, 6146otherwise some target default should be used. Only targets that must 6147specify an alignment within the section directive need pay attention to 6148@var{align} -- we will still use @code{ASM_OUTPUT_ALIGN}. 6149@end deftypefn 6150 6151@deftypefn {Target Hook} bool TARGET_HAVE_NAMED_SECTIONS 6152This flag is true if the target supports @code{TARGET_ASM_NAMED_SECTION}. 6153@end deftypefn 6154 6155@deftypefn {Target Hook} {unsigned int} TARGET_SECTION_TYPE_FLAGS (tree @var{decl}, const char *@var{name}, int @var{reloc}) 6156Choose a set of section attributes for use by @code{TARGET_ASM_NAMED_SECTION} 6157based on a variable or function decl, a section name, and whether or not the 6158declaration's initializer may contain runtime relocations. @var{decl} may be 6159 null, in which case read-write data should be assumed. 6160 6161The default version if this function handles choosing code vs data, 6162read-only vs read-write data, and @code{flag_pic}. You should only 6163need to override this if your target has special flags that might be 6164set via @code{__attribute__}. 6165@end deftypefn 6166 6167@need 2000 6168@node Data Output 6169@subsection Output of Data 6170 6171 6172@deftypevr {Target Hook} {const char *} TARGET_ASM_BYTE_OP 6173@deftypevrx {Target Hook} {const char *} TARGET_ASM_ALIGNED_HI_OP 6174@deftypevrx {Target Hook} {const char *} TARGET_ASM_ALIGNED_SI_OP 6175@deftypevrx {Target Hook} {const char *} TARGET_ASM_ALIGNED_DI_OP 6176@deftypevrx {Target Hook} {const char *} TARGET_ASM_ALIGNED_TI_OP 6177@deftypevrx {Target Hook} {const char *} TARGET_ASM_UNALIGNED_HI_OP 6178@deftypevrx {Target Hook} {const char *} TARGET_ASM_UNALIGNED_SI_OP 6179@deftypevrx {Target Hook} {const char *} TARGET_ASM_UNALIGNED_DI_OP 6180@deftypevrx {Target Hook} {const char *} TARGET_ASM_UNALIGNED_TI_OP 6181These hooks specify assembly directives for creating certain kinds 6182of integer object. The @code{TARGET_ASM_BYTE_OP} directive creates a 6183byte-sized object, the @code{TARGET_ASM_ALIGNED_HI_OP} one creates an 6184aligned two-byte object, and so on. Any of the hooks may be 6185@code{NULL}, indicating that no suitable directive is available. 6186 6187The compiler will print these strings at the start of a new line, 6188followed immediately by the object's initial value. In most cases, 6189the string should contain a tab, a pseudo-op, and then another tab. 6190@end deftypevr 6191 6192@deftypefn {Target Hook} bool TARGET_ASM_INTEGER (rtx @var{x}, unsigned int @var{size}, int @var{aligned_p}) 6193The @code{assemble_integer} function uses this hook to output an 6194integer object. @var{x} is the object's value, @var{size} is its size 6195in bytes and @var{aligned_p} indicates whether it is aligned. The 6196function should return @code{true} if it was able to output the 6197object. If it returns false, @code{assemble_integer} will try to 6198split the object into smaller parts. 6199 6200The default implementation of this hook will use the 6201@code{TARGET_ASM_BYTE_OP} family of strings, returning @code{false} 6202when the relevant string is @code{NULL}. 6203@end deftypefn 6204 6205@table @code 6206@findex OUTPUT_ADDR_CONST_EXTRA 6207@item OUTPUT_ADDR_CONST_EXTRA (@var{stream}, @var{x}, @var{fail}) 6208A C statement to recognize @var{rtx} patterns that 6209@code{output_addr_const} can't deal with, and output assembly code to 6210@var{stream} corresponding to the pattern @var{x}. This may be used to 6211allow machine-dependent @code{UNSPEC}s to appear within constants. 6212 6213If @code{OUTPUT_ADDR_CONST_EXTRA} fails to recognize a pattern, it must 6214@code{goto fail}, so that a standard error message is printed. If it 6215prints an error message itself, by calling, for example, 6216@code{output_operand_lossage}, it may just complete normally. 6217 6218@findex ASM_OUTPUT_ASCII 6219@item ASM_OUTPUT_ASCII (@var{stream}, @var{ptr}, @var{len}) 6220A C statement to output to the stdio stream @var{stream} an assembler 6221instruction to assemble a string constant containing the @var{len} 6222bytes at @var{ptr}. @var{ptr} will be a C expression of type 6223@code{char *} and @var{len} a C expression of type @code{int}. 6224 6225If the assembler has a @code{.ascii} pseudo-op as found in the 6226Berkeley Unix assembler, do not define the macro 6227@code{ASM_OUTPUT_ASCII}. 6228 6229@findex ASM_OUTPUT_FDESC 6230@item ASM_OUTPUT_FDESC (@var{stream}, @var{decl}, @var{n}) 6231A C statement to output word @var{n} of a function descriptor for 6232@var{decl}. This must be defined if @code{TARGET_VTABLE_USES_DESCRIPTORS} 6233is defined, and is otherwise unused. 6234 6235@findex CONSTANT_POOL_BEFORE_FUNCTION 6236@item CONSTANT_POOL_BEFORE_FUNCTION 6237You may define this macro as a C expression. You should define the 6238expression to have a nonzero value if GCC should output the constant 6239pool for a function before the code for the function, or a zero value if 6240GCC should output the constant pool after the function. If you do 6241not define this macro, the usual case, GCC will output the constant 6242pool before the function. 6243 6244@findex ASM_OUTPUT_POOL_PROLOGUE 6245@item ASM_OUTPUT_POOL_PROLOGUE (@var{file}, @var{funname}, @var{fundecl}, @var{size}) 6246A C statement to output assembler commands to define the start of the 6247constant pool for a function. @var{funname} is a string giving 6248the name of the function. Should the return type of the function 6249be required, it can be obtained via @var{fundecl}. @var{size} 6250is the size, in bytes, of the constant pool that will be written 6251immediately after this call. 6252 6253If no constant-pool prefix is required, the usual case, this macro need 6254not be defined. 6255 6256@findex ASM_OUTPUT_SPECIAL_POOL_ENTRY 6257@item ASM_OUTPUT_SPECIAL_POOL_ENTRY (@var{file}, @var{x}, @var{mode}, @var{align}, @var{labelno}, @var{jumpto}) 6258A C statement (with or without semicolon) to output a constant in the 6259constant pool, if it needs special treatment. (This macro need not do 6260anything for RTL expressions that can be output normally.) 6261 6262The argument @var{file} is the standard I/O stream to output the 6263assembler code on. @var{x} is the RTL expression for the constant to 6264output, and @var{mode} is the machine mode (in case @var{x} is a 6265@samp{const_int}). @var{align} is the required alignment for the value 6266@var{x}; you should output an assembler directive to force this much 6267alignment. 6268 6269The argument @var{labelno} is a number to use in an internal label for 6270the address of this pool entry. The definition of this macro is 6271responsible for outputting the label definition at the proper place. 6272Here is how to do this: 6273 6274@example 6275ASM_OUTPUT_INTERNAL_LABEL (@var{file}, "LC", @var{labelno}); 6276@end example 6277 6278When you output a pool entry specially, you should end with a 6279@code{goto} to the label @var{jumpto}. This will prevent the same pool 6280entry from being output a second time in the usual manner. 6281 6282You need not define this macro if it would do nothing. 6283 6284@findex CONSTANT_AFTER_FUNCTION_P 6285@item CONSTANT_AFTER_FUNCTION_P (@var{exp}) 6286Define this macro as a C expression which is nonzero if the constant 6287@var{exp}, of type @code{tree}, should be output after the code for a 6288function. The compiler will normally output all constants before the 6289function; you need not define this macro if this is OK@. 6290 6291@findex ASM_OUTPUT_POOL_EPILOGUE 6292@item ASM_OUTPUT_POOL_EPILOGUE (@var{file} @var{funname} @var{fundecl} @var{size}) 6293A C statement to output assembler commands to at the end of the constant 6294pool for a function. @var{funname} is a string giving the name of the 6295function. Should the return type of the function be required, you can 6296obtain it via @var{fundecl}. @var{size} is the size, in bytes, of the 6297constant pool that GCC wrote immediately before this call. 6298 6299If no constant-pool epilogue is required, the usual case, you need not 6300define this macro. 6301 6302@findex IS_ASM_LOGICAL_LINE_SEPARATOR 6303@item IS_ASM_LOGICAL_LINE_SEPARATOR (@var{C}) 6304Define this macro as a C expression which is nonzero if @var{C} is 6305used as a logical line separator by the assembler. 6306 6307If you do not define this macro, the default is that only 6308the character @samp{;} is treated as a logical line separator. 6309@end table 6310 6311@deftypevr {Target Hook} {const char *} TARGET_ASM_OPEN_PAREN 6312@deftypevrx {Target Hook} {const char *} TARGET_ASM_CLOSE_PAREN 6313These target hooks are C string constants, describing the syntax in the 6314assembler for grouping arithmetic expressions. If not overridden, they 6315default to normal parentheses, which is correct for most assemblers. 6316@end deftypevr 6317 6318 These macros are provided by @file{real.h} for writing the definitions 6319of @code{ASM_OUTPUT_DOUBLE} and the like: 6320 6321@table @code 6322@item REAL_VALUE_TO_TARGET_SINGLE (@var{x}, @var{l}) 6323@itemx REAL_VALUE_TO_TARGET_DOUBLE (@var{x}, @var{l}) 6324@itemx REAL_VALUE_TO_TARGET_LONG_DOUBLE (@var{x}, @var{l}) 6325@findex REAL_VALUE_TO_TARGET_SINGLE 6326@findex REAL_VALUE_TO_TARGET_DOUBLE 6327@findex REAL_VALUE_TO_TARGET_LONG_DOUBLE 6328These translate @var{x}, of type @code{REAL_VALUE_TYPE}, to the target's 6329floating point representation, and store its bit pattern in the variable 6330@var{l}. For @code{REAL_VALUE_TO_TARGET_SINGLE}, this variable should 6331be a simple @code{long int}. For the others, it should be an array of 6332@code{long int}. The number of elements in this array is determined by 6333the size of the desired target floating point data type: 32 bits of it 6334go in each @code{long int} array element. Each array element holds 32 6335bits of the result, even if @code{long int} is wider than 32 bits on the 6336host machine. 6337 6338The array element values are designed so that you can print them out 6339using @code{fprintf} in the order they should appear in the target 6340machine's memory. 6341@end table 6342 6343@node Uninitialized Data 6344@subsection Output of Uninitialized Variables 6345 6346Each of the macros in this section is used to do the whole job of 6347outputting a single uninitialized variable. 6348 6349@table @code 6350@findex ASM_OUTPUT_COMMON 6351@item ASM_OUTPUT_COMMON (@var{stream}, @var{name}, @var{size}, @var{rounded}) 6352A C statement (sans semicolon) to output to the stdio stream 6353@var{stream} the assembler definition of a common-label named 6354@var{name} whose size is @var{size} bytes. The variable @var{rounded} 6355is the size rounded up to whatever alignment the caller wants. 6356 6357Use the expression @code{assemble_name (@var{stream}, @var{name})} to 6358output the name itself; before and after that, output the additional 6359assembler syntax for defining the name, and a newline. 6360 6361This macro controls how the assembler definitions of uninitialized 6362common global variables are output. 6363 6364@findex ASM_OUTPUT_ALIGNED_COMMON 6365@item ASM_OUTPUT_ALIGNED_COMMON (@var{stream}, @var{name}, @var{size}, @var{alignment}) 6366Like @code{ASM_OUTPUT_COMMON} except takes the required alignment as a 6367separate, explicit argument. If you define this macro, it is used in 6368place of @code{ASM_OUTPUT_COMMON}, and gives you more flexibility in 6369handling the required alignment of the variable. The alignment is specified 6370as the number of bits. 6371 6372@findex ASM_OUTPUT_ALIGNED_DECL_COMMON 6373@item ASM_OUTPUT_ALIGNED_DECL_COMMON (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{alignment}) 6374Like @code{ASM_OUTPUT_ALIGNED_COMMON} except that @var{decl} of the 6375variable to be output, if there is one, or @code{NULL_TREE} if there 6376is no corresponding variable. If you define this macro, GCC will use it 6377in place of both @code{ASM_OUTPUT_COMMON} and 6378@code{ASM_OUTPUT_ALIGNED_COMMON}. Define this macro when you need to see 6379the variable's decl in order to chose what to output. 6380 6381@findex ASM_OUTPUT_SHARED_COMMON 6382@item ASM_OUTPUT_SHARED_COMMON (@var{stream}, @var{name}, @var{size}, @var{rounded}) 6383If defined, it is similar to @code{ASM_OUTPUT_COMMON}, except that it 6384is used when @var{name} is shared. If not defined, @code{ASM_OUTPUT_COMMON} 6385will be used. 6386 6387@findex ASM_OUTPUT_BSS 6388@item ASM_OUTPUT_BSS (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{rounded}) 6389A C statement (sans semicolon) to output to the stdio stream 6390@var{stream} the assembler definition of uninitialized global @var{decl} named 6391@var{name} whose size is @var{size} bytes. The variable @var{rounded} 6392is the size rounded up to whatever alignment the caller wants. 6393 6394Try to use function @code{asm_output_bss} defined in @file{varasm.c} when 6395defining this macro. If unable, use the expression 6396@code{assemble_name (@var{stream}, @var{name})} to output the name itself; 6397before and after that, output the additional assembler syntax for defining 6398the name, and a newline. 6399 6400This macro controls how the assembler definitions of uninitialized global 6401variables are output. This macro exists to properly support languages like 6402C++ which do not have @code{common} data. However, this macro currently 6403is not defined for all targets. If this macro and 6404@code{ASM_OUTPUT_ALIGNED_BSS} are not defined then @code{ASM_OUTPUT_COMMON} 6405or @code{ASM_OUTPUT_ALIGNED_COMMON} or 6406@code{ASM_OUTPUT_ALIGNED_DECL_COMMON} is used. 6407 6408@findex ASM_OUTPUT_ALIGNED_BSS 6409@item ASM_OUTPUT_ALIGNED_BSS (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{alignment}) 6410Like @code{ASM_OUTPUT_BSS} except takes the required alignment as a 6411separate, explicit argument. If you define this macro, it is used in 6412place of @code{ASM_OUTPUT_BSS}, and gives you more flexibility in 6413handling the required alignment of the variable. The alignment is specified 6414as the number of bits. 6415 6416Try to use function @code{asm_output_aligned_bss} defined in file 6417@file{varasm.c} when defining this macro. 6418 6419@findex ASM_OUTPUT_SHARED_BSS 6420@item ASM_OUTPUT_SHARED_BSS (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{rounded}) 6421If defined, it is similar to @code{ASM_OUTPUT_BSS}, except that it 6422is used when @var{name} is shared. If not defined, @code{ASM_OUTPUT_BSS} 6423will be used. 6424 6425@findex ASM_OUTPUT_LOCAL 6426@item ASM_OUTPUT_LOCAL (@var{stream}, @var{name}, @var{size}, @var{rounded}) 6427A C statement (sans semicolon) to output to the stdio stream 6428@var{stream} the assembler definition of a local-common-label named 6429@var{name} whose size is @var{size} bytes. The variable @var{rounded} 6430is the size rounded up to whatever alignment the caller wants. 6431 6432Use the expression @code{assemble_name (@var{stream}, @var{name})} to 6433output the name itself; before and after that, output the additional 6434assembler syntax for defining the name, and a newline. 6435 6436This macro controls how the assembler definitions of uninitialized 6437static variables are output. 6438 6439@findex ASM_OUTPUT_ALIGNED_LOCAL 6440@item ASM_OUTPUT_ALIGNED_LOCAL (@var{stream}, @var{name}, @var{size}, @var{alignment}) 6441Like @code{ASM_OUTPUT_LOCAL} except takes the required alignment as a 6442separate, explicit argument. If you define this macro, it is used in 6443place of @code{ASM_OUTPUT_LOCAL}, and gives you more flexibility in 6444handling the required alignment of the variable. The alignment is specified 6445as the number of bits. 6446 6447@findex ASM_OUTPUT_ALIGNED_DECL_LOCAL 6448@item ASM_OUTPUT_ALIGNED_DECL_LOCAL (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{alignment}) 6449Like @code{ASM_OUTPUT_ALIGNED_DECL} except that @var{decl} of the 6450variable to be output, if there is one, or @code{NULL_TREE} if there 6451is no corresponding variable. If you define this macro, GCC will use it 6452in place of both @code{ASM_OUTPUT_DECL} and 6453@code{ASM_OUTPUT_ALIGNED_DECL}. Define this macro when you need to see 6454the variable's decl in order to chose what to output. 6455 6456@findex ASM_OUTPUT_SHARED_LOCAL 6457@item ASM_OUTPUT_SHARED_LOCAL (@var{stream}, @var{name}, @var{size}, @var{rounded}) 6458If defined, it is similar to @code{ASM_OUTPUT_LOCAL}, except that it 6459is used when @var{name} is shared. If not defined, @code{ASM_OUTPUT_LOCAL} 6460will be used. 6461@end table 6462 6463@node Label Output 6464@subsection Output and Generation of Labels 6465 6466@c prevent bad page break with this line 6467This is about outputting labels. 6468 6469@table @code 6470@findex ASM_OUTPUT_LABEL 6471@findex assemble_name 6472@item ASM_OUTPUT_LABEL (@var{stream}, @var{name}) 6473A C statement (sans semicolon) to output to the stdio stream 6474@var{stream} the assembler definition of a label named @var{name}. 6475Use the expression @code{assemble_name (@var{stream}, @var{name})} to 6476output the name itself; before and after that, output the additional 6477assembler syntax for defining the name, and a newline. A default 6478definition of this macro is provided which is correct for most systems. 6479 6480@findex SIZE_ASM_OP 6481@item SIZE_ASM_OP 6482A C string containing the appropriate assembler directive to specify the 6483size of a symbol, without any arguments. On systems that use ELF, the 6484default (in @file{config/elfos.h}) is @samp{"\t.size\t"}; on other 6485systems, the default is not to define this macro. 6486 6487Define this macro only if it is correct to use the default definitions 6488of @code{ASM_OUTPUT_SIZE_DIRECTIVE} and @code{ASM_OUTPUT_MEASURED_SIZE} 6489for your system. If you need your own custom definitions of those 6490macros, or if you do not need explicit symbol sizes at all, do not 6491define this macro. 6492 6493@findex ASM_OUTPUT_SIZE_DIRECTIVE 6494@item ASM_OUTPUT_SIZE_DIRECTIVE (@var{stream}, @var{name}, @var{size}) 6495A C statement (sans semicolon) to output to the stdio stream 6496@var{stream} a directive telling the assembler that the size of the 6497symbol @var{name} is @var{size}. @var{size} is a @code{HOST_WIDE_INT}. 6498If you define @code{SIZE_ASM_OP}, a default definition of this macro is 6499provided. 6500 6501@findex ASM_OUTPUT_MEASURED_SIZE 6502@item ASM_OUTPUT_MEASURED_SIZE (@var{stream}, @var{name}) 6503A C statement (sans semicolon) to output to the stdio stream 6504@var{stream} a directive telling the assembler to calculate the size of 6505the symbol @var{name} by subtracting its address from the current 6506address. 6507 6508If you define @code{SIZE_ASM_OP}, a default definition of this macro is 6509provided. The default assumes that the assembler recognizes a special 6510@samp{.} symbol as referring to the current address, and can calculate 6511the difference between this and another symbol. If your assembler does 6512not recognize @samp{.} or cannot do calculations with it, you will need 6513to redefine @code{ASM_OUTPUT_MEASURED_SIZE} to use some other technique. 6514 6515@findex TYPE_ASM_OP 6516@item TYPE_ASM_OP 6517A C string containing the appropriate assembler directive to specify the 6518type of a symbol, without any arguments. On systems that use ELF, the 6519default (in @file{config/elfos.h}) is @samp{"\t.type\t"}; on other 6520systems, the default is not to define this macro. 6521 6522Define this macro only if it is correct to use the default definition of 6523@code{ASM_OUTPUT_TYPE_DIRECTIVE} for your system. If you need your own 6524custom definition of this macro, or if you do not need explicit symbol 6525types at all, do not define this macro. 6526 6527@findex TYPE_OPERAND_FMT 6528@item TYPE_OPERAND_FMT 6529A C string which specifies (using @code{printf} syntax) the format of 6530the second operand to @code{TYPE_ASM_OP}. On systems that use ELF, the 6531default (in @file{config/elfos.h}) is @samp{"@@%s"}; on other systems, 6532the default is not to define this macro. 6533 6534Define this macro only if it is correct to use the default definition of 6535@code{ASM_OUTPUT_TYPE_DIRECTIVE} for your system. If you need your own 6536custom definition of this macro, or if you do not need explicit symbol 6537types at all, do not define this macro. 6538 6539@findex ASM_OUTPUT_TYPE_DIRECTIVE 6540@item ASM_OUTPUT_TYPE_DIRECTIVE (@var{stream}, @var{type}) 6541A C statement (sans semicolon) to output to the stdio stream 6542@var{stream} a directive telling the assembler that the type of the 6543symbol @var{name} is @var{type}. @var{type} is a C string; currently, 6544that string is always either @samp{"function"} or @samp{"object"}, but 6545you should not count on this. 6546 6547If you define @code{TYPE_ASM_OP} and @code{TYPE_OPERAND_FMT}, a default 6548definition of this macro is provided. 6549 6550@findex ASM_DECLARE_FUNCTION_NAME 6551@item ASM_DECLARE_FUNCTION_NAME (@var{stream}, @var{name}, @var{decl}) 6552A C statement (sans semicolon) to output to the stdio stream 6553@var{stream} any text necessary for declaring the name @var{name} of a 6554function which is being defined. This macro is responsible for 6555outputting the label definition (perhaps using 6556@code{ASM_OUTPUT_LABEL}). The argument @var{decl} is the 6557@code{FUNCTION_DECL} tree node representing the function. 6558 6559If this macro is not defined, then the function name is defined in the 6560usual manner as a label (by means of @code{ASM_OUTPUT_LABEL}). 6561 6562You may wish to use @code{ASM_OUTPUT_TYPE_DIRECTIVE} in the definition 6563of this macro. 6564 6565@findex ASM_DECLARE_FUNCTION_SIZE 6566@item ASM_DECLARE_FUNCTION_SIZE (@var{stream}, @var{name}, @var{decl}) 6567A C statement (sans semicolon) to output to the stdio stream 6568@var{stream} any text necessary for declaring the size of a function 6569which is being defined. The argument @var{name} is the name of the 6570function. The argument @var{decl} is the @code{FUNCTION_DECL} tree node 6571representing the function. 6572 6573If this macro is not defined, then the function size is not defined. 6574 6575You may wish to use @code{ASM_OUTPUT_MEASURED_SIZE} in the definition 6576of this macro. 6577 6578@findex ASM_DECLARE_OBJECT_NAME 6579@item ASM_DECLARE_OBJECT_NAME (@var{stream}, @var{name}, @var{decl}) 6580A C statement (sans semicolon) to output to the stdio stream 6581@var{stream} any text necessary for declaring the name @var{name} of an 6582initialized variable which is being defined. This macro must output the 6583label definition (perhaps using @code{ASM_OUTPUT_LABEL}). The argument 6584@var{decl} is the @code{VAR_DECL} tree node representing the variable. 6585 6586If this macro is not defined, then the variable name is defined in the 6587usual manner as a label (by means of @code{ASM_OUTPUT_LABEL}). 6588 6589You may wish to use @code{ASM_OUTPUT_TYPE_DIRECTIVE} and/or 6590@code{ASM_OUTPUT_SIZE_DIRECTIVE} in the definition of this macro. 6591 6592@findex ASM_DECLARE_REGISTER_GLOBAL 6593@item ASM_DECLARE_REGISTER_GLOBAL (@var{stream}, @var{decl}, @var{regno}, @var{name}) 6594A C statement (sans semicolon) to output to the stdio stream 6595@var{stream} any text necessary for claiming a register @var{regno} 6596for a global variable @var{decl} with name @var{name}. 6597 6598If you don't define this macro, that is equivalent to defining it to do 6599nothing. 6600 6601@findex ASM_FINISH_DECLARE_OBJECT 6602@item ASM_FINISH_DECLARE_OBJECT (@var{stream}, @var{decl}, @var{toplevel}, @var{atend}) 6603A C statement (sans semicolon) to finish up declaring a variable name 6604once the compiler has processed its initializer fully and thus has had a 6605chance to determine the size of an array when controlled by an 6606initializer. This is used on systems where it's necessary to declare 6607something about the size of the object. 6608 6609If you don't define this macro, that is equivalent to defining it to do 6610nothing. 6611 6612You may wish to use @code{ASM_OUTPUT_SIZE_DIRECTIVE} and/or 6613@code{ASM_OUTPUT_MEASURED_SIZE} in the definition of this macro. 6614@end table 6615 6616@deftypefn {Target Hook} void TARGET_ASM_GLOBALIZE_LABEL (FILE *@var{stream}, const char *@var{name}) 6617This target hook is a function to output to the stdio stream 6618@var{stream} some commands that will make the label @var{name} global; 6619that is, available for reference from other files. 6620 6621The default implementation relies on a proper definition of 6622@code{GLOBAL_ASM_OP}. 6623@end deftypefn 6624 6625@table @code 6626@findex ASM_WEAKEN_LABEL 6627@item ASM_WEAKEN_LABEL (@var{stream}, @var{name}) 6628A C statement (sans semicolon) to output to the stdio stream 6629@var{stream} some commands that will make the label @var{name} weak; 6630that is, available for reference from other files but only used if 6631no other definition is available. Use the expression 6632@code{assemble_name (@var{stream}, @var{name})} to output the name 6633itself; before and after that, output the additional assembler syntax 6634for making that name weak, and a newline. 6635 6636If you don't define this macro or @code{ASM_WEAKEN_DECL}, GCC will not 6637support weak symbols and you should not define the @code{SUPPORTS_WEAK} 6638macro. 6639 6640@findex ASM_WEAKEN_DECL 6641@item ASM_WEAKEN_DECL (@var{stream}, @var{decl}, @var{name}, @var{value}) 6642Combines (and replaces) the function of @code{ASM_WEAKEN_LABEL} and 6643@code{ASM_OUTPUT_WEAK_ALIAS}, allowing access to the associated function 6644or variable decl. If @var{value} is not @code{NULL}, this C statement 6645should output to the stdio stream @var{stream} assembler code which 6646defines (equates) the weak symbol @var{name} to have the value 6647@var{value}. If @var{value} is @code{NULL}, it should output commands 6648to make @var{name} weak. 6649 6650@findex SUPPORTS_WEAK 6651@item SUPPORTS_WEAK 6652A C expression which evaluates to true if the target supports weak symbols. 6653 6654If you don't define this macro, @file{defaults.h} provides a default 6655definition. If either @code{ASM_WEAKEN_LABEL} or @code{ASM_WEAKEN_DECL} 6656is defined, the default definition is @samp{1}; otherwise, it is 6657@samp{0}. Define this macro if you want to control weak symbol support 6658with a compiler flag such as @option{-melf}. 6659 6660@findex MAKE_DECL_ONE_ONLY (@var{decl}) 6661@item MAKE_DECL_ONE_ONLY 6662A C statement (sans semicolon) to mark @var{decl} to be emitted as a 6663public symbol such that extra copies in multiple translation units will 6664be discarded by the linker. Define this macro if your object file 6665format provides support for this concept, such as the @samp{COMDAT} 6666section flags in the Microsoft Windows PE/COFF format, and this support 6667requires changes to @var{decl}, such as putting it in a separate section. 6668 6669@findex SUPPORTS_ONE_ONLY 6670@item SUPPORTS_ONE_ONLY 6671A C expression which evaluates to true if the target supports one-only 6672semantics. 6673 6674If you don't define this macro, @file{varasm.c} provides a default 6675definition. If @code{MAKE_DECL_ONE_ONLY} is defined, the default 6676definition is @samp{1}; otherwise, it is @samp{0}. Define this macro if 6677you want to control one-only symbol support with a compiler flag, or if 6678setting the @code{DECL_ONE_ONLY} flag is enough to mark a declaration to 6679be emitted as one-only. 6680 6681@deftypefn {Target Hook} void TARGET_ASM_ASSEMBLE_VISIBILITY (tree @var{decl}, const char *@var{visibility}) 6682This target hook is a function to output to @var{asm_out_file} some 6683commands that will make the symbol(s) associated with @var{decl} have 6684hidden, protected or internal visibility as specified by @var{visibility}. 6685@end deftypefn 6686 6687@findex ASM_OUTPUT_EXTERNAL 6688@item ASM_OUTPUT_EXTERNAL (@var{stream}, @var{decl}, @var{name}) 6689A C statement (sans semicolon) to output to the stdio stream 6690@var{stream} any text necessary for declaring the name of an external 6691symbol named @var{name} which is referenced in this compilation but 6692not defined. The value of @var{decl} is the tree node for the 6693declaration. 6694 6695This macro need not be defined if it does not need to output anything. 6696The GNU assembler and most Unix assemblers don't require anything. 6697 6698@findex ASM_OUTPUT_EXTERNAL_LIBCALL 6699@item ASM_OUTPUT_EXTERNAL_LIBCALL (@var{stream}, @var{symref}) 6700A C statement (sans semicolon) to output on @var{stream} an assembler 6701pseudo-op to declare a library function name external. The name of the 6702library function is given by @var{symref}, which has type @code{rtx} and 6703is a @code{symbol_ref}. 6704 6705This macro need not be defined if it does not need to output anything. 6706The GNU assembler and most Unix assemblers don't require anything. 6707 6708@findex ASM_OUTPUT_LABELREF 6709@item ASM_OUTPUT_LABELREF (@var{stream}, @var{name}) 6710A C statement (sans semicolon) to output to the stdio stream 6711@var{stream} a reference in assembler syntax to a label named 6712@var{name}. This should add @samp{_} to the front of the name, if that 6713is customary on your operating system, as it is in most Berkeley Unix 6714systems. This macro is used in @code{assemble_name}. 6715 6716@findex ASM_OUTPUT_SYMBOL_REF 6717@item ASM_OUTPUT_SYMBOL_REF (@var{stream}, @var{sym}) 6718A C statement (sans semicolon) to output a reference to 6719@code{SYMBOL_REF} @var{sym}. If not defined, @code{assemble_name} 6720will be used to output the name of the symbol. This macro may be used 6721to modify the way a symbol is referenced depending on information 6722encoded by @code{TARGET_ENCODE_SECTION_INFO}. 6723 6724@findex ASM_OUTPUT_LABEL_REF 6725@item ASM_OUTPUT_LABEL_REF (@var{stream}, @var{buf}) 6726A C statement (sans semicolon) to output a reference to @var{buf}, the 6727result of @code{ASM_GENERATE_INTERNAL_LABEL}. If not defined, 6728@code{assemble_name} will be used to output the name of the symbol. 6729This macro is not used by @code{output_asm_label}, or the @code{%l} 6730specifier that calls it; the intention is that this macro should be set 6731when it is necessary to output a label differently when its address is 6732being taken. 6733 6734@findex ASM_OUTPUT_INTERNAL_LABEL 6735@item ASM_OUTPUT_INTERNAL_LABEL (@var{stream}, @var{prefix}, @var{num}) 6736A C statement to output to the stdio stream @var{stream} a label whose 6737name is made from the string @var{prefix} and the number @var{num}. 6738 6739It is absolutely essential that these labels be distinct from the labels 6740used for user-level functions and variables. Otherwise, certain programs 6741will have name conflicts with internal labels. 6742 6743It is desirable to exclude internal labels from the symbol table of the 6744object file. Most assemblers have a naming convention for labels that 6745should be excluded; on many systems, the letter @samp{L} at the 6746beginning of a label has this effect. You should find out what 6747convention your system uses, and follow it. 6748 6749The usual definition of this macro is as follows: 6750 6751@example 6752fprintf (@var{stream}, "L%s%d:\n", @var{prefix}, @var{num}) 6753@end example 6754 6755@findex ASM_OUTPUT_DEBUG_LABEL 6756@item ASM_OUTPUT_DEBUG_LABEL (@var{stream}, @var{prefix}, @var{num}) 6757A C statement to output to the stdio stream @var{stream} a debug info 6758label whose name is made from the string @var{prefix} and the number 6759@var{num}. This is useful for VLIW targets, where debug info labels 6760may need to be treated differently than branch target labels. On some 6761systems, branch target labels must be at the beginning of instruction 6762bundles, but debug info labels can occur in the middle of instruction 6763bundles. 6764 6765If this macro is not defined, then @code{ASM_OUTPUT_INTERNAL_LABEL} will be 6766used. 6767 6768@findex ASM_GENERATE_INTERNAL_LABEL 6769@item ASM_GENERATE_INTERNAL_LABEL (@var{string}, @var{prefix}, @var{num}) 6770A C statement to store into the string @var{string} a label whose name 6771is made from the string @var{prefix} and the number @var{num}. 6772 6773This string, when output subsequently by @code{assemble_name}, should 6774produce the output that @code{ASM_OUTPUT_INTERNAL_LABEL} would produce 6775with the same @var{prefix} and @var{num}. 6776 6777If the string begins with @samp{*}, then @code{assemble_name} will 6778output the rest of the string unchanged. It is often convenient for 6779@code{ASM_GENERATE_INTERNAL_LABEL} to use @samp{*} in this way. If the 6780string doesn't start with @samp{*}, then @code{ASM_OUTPUT_LABELREF} gets 6781to output the string, and may change it. (Of course, 6782@code{ASM_OUTPUT_LABELREF} is also part of your machine description, so 6783you should know what it does on your machine.) 6784 6785@findex ASM_FORMAT_PRIVATE_NAME 6786@item ASM_FORMAT_PRIVATE_NAME (@var{outvar}, @var{name}, @var{number}) 6787A C expression to assign to @var{outvar} (which is a variable of type 6788@code{char *}) a newly allocated string made from the string 6789@var{name} and the number @var{number}, with some suitable punctuation 6790added. Use @code{alloca} to get space for the string. 6791 6792The string will be used as an argument to @code{ASM_OUTPUT_LABELREF} to 6793produce an assembler label for an internal static variable whose name is 6794@var{name}. Therefore, the string must be such as to result in valid 6795assembler code. The argument @var{number} is different each time this 6796macro is executed; it prevents conflicts between similarly-named 6797internal static variables in different scopes. 6798 6799Ideally this string should not be a valid C identifier, to prevent any 6800conflict with the user's own symbols. Most assemblers allow periods 6801or percent signs in assembler symbols; putting at least one of these 6802between the name and the number will suffice. 6803 6804@findex ASM_OUTPUT_DEF 6805@item ASM_OUTPUT_DEF (@var{stream}, @var{name}, @var{value}) 6806A C statement to output to the stdio stream @var{stream} assembler code 6807which defines (equates) the symbol @var{name} to have the value @var{value}. 6808 6809@findex SET_ASM_OP 6810If @code{SET_ASM_OP} is defined, a default definition is provided which is 6811correct for most systems. 6812 6813@findex ASM_OUTPUT_DEF_FROM_DECLS 6814@item ASM_OUTPUT_DEF_FROM_DECLS (@var{stream}, @var{decl_of_name}, @var{decl_of_value}) 6815A C statement to output to the stdio stream @var{stream} assembler code 6816which defines (equates) the symbol whose tree node is @var{decl_of_name} 6817to have the value of the tree node @var{decl_of_value}. This macro will 6818be used in preference to @samp{ASM_OUTPUT_DEF} if it is defined and if 6819the tree nodes are available. 6820 6821@findex SET_ASM_OP 6822If @code{SET_ASM_OP} is defined, a default definition is provided which is 6823correct for most systems. 6824 6825@findex ASM_OUTPUT_WEAK_ALIAS 6826@item ASM_OUTPUT_WEAK_ALIAS (@var{stream}, @var{name}, @var{value}) 6827A C statement to output to the stdio stream @var{stream} assembler code 6828which defines (equates) the weak symbol @var{name} to have the value 6829@var{value}. If @var{value} is @code{NULL}, it defines @var{name} as 6830an undefined weak symbol. 6831 6832Define this macro if the target only supports weak aliases; define 6833@code{ASM_OUTPUT_DEF} instead if possible. 6834 6835@findex OBJC_GEN_METHOD_LABEL 6836@item OBJC_GEN_METHOD_LABEL (@var{buf}, @var{is_inst}, @var{class_name}, @var{cat_name}, @var{sel_name}) 6837Define this macro to override the default assembler names used for 6838Objective-C methods. 6839 6840The default name is a unique method number followed by the name of the 6841class (e.g.@: @samp{_1_Foo}). For methods in categories, the name of 6842the category is also included in the assembler name (e.g.@: 6843@samp{_1_Foo_Bar}). 6844 6845These names are safe on most systems, but make debugging difficult since 6846the method's selector is not present in the name. Therefore, particular 6847systems define other ways of computing names. 6848 6849@var{buf} is an expression of type @code{char *} which gives you a 6850buffer in which to store the name; its length is as long as 6851@var{class_name}, @var{cat_name} and @var{sel_name} put together, plus 685250 characters extra. 6853 6854The argument @var{is_inst} specifies whether the method is an instance 6855method or a class method; @var{class_name} is the name of the class; 6856@var{cat_name} is the name of the category (or @code{NULL} if the method is not 6857in a category); and @var{sel_name} is the name of the selector. 6858 6859On systems where the assembler can handle quoted names, you can use this 6860macro to provide more human-readable names. 6861 6862@findex ASM_DECLARE_CLASS_REFERENCE 6863@item ASM_DECLARE_CLASS_REFERENCE (@var{stream}, @var{name}) 6864A C statement (sans semicolon) to output to the stdio stream 6865@var{stream} commands to declare that the label @var{name} is an 6866Objective-C class reference. This is only needed for targets whose 6867linkers have special support for NeXT-style runtimes. 6868 6869@findex ASM_DECLARE_UNRESOLVED_REFERENCE 6870@item ASM_DECLARE_UNRESOLVED_REFERENCE (@var{stream}, @var{name}) 6871A C statement (sans semicolon) to output to the stdio stream 6872@var{stream} commands to declare that the label @var{name} is an 6873unresolved Objective-C class reference. This is only needed for targets 6874whose linkers have special support for NeXT-style runtimes. 6875@end table 6876 6877@node Initialization 6878@subsection How Initialization Functions Are Handled 6879@cindex initialization routines 6880@cindex termination routines 6881@cindex constructors, output of 6882@cindex destructors, output of 6883 6884The compiled code for certain languages includes @dfn{constructors} 6885(also called @dfn{initialization routines})---functions to initialize 6886data in the program when the program is started. These functions need 6887to be called before the program is ``started''---that is to say, before 6888@code{main} is called. 6889 6890Compiling some languages generates @dfn{destructors} (also called 6891@dfn{termination routines}) that should be called when the program 6892terminates. 6893 6894To make the initialization and termination functions work, the compiler 6895must output something in the assembler code to cause those functions to 6896be called at the appropriate time. When you port the compiler to a new 6897system, you need to specify how to do this. 6898 6899There are two major ways that GCC currently supports the execution of 6900initialization and termination functions. Each way has two variants. 6901Much of the structure is common to all four variations. 6902 6903@findex __CTOR_LIST__ 6904@findex __DTOR_LIST__ 6905The linker must build two lists of these functions---a list of 6906initialization functions, called @code{__CTOR_LIST__}, and a list of 6907termination functions, called @code{__DTOR_LIST__}. 6908 6909Each list always begins with an ignored function pointer (which may hold 69100, @minus{}1, or a count of the function pointers after it, depending on 6911the environment). This is followed by a series of zero or more function 6912pointers to constructors (or destructors), followed by a function 6913pointer containing zero. 6914 6915Depending on the operating system and its executable file format, either 6916@file{crtstuff.c} or @file{libgcc2.c} traverses these lists at startup 6917time and exit time. Constructors are called in reverse order of the 6918list; destructors in forward order. 6919 6920The best way to handle static constructors works only for object file 6921formats which provide arbitrarily-named sections. A section is set 6922aside for a list of constructors, and another for a list of destructors. 6923Traditionally these are called @samp{.ctors} and @samp{.dtors}. Each 6924object file that defines an initialization function also puts a word in 6925the constructor section to point to that function. The linker 6926accumulates all these words into one contiguous @samp{.ctors} section. 6927Termination functions are handled similarly. 6928 6929This method will be chosen as the default by @file{target-def.h} if 6930@code{TARGET_ASM_NAMED_SECTION} is defined. A target that does not 6931support arbitrary sections, but does support special designated 6932constructor and destructor sections may define @code{CTORS_SECTION_ASM_OP} 6933and @code{DTORS_SECTION_ASM_OP} to achieve the same effect. 6934 6935When arbitrary sections are available, there are two variants, depending 6936upon how the code in @file{crtstuff.c} is called. On systems that 6937support a @dfn{.init} section which is executed at program startup, 6938parts of @file{crtstuff.c} are compiled into that section. The 6939program is linked by the @command{gcc} driver like this: 6940 6941@example 6942ld -o @var{output_file} crti.o crtbegin.o @dots{} -lgcc crtend.o crtn.o 6943@end example 6944 6945The prologue of a function (@code{__init}) appears in the @code{.init} 6946section of @file{crti.o}; the epilogue appears in @file{crtn.o}. Likewise 6947for the function @code{__fini} in the @dfn{.fini} section. Normally these 6948files are provided by the operating system or by the GNU C library, but 6949are provided by GCC for a few targets. 6950 6951The objects @file{crtbegin.o} and @file{crtend.o} are (for most targets) 6952compiled from @file{crtstuff.c}. They contain, among other things, code 6953fragments within the @code{.init} and @code{.fini} sections that branch 6954to routines in the @code{.text} section. The linker will pull all parts 6955of a section together, which results in a complete @code{__init} function 6956that invokes the routines we need at startup. 6957 6958To use this variant, you must define the @code{INIT_SECTION_ASM_OP} 6959macro properly. 6960 6961If no init section is available, when GCC compiles any function called 6962@code{main} (or more accurately, any function designated as a program 6963entry point by the language front end calling @code{expand_main_function}), 6964it inserts a procedure call to @code{__main} as the first executable code 6965after the function prologue. The @code{__main} function is defined 6966in @file{libgcc2.c} and runs the global constructors. 6967 6968In file formats that don't support arbitrary sections, there are again 6969two variants. In the simplest variant, the GNU linker (GNU @code{ld}) 6970and an `a.out' format must be used. In this case, 6971@code{TARGET_ASM_CONSTRUCTOR} is defined to produce a @code{.stabs} 6972entry of type @samp{N_SETT}, referencing the name @code{__CTOR_LIST__}, 6973and with the address of the void function containing the initialization 6974code as its value. The GNU linker recognizes this as a request to add 6975the value to a @dfn{set}; the values are accumulated, and are eventually 6976placed in the executable as a vector in the format described above, with 6977a leading (ignored) count and a trailing zero element. 6978@code{TARGET_ASM_DESTRUCTOR} is handled similarly. Since no init 6979section is available, the absence of @code{INIT_SECTION_ASM_OP} causes 6980the compilation of @code{main} to call @code{__main} as above, starting 6981the initialization process. 6982 6983The last variant uses neither arbitrary sections nor the GNU linker. 6984This is preferable when you want to do dynamic linking and when using 6985file formats which the GNU linker does not support, such as `ECOFF'@. In 6986this case, @code{TARGET_HAVE_CTORS_DTORS} is false, initialization and 6987termination functions are recognized simply by their names. This requires 6988an extra program in the linkage step, called @command{collect2}. This program 6989pretends to be the linker, for use with GCC; it does its job by running 6990the ordinary linker, but also arranges to include the vectors of 6991initialization and termination functions. These functions are called 6992via @code{__main} as described above. In order to use this method, 6993@code{use_collect2} must be defined in the target in @file{config.gcc}. 6994 6995@ifinfo 6996The following section describes the specific macros that control and 6997customize the handling of initialization and termination functions. 6998@end ifinfo 6999 7000@node Macros for Initialization 7001@subsection Macros Controlling Initialization Routines 7002 7003Here are the macros that control how the compiler handles initialization 7004and termination functions: 7005 7006@table @code 7007@findex INIT_SECTION_ASM_OP 7008@item INIT_SECTION_ASM_OP 7009If defined, a C string constant, including spacing, for the assembler 7010operation to identify the following data as initialization code. If not 7011defined, GCC will assume such a section does not exist. When you are 7012using special sections for initialization and termination functions, this 7013macro also controls how @file{crtstuff.c} and @file{libgcc2.c} arrange to 7014run the initialization functions. 7015 7016@item HAS_INIT_SECTION 7017@findex HAS_INIT_SECTION 7018If defined, @code{main} will not call @code{__main} as described above. 7019This macro should be defined for systems that control start-up code 7020on a symbol-by-symbol basis, such as OSF/1, and should not 7021be defined explicitly for systems that support @code{INIT_SECTION_ASM_OP}. 7022 7023@item LD_INIT_SWITCH 7024@findex LD_INIT_SWITCH 7025If defined, a C string constant for a switch that tells the linker that 7026the following symbol is an initialization routine. 7027 7028@item LD_FINI_SWITCH 7029@findex LD_FINI_SWITCH 7030If defined, a C string constant for a switch that tells the linker that 7031the following symbol is a finalization routine. 7032 7033@item COLLECT_SHARED_INIT_FUNC (@var{stream}, @var{func}) 7034If defined, a C statement that will write a function that can be 7035automatically called when a shared library is loaded. The function 7036should call @var{func}, which takes no arguments. If not defined, and 7037the object format requires an explicit initialization function, then a 7038function called @code{_GLOBAL__DI} will be generated. 7039 7040This function and the following one are used by collect2 when linking a 7041shared library that needs constructors or destructors, or has DWARF2 7042exception tables embedded in the code. 7043 7044@item COLLECT_SHARED_FINI_FUNC (@var{stream}, @var{func}) 7045If defined, a C statement that will write a function that can be 7046automatically called when a shared library is unloaded. The function 7047should call @var{func}, which takes no arguments. If not defined, and 7048the object format requires an explicit finalization function, then a 7049function called @code{_GLOBAL__DD} will be generated. 7050 7051@item INVOKE__main 7052@findex INVOKE__main 7053If defined, @code{main} will call @code{__main} despite the presence of 7054@code{INIT_SECTION_ASM_OP}. This macro should be defined for systems 7055where the init section is not actually run automatically, but is still 7056useful for collecting the lists of constructors and destructors. 7057 7058@item SUPPORTS_INIT_PRIORITY 7059@findex SUPPORTS_INIT_PRIORITY 7060If nonzero, the C++ @code{init_priority} attribute is supported and the 7061compiler should emit instructions to control the order of initialization 7062of objects. If zero, the compiler will issue an error message upon 7063encountering an @code{init_priority} attribute. 7064@end table 7065 7066@deftypefn {Target Hook} bool TARGET_HAVE_CTORS_DTORS 7067This value is true if the target supports some ``native'' method of 7068collecting constructors and destructors to be run at startup and exit. 7069It is false if we must use @command{collect2}. 7070@end deftypefn 7071 7072@deftypefn {Target Hook} void TARGET_ASM_CONSTRUCTOR (rtx @var{symbol}, int @var{priority}) 7073If defined, a function that outputs assembler code to arrange to call 7074the function referenced by @var{symbol} at initialization time. 7075 7076Assume that @var{symbol} is a @code{SYMBOL_REF} for a function taking 7077no arguments and with no return value. If the target supports initialization 7078priorities, @var{priority} is a value between 0 and @code{MAX_INIT_PRIORITY}; 7079otherwise it must be @code{DEFAULT_INIT_PRIORITY}. 7080 7081If this macro is not defined by the target, a suitable default will 7082be chosen if (1) the target supports arbitrary section names, (2) the 7083target defines @code{CTORS_SECTION_ASM_OP}, or (3) @code{USE_COLLECT2} 7084is not defined. 7085@end deftypefn 7086 7087@deftypefn {Target Hook} void TARGET_ASM_DESTRUCTOR (rtx @var{symbol}, int @var{priority}) 7088This is like @code{TARGET_ASM_CONSTRUCTOR} but used for termination 7089functions rather than initialization functions. 7090@end deftypefn 7091 7092If @code{TARGET_HAVE_CTORS_DTORS} is true, the initialization routine 7093generated for the generated object file will have static linkage. 7094 7095If your system uses @command{collect2} as the means of processing 7096constructors, then that program normally uses @command{nm} to scan 7097an object file for constructor functions to be called. 7098 7099On certain kinds of systems, you can define these macros to make 7100@command{collect2} work faster (and, in some cases, make it work at all): 7101 7102@table @code 7103@findex OBJECT_FORMAT_COFF 7104@item OBJECT_FORMAT_COFF 7105Define this macro if the system uses COFF (Common Object File Format) 7106object files, so that @command{collect2} can assume this format and scan 7107object files directly for dynamic constructor/destructor functions. 7108 7109@findex OBJECT_FORMAT_ROSE 7110@item OBJECT_FORMAT_ROSE 7111Define this macro if the system uses ROSE format object files, so that 7112@command{collect2} can assume this format and scan object files directly 7113for dynamic constructor/destructor functions. 7114 7115These macros are effective only in a native compiler; @command{collect2} as 7116part of a cross compiler always uses @command{nm} for the target machine. 7117 7118@findex REAL_NM_FILE_NAME 7119@item REAL_NM_FILE_NAME 7120Define this macro as a C string constant containing the file name to use 7121to execute @command{nm}. The default is to search the path normally for 7122@command{nm}. 7123 7124If your system supports shared libraries and has a program to list the 7125dynamic dependencies of a given library or executable, you can define 7126these macros to enable support for running initialization and 7127termination functions in shared libraries: 7128 7129@findex LDD_SUFFIX 7130@item LDD_SUFFIX 7131Define this macro to a C string constant containing the name of the program 7132which lists dynamic dependencies, like @command{"ldd"} under SunOS 4. 7133 7134@findex PARSE_LDD_OUTPUT 7135@item PARSE_LDD_OUTPUT (@var{ptr}) 7136Define this macro to be C code that extracts filenames from the output 7137of the program denoted by @code{LDD_SUFFIX}. @var{ptr} is a variable 7138of type @code{char *} that points to the beginning of a line of output 7139from @code{LDD_SUFFIX}. If the line lists a dynamic dependency, the 7140code must advance @var{ptr} to the beginning of the filename on that 7141line. Otherwise, it must set @var{ptr} to @code{NULL}. 7142@end table 7143 7144@node Instruction Output 7145@subsection Output of Assembler Instructions 7146 7147@c prevent bad page break with this line 7148This describes assembler instruction output. 7149 7150@table @code 7151@findex REGISTER_NAMES 7152@item REGISTER_NAMES 7153A C initializer containing the assembler's names for the machine 7154registers, each one as a C string constant. This is what translates 7155register numbers in the compiler into assembler language. 7156 7157@findex ADDITIONAL_REGISTER_NAMES 7158@item ADDITIONAL_REGISTER_NAMES 7159If defined, a C initializer for an array of structures containing a name 7160and a register number. This macro defines additional names for hard 7161registers, thus allowing the @code{asm} option in declarations to refer 7162to registers using alternate names. 7163 7164@findex ASM_OUTPUT_OPCODE 7165@item ASM_OUTPUT_OPCODE (@var{stream}, @var{ptr}) 7166Define this macro if you are using an unusual assembler that 7167requires different names for the machine instructions. 7168 7169The definition is a C statement or statements which output an 7170assembler instruction opcode to the stdio stream @var{stream}. The 7171macro-operand @var{ptr} is a variable of type @code{char *} which 7172points to the opcode name in its ``internal'' form---the form that is 7173written in the machine description. The definition should output the 7174opcode name to @var{stream}, performing any translation you desire, and 7175increment the variable @var{ptr} to point at the end of the opcode 7176so that it will not be output twice. 7177 7178In fact, your macro definition may process less than the entire opcode 7179name, or more than the opcode name; but if you want to process text 7180that includes @samp{%}-sequences to substitute operands, you must take 7181care of the substitution yourself. Just be sure to increment 7182@var{ptr} over whatever text should not be output normally. 7183 7184@findex recog_data.operand 7185If you need to look at the operand values, they can be found as the 7186elements of @code{recog_data.operand}. 7187 7188If the macro definition does nothing, the instruction is output 7189in the usual way. 7190 7191@findex FINAL_PRESCAN_INSN 7192@item FINAL_PRESCAN_INSN (@var{insn}, @var{opvec}, @var{noperands}) 7193If defined, a C statement to be executed just prior to the output of 7194assembler code for @var{insn}, to modify the extracted operands so 7195they will be output differently. 7196 7197Here the argument @var{opvec} is the vector containing the operands 7198extracted from @var{insn}, and @var{noperands} is the number of 7199elements of the vector which contain meaningful data for this insn. 7200The contents of this vector are what will be used to convert the insn 7201template into assembler code, so you can change the assembler output 7202by changing the contents of the vector. 7203 7204This macro is useful when various assembler syntaxes share a single 7205file of instruction patterns; by defining this macro differently, you 7206can cause a large class of instructions to be output differently (such 7207as with rearranged operands). Naturally, variations in assembler 7208syntax affecting individual insn patterns ought to be handled by 7209writing conditional output routines in those patterns. 7210 7211If this macro is not defined, it is equivalent to a null statement. 7212 7213@findex FINAL_PRESCAN_LABEL 7214@item FINAL_PRESCAN_LABEL 7215If defined, @code{FINAL_PRESCAN_INSN} will be called on each 7216@code{CODE_LABEL}. In that case, @var{opvec} will be a null pointer and 7217@var{noperands} will be zero. 7218 7219@findex PRINT_OPERAND 7220@item PRINT_OPERAND (@var{stream}, @var{x}, @var{code}) 7221A C compound statement to output to stdio stream @var{stream} the 7222assembler syntax for an instruction operand @var{x}. @var{x} is an 7223RTL expression. 7224 7225@var{code} is a value that can be used to specify one of several ways 7226of printing the operand. It is used when identical operands must be 7227printed differently depending on the context. @var{code} comes from 7228the @samp{%} specification that was used to request printing of the 7229operand. If the specification was just @samp{%@var{digit}} then 7230@var{code} is 0; if the specification was @samp{%@var{ltr} 7231@var{digit}} then @var{code} is the ASCII code for @var{ltr}. 7232 7233@findex reg_names 7234If @var{x} is a register, this macro should print the register's name. 7235The names can be found in an array @code{reg_names} whose type is 7236@code{char *[]}. @code{reg_names} is initialized from 7237@code{REGISTER_NAMES}. 7238 7239When the machine description has a specification @samp{%@var{punct}} 7240(a @samp{%} followed by a punctuation character), this macro is called 7241with a null pointer for @var{x} and the punctuation character for 7242@var{code}. 7243 7244@findex PRINT_OPERAND_PUNCT_VALID_P 7245@item PRINT_OPERAND_PUNCT_VALID_P (@var{code}) 7246A C expression which evaluates to true if @var{code} is a valid 7247punctuation character for use in the @code{PRINT_OPERAND} macro. If 7248@code{PRINT_OPERAND_PUNCT_VALID_P} is not defined, it means that no 7249punctuation characters (except for the standard one, @samp{%}) are used 7250in this way. 7251 7252@findex PRINT_OPERAND_ADDRESS 7253@item PRINT_OPERAND_ADDRESS (@var{stream}, @var{x}) 7254A C compound statement to output to stdio stream @var{stream} the 7255assembler syntax for an instruction operand that is a memory reference 7256whose address is @var{x}. @var{x} is an RTL expression. 7257 7258@cindex @code{TARGET_ENCODE_SECTION_INFO} usage 7259On some machines, the syntax for a symbolic address depends on the 7260section that the address refers to. On these machines, define the hook 7261@code{TARGET_ENCODE_SECTION_INFO} to store the information into the 7262@code{symbol_ref}, and then check for it here. @xref{Assembler Format}. 7263 7264@findex DBR_OUTPUT_SEQEND 7265@findex dbr_sequence_length 7266@item DBR_OUTPUT_SEQEND(@var{file}) 7267A C statement, to be executed after all slot-filler instructions have 7268been output. If necessary, call @code{dbr_sequence_length} to 7269determine the number of slots filled in a sequence (zero if not 7270currently outputting a sequence), to decide how many no-ops to output, 7271or whatever. 7272 7273Don't define this macro if it has nothing to do, but it is helpful in 7274reading assembly output if the extent of the delay sequence is made 7275explicit (e.g.@: with white space). 7276 7277@findex final_sequence 7278Note that output routines for instructions with delay slots must be 7279prepared to deal with not being output as part of a sequence 7280(i.e.@: when the scheduling pass is not run, or when no slot fillers could be 7281found.) The variable @code{final_sequence} is null when not 7282processing a sequence, otherwise it contains the @code{sequence} rtx 7283being output. 7284 7285@findex REGISTER_PREFIX 7286@findex LOCAL_LABEL_PREFIX 7287@findex USER_LABEL_PREFIX 7288@findex IMMEDIATE_PREFIX 7289@findex asm_fprintf 7290@item REGISTER_PREFIX 7291@itemx LOCAL_LABEL_PREFIX 7292@itemx USER_LABEL_PREFIX 7293@itemx IMMEDIATE_PREFIX 7294If defined, C string expressions to be used for the @samp{%R}, @samp{%L}, 7295@samp{%U}, and @samp{%I} options of @code{asm_fprintf} (see 7296@file{final.c}). These are useful when a single @file{md} file must 7297support multiple assembler formats. In that case, the various @file{tm.h} 7298files can define these macros differently. 7299 7300@item ASM_FPRINTF_EXTENSIONS(@var{file}, @var{argptr}, @var{format}) 7301@findex ASM_FPRINTF_EXTENSIONS 7302If defined this macro should expand to a series of @code{case} 7303statements which will be parsed inside the @code{switch} statement of 7304the @code{asm_fprintf} function. This allows targets to define extra 7305printf formats which may useful when generating their assembler 7306statements. Note that upper case letters are reserved for future 7307generic extensions to asm_fprintf, and so are not available to target 7308specific code. The output file is given by the parameter @var{file}. 7309The varargs input pointer is @var{argptr} and the rest of the format 7310string, starting the character after the one that is being switched 7311upon, is pointed to by @var{format}. 7312 7313@findex ASSEMBLER_DIALECT 7314@item ASSEMBLER_DIALECT 7315If your target supports multiple dialects of assembler language (such as 7316different opcodes), define this macro as a C expression that gives the 7317numeric index of the assembler language dialect to use, with zero as the 7318first variant. 7319 7320If this macro is defined, you may use constructs of the form 7321@smallexample 7322@samp{@{option0|option1|option2@dots{}@}} 7323@end smallexample 7324@noindent 7325in the output templates of patterns (@pxref{Output Template}) or in the 7326first argument of @code{asm_fprintf}. This construct outputs 7327@samp{option0}, @samp{option1}, @samp{option2}, etc., if the value of 7328@code{ASSEMBLER_DIALECT} is zero, one, two, etc. Any special characters 7329within these strings retain their usual meaning. If there are fewer 7330alternatives within the braces than the value of 7331@code{ASSEMBLER_DIALECT}, the construct outputs nothing. 7332 7333If you do not define this macro, the characters @samp{@{}, @samp{|} and 7334@samp{@}} do not have any special meaning when used in templates or 7335operands to @code{asm_fprintf}. 7336 7337Define the macros @code{REGISTER_PREFIX}, @code{LOCAL_LABEL_PREFIX}, 7338@code{USER_LABEL_PREFIX} and @code{IMMEDIATE_PREFIX} if you can express 7339the variations in assembler language syntax with that mechanism. Define 7340@code{ASSEMBLER_DIALECT} and use the @samp{@{option0|option1@}} syntax 7341if the syntax variant are larger and involve such things as different 7342opcodes or operand order. 7343 7344@findex ASM_OUTPUT_REG_PUSH 7345@item ASM_OUTPUT_REG_PUSH (@var{stream}, @var{regno}) 7346A C expression to output to @var{stream} some assembler code 7347which will push hard register number @var{regno} onto the stack. 7348The code need not be optimal, since this macro is used only when 7349profiling. 7350 7351@findex ASM_OUTPUT_REG_POP 7352@item ASM_OUTPUT_REG_POP (@var{stream}, @var{regno}) 7353A C expression to output to @var{stream} some assembler code 7354which will pop hard register number @var{regno} off of the stack. 7355The code need not be optimal, since this macro is used only when 7356profiling. 7357@end table 7358 7359@node Dispatch Tables 7360@subsection Output of Dispatch Tables 7361 7362@c prevent bad page break with this line 7363This concerns dispatch tables. 7364 7365@table @code 7366@cindex dispatch table 7367@findex ASM_OUTPUT_ADDR_DIFF_ELT 7368@item ASM_OUTPUT_ADDR_DIFF_ELT (@var{stream}, @var{body}, @var{value}, @var{rel}) 7369A C statement to output to the stdio stream @var{stream} an assembler 7370pseudo-instruction to generate a difference between two labels. 7371@var{value} and @var{rel} are the numbers of two internal labels. The 7372definitions of these labels are output using 7373@code{ASM_OUTPUT_INTERNAL_LABEL}, and they must be printed in the same 7374way here. For example, 7375 7376@example 7377fprintf (@var{stream}, "\t.word L%d-L%d\n", 7378 @var{value}, @var{rel}) 7379@end example 7380 7381You must provide this macro on machines where the addresses in a 7382dispatch table are relative to the table's own address. If defined, GCC 7383will also use this macro on all machines when producing PIC@. 7384@var{body} is the body of the @code{ADDR_DIFF_VEC}; it is provided so that the 7385mode and flags can be read. 7386 7387@findex ASM_OUTPUT_ADDR_VEC_ELT 7388@item ASM_OUTPUT_ADDR_VEC_ELT (@var{stream}, @var{value}) 7389This macro should be provided on machines where the addresses 7390in a dispatch table are absolute. 7391 7392The definition should be a C statement to output to the stdio stream 7393@var{stream} an assembler pseudo-instruction to generate a reference to 7394a label. @var{value} is the number of an internal label whose 7395definition is output using @code{ASM_OUTPUT_INTERNAL_LABEL}. 7396For example, 7397 7398@example 7399fprintf (@var{stream}, "\t.word L%d\n", @var{value}) 7400@end example 7401 7402@findex ASM_OUTPUT_CASE_LABEL 7403@item ASM_OUTPUT_CASE_LABEL (@var{stream}, @var{prefix}, @var{num}, @var{table}) 7404Define this if the label before a jump-table needs to be output 7405specially. The first three arguments are the same as for 7406@code{ASM_OUTPUT_INTERNAL_LABEL}; the fourth argument is the 7407jump-table which follows (a @code{jump_insn} containing an 7408@code{addr_vec} or @code{addr_diff_vec}). 7409 7410This feature is used on system V to output a @code{swbeg} statement 7411for the table. 7412 7413If this macro is not defined, these labels are output with 7414@code{ASM_OUTPUT_INTERNAL_LABEL}. 7415 7416@findex ASM_OUTPUT_CASE_END 7417@item ASM_OUTPUT_CASE_END (@var{stream}, @var{num}, @var{table}) 7418Define this if something special must be output at the end of a 7419jump-table. The definition should be a C statement to be executed 7420after the assembler code for the table is written. It should write 7421the appropriate code to stdio stream @var{stream}. The argument 7422@var{table} is the jump-table insn, and @var{num} is the label-number 7423of the preceding label. 7424 7425If this macro is not defined, nothing special is output at the end of 7426the jump-table. 7427@end table 7428 7429@node Exception Region Output 7430@subsection Assembler Commands for Exception Regions 7431 7432@c prevent bad page break with this line 7433 7434This describes commands marking the start and the end of an exception 7435region. 7436 7437@table @code 7438@findex EH_FRAME_SECTION_NAME 7439@item EH_FRAME_SECTION_NAME 7440If defined, a C string constant for the name of the section containing 7441exception handling frame unwind information. If not defined, GCC will 7442provide a default definition if the target supports named sections. 7443@file{crtstuff.c} uses this macro to switch to the appropriate section. 7444 7445You should define this symbol if your target supports DWARF 2 frame 7446unwind information and the default definition does not work. 7447 7448@findex EH_FRAME_IN_DATA_SECTION 7449@item EH_FRAME_IN_DATA_SECTION 7450If defined, DWARF 2 frame unwind information will be placed in the 7451data section even though the target supports named sections. This 7452might be necessary, for instance, if the system linker does garbage 7453collection and sections cannot be marked as not to be collected. 7454 7455Do not define this macro unless @code{TARGET_ASM_NAMED_SECTION} is 7456also defined. 7457 7458@findex MASK_RETURN_ADDR 7459@item MASK_RETURN_ADDR 7460An rtx used to mask the return address found via @code{RETURN_ADDR_RTX}, so 7461that it does not contain any extraneous set bits in it. 7462 7463@findex DWARF2_UNWIND_INFO 7464@item DWARF2_UNWIND_INFO 7465Define this macro to 0 if your target supports DWARF 2 frame unwind 7466information, but it does not yet work with exception handling. 7467Otherwise, if your target supports this information (if it defines 7468@samp{INCOMING_RETURN_ADDR_RTX} and either @samp{UNALIGNED_INT_ASM_OP} 7469or @samp{OBJECT_FORMAT_ELF}), GCC will provide a default definition of 74701. 7471 7472If this macro is defined to 1, the DWARF 2 unwinder will be the default 7473exception handling mechanism; otherwise, @code{setjmp}/@code{longjmp} will be used by 7474default. 7475 7476If this macro is defined to anything, the DWARF 2 unwinder will be used 7477instead of inline unwinders and @code{__unwind_function} in the non-@code{setjmp} case. 7478 7479@findex DWARF_CIE_DATA_ALIGNMENT 7480@item DWARF_CIE_DATA_ALIGNMENT 7481This macro need only be defined if the target might save registers in the 7482function prologue at an offset to the stack pointer that is not aligned to 7483@code{UNITS_PER_WORD}. The definition should be the negative minimum 7484alignment if @code{STACK_GROWS_DOWNWARD} is defined, and the positive 7485minimum alignment otherwise. @xref{SDB and DWARF}. Only applicable if 7486the target supports DWARF 2 frame unwind information. 7487 7488@end table 7489 7490@deftypefn {Target Hook} void TARGET_ASM_EXCEPTION_SECTION () 7491If defined, a function that switches to the section in which the main 7492exception table is to be placed (@pxref{Sections}). The default is a 7493function that switches to a section named @code{.gcc_except_table} on 7494machines that support named sections via 7495@code{TARGET_ASM_NAMED_SECTION}, otherwise if @option{-fpic} or 7496@option{-fPIC} is in effect, the @code{data_section}, otherwise the 7497@code{readonly_data_section}. 7498@end deftypefn 7499 7500@deftypefn {Target Hook} void TARGET_ASM_EH_FRAME_SECTION () 7501If defined, a function that switches to the section in which the DWARF 2 7502frame unwind information to be placed (@pxref{Sections}). The default 7503is a function that outputs a standard GAS section directive, if 7504@code{EH_FRAME_SECTION_NAME} is defined, or else a data section 7505directive followed by a synthetic label. 7506@end deftypefn 7507 7508@deftypevar {Target Hook} bool TARGET_TERMINATE_DW2_EH_FRAME_INFO 7509Contains the value true if the target should add a zero word onto the 7510end of a Dwarf-2 frame info section when used for exception handling. 7511Default value is false if @code{EH_FRAME_SECTION_NAME} is defined, and 7512true otherwise. 7513@end deftypevar 7514 7515@node Alignment Output 7516@subsection Assembler Commands for Alignment 7517 7518@c prevent bad page break with this line 7519This describes commands for alignment. 7520 7521@table @code 7522@findex JUMP_ALIGN 7523@item JUMP_ALIGN (@var{label}) 7524The alignment (log base 2) to put in front of @var{label}, which is 7525a common destination of jumps and has no fallthru incoming edge. 7526 7527This macro need not be defined if you don't want any special alignment 7528to be done at such a time. Most machine descriptions do not currently 7529define the macro. 7530 7531Unless it's necessary to inspect the @var{label} parameter, it is better 7532to set the variable @var{align_jumps} in the target's 7533@code{OVERRIDE_OPTIONS}. Otherwise, you should try to honor the user's 7534selection in @var{align_jumps} in a @code{JUMP_ALIGN} implementation. 7535 7536@findex LABEL_ALIGN_AFTER_BARRIER 7537@item LABEL_ALIGN_AFTER_BARRIER (@var{label}) 7538The alignment (log base 2) to put in front of @var{label}, which follows 7539a @code{BARRIER}. 7540 7541This macro need not be defined if you don't want any special alignment 7542to be done at such a time. Most machine descriptions do not currently 7543define the macro. 7544 7545@findex LABEL_ALIGN_AFTER_BARRIER_MAX_SKIP 7546@item LABEL_ALIGN_AFTER_BARRIER_MAX_SKIP 7547The maximum number of bytes to skip when applying 7548@code{LABEL_ALIGN_AFTER_BARRIER}. This works only if 7549@code{ASM_OUTPUT_MAX_SKIP_ALIGN} is defined. 7550 7551@findex LOOP_ALIGN 7552@item LOOP_ALIGN (@var{label}) 7553The alignment (log base 2) to put in front of @var{label}, which follows 7554a @code{NOTE_INSN_LOOP_BEG} note. 7555 7556This macro need not be defined if you don't want any special alignment 7557to be done at such a time. Most machine descriptions do not currently 7558define the macro. 7559 7560Unless it's necessary to inspect the @var{label} parameter, it is better 7561to set the variable @code{align_loops} in the target's 7562@code{OVERRIDE_OPTIONS}. Otherwise, you should try to honor the user's 7563selection in @code{align_loops} in a @code{LOOP_ALIGN} implementation. 7564 7565@findex LOOP_ALIGN_MAX_SKIP 7566@item LOOP_ALIGN_MAX_SKIP 7567The maximum number of bytes to skip when applying @code{LOOP_ALIGN}. 7568This works only if @code{ASM_OUTPUT_MAX_SKIP_ALIGN} is defined. 7569 7570@findex LABEL_ALIGN 7571@item LABEL_ALIGN (@var{label}) 7572The alignment (log base 2) to put in front of @var{label}. 7573If @code{LABEL_ALIGN_AFTER_BARRIER} / @code{LOOP_ALIGN} specify a different alignment, 7574the maximum of the specified values is used. 7575 7576Unless it's necessary to inspect the @var{label} parameter, it is better 7577to set the variable @code{align_labels} in the target's 7578@code{OVERRIDE_OPTIONS}. Otherwise, you should try to honor the user's 7579selection in @code{align_labels} in a @code{LABEL_ALIGN} implementation. 7580 7581@findex LABEL_ALIGN_MAX_SKIP 7582@item LABEL_ALIGN_MAX_SKIP 7583The maximum number of bytes to skip when applying @code{LABEL_ALIGN}. 7584This works only if @code{ASM_OUTPUT_MAX_SKIP_ALIGN} is defined. 7585 7586@findex ASM_OUTPUT_SKIP 7587@item ASM_OUTPUT_SKIP (@var{stream}, @var{nbytes}) 7588A C statement to output to the stdio stream @var{stream} an assembler 7589instruction to advance the location counter by @var{nbytes} bytes. 7590Those bytes should be zero when loaded. @var{nbytes} will be a C 7591expression of type @code{int}. 7592 7593@findex ASM_NO_SKIP_IN_TEXT 7594@item ASM_NO_SKIP_IN_TEXT 7595Define this macro if @code{ASM_OUTPUT_SKIP} should not be used in the 7596text section because it fails to put zeros in the bytes that are skipped. 7597This is true on many Unix systems, where the pseudo--op to skip bytes 7598produces no-op instructions rather than zeros when used in the text 7599section. 7600 7601@findex ASM_OUTPUT_ALIGN 7602@item ASM_OUTPUT_ALIGN (@var{stream}, @var{power}) 7603A C statement to output to the stdio stream @var{stream} an assembler 7604command to advance the location counter to a multiple of 2 to the 7605@var{power} bytes. @var{power} will be a C expression of type @code{int}. 7606 7607@findex ASM_OUTPUT_ALIGN_WITH_NOP 7608@item ASM_OUTPUT_ALIGN_WITH_NOP (@var{stream}, @var{power}) 7609Like @code{ASM_OUTPUT_ALIGN}, except that the ``nop'' instruction is used 7610for padding, if necessary. 7611 7612@findex ASM_OUTPUT_MAX_SKIP_ALIGN 7613@item ASM_OUTPUT_MAX_SKIP_ALIGN (@var{stream}, @var{power}, @var{max_skip}) 7614A C statement to output to the stdio stream @var{stream} an assembler 7615command to advance the location counter to a multiple of 2 to the 7616@var{power} bytes, but only if @var{max_skip} or fewer bytes are needed to 7617satisfy the alignment request. @var{power} and @var{max_skip} will be 7618a C expression of type @code{int}. 7619@end table 7620 7621@need 3000 7622@node Debugging Info 7623@section Controlling Debugging Information Format 7624 7625@c prevent bad page break with this line 7626This describes how to specify debugging information. 7627 7628@menu 7629* All Debuggers:: Macros that affect all debugging formats uniformly. 7630* DBX Options:: Macros enabling specific options in DBX format. 7631* DBX Hooks:: Hook macros for varying DBX format. 7632* File Names and DBX:: Macros controlling output of file names in DBX format. 7633* SDB and DWARF:: Macros for SDB (COFF) and DWARF formats. 7634* VMS Debug:: Macros for VMS debug format. 7635@end menu 7636 7637@node All Debuggers 7638@subsection Macros Affecting All Debugging Formats 7639 7640@c prevent bad page break with this line 7641These macros affect all debugging formats. 7642 7643@table @code 7644@findex DBX_REGISTER_NUMBER 7645@item DBX_REGISTER_NUMBER (@var{regno}) 7646A C expression that returns the DBX register number for the compiler 7647register number @var{regno}. In the default macro provided, the value 7648of this expression will be @var{regno} itself. But sometimes there are 7649some registers that the compiler knows about and DBX does not, or vice 7650versa. In such cases, some register may need to have one number in the 7651compiler and another for DBX@. 7652 7653If two registers have consecutive numbers inside GCC, and they can be 7654used as a pair to hold a multiword value, then they @emph{must} have 7655consecutive numbers after renumbering with @code{DBX_REGISTER_NUMBER}. 7656Otherwise, debuggers will be unable to access such a pair, because they 7657expect register pairs to be consecutive in their own numbering scheme. 7658 7659If you find yourself defining @code{DBX_REGISTER_NUMBER} in way that 7660does not preserve register pairs, then what you must do instead is 7661redefine the actual register numbering scheme. 7662 7663@findex DEBUGGER_AUTO_OFFSET 7664@item DEBUGGER_AUTO_OFFSET (@var{x}) 7665A C expression that returns the integer offset value for an automatic 7666variable having address @var{x} (an RTL expression). The default 7667computation assumes that @var{x} is based on the frame-pointer and 7668gives the offset from the frame-pointer. This is required for targets 7669that produce debugging output for DBX or COFF-style debugging output 7670for SDB and allow the frame-pointer to be eliminated when the 7671@option{-g} options is used. 7672 7673@findex DEBUGGER_ARG_OFFSET 7674@item DEBUGGER_ARG_OFFSET (@var{offset}, @var{x}) 7675A C expression that returns the integer offset value for an argument 7676having address @var{x} (an RTL expression). The nominal offset is 7677@var{offset}. 7678 7679@findex PREFERRED_DEBUGGING_TYPE 7680@item PREFERRED_DEBUGGING_TYPE 7681A C expression that returns the type of debugging output GCC should 7682produce when the user specifies just @option{-g}. Define 7683this if you have arranged for GCC to support more than one format of 7684debugging output. Currently, the allowable values are @code{DBX_DEBUG}, 7685@code{SDB_DEBUG}, @code{DWARF_DEBUG}, @code{DWARF2_DEBUG}, 7686@code{XCOFF_DEBUG}, @code{VMS_DEBUG}, and @code{VMS_AND_DWARF2_DEBUG}. 7687 7688When the user specifies @option{-ggdb}, GCC normally also uses the 7689value of this macro to select the debugging output format, but with two 7690exceptions. If @code{DWARF2_DEBUGGING_INFO} is defined and 7691@code{LINKER_DOES_NOT_WORK_WITH_DWARF2} is not defined, GCC uses the 7692value @code{DWARF2_DEBUG}. Otherwise, if @code{DBX_DEBUGGING_INFO} is 7693defined, GCC uses @code{DBX_DEBUG}. 7694 7695The value of this macro only affects the default debugging output; the 7696user can always get a specific type of output by using @option{-gstabs}, 7697@option{-gcoff}, @option{-gdwarf-1}, @option{-gdwarf-2}, @option{-gxcoff}, 7698or @option{-gvms}. 7699@end table 7700 7701@node DBX Options 7702@subsection Specific Options for DBX Output 7703 7704@c prevent bad page break with this line 7705These are specific options for DBX output. 7706 7707@table @code 7708@findex DBX_DEBUGGING_INFO 7709@item DBX_DEBUGGING_INFO 7710Define this macro if GCC should produce debugging output for DBX 7711in response to the @option{-g} option. 7712 7713@findex XCOFF_DEBUGGING_INFO 7714@item XCOFF_DEBUGGING_INFO 7715Define this macro if GCC should produce XCOFF format debugging output 7716in response to the @option{-g} option. This is a variant of DBX format. 7717 7718@findex DEFAULT_GDB_EXTENSIONS 7719@item DEFAULT_GDB_EXTENSIONS 7720Define this macro to control whether GCC should by default generate 7721GDB's extended version of DBX debugging information (assuming DBX-format 7722debugging information is enabled at all). If you don't define the 7723macro, the default is 1: always generate the extended information 7724if there is any occasion to. 7725 7726@findex DEBUG_SYMS_TEXT 7727@item DEBUG_SYMS_TEXT 7728Define this macro if all @code{.stabs} commands should be output while 7729in the text section. 7730 7731@findex ASM_STABS_OP 7732@item ASM_STABS_OP 7733A C string constant, including spacing, naming the assembler pseudo op to 7734use instead of @code{"\t.stabs\t"} to define an ordinary debugging symbol. 7735If you don't define this macro, @code{"\t.stabs\t"} is used. This macro 7736applies only to DBX debugging information format. 7737 7738@findex ASM_STABD_OP 7739@item ASM_STABD_OP 7740A C string constant, including spacing, naming the assembler pseudo op to 7741use instead of @code{"\t.stabd\t"} to define a debugging symbol whose 7742value is the current location. If you don't define this macro, 7743@code{"\t.stabd\t"} is used. This macro applies only to DBX debugging 7744information format. 7745 7746@findex ASM_STABN_OP 7747@item ASM_STABN_OP 7748A C string constant, including spacing, naming the assembler pseudo op to 7749use instead of @code{"\t.stabn\t"} to define a debugging symbol with no 7750name. If you don't define this macro, @code{"\t.stabn\t"} is used. This 7751macro applies only to DBX debugging information format. 7752 7753@findex DBX_NO_XREFS 7754@item DBX_NO_XREFS 7755Define this macro if DBX on your system does not support the construct 7756@samp{xs@var{tagname}}. On some systems, this construct is used to 7757describe a forward reference to a structure named @var{tagname}. 7758On other systems, this construct is not supported at all. 7759 7760@findex DBX_CONTIN_LENGTH 7761@item DBX_CONTIN_LENGTH 7762A symbol name in DBX-format debugging information is normally 7763continued (split into two separate @code{.stabs} directives) when it 7764exceeds a certain length (by default, 80 characters). On some 7765operating systems, DBX requires this splitting; on others, splitting 7766must not be done. You can inhibit splitting by defining this macro 7767with the value zero. You can override the default splitting-length by 7768defining this macro as an expression for the length you desire. 7769 7770@findex DBX_CONTIN_CHAR 7771@item DBX_CONTIN_CHAR 7772Normally continuation is indicated by adding a @samp{\} character to 7773the end of a @code{.stabs} string when a continuation follows. To use 7774a different character instead, define this macro as a character 7775constant for the character you want to use. Do not define this macro 7776if backslash is correct for your system. 7777 7778@findex DBX_STATIC_STAB_DATA_SECTION 7779@item DBX_STATIC_STAB_DATA_SECTION 7780Define this macro if it is necessary to go to the data section before 7781outputting the @samp{.stabs} pseudo-op for a non-global static 7782variable. 7783 7784@findex DBX_TYPE_DECL_STABS_CODE 7785@item DBX_TYPE_DECL_STABS_CODE 7786The value to use in the ``code'' field of the @code{.stabs} directive 7787for a typedef. The default is @code{N_LSYM}. 7788 7789@findex DBX_STATIC_CONST_VAR_CODE 7790@item DBX_STATIC_CONST_VAR_CODE 7791The value to use in the ``code'' field of the @code{.stabs} directive 7792for a static variable located in the text section. DBX format does not 7793provide any ``right'' way to do this. The default is @code{N_FUN}. 7794 7795@findex DBX_REGPARM_STABS_CODE 7796@item DBX_REGPARM_STABS_CODE 7797The value to use in the ``code'' field of the @code{.stabs} directive 7798for a parameter passed in registers. DBX format does not provide any 7799``right'' way to do this. The default is @code{N_RSYM}. 7800 7801@findex DBX_REGPARM_STABS_LETTER 7802@item DBX_REGPARM_STABS_LETTER 7803The letter to use in DBX symbol data to identify a symbol as a parameter 7804passed in registers. DBX format does not customarily provide any way to 7805do this. The default is @code{'P'}. 7806 7807@findex DBX_MEMPARM_STABS_LETTER 7808@item DBX_MEMPARM_STABS_LETTER 7809The letter to use in DBX symbol data to identify a symbol as a stack 7810parameter. The default is @code{'p'}. 7811 7812@findex DBX_FUNCTION_FIRST 7813@item DBX_FUNCTION_FIRST 7814Define this macro if the DBX information for a function and its 7815arguments should precede the assembler code for the function. Normally, 7816in DBX format, the debugging information entirely follows the assembler 7817code. 7818 7819@findex DBX_LBRAC_FIRST 7820@item DBX_LBRAC_FIRST 7821Define this macro if the @code{N_LBRAC} symbol for a block should 7822precede the debugging information for variables and functions defined in 7823that block. Normally, in DBX format, the @code{N_LBRAC} symbol comes 7824first. 7825 7826@findex DBX_BLOCKS_FUNCTION_RELATIVE 7827@item DBX_BLOCKS_FUNCTION_RELATIVE 7828Define this macro if the value of a symbol describing the scope of a 7829block (@code{N_LBRAC} or @code{N_RBRAC}) should be relative to the start 7830of the enclosing function. Normally, GCC uses an absolute address. 7831 7832@findex DBX_USE_BINCL 7833@item DBX_USE_BINCL 7834Define this macro if GCC should generate @code{N_BINCL} and 7835@code{N_EINCL} stabs for included header files, as on Sun systems. This 7836macro also directs GCC to output a type number as a pair of a file 7837number and a type number within the file. Normally, GCC does not 7838generate @code{N_BINCL} or @code{N_EINCL} stabs, and it outputs a single 7839number for a type number. 7840@end table 7841 7842@node DBX Hooks 7843@subsection Open-Ended Hooks for DBX Format 7844 7845@c prevent bad page break with this line 7846These are hooks for DBX format. 7847 7848@table @code 7849@findex DBX_OUTPUT_LBRAC 7850@item DBX_OUTPUT_LBRAC (@var{stream}, @var{name}) 7851Define this macro to say how to output to @var{stream} the debugging 7852information for the start of a scope level for variable names. The 7853argument @var{name} is the name of an assembler symbol (for use with 7854@code{assemble_name}) whose value is the address where the scope begins. 7855 7856@findex DBX_OUTPUT_RBRAC 7857@item DBX_OUTPUT_RBRAC (@var{stream}, @var{name}) 7858Like @code{DBX_OUTPUT_LBRAC}, but for the end of a scope level. 7859 7860@findex DBX_OUTPUT_NFUN 7861@item DBX_OUTPUT_NFUN (@var{stream}, @var{lscope_label}, @var{decl}) 7862Define this macro if the target machine requires special handling to 7863output an @code{N_FUN} entry for the function @var{decl}. 7864 7865@findex DBX_OUTPUT_ENUM 7866@item DBX_OUTPUT_ENUM (@var{stream}, @var{type}) 7867Define this macro if the target machine requires special handling to 7868output an enumeration type. The definition should be a C statement 7869(sans semicolon) to output the appropriate information to @var{stream} 7870for the type @var{type}. 7871 7872@findex DBX_OUTPUT_FUNCTION_END 7873@item DBX_OUTPUT_FUNCTION_END (@var{stream}, @var{function}) 7874Define this macro if the target machine requires special output at the 7875end of the debugging information for a function. The definition should 7876be a C statement (sans semicolon) to output the appropriate information 7877to @var{stream}. @var{function} is the @code{FUNCTION_DECL} node for 7878the function. 7879 7880@findex DBX_OUTPUT_STANDARD_TYPES 7881@item DBX_OUTPUT_STANDARD_TYPES (@var{syms}) 7882Define this macro if you need to control the order of output of the 7883standard data types at the beginning of compilation. The argument 7884@var{syms} is a @code{tree} which is a chain of all the predefined 7885global symbols, including names of data types. 7886 7887Normally, DBX output starts with definitions of the types for integers 7888and characters, followed by all the other predefined types of the 7889particular language in no particular order. 7890 7891On some machines, it is necessary to output different particular types 7892first. To do this, define @code{DBX_OUTPUT_STANDARD_TYPES} to output 7893those symbols in the necessary order. Any predefined types that you 7894don't explicitly output will be output afterward in no particular order. 7895 7896Be careful not to define this macro so that it works only for C@. There 7897are no global variables to access most of the built-in types, because 7898another language may have another set of types. The way to output a 7899particular type is to look through @var{syms} to see if you can find it. 7900Here is an example: 7901 7902@smallexample 7903@{ 7904 tree decl; 7905 for (decl = syms; decl; decl = TREE_CHAIN (decl)) 7906 if (!strcmp (IDENTIFIER_POINTER (DECL_NAME (decl)), 7907 "long int")) 7908 dbxout_symbol (decl); 7909 @dots{} 7910@} 7911@end smallexample 7912 7913@noindent 7914This does nothing if the expected type does not exist. 7915 7916See the function @code{init_decl_processing} in @file{c-decl.c} to find 7917the names to use for all the built-in C types. 7918 7919Here is another way of finding a particular type: 7920 7921@c this is still overfull. --mew 10feb93 7922@smallexample 7923@{ 7924 tree decl; 7925 for (decl = syms; decl; decl = TREE_CHAIN (decl)) 7926 if (TREE_CODE (decl) == TYPE_DECL 7927 && (TREE_CODE (TREE_TYPE (decl)) 7928 == INTEGER_CST) 7929 && TYPE_PRECISION (TREE_TYPE (decl)) == 16 7930 && TYPE_UNSIGNED (TREE_TYPE (decl))) 7931@group 7932 /* @r{This must be @code{unsigned short}.} */ 7933 dbxout_symbol (decl); 7934 @dots{} 7935@} 7936@end group 7937@end smallexample 7938 7939@findex NO_DBX_FUNCTION_END 7940@item NO_DBX_FUNCTION_END 7941Some stabs encapsulation formats (in particular ECOFF), cannot handle the 7942@code{.stabs "",N_FUN,,0,0,Lscope-function-1} gdb dbx extension construct. 7943On those machines, define this macro to turn this feature off without 7944disturbing the rest of the gdb extensions. 7945 7946@end table 7947 7948@node File Names and DBX 7949@subsection File Names in DBX Format 7950 7951@c prevent bad page break with this line 7952This describes file names in DBX format. 7953 7954@table @code 7955@findex DBX_WORKING_DIRECTORY 7956@item DBX_WORKING_DIRECTORY 7957Define this if DBX wants to have the current directory recorded in each 7958object file. 7959 7960Note that the working directory is always recorded if GDB extensions are 7961enabled. 7962 7963@findex DBX_OUTPUT_MAIN_SOURCE_FILENAME 7964@item DBX_OUTPUT_MAIN_SOURCE_FILENAME (@var{stream}, @var{name}) 7965A C statement to output DBX debugging information to the stdio stream 7966@var{stream} which indicates that file @var{name} is the main source 7967file---the file specified as the input file for compilation. 7968This macro is called only once, at the beginning of compilation. 7969 7970This macro need not be defined if the standard form of output 7971for DBX debugging information is appropriate. 7972 7973@findex DBX_OUTPUT_MAIN_SOURCE_DIRECTORY 7974@item DBX_OUTPUT_MAIN_SOURCE_DIRECTORY (@var{stream}, @var{name}) 7975A C statement to output DBX debugging information to the stdio stream 7976@var{stream} which indicates that the current directory during 7977compilation is named @var{name}. 7978 7979This macro need not be defined if the standard form of output 7980for DBX debugging information is appropriate. 7981 7982@findex DBX_OUTPUT_MAIN_SOURCE_FILE_END 7983@item DBX_OUTPUT_MAIN_SOURCE_FILE_END (@var{stream}, @var{name}) 7984A C statement to output DBX debugging information at the end of 7985compilation of the main source file @var{name}. 7986 7987If you don't define this macro, nothing special is output at the end 7988of compilation, which is correct for most machines. 7989 7990@findex DBX_OUTPUT_SOURCE_FILENAME 7991@item DBX_OUTPUT_SOURCE_FILENAME (@var{stream}, @var{name}) 7992A C statement to output DBX debugging information to the stdio stream 7993@var{stream} which indicates that file @var{name} is the current source 7994file. This output is generated each time input shifts to a different 7995source file as a result of @samp{#include}, the end of an included file, 7996or a @samp{#line} command. 7997 7998This macro need not be defined if the standard form of output 7999for DBX debugging information is appropriate. 8000@end table 8001 8002@need 2000 8003@node SDB and DWARF 8004@subsection Macros for SDB and DWARF Output 8005 8006@c prevent bad page break with this line 8007Here are macros for SDB and DWARF output. 8008 8009@table @code 8010@findex SDB_DEBUGGING_INFO 8011@item SDB_DEBUGGING_INFO 8012Define this macro if GCC should produce COFF-style debugging output 8013for SDB in response to the @option{-g} option. 8014 8015@findex DWARF_DEBUGGING_INFO 8016@item DWARF_DEBUGGING_INFO 8017Define this macro if GCC should produce dwarf format debugging output 8018in response to the @option{-g} option. 8019 8020@findex DWARF2_DEBUGGING_INFO 8021@item DWARF2_DEBUGGING_INFO 8022Define this macro if GCC should produce dwarf version 2 format 8023debugging output in response to the @option{-g} option. 8024 8025To support optional call frame debugging information, you must also 8026define @code{INCOMING_RETURN_ADDR_RTX} and either set 8027@code{RTX_FRAME_RELATED_P} on the prologue insns if you use RTL for the 8028prologue, or call @code{dwarf2out_def_cfa} and @code{dwarf2out_reg_save} 8029as appropriate from @code{TARGET_ASM_FUNCTION_PROLOGUE} if you don't. 8030 8031@findex DWARF2_FRAME_INFO 8032@item DWARF2_FRAME_INFO 8033Define this macro to a nonzero value if GCC should always output 8034Dwarf 2 frame information. If @code{DWARF2_UNWIND_INFO} 8035(@pxref{Exception Region Output} is nonzero, GCC will output this 8036information not matter how you define @code{DWARF2_FRAME_INFO}. 8037 8038@findex LINKER_DOES_NOT_WORK_WITH_DWARF2 8039@item LINKER_DOES_NOT_WORK_WITH_DWARF2 8040Define this macro if the linker does not work with Dwarf version 2. 8041Normally, if the user specifies only @option{-ggdb} GCC will use Dwarf 8042version 2 if available; this macro disables this. See the description 8043of the @code{PREFERRED_DEBUGGING_TYPE} macro for more details. 8044 8045@findex DWARF2_GENERATE_TEXT_SECTION_LABEL 8046@item DWARF2_GENERATE_TEXT_SECTION_LABEL 8047By default, the Dwarf 2 debugging information generator will generate a 8048label to mark the beginning of the text section. If it is better simply 8049to use the name of the text section itself, rather than an explicit label, 8050to indicate the beginning of the text section, define this macro to zero. 8051 8052@findex DWARF2_ASM_LINE_DEBUG_INFO 8053@item DWARF2_ASM_LINE_DEBUG_INFO 8054Define this macro to be a nonzero value if the assembler can generate Dwarf 2 8055line debug info sections. This will result in much more compact line number 8056tables, and hence is desirable if it works. 8057 8058@findex ASM_OUTPUT_DWARF_DELTA 8059@item ASM_OUTPUT_DWARF_DELTA (@var{stream}, @var{size}, @var{label1}, @var{label2}) 8060A C statement to issue assembly directives that create a difference 8061between the two given labels, using an integer of the given size. 8062 8063@findex ASM_OUTPUT_DWARF_OFFSET 8064@item ASM_OUTPUT_DWARF_OFFSET (@var{stream}, @var{size}, @var{label}) 8065A C statement to issue assembly directives that create a 8066section-relative reference to the given label, using an integer of the 8067given size. 8068 8069@findex ASM_OUTPUT_DWARF_PCREL 8070@item ASM_OUTPUT_DWARF_PCREL (@var{stream}, @var{size}, @var{label}) 8071A C statement to issue assembly directives that create a self-relative 8072reference to the given label, using an integer of the given size. 8073 8074@findex PUT_SDB_@dots{} 8075@item PUT_SDB_@dots{} 8076Define these macros to override the assembler syntax for the special 8077SDB assembler directives. See @file{sdbout.c} for a list of these 8078macros and their arguments. If the standard syntax is used, you need 8079not define them yourself. 8080 8081@findex SDB_DELIM 8082@item SDB_DELIM 8083Some assemblers do not support a semicolon as a delimiter, even between 8084SDB assembler directives. In that case, define this macro to be the 8085delimiter to use (usually @samp{\n}). It is not necessary to define 8086a new set of @code{PUT_SDB_@var{op}} macros if this is the only change 8087required. 8088 8089@findex SDB_GENERATE_FAKE 8090@item SDB_GENERATE_FAKE 8091Define this macro to override the usual method of constructing a dummy 8092name for anonymous structure and union types. See @file{sdbout.c} for 8093more information. 8094 8095@findex SDB_ALLOW_UNKNOWN_REFERENCES 8096@item SDB_ALLOW_UNKNOWN_REFERENCES 8097Define this macro to allow references to unknown structure, 8098union, or enumeration tags to be emitted. Standard COFF does not 8099allow handling of unknown references, MIPS ECOFF has support for 8100it. 8101 8102@findex SDB_ALLOW_FORWARD_REFERENCES 8103@item SDB_ALLOW_FORWARD_REFERENCES 8104Define this macro to allow references to structure, union, or 8105enumeration tags that have not yet been seen to be handled. Some 8106assemblers choke if forward tags are used, while some require it. 8107@end table 8108 8109@need 2000 8110@node VMS Debug 8111@subsection Macros for VMS Debug Format 8112 8113@c prevent bad page break with this line 8114Here are macros for VMS debug format. 8115 8116@table @code 8117@findex VMS_DEBUGGING_INFO 8118@item VMS_DEBUGGING_INFO 8119Define this macro if GCC should produce debugging output for VMS 8120in response to the @option{-g} option. The default behavior for VMS 8121is to generate minimal debug info for a traceback in the absence of 8122@option{-g} unless explicitly overridden with @option{-g0}. This 8123behavior is controlled by @code{OPTIMIZATION_OPTIONS} and 8124@code{OVERRIDE_OPTIONS}. 8125@end table 8126 8127@node Floating Point 8128@section Cross Compilation and Floating Point 8129@cindex cross compilation and floating point 8130@cindex floating point and cross compilation 8131 8132While all modern machines use twos-complement representation for integers, 8133there are a variety of representations for floating point numbers. This 8134means that in a cross-compiler the representation of floating point numbers 8135in the compiled program may be different from that used in the machine 8136doing the compilation. 8137 8138Because different representation systems may offer different amounts of 8139range and precision, all floating point constants must be represented in 8140the target machine's format. Therefore, the cross compiler cannot 8141safely use the host machine's floating point arithmetic; it must emulate 8142the target's arithmetic. To ensure consistency, GCC always uses 8143emulation to work with floating point values, even when the host and 8144target floating point formats are identical. 8145 8146The following macros are provided by @file{real.h} for the compiler to 8147use. All parts of the compiler which generate or optimize 8148floating-point calculations must use these macros. They may evaluate 8149their operands more than once, so operands must not have side effects. 8150 8151@defmac REAL_VALUE_TYPE 8152The C data type to be used to hold a floating point value in the target 8153machine's format. Typically this is a @code{struct} containing an 8154array of @code{HOST_WIDE_INT}, but all code should treat it as an opaque 8155quantity. 8156@end defmac 8157 8158@deftypefn Macro int REAL_VALUES_EQUAL (REAL_VALUE_TYPE @var{x}, REAL_VALUE_TYPE @var{y}) 8159Compares for equality the two values, @var{x} and @var{y}. If the target 8160floating point format supports negative zeroes and/or NaNs, 8161@samp{REAL_VALUES_EQUAL (-0.0, 0.0)} is true, and 8162@samp{REAL_VALUES_EQUAL (NaN, NaN)} is false. 8163@end deftypefn 8164 8165@deftypefn Macro int REAL_VALUES_LESS (REAL_VALUE_TYPE @var{x}, REAL_VALUE_TYPE @var{y}) 8166Tests whether @var{x} is less than @var{y}. 8167@end deftypefn 8168 8169@deftypefn Macro HOST_WIDE_INT REAL_VALUE_FIX (REAL_VALUE_TYPE @var{x}) 8170Truncates @var{x} to a signed integer, rounding toward zero. 8171@end deftypefn 8172 8173@deftypefn Macro {unsigned HOST_WIDE_INT} REAL_VALUE_UNSIGNED_FIX (REAL_VALUE_TYPE @var{x}) 8174Truncates @var{x} to an unsigned integer, rounding toward zero. If 8175@var{x} is negative, returns zero. 8176@end deftypefn 8177 8178@deftypefn Macro REAL_VALUE_TYPE REAL_VALUE_ATOF (const char *@var{string}, enum machine_mode @var{mode}) 8179Converts @var{string} into a floating point number in the target machine's 8180representation for mode @var{mode}. This routine can handle both 8181decimal and hexadecimal floating point constants, using the syntax 8182defined by the C language for both. 8183@end deftypefn 8184 8185@deftypefn Macro int REAL_VALUE_NEGATIVE (REAL_VALUE_TYPE @var{x}) 8186Returns 1 if @var{x} is negative (including negative zero), 0 otherwise. 8187@end deftypefn 8188 8189@deftypefn Macro int REAL_VALUE_ISINF (REAL_VALUE_TYPE @var{x}) 8190Determines whether @var{x} represents infinity (positive or negative). 8191@end deftypefn 8192 8193@deftypefn Macro int REAL_VALUE_ISNAN (REAL_VALUE_TYPE @var{x}) 8194Determines whether @var{x} represents a ``NaN'' (not-a-number). 8195@end deftypefn 8196 8197@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}) 8198Calculates an arithmetic operation on the two floating point values 8199@var{x} and @var{y}, storing the result in @var{output} (which must be a 8200variable). 8201 8202The operation to be performed is specified by @var{code}. Only the 8203following codes are supported: @code{PLUS_EXPR}, @code{MINUS_EXPR}, 8204@code{MULT_EXPR}, @code{RDIV_EXPR}, @code{MAX_EXPR}, @code{MIN_EXPR}. 8205 8206If @code{REAL_ARITHMETIC} is asked to evaluate division by zero and the 8207target's floating point format cannot represent infinity, it will call 8208@code{abort}. Callers should check for this situation first, using 8209@code{MODE_HAS_INFINITIES}. @xref{Storage Layout}. 8210@end deftypefn 8211 8212@deftypefn Macro REAL_VALUE_TYPE REAL_VALUE_NEGATE (REAL_VALUE_TYPE @var{x}) 8213Returns the negative of the floating point value @var{x}. 8214@end deftypefn 8215 8216@deftypefn Macro REAL_VALUE_TYPE REAL_VALUE_ABS (REAL_VALUE_TYPE @var{x}) 8217Returns the absolute value of @var{x}. 8218@end deftypefn 8219 8220@deftypefn Macro REAL_VALUE_TYPE REAL_VALUE_TRUNCATE (REAL_VALUE_TYPE @var{mode}, enum machine_mode @var{x}) 8221Truncates the floating point value @var{x} to fit in @var{mode}. The 8222return value is still a full-size @code{REAL_VALUE_TYPE}, but it has an 8223appropriate bit pattern to be output asa floating constant whose 8224precision accords with mode @var{mode}. 8225@end deftypefn 8226 8227@deftypefn Macro void REAL_VALUE_TO_INT (HOST_WIDE_INT @var{low}, HOST_WIDE_INT @var{high}, REAL_VALUE_TYPE @var{x}) 8228Converts a floating point value @var{x} into a double-precision integer 8229which is then stored into @var{low} and @var{high}. If the value is not 8230integral, it is truncated. 8231@end deftypefn 8232 8233@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}) 8234@findex REAL_VALUE_FROM_INT 8235Converts a double-precision integer found in @var{low} and @var{high}, 8236into a floating point value which is then stored into @var{x}. The 8237value is truncated to fit in mode @var{mode}. 8238@end deftypefn 8239 8240@node Mode Switching 8241@section Mode Switching Instructions 8242@cindex mode switching 8243The following macros control mode switching optimizations: 8244 8245@table @code 8246@findex OPTIMIZE_MODE_SWITCHING 8247@item OPTIMIZE_MODE_SWITCHING (@var{entity}) 8248Define this macro if the port needs extra instructions inserted for mode 8249switching in an optimizing compilation. 8250 8251For an example, the SH4 can perform both single and double precision 8252floating point operations, but to perform a single precision operation, 8253the FPSCR PR bit has to be cleared, while for a double precision 8254operation, this bit has to be set. Changing the PR bit requires a general 8255purpose register as a scratch register, hence these FPSCR sets have to 8256be inserted before reload, i.e.@: you can't put this into instruction emitting 8257or @code{MACHINE_DEPENDENT_REORG}. 8258 8259You can have multiple entities that are mode-switched, and select at run time 8260which entities actually need it. @code{OPTIMIZE_MODE_SWITCHING} should 8261return nonzero for any @var{entity} that needs mode-switching. 8262If you define this macro, you also have to define 8263@code{NUM_MODES_FOR_MODE_SWITCHING}, @code{MODE_NEEDED}, 8264@code{MODE_PRIORITY_TO_MODE} and @code{EMIT_MODE_SET}. 8265@code{NORMAL_MODE} is optional. 8266 8267@findex NUM_MODES_FOR_MODE_SWITCHING 8268@item NUM_MODES_FOR_MODE_SWITCHING 8269If you define @code{OPTIMIZE_MODE_SWITCHING}, you have to define this as 8270initializer for an array of integers. Each initializer element 8271N refers to an entity that needs mode switching, and specifies the number 8272of different modes that might need to be set for this entity. 8273The position of the initializer in the initializer - starting counting at 8274zero - determines the integer that is used to refer to the mode-switched 8275entity in question. 8276In macros that take mode arguments / yield a mode result, modes are 8277represented as numbers 0 @dots{} N @minus{} 1. N is used to specify that no mode 8278switch is needed / supplied. 8279 8280@findex MODE_NEEDED 8281@item MODE_NEEDED (@var{entity}, @var{insn}) 8282@var{entity} is an integer specifying a mode-switched entity. If 8283@code{OPTIMIZE_MODE_SWITCHING} is defined, you must define this macro to 8284return an integer value not larger than the corresponding element in 8285@code{NUM_MODES_FOR_MODE_SWITCHING}, to denote the mode that @var{entity} must 8286be switched into prior to the execution of @var{insn}. 8287 8288@findex NORMAL_MODE 8289@item NORMAL_MODE (@var{entity}) 8290If this macro is defined, it is evaluated for every @var{entity} that needs 8291mode switching. It should evaluate to an integer, which is a mode that 8292@var{entity} is assumed to be switched to at function entry and exit. 8293 8294@findex MODE_PRIORITY_TO_MODE 8295@item MODE_PRIORITY_TO_MODE (@var{entity}, @var{n}) 8296This macro specifies the order in which modes for @var{entity} are processed. 82970 is the highest priority, @code{NUM_MODES_FOR_MODE_SWITCHING[@var{entity}] - 1} the 8298lowest. The value of the macro should be an integer designating a mode 8299for @var{entity}. For any fixed @var{entity}, @code{mode_priority_to_mode} 8300(@var{entity}, @var{n}) shall be a bijection in 0 @dots{} 8301@code{num_modes_for_mode_switching[@var{entity}] - 1}. 8302 8303@findex EMIT_MODE_SET 8304@item EMIT_MODE_SET (@var{entity}, @var{mode}, @var{hard_regs_live}) 8305Generate one or more insns to set @var{entity} to @var{mode}. 8306@var{hard_reg_live} is the set of hard registers live at the point where 8307the insn(s) are to be inserted. 8308@end table 8309 8310@node Target Attributes 8311@section Defining target-specific uses of @code{__attribute__} 8312@cindex target attributes 8313@cindex machine attributes 8314@cindex attributes, target-specific 8315 8316Target-specific attributes may be defined for functions, data and types. 8317These are described using the following target hooks; they also need to 8318be documented in @file{extend.texi}. 8319 8320@deftypevr {Target Hook} {const struct attribute_spec *} TARGET_ATTRIBUTE_TABLE 8321If defined, this target hook points to an array of @samp{struct 8322attribute_spec} (defined in @file{tree.h}) specifying the machine 8323specific attributes for this target and some of the restrictions on the 8324entities to which these attributes are applied and the arguments they 8325take. 8326@end deftypevr 8327 8328@deftypefn {Target Hook} int TARGET_COMP_TYPE_ATTRIBUTES (tree @var{type1}, tree @var{type2}) 8329If defined, this target hook is a function which returns zero if the attributes on 8330@var{type1} and @var{type2} are incompatible, one if they are compatible, 8331and two if they are nearly compatible (which causes a warning to be 8332generated). If this is not defined, machine-specific attributes are 8333supposed always to be compatible. 8334@end deftypefn 8335 8336@deftypefn {Target Hook} void TARGET_SET_DEFAULT_TYPE_ATTRIBUTES (tree @var{type}) 8337If defined, this target hook is a function which assigns default attributes to 8338newly defined @var{type}. 8339@end deftypefn 8340 8341@deftypefn {Target Hook} tree TARGET_MERGE_TYPE_ATTRIBUTES (tree @var{type1}, tree @var{type2}) 8342Define this target hook if the merging of type attributes needs special 8343handling. If defined, the result is a list of the combined 8344@code{TYPE_ATTRIBUTES} of @var{type1} and @var{type2}. It is assumed 8345that @code{comptypes} has already been called and returned 1. This 8346function may call @code{merge_attributes} to handle machine-independent 8347merging. 8348@end deftypefn 8349 8350@deftypefn {Target Hook} tree TARGET_MERGE_DECL_ATTRIBUTES (tree @var{olddecl}, tree @var{newdecl}) 8351Define this target hook if the merging of decl attributes needs special 8352handling. If defined, the result is a list of the combined 8353@code{DECL_ATTRIBUTES} of @var{olddecl} and @var{newdecl}. 8354@var{newdecl} is a duplicate declaration of @var{olddecl}. Examples of 8355when this is needed are when one attribute overrides another, or when an 8356attribute is nullified by a subsequent definition. This function may 8357call @code{merge_attributes} to handle machine-independent merging. 8358 8359@findex TARGET_DLLIMPORT_DECL_ATTRIBUTES 8360If the only target-specific handling you require is @samp{dllimport} for 8361Windows targets, you should define the macro 8362@code{TARGET_DLLIMPORT_DECL_ATTRIBUTES}. This links in a function 8363called @code{merge_dllimport_decl_attributes} which can then be defined 8364as the expansion of @code{TARGET_MERGE_DECL_ATTRIBUTES}. This is done 8365in @file{i386/cygwin.h} and @file{i386/i386.c}, for example. 8366@end deftypefn 8367 8368@deftypefn {Target Hook} void TARGET_INSERT_ATTRIBUTES (tree @var{node}, tree *@var{attr_ptr}) 8369Define this target hook if you want to be able to add attributes to a decl 8370when it is being created. This is normally useful for back ends which 8371wish to implement a pragma by using the attributes which correspond to 8372the pragma's effect. The @var{node} argument is the decl which is being 8373created. The @var{attr_ptr} argument is a pointer to the attribute list 8374for this decl. The list itself should not be modified, since it may be 8375shared with other decls, but attributes may be chained on the head of 8376the list and @code{*@var{attr_ptr}} modified to point to the new 8377attributes, or a copy of the list may be made if further changes are 8378needed. 8379@end deftypefn 8380 8381@deftypefn {Target Hook} bool TARGET_FUNCTION_ATTRIBUTE_INLINABLE_P (tree @var{fndecl}) 8382@cindex inlining 8383This target hook returns @code{true} if it is ok to inline @var{fndecl} 8384into the current function, despite its having target-specific 8385attributes, @code{false} otherwise. By default, if a function has a 8386target specific attribute attached to it, it will not be inlined. 8387@end deftypefn 8388 8389@node MIPS Coprocessors 8390@section Defining coprocessor specifics for MIPS targets. 8391@cindex MIPS coprocessor-definition macros 8392 8393The MIPS specification allows MIPS implementations to have as many as 4 8394coprocessors, each with as many as 32 private registers. gcc supports 8395accessing these registers and transferring values between the registers 8396and memory using asm-ized variables. For example: 8397 8398@smallexample 8399 register unsigned int cp0count asm ("c0r1"); 8400 unsigned int d; 8401 8402 d = cp0count + 3; 8403@end smallexample 8404 8405(``c0r1'' is the default name of register 1 in coprocessor 0; alternate 8406names may be added as described below, or the default names may be 8407overridden entirely in @code{SUBTARGET_CONDITIONAL_REGISTER_USAGE}.) 8408 8409Coprocessor registers are assumed to be epilogue-used; sets to them will 8410be preserved even if it does not appear that the register is used again 8411later in the function. 8412 8413Another note: according to the MIPS spec, coprocessor 1 (if present) is 8414the FPU. One accesses COP1 registers through standard mips 8415floating-point support; they are not included in this mechanism. 8416 8417There is one macro used in defining the MIPS coprocessor interface which 8418you may want to override in subtargets; it is described below. 8419 8420@table @code 8421 8422@item ALL_COP_ADDITIONAL_REGISTER_NAMES 8423@findex ALL_COP_ADDITIONAL_REGISTER_NAMES 8424A comma-separated list (with leading comma) of pairs describing the 8425alternate names of coprocessor registers. The format of each entry should be 8426@smallexample 8427@{ @var{alternatename}, @var{register_number}@} 8428@end smallexample 8429Default: empty. 8430 8431@end table 8432 8433@node Misc 8434@section Miscellaneous Parameters 8435@cindex parameters, miscellaneous 8436 8437@c prevent bad page break with this line 8438Here are several miscellaneous parameters. 8439 8440@table @code 8441@item PREDICATE_CODES 8442@findex PREDICATE_CODES 8443Define this if you have defined special-purpose predicates in the file 8444@file{@var{machine}.c}. This macro is called within an initializer of an 8445array of structures. The first field in the structure is the name of a 8446predicate and the second field is an array of rtl codes. For each 8447predicate, list all rtl codes that can be in expressions matched by the 8448predicate. The list should have a trailing comma. Here is an example 8449of two entries in the list for a typical RISC machine: 8450 8451@smallexample 8452#define PREDICATE_CODES \ 8453 @{"gen_reg_rtx_operand", @{SUBREG, REG@}@}, \ 8454 @{"reg_or_short_cint_operand", @{SUBREG, REG, CONST_INT@}@}, 8455@end smallexample 8456 8457Defining this macro does not affect the generated code (however, 8458incorrect definitions that omit an rtl code that may be matched by the 8459predicate can cause the compiler to malfunction). Instead, it allows 8460the table built by @file{genrecog} to be more compact and efficient, 8461thus speeding up the compiler. The most important predicates to include 8462in the list specified by this macro are those used in the most insn 8463patterns. 8464 8465For each predicate function named in @code{PREDICATE_CODES}, a 8466declaration will be generated in @file{insn-codes.h}. 8467 8468@item SPECIAL_MODE_PREDICATES 8469@findex SPECIAL_MODE_PREDICATES 8470Define this if you have special predicates that know special things 8471about modes. Genrecog will warn about certain forms of 8472@code{match_operand} without a mode; if the operand predicate is 8473listed in @code{SPECIAL_MODE_PREDICATES}, the warning will be 8474suppressed. 8475 8476Here is an example from the IA-32 port (@code{ext_register_operand} 8477specially checks for @code{HImode} or @code{SImode} in preparation 8478for a byte extraction from @code{%ah} etc.). 8479 8480@smallexample 8481#define SPECIAL_MODE_PREDICATES \ 8482 "ext_register_operand", 8483@end smallexample 8484 8485@findex CASE_VECTOR_MODE 8486@item CASE_VECTOR_MODE 8487An alias for a machine mode name. This is the machine mode that 8488elements of a jump-table should have. 8489 8490@findex CASE_VECTOR_SHORTEN_MODE 8491@item CASE_VECTOR_SHORTEN_MODE (@var{min_offset}, @var{max_offset}, @var{body}) 8492Optional: return the preferred mode for an @code{addr_diff_vec} 8493when the minimum and maximum offset are known. If you define this, 8494it enables extra code in branch shortening to deal with @code{addr_diff_vec}. 8495To make this work, you also have to define @code{INSN_ALIGN} and 8496make the alignment for @code{addr_diff_vec} explicit. 8497The @var{body} argument is provided so that the offset_unsigned and scale 8498flags can be updated. 8499 8500@findex CASE_VECTOR_PC_RELATIVE 8501@item CASE_VECTOR_PC_RELATIVE 8502Define this macro to be a C expression to indicate when jump-tables 8503should contain relative addresses. If jump-tables never contain 8504relative addresses, then you need not define this macro. 8505 8506@findex CASE_DROPS_THROUGH 8507@item CASE_DROPS_THROUGH 8508Define this if control falls through a @code{case} insn when the index 8509value is out of range. This means the specified default-label is 8510actually ignored by the @code{case} insn proper. 8511 8512@findex CASE_VALUES_THRESHOLD 8513@item CASE_VALUES_THRESHOLD 8514Define this to be the smallest number of different values for which it 8515is best to use a jump-table instead of a tree of conditional branches. 8516The default is four for machines with a @code{casesi} instruction and 8517five otherwise. This is best for most machines. 8518 8519@findex WORD_REGISTER_OPERATIONS 8520@item WORD_REGISTER_OPERATIONS 8521Define this macro if operations between registers with integral mode 8522smaller than a word are always performed on the entire register. 8523Most RISC machines have this property and most CISC machines do not. 8524 8525@findex LOAD_EXTEND_OP 8526@item LOAD_EXTEND_OP (@var{mode}) 8527Define this macro to be a C expression indicating when insns that read 8528memory in @var{mode}, an integral mode narrower than a word, set the 8529bits outside of @var{mode} to be either the sign-extension or the 8530zero-extension of the data read. Return @code{SIGN_EXTEND} for values 8531of @var{mode} for which the 8532insn sign-extends, @code{ZERO_EXTEND} for which it zero-extends, and 8533@code{NIL} for other modes. 8534 8535This macro is not called with @var{mode} non-integral or with a width 8536greater than or equal to @code{BITS_PER_WORD}, so you may return any 8537value in this case. Do not define this macro if it would always return 8538@code{NIL}. On machines where this macro is defined, you will normally 8539define it as the constant @code{SIGN_EXTEND} or @code{ZERO_EXTEND}. 8540 8541@findex SHORT_IMMEDIATES_SIGN_EXTEND 8542@item SHORT_IMMEDIATES_SIGN_EXTEND 8543Define this macro if loading short immediate values into registers sign 8544extends. 8545 8546@findex FIXUNS_TRUNC_LIKE_FIX_TRUNC 8547@item FIXUNS_TRUNC_LIKE_FIX_TRUNC 8548Define this macro if the same instructions that convert a floating 8549point number to a signed fixed point number also convert validly to an 8550unsigned one. 8551 8552@findex MOVE_MAX 8553@item MOVE_MAX 8554The maximum number of bytes that a single instruction can move quickly 8555between memory and registers or between two memory locations. 8556 8557@findex MAX_MOVE_MAX 8558@item MAX_MOVE_MAX 8559The maximum number of bytes that a single instruction can move quickly 8560between memory and registers or between two memory locations. If this 8561is undefined, the default is @code{MOVE_MAX}. Otherwise, it is the 8562constant value that is the largest value that @code{MOVE_MAX} can have 8563at run-time. 8564 8565@findex SHIFT_COUNT_TRUNCATED 8566@item SHIFT_COUNT_TRUNCATED 8567A C expression that is nonzero if on this machine the number of bits 8568actually used for the count of a shift operation is equal to the number 8569of bits needed to represent the size of the object being shifted. When 8570this macro is nonzero, the compiler will assume that it is safe to omit 8571a sign-extend, zero-extend, and certain bitwise `and' instructions that 8572truncates the count of a shift operation. On machines that have 8573instructions that act on bit-fields at variable positions, which may 8574include `bit test' instructions, a nonzero @code{SHIFT_COUNT_TRUNCATED} 8575also enables deletion of truncations of the values that serve as 8576arguments to bit-field instructions. 8577 8578If both types of instructions truncate the count (for shifts) and 8579position (for bit-field operations), or if no variable-position bit-field 8580instructions exist, you should define this macro. 8581 8582However, on some machines, such as the 80386 and the 680x0, truncation 8583only applies to shift operations and not the (real or pretended) 8584bit-field operations. Define @code{SHIFT_COUNT_TRUNCATED} to be zero on 8585such machines. Instead, add patterns to the @file{md} file that include 8586the implied truncation of the shift instructions. 8587 8588You need not define this macro if it would always have the value of zero. 8589 8590@findex TRULY_NOOP_TRUNCATION 8591@item TRULY_NOOP_TRUNCATION (@var{outprec}, @var{inprec}) 8592A C expression which is nonzero if on this machine it is safe to 8593``convert'' an integer of @var{inprec} bits to one of @var{outprec} 8594bits (where @var{outprec} is smaller than @var{inprec}) by merely 8595operating on it as if it had only @var{outprec} bits. 8596 8597On many machines, this expression can be 1. 8598 8599@c rearranged this, removed the phrase "it is reported that". this was 8600@c to fix an overfull hbox. --mew 10feb93 8601When @code{TRULY_NOOP_TRUNCATION} returns 1 for a pair of sizes for 8602modes for which @code{MODES_TIEABLE_P} is 0, suboptimal code can result. 8603If this is the case, making @code{TRULY_NOOP_TRUNCATION} return 0 in 8604such cases may improve things. 8605 8606@findex STORE_FLAG_VALUE 8607@item STORE_FLAG_VALUE 8608A C expression describing the value returned by a comparison operator 8609with an integral mode and stored by a store-flag instruction 8610(@samp{s@var{cond}}) when the condition is true. This description must 8611apply to @emph{all} the @samp{s@var{cond}} patterns and all the 8612comparison operators whose results have a @code{MODE_INT} mode. 8613 8614A value of 1 or @minus{}1 means that the instruction implementing the 8615comparison operator returns exactly 1 or @minus{}1 when the comparison is true 8616and 0 when the comparison is false. Otherwise, the value indicates 8617which bits of the result are guaranteed to be 1 when the comparison is 8618true. This value is interpreted in the mode of the comparison 8619operation, which is given by the mode of the first operand in the 8620@samp{s@var{cond}} pattern. Either the low bit or the sign bit of 8621@code{STORE_FLAG_VALUE} be on. Presently, only those bits are used by 8622the compiler. 8623 8624If @code{STORE_FLAG_VALUE} is neither 1 or @minus{}1, the compiler will 8625generate code that depends only on the specified bits. It can also 8626replace comparison operators with equivalent operations if they cause 8627the required bits to be set, even if the remaining bits are undefined. 8628For example, on a machine whose comparison operators return an 8629@code{SImode} value and where @code{STORE_FLAG_VALUE} is defined as 8630@samp{0x80000000}, saying that just the sign bit is relevant, the 8631expression 8632 8633@smallexample 8634(ne:SI (and:SI @var{x} (const_int @var{power-of-2})) (const_int 0)) 8635@end smallexample 8636 8637@noindent 8638can be converted to 8639 8640@smallexample 8641(ashift:SI @var{x} (const_int @var{n})) 8642@end smallexample 8643 8644@noindent 8645where @var{n} is the appropriate shift count to move the bit being 8646tested into the sign bit. 8647 8648There is no way to describe a machine that always sets the low-order bit 8649for a true value, but does not guarantee the value of any other bits, 8650but we do not know of any machine that has such an instruction. If you 8651are trying to port GCC to such a machine, include an instruction to 8652perform a logical-and of the result with 1 in the pattern for the 8653comparison operators and let us know at @email{gcc@@gcc.gnu.org}. 8654 8655Often, a machine will have multiple instructions that obtain a value 8656from a comparison (or the condition codes). Here are rules to guide the 8657choice of value for @code{STORE_FLAG_VALUE}, and hence the instructions 8658to be used: 8659 8660@itemize @bullet 8661@item 8662Use the shortest sequence that yields a valid definition for 8663@code{STORE_FLAG_VALUE}. It is more efficient for the compiler to 8664``normalize'' the value (convert it to, e.g., 1 or 0) than for the 8665comparison operators to do so because there may be opportunities to 8666combine the normalization with other operations. 8667 8668@item 8669For equal-length sequences, use a value of 1 or @minus{}1, with @minus{}1 being 8670slightly preferred on machines with expensive jumps and 1 preferred on 8671other machines. 8672 8673@item 8674As a second choice, choose a value of @samp{0x80000001} if instructions 8675exist that set both the sign and low-order bits but do not define the 8676others. 8677 8678@item 8679Otherwise, use a value of @samp{0x80000000}. 8680@end itemize 8681 8682Many machines can produce both the value chosen for 8683@code{STORE_FLAG_VALUE} and its negation in the same number of 8684instructions. On those machines, you should also define a pattern for 8685those cases, e.g., one matching 8686 8687@smallexample 8688(set @var{A} (neg:@var{m} (ne:@var{m} @var{B} @var{C}))) 8689@end smallexample 8690 8691Some machines can also perform @code{and} or @code{plus} operations on 8692condition code values with less instructions than the corresponding 8693@samp{s@var{cond}} insn followed by @code{and} or @code{plus}. On those 8694machines, define the appropriate patterns. Use the names @code{incscc} 8695and @code{decscc}, respectively, for the patterns which perform 8696@code{plus} or @code{minus} operations on condition code values. See 8697@file{rs6000.md} for some examples. The GNU Superoptizer can be used to 8698find such instruction sequences on other machines. 8699 8700You need not define @code{STORE_FLAG_VALUE} if the machine has no store-flag 8701instructions. 8702 8703@findex FLOAT_STORE_FLAG_VALUE 8704@item FLOAT_STORE_FLAG_VALUE (@var{mode}) 8705A C expression that gives a nonzero @code{REAL_VALUE_TYPE} value that is 8706returned when comparison operators with floating-point results are true. 8707Define this macro on machine that have comparison operations that return 8708floating-point values. If there are no such operations, do not define 8709this macro. 8710 8711@findex Pmode 8712@item Pmode 8713An alias for the machine mode for pointers. On most machines, define 8714this to be the integer mode corresponding to the width of a hardware 8715pointer; @code{SImode} on 32-bit machine or @code{DImode} on 64-bit machines. 8716On some machines you must define this to be one of the partial integer 8717modes, such as @code{PSImode}. 8718 8719The width of @code{Pmode} must be at least as large as the value of 8720@code{POINTER_SIZE}. If it is not equal, you must define the macro 8721@code{POINTERS_EXTEND_UNSIGNED} to specify how pointers are extended 8722to @code{Pmode}. 8723 8724@findex FUNCTION_MODE 8725@item FUNCTION_MODE 8726An alias for the machine mode used for memory references to functions 8727being called, in @code{call} RTL expressions. On most machines this 8728should be @code{QImode}. 8729 8730@findex INTEGRATE_THRESHOLD 8731@item INTEGRATE_THRESHOLD (@var{decl}) 8732A C expression for the maximum number of instructions above which the 8733function @var{decl} should not be inlined. @var{decl} is a 8734@code{FUNCTION_DECL} node. 8735 8736The default definition of this macro is 64 plus 8 times the number of 8737arguments that the function accepts. Some people think a larger 8738threshold should be used on RISC machines. 8739 8740@findex STDC_0_IN_SYSTEM_HEADERS 8741@item STDC_0_IN_SYSTEM_HEADERS 8742In normal operation, the preprocessor expands @code{__STDC__} to the 8743constant 1, to signify that GCC conforms to ISO Standard C@. On some 8744hosts, like Solaris, the system compiler uses a different convention, 8745where @code{__STDC__} is normally 0, but is 1 if the user specifies 8746strict conformance to the C Standard. 8747 8748Defining @code{STDC_0_IN_SYSTEM_HEADERS} makes GNU CPP follows the host 8749convention when processing system header files, but when processing user 8750files @code{__STDC__} will always expand to 1. 8751 8752@findex NO_IMPLICIT_EXTERN_C 8753@item NO_IMPLICIT_EXTERN_C 8754Define this macro if the system header files support C++ as well as C@. 8755This macro inhibits the usual method of using system header files in 8756C++, which is to pretend that the file's contents are enclosed in 8757@samp{extern "C" @{@dots{}@}}. 8758 8759@findex HANDLE_PRAGMA 8760@item HANDLE_PRAGMA (@var{getc}, @var{ungetc}, @var{name}) 8761This macro is no longer supported. You must use 8762@code{REGISTER_TARGET_PRAGMAS} instead. 8763 8764@findex REGISTER_TARGET_PRAGMAS 8765@findex #pragma 8766@findex pragma 8767@item REGISTER_TARGET_PRAGMAS (@var{pfile}) 8768Define this macro if you want to implement any target-specific pragmas. 8769If defined, it is a C expression which makes a series of calls to 8770@code{cpp_register_pragma} for each pragma, with @var{pfile} passed as 8771the first argument to to these functions. The macro may also do any 8772setup required for the pragmas. 8773 8774The primary reason to define this macro is to provide compatibility with 8775other compilers for the same target. In general, we discourage 8776definition of target-specific pragmas for GCC@. 8777 8778If the pragma can be implemented by attributes then you should consider 8779defining the target hook @samp{TARGET_INSERT_ATTRIBUTES} as well. 8780 8781Preprocessor macros that appear on pragma lines are not expanded. All 8782@samp{#pragma} directives that do not match any registered pragma are 8783silently ignored, unless the user specifies @option{-Wunknown-pragmas}. 8784 8785@deftypefun void cpp_register_pragma (cpp_reader *@var{pfile}, const char *@var{space}, const char *@var{name}, void (*@var{callback}) (cpp_reader *)) 8786 8787Each call to @code{cpp_register_pragma} establishes one pragma. The 8788@var{callback} routine will be called when the preprocessor encounters a 8789pragma of the form 8790 8791@smallexample 8792#pragma [@var{space}] @var{name} @dots{} 8793@end smallexample 8794 8795@var{space} is the case-sensitive namespace of the pragma, or 8796@code{NULL} to put the pragma in the global namespace. The callback 8797routine receives @var{pfile} as its first argument, which can be passed 8798on to cpplib's functions if necessary. You can lex tokens after the 8799@var{name} by calling @code{c_lex}. Tokens that are not read by the 8800callback will be silently ignored. The end of the line is indicated by 8801a token of type @code{CPP_EOF}. 8802 8803For an example use of this routine, see @file{c4x.h} and the callback 8804routines defined in @file{c4x-c.c}. 8805 8806Note that the use of @code{c_lex} is specific to the C and C++ 8807compilers. It will not work in the Java or Fortran compilers, or any 8808other language compilers for that matter. Thus if @code{c_lex} is going 8809to be called from target-specific code, it must only be done so when 8810building the C and C++ compilers. This can be done by defining the 8811variables @code{c_target_objs} and @code{cxx_target_objs} in the 8812target entry in the @file{config.gcc} file. These variables should name 8813the target-specific, language-specific object file which contains the 8814code that uses @code{c_lex}. Note it will also be necessary to add a 8815rule to the makefile fragment pointed to by @code{tmake_file} that shows 8816how to build this object file. 8817@end deftypefun 8818 8819@findex HANDLE_SYSV_PRAGMA 8820@findex #pragma 8821@findex pragma 8822@item HANDLE_SYSV_PRAGMA 8823Define this macro (to a value of 1) if you want the System V style 8824pragmas @samp{#pragma pack(<n>)} and @samp{#pragma weak <name> 8825[=<value>]} to be supported by gcc. 8826 8827The pack pragma specifies the maximum alignment (in bytes) of fields 8828within a structure, in much the same way as the @samp{__aligned__} and 8829@samp{__packed__} @code{__attribute__}s do. A pack value of zero resets 8830the behavior to the default. 8831 8832A subtlety for Microsoft Visual C/C++ style bit-field packing 8833(e.g. -mms-bitfields) for targets that support it: 8834When a bit-field is inserted into a packed record, the whole size 8835of the underlying type is used by one or more same-size adjacent 8836bit-fields (that is, if its long:3, 32 bits is used in the record, 8837and any additional adjacent long bit-fields are packed into the same 8838chunk of 32 bits. However, if the size changes, a new field of that 8839size is allocated). 8840 8841If both MS bit-fields and @samp{__attribute__((packed))} are used, 8842the latter will take precedence. If @samp{__attribute__((packed))} is 8843used on a single field when MS bit-fields are in use, it will take 8844precedence for that field, but the alignment of the rest of the structure 8845may affect its placement. 8846 8847The weak pragma only works if @code{SUPPORTS_WEAK} and 8848@code{ASM_WEAKEN_LABEL} are defined. If enabled it allows the creation 8849of specifically named weak labels, optionally with a value. 8850 8851@findex HANDLE_PRAGMA_PACK_PUSH_POP 8852@findex #pragma 8853@findex pragma 8854@item HANDLE_PRAGMA_PACK_PUSH_POP 8855Define this macro (to a value of 1) if you want to support the Win32 8856style pragmas @samp{#pragma pack(push,@var{n})} and @samp{#pragma 8857pack(pop)}. The @samp{pack(push,@var{n})} pragma specifies the maximum alignment 8858(in bytes) of fields within a structure, in much the same way as the 8859@samp{__aligned__} and @samp{__packed__} @code{__attribute__}s do. A 8860pack value of zero resets the behavior to the default. Successive 8861invocations of this pragma cause the previous values to be stacked, so 8862that invocations of @samp{#pragma pack(pop)} will return to the previous 8863value. 8864 8865@findex DOLLARS_IN_IDENTIFIERS 8866@item DOLLARS_IN_IDENTIFIERS 8867Define this macro to control use of the character @samp{$} in identifier 8868names. 0 means @samp{$} is not allowed by default; 1 means it is allowed. 88691 is the default; there is no need to define this macro in that case. 8870This macro controls the compiler proper; it does not affect the preprocessor. 8871 8872@findex NO_DOLLAR_IN_LABEL 8873@item NO_DOLLAR_IN_LABEL 8874Define this macro if the assembler does not accept the character 8875@samp{$} in label names. By default constructors and destructors in 8876G++ have @samp{$} in the identifiers. If this macro is defined, 8877@samp{.} is used instead. 8878 8879@findex NO_DOT_IN_LABEL 8880@item NO_DOT_IN_LABEL 8881Define this macro if the assembler does not accept the character 8882@samp{.} in label names. By default constructors and destructors in G++ 8883have names that use @samp{.}. If this macro is defined, these names 8884are rewritten to avoid @samp{.}. 8885 8886@findex DEFAULT_MAIN_RETURN 8887@item DEFAULT_MAIN_RETURN 8888Define this macro if the target system expects every program's @code{main} 8889function to return a standard ``success'' value by default (if no other 8890value is explicitly returned). 8891 8892The definition should be a C statement (sans semicolon) to generate the 8893appropriate rtl instructions. It is used only when compiling the end of 8894@code{main}. 8895 8896@item NEED_ATEXIT 8897@findex NEED_ATEXIT 8898Define this if the target system lacks the function @code{atexit} 8899from the ISO C standard. If this macro is defined, a default definition 8900will be provided to support C++. If @code{ON_EXIT} is not defined, 8901a default @code{exit} function will also be provided. 8902 8903@item ON_EXIT 8904@findex ON_EXIT 8905Define this macro if the target has another way to implement atexit 8906functionality without replacing @code{exit}. For instance, SunOS 4 has 8907a similar @code{on_exit} library function. 8908 8909The definition should be a functional macro which can be used just like 8910the @code{atexit} function. 8911 8912@item EXIT_BODY 8913@findex EXIT_BODY 8914Define this if your @code{exit} function needs to do something 8915besides calling an external function @code{_cleanup} before 8916terminating with @code{_exit}. The @code{EXIT_BODY} macro is 8917only needed if @code{NEED_ATEXIT} is defined and @code{ON_EXIT} is not 8918defined. 8919 8920@findex INSN_SETS_ARE_DELAYED 8921@item INSN_SETS_ARE_DELAYED (@var{insn}) 8922Define this macro as a C expression that is nonzero if it is safe for the 8923delay slot scheduler to place instructions in the delay slot of @var{insn}, 8924even if they appear to use a resource set or clobbered in @var{insn}. 8925@var{insn} is always a @code{jump_insn} or an @code{insn}; GCC knows that 8926every @code{call_insn} has this behavior. On machines where some @code{insn} 8927or @code{jump_insn} is really a function call and hence has this behavior, 8928you should define this macro. 8929 8930You need not define this macro if it would always return zero. 8931 8932@findex INSN_REFERENCES_ARE_DELAYED 8933@item INSN_REFERENCES_ARE_DELAYED (@var{insn}) 8934Define this macro as a C expression that is nonzero if it is safe for the 8935delay slot scheduler to place instructions in the delay slot of @var{insn}, 8936even if they appear to set or clobber a resource referenced in @var{insn}. 8937@var{insn} is always a @code{jump_insn} or an @code{insn}. On machines where 8938some @code{insn} or @code{jump_insn} is really a function call and its operands 8939are registers whose use is actually in the subroutine it calls, you should 8940define this macro. Doing so allows the delay slot scheduler to move 8941instructions which copy arguments into the argument registers into the delay 8942slot of @var{insn}. 8943 8944You need not define this macro if it would always return zero. 8945 8946@findex MACHINE_DEPENDENT_REORG 8947@item MACHINE_DEPENDENT_REORG (@var{insn}) 8948In rare cases, correct code generation requires extra machine 8949dependent processing between the second jump optimization pass and 8950delayed branch scheduling. On those machines, define this macro as a C 8951statement to act on the code starting at @var{insn}. 8952 8953@findex MULTIPLE_SYMBOL_SPACES 8954@item MULTIPLE_SYMBOL_SPACES 8955Define this macro if in some cases global symbols from one translation 8956unit may not be bound to undefined symbols in another translation unit 8957without user intervention. For instance, under Microsoft Windows 8958symbols must be explicitly imported from shared libraries (DLLs). 8959 8960@findex MD_ASM_CLOBBERS 8961@item MD_ASM_CLOBBERS (@var{clobbers}) 8962A C statement that adds to @var{clobbers} @code{STRING_CST} trees for 8963any hard regs the port wishes to automatically clobber for all asms. 8964 8965@findex MAX_INTEGER_COMPUTATION_MODE 8966@item MAX_INTEGER_COMPUTATION_MODE 8967Define this to the largest integer machine mode which can be used for 8968operations other than load, store and copy operations. 8969 8970You need only define this macro if the target holds values larger than 8971@code{word_mode} in general purpose registers. Most targets should not define 8972this macro. 8973 8974@findex MATH_LIBRARY 8975@item MATH_LIBRARY 8976Define this macro as a C string constant for the linker argument to link 8977in the system math library, or @samp{""} if the target does not have a 8978separate math library. 8979 8980You need only define this macro if the default of @samp{"-lm"} is wrong. 8981 8982@findex LIBRARY_PATH_ENV 8983@item LIBRARY_PATH_ENV 8984Define this macro as a C string constant for the environment variable that 8985specifies where the linker should look for libraries. 8986 8987You need only define this macro if the default of @samp{"LIBRARY_PATH"} 8988is wrong. 8989 8990@findex TARGET_HAS_F_SETLKW 8991@item TARGET_HAS_F_SETLKW 8992Define this macro if the target supports file locking with fcntl / F_SETLKW@. 8993Note that this functionality is part of POSIX@. 8994Defining @code{TARGET_HAS_F_SETLKW} will enable the test coverage code 8995to use file locking when exiting a program, which avoids race conditions 8996if the program has forked. 8997 8998@findex MAX_CONDITIONAL_EXECUTE 8999@item MAX_CONDITIONAL_EXECUTE 9000 9001A C expression for the maximum number of instructions to execute via 9002conditional execution instructions instead of a branch. A value of 9003@code{BRANCH_COST}+1 is the default if the machine does not use cc0, and 90041 if it does use cc0. 9005 9006@findex IFCVT_MODIFY_TESTS 9007@item IFCVT_MODIFY_TESTS(@var{ce_info}, @var{true_expr}, @var{false_expr}) 9008Used if the target needs to perform machine-dependent modifications on the 9009conditionals used for turning basic blocks into conditionally executed code. 9010@var{ce_info} points to a data structure, @code{struct ce_if_block}, which 9011contains information about the currently processed blocks. @var{true_expr} 9012and @var{false_expr} are the tests that are used for converting the 9013then-block and the else-block, respectively. Set either @var{true_expr} or 9014@var{false_expr} to a null pointer if the tests cannot be converted. 9015 9016@findex IFCVT_MODIFY_MULTIPLE_TESTS 9017@item IFCVT_MODIFY_MULTIPLE_TESTS(@var{ce_info}, @var{bb}, @var{true_expr}, @var{false_expr}) 9018Like @code{IFCVT_MODIFY_TESTS}, but used when converting more complicated 9019if-statements into conditions combined by @code{and} and @code{or} operations. 9020@var{bb} contains the basic block that contains the test that is currently 9021being processed and about to be turned into a condition. 9022 9023@findex IFCVT_MODIFY_INSN 9024@item IFCVT_MODIFY_INSN(@var{ce_info}, @var{pattern}, @var{insn}) 9025A C expression to modify the @var{PATTERN} of an @var{INSN} that is to 9026be converted to conditional execution format. @var{ce_info} points to 9027a data structure, @code{struct ce_if_block}, which contains information 9028about the currently processed blocks. 9029 9030@findex IFCVT_MODIFY_FINAL 9031@item IFCVT_MODIFY_FINAL(@var{ce_info}) 9032A C expression to perform any final machine dependent modifications in 9033converting code to conditional execution. The involved basic blocks 9034can be found in the @code{struct ce_if_block} structure that is pointed 9035to by @var{ce_info}. 9036 9037@findex IFCVT_MODIFY_CANCEL 9038@item IFCVT_MODIFY_CANCEL(@var{ce_info}) 9039A C expression to cancel any machine dependent modifications in 9040converting code to conditional execution. The involved basic blocks 9041can be found in the @code{struct ce_if_block} structure that is pointed 9042to by @var{ce_info}. 9043 9044@findex IFCVT_INIT_EXTRA_FIELDS 9045@item IFCVT_INIT_EXTRA_FIELDS(@var{ce_info}) 9046A C expression to initialize any extra fields in a @code{struct ce_if_block} 9047structure, which are defined by the @code{IFCVT_EXTRA_FIELDS} macro. 9048 9049@findex IFCVT_EXTRA_FIELDS 9050@item IFCVT_EXTRA_FIELDS 9051If defined, it should expand to a set of field declarations that will be 9052added to the @code{struct ce_if_block} structure. These should be initialized 9053by the @code{IFCVT_INIT_EXTRA_FIELDS} macro. 9054 9055@end table 9056 9057@deftypefn {Target Hook} void TARGET_INIT_BUILTINS () 9058Define this hook if you have any machine-specific built-in functions 9059that need to be defined. It should be a function that performs the 9060necessary setup. 9061 9062Machine specific built-in functions can be useful to expand special machine 9063instructions that would otherwise not normally be generated because 9064they have no equivalent in the source language (for example, SIMD vector 9065instructions or prefetch instructions). 9066 9067To create a built-in function, call the function @code{builtin_function} 9068which is defined by the language front end. You can use any type nodes set 9069up by @code{build_common_tree_nodes} and @code{build_common_tree_nodes_2}; 9070only language front ends that use those two functions will call 9071@samp{TARGET_INIT_BUILTINS}. 9072@end deftypefn 9073 9074@deftypefn {Target Hook} rtx TARGET_EXPAND_BUILTIN (tree @var{exp}, rtx @var{target}, rtx @var{subtarget}, enum machine_mode @var{mode}, int @var{ignore}) 9075 9076Expand a call to a machine specific built-in function that was set up by 9077@samp{TARGET_INIT_BUILTINS}. @var{exp} is the expression for the 9078function call; the result should go to @var{target} if that is 9079convenient, and have mode @var{mode} if that is convenient. 9080@var{subtarget} may be used as the target for computing one of 9081@var{exp}'s operands. @var{ignore} is nonzero if the value is to be 9082ignored. This function should return the result of the call to the 9083built-in function. 9084@end deftypefn 9085 9086@table @code 9087@findex MD_CAN_REDIRECT_BRANCH 9088@item MD_CAN_REDIRECT_BRANCH(@var{branch1}, @var{branch2}) 9089 9090Take a branch insn in @var{branch1} and another in @var{branch2}. 9091Return true if redirecting @var{branch1} to the destination of 9092@var{branch2} is possible. 9093 9094On some targets, branches may have a limited range. Optimizing the 9095filling of delay slots can result in branches being redirected, and this 9096may in turn cause a branch offset to overflow. 9097 9098@findex ALLOCATE_INITIAL_VALUE 9099@item ALLOCATE_INITIAL_VALUE(@var{hard_reg}) 9100 9101When the initial value of a hard register has been copied in a pseudo 9102register, it is often not necessary to actually allocate another register 9103to this pseudo register, because the original hard register or a stack slot 9104it has been saved into can be used. @code{ALLOCATE_INITIAL_VALUE}, if 9105defined, is called at the start of register allocation once for each 9106hard register that had its initial value copied by using 9107@code{get_func_hard_reg_initial_val} or @code{get_hard_reg_initial_val}. 9108Possible values are @code{NULL_RTX}, if you don't want 9109to do any special allocation, a @code{REG} rtx---that would typically be 9110the hard register itself, if it is known not to be clobbered---or a 9111@code{MEM}. 9112If you are returning a @code{MEM}, this is only a hint for the allocator; 9113it might decide to use another register anyways. 9114You may use @code{current_function_leaf_function} in the definition of the 9115macro, functions that use @code{REG_N_SETS}, to determine if the hard 9116register in question will not be clobbered. 9117 9118@findex TARGET_OBJECT_SUFFIX 9119@item TARGET_OBJECT_SUFFIX 9120Define this macro to be a C string representing the suffix for object 9121files on your target machine. If you do not define this macro, GCC will 9122use @samp{.o} as the suffix for object files. 9123 9124@findex TARGET_EXECUTABLE_SUFFIX 9125@item TARGET_EXECUTABLE_SUFFIX 9126Define this macro to be a C string representing the suffix to be 9127automatically added to executable files on your target machine. If you 9128do not define this macro, GCC will use the null string as the suffix for 9129executable files. 9130 9131@findex COLLECT_EXPORT_LIST 9132@item COLLECT_EXPORT_LIST 9133If defined, @code{collect2} will scan the individual object files 9134specified on its command line and create an export list for the linker. 9135Define this macro for systems like AIX, where the linker discards 9136object files that are not referenced from @code{main} and uses export 9137lists. 9138 9139@findex MODIFY_JNI_METHOD_CALL 9140@item MODIFY_JNI_METHOD_CALL (@var{mdecl}) 9141Define this macro to a C expression representing a variant of the 9142method call @var{mdecl}, if Java Native Interface (JNI) methods 9143must be invoked differently from other methods on your target. 9144For example, on 32-bit Windows, JNI methods must be invoked using 9145the @code{stdcall} calling convention and this macro is then 9146defined as this expression: 9147 9148@smallexample 9149build_type_attribute_variant (@var{mdecl}, 9150 build_tree_list 9151 (get_identifier ("stdcall"), 9152 NULL)) 9153@end smallexample 9154 9155@end table 9156 9157@deftypefn {Target Hook} bool TARGET_CANNOT_MODIFY_JUMPS_P (void) 9158This target hook returns @code{true} past the point in which new jump 9159instructions could be created. On machines that require a register for 9160every jump such as the SHmedia ISA of SH5, this point would typically be 9161reload, so this target hook should be defined to a function such as: 9162 9163@smallexample 9164static bool 9165cannot_modify_jumps_past_reload_p () 9166@{ 9167 return (reload_completed || reload_in_progress); 9168@} 9169@end smallexample 9170@end deftypefn 9171