tm.texi revision 122180
1@c Copyright (C) 1988,1989,1992,1993,1994,1995,1996,1997,1998,1999,2000,2001,2002,2003 2@c Free Software Foundation, Inc. 3@c This is part of the GCC manual. 4@c For copying conditions, see the file gcc.texi. 5 6@node Target Macros 7@chapter Target Description Macros and Functions 8@cindex machine description macros 9@cindex target description macros 10@cindex macros, target description 11@cindex @file{tm.h} macros 12 13In addition to the file @file{@var{machine}.md}, a machine description 14includes a C header file conventionally given the name 15@file{@var{machine}.h} and a C source file named @file{@var{machine}.c}. 16The header file defines numerous macros that convey the information 17about the target machine that does not fit into the scheme of the 18@file{.md} file. The file @file{tm.h} should be a link to 19@file{@var{machine}.h}. The header file @file{config.h} includes 20@file{tm.h} and most compiler source files include @file{config.h}. The 21source file defines a variable @code{targetm}, which is a structure 22containing pointers to functions and data relating to the target 23machine. @file{@var{machine}.c} should also contain their definitions, 24if they are not defined elsewhere in GCC, and other functions called 25through the macros defined in the @file{.h} file. 26 27@menu 28* Target Structure:: The @code{targetm} variable. 29* Driver:: Controlling how the driver runs the compilation passes. 30* Run-time Target:: Defining @samp{-m} options like @option{-m68000} and @option{-m68020}. 31* Per-Function Data:: Defining data structures for per-function information. 32* Storage Layout:: Defining sizes and alignments of data. 33* Type Layout:: Defining sizes and properties of basic user data types. 34* Escape Sequences:: Defining the value of target character escape sequences 35* Registers:: Naming and describing the hardware registers. 36* Register Classes:: Defining the classes of hardware registers. 37* Stack and Calling:: Defining which way the stack grows and by how much. 38* Varargs:: Defining the varargs macros. 39* Trampolines:: Code set up at run time to enter a nested function. 40* Library Calls:: Controlling how library routines are implicitly called. 41* Addressing Modes:: Defining addressing modes valid for memory operands. 42* Condition Code:: Defining how insns update the condition code. 43* Costs:: Defining relative costs of different operations. 44* Scheduling:: Adjusting the behavior of the instruction scheduler. 45* Sections:: Dividing storage into text, data, and other sections. 46* PIC:: Macros for position independent code. 47* Assembler Format:: Defining how to write insns and pseudo-ops to output. 48* Debugging Info:: Defining the format of debugging output. 49* Floating Point:: Handling floating point for cross-compilers. 50* Mode Switching:: Insertion of mode-switching instructions. 51* Target Attributes:: Defining target-specific uses of @code{__attribute__}. 52* MIPS Coprocessors:: MIPS coprocessor support and how to customize it. 53* Misc:: Everything else. 54@end menu 55 56@node Target Structure 57@section The Global @code{targetm} Variable 58@cindex target hooks 59@cindex target functions 60 61@deftypevar {struct gcc_target} targetm 62The target @file{.c} file must define the global @code{targetm} variable 63which contains pointers to functions and data relating to the target 64machine. The variable is declared in @file{target.h}; 65@file{target-def.h} defines the macro @code{TARGET_INITIALIZER} which is 66used to initialize the variable, and macros for the default initializers 67for elements of the structure. The @file{.c} file should override those 68macros for which the default definition is inappropriate. For example: 69@smallexample 70#include "target.h" 71#include "target-def.h" 72 73/* @r{Initialize the GCC target structure.} */ 74 75#undef TARGET_COMP_TYPE_ATTRIBUTES 76#define TARGET_COMP_TYPE_ATTRIBUTES @var{machine}_comp_type_attributes 77 78struct gcc_target targetm = TARGET_INITIALIZER; 79@end smallexample 80@end deftypevar 81 82Where a macro should be defined in the @file{.c} file in this manner to 83form part of the @code{targetm} structure, it is documented below as a 84``Target Hook'' with a prototype. Many macros will change in future 85from being defined in the @file{.h} file to being part of the 86@code{targetm} structure. 87 88@node Driver 89@section Controlling the Compilation Driver, @file{gcc} 90@cindex driver 91@cindex controlling the compilation driver 92 93@c prevent bad page break with this line 94You can control the compilation driver. 95 96@table @code 97@findex SWITCH_TAKES_ARG 98@item SWITCH_TAKES_ARG (@var{char}) 99A C expression which determines whether the option @option{-@var{char}} 100takes arguments. The value should be the number of arguments that 101option takes--zero, for many options. 102 103By default, this macro is defined as 104@code{DEFAULT_SWITCH_TAKES_ARG}, which handles the standard options 105properly. You need not define @code{SWITCH_TAKES_ARG} unless you 106wish to add additional options which take arguments. Any redefinition 107should call @code{DEFAULT_SWITCH_TAKES_ARG} and then check for 108additional options. 109 110@findex WORD_SWITCH_TAKES_ARG 111@item WORD_SWITCH_TAKES_ARG (@var{name}) 112A C expression which determines whether the option @option{-@var{name}} 113takes arguments. The value should be the number of arguments that 114option takes--zero, for many options. This macro rather than 115@code{SWITCH_TAKES_ARG} is used for multi-character option names. 116 117By default, this macro is defined as 118@code{DEFAULT_WORD_SWITCH_TAKES_ARG}, which handles the standard options 119properly. You need not define @code{WORD_SWITCH_TAKES_ARG} unless you 120wish to add additional options which take arguments. Any redefinition 121should call @code{DEFAULT_WORD_SWITCH_TAKES_ARG} and then check for 122additional options. 123 124@findex SWITCH_CURTAILS_COMPILATION 125@item SWITCH_CURTAILS_COMPILATION (@var{char}) 126A C expression which determines whether the option @option{-@var{char}} 127stops compilation before the generation of an executable. The value is 128boolean, nonzero if the option does stop an executable from being 129generated, zero otherwise. 130 131By default, this macro is defined as 132@code{DEFAULT_SWITCH_CURTAILS_COMPILATION}, which handles the standard 133options properly. You need not define 134@code{SWITCH_CURTAILS_COMPILATION} unless you wish to add additional 135options which affect the generation of an executable. Any redefinition 136should call @code{DEFAULT_SWITCH_CURTAILS_COMPILATION} and then check 137for additional options. 138 139@findex SWITCHES_NEED_SPACES 140@item SWITCHES_NEED_SPACES 141A string-valued C expression which enumerates the options for which 142the linker needs a space between the option and its argument. 143 144If this macro is not defined, the default value is @code{""}. 145 146@findex TARGET_OPTION_TRANSLATE_TABLE 147@item TARGET_OPTION_TRANSLATE_TABLE 148If defined, a list of pairs of strings, the first of which is a 149potential command line target to the @file{gcc} driver program, and the 150second of which is a space-separated (tabs and other whitespace are not 151supported) list of options with which to replace the first option. The 152target defining this list is responsible for assuring that the results 153are valid. Replacement options may not be the @code{--opt} style, they 154must be the @code{-opt} style. It is the intention of this macro to 155provide a mechanism for substitution that affects the multilibs chosen, 156such as one option that enables many options, some of which select 157multilibs. Example nonsensical definition, where @code{-malt-abi}, 158@code{-EB}, and @code{-mspoo} cause different multilibs to be chosen: 159 160@smallexample 161#define TARGET_OPTION_TRANSLATE_TABLE \ 162@{ "-fast", "-march=fast-foo -malt-abi -I/usr/fast-foo" @}, \ 163@{ "-compat", "-EB -malign=4 -mspoo" @} 164@end smallexample 165 166@findex DRIVER_SELF_SPECS 167@item DRIVER_SELF_SPECS 168A list of specs for the driver itself. It should be a suitable 169initializer for an array of strings, with no surrounding braces. 170 171The driver applies these specs to its own command line before choosing 172the multilib directory or running any subcommands. It applies them in 173the order given, so each spec can depend on the options added by 174earlier ones. It is also possible to remove options using 175@samp{%<@var{option}} in the usual way. 176 177This macro can be useful when a port has several interdependent target 178options. It provides a way of standardizing the command line so 179that the other specs are easier to write. 180 181Do not define this macro if it does not need to do anything. 182 183@findex CPP_SPEC 184@item CPP_SPEC 185A C string constant that tells the GCC driver program options to 186pass to CPP@. It can also specify how to translate options you 187give to GCC into options for GCC to pass to the CPP@. 188 189Do not define this macro if it does not need to do anything. 190 191@findex CPLUSPLUS_CPP_SPEC 192@item CPLUSPLUS_CPP_SPEC 193This macro is just like @code{CPP_SPEC}, but is used for C++, rather 194than C@. If you do not define this macro, then the value of 195@code{CPP_SPEC} (if any) will be used instead. 196 197@findex CC1_SPEC 198@item CC1_SPEC 199A C string constant that tells the GCC driver program options to 200pass to @code{cc1}, @code{cc1plus}, @code{f771}, and the other language 201front ends. 202It can also specify how to translate options you give to GCC into options 203for GCC to pass to front ends. 204 205Do not define this macro if it does not need to do anything. 206 207@findex CC1PLUS_SPEC 208@item CC1PLUS_SPEC 209A C string constant that tells the GCC driver program options to 210pass to @code{cc1plus}. It can also specify how to translate options you 211give to GCC into options for GCC to pass to the @code{cc1plus}. 212 213Do not define this macro if it does not need to do anything. 214Note that everything defined in CC1_SPEC is already passed to 215@code{cc1plus} so there is no need to duplicate the contents of 216CC1_SPEC in CC1PLUS_SPEC@. 217 218@findex ASM_SPEC 219@item ASM_SPEC 220A C string constant that tells the GCC driver program options to 221pass to the assembler. It can also specify how to translate options 222you give to GCC into options for GCC to pass to the assembler. 223See the file @file{sun3.h} for an example of this. 224 225Do not define this macro if it does not need to do anything. 226 227@findex ASM_FINAL_SPEC 228@item ASM_FINAL_SPEC 229A C string constant that tells the GCC driver program how to 230run any programs which cleanup after the normal assembler. 231Normally, this is not needed. See the file @file{mips.h} for 232an example of this. 233 234Do not define this macro if it does not need to do anything. 235 236@findex LINK_SPEC 237@item LINK_SPEC 238A C string constant that tells the GCC driver program options to 239pass to the linker. It can also specify how to translate options you 240give to GCC into options for GCC to pass to the linker. 241 242Do not define this macro if it does not need to do anything. 243 244@findex LIB_SPEC 245@item LIB_SPEC 246Another C string constant used much like @code{LINK_SPEC}. The difference 247between the two is that @code{LIB_SPEC} is used at the end of the 248command given to the linker. 249 250If this macro is not defined, a default is provided that 251loads the standard C library from the usual place. See @file{gcc.c}. 252 253@findex LIBGCC_SPEC 254@item LIBGCC_SPEC 255Another C string constant that tells the GCC driver program 256how and when to place a reference to @file{libgcc.a} into the 257linker command line. This constant is placed both before and after 258the value of @code{LIB_SPEC}. 259 260If this macro is not defined, the GCC driver provides a default that 261passes the string @option{-lgcc} to the linker. 262 263@findex STARTFILE_SPEC 264@item STARTFILE_SPEC 265Another C string constant used much like @code{LINK_SPEC}. The 266difference between the two is that @code{STARTFILE_SPEC} is used at 267the very beginning of the command given to the linker. 268 269If this macro is not defined, a default is provided that loads the 270standard C startup file from the usual place. See @file{gcc.c}. 271 272@findex ENDFILE_SPEC 273@item ENDFILE_SPEC 274Another C string constant used much like @code{LINK_SPEC}. The 275difference between the two is that @code{ENDFILE_SPEC} is used at 276the very end of the command given to the linker. 277 278Do not define this macro if it does not need to do anything. 279 280@findex THREAD_MODEL_SPEC 281@item THREAD_MODEL_SPEC 282GCC @code{-v} will print the thread model GCC was configured to use. 283However, this doesn't work on platforms that are multilibbed on thread 284models, such as AIX 4.3. On such platforms, define 285@code{THREAD_MODEL_SPEC} such that it evaluates to a string without 286blanks that names one of the recognized thread models. @code{%*}, the 287default value of this macro, will expand to the value of 288@code{thread_file} set in @file{config.gcc}. 289 290@findex EXTRA_SPECS 291@item EXTRA_SPECS 292Define this macro to provide additional specifications to put in the 293@file{specs} file that can be used in various specifications like 294@code{CC1_SPEC}. 295 296The definition should be an initializer for an array of structures, 297containing a string constant, that defines the specification name, and a 298string constant that provides the specification. 299 300Do not define this macro if it does not need to do anything. 301 302@code{EXTRA_SPECS} is useful when an architecture contains several 303related targets, which have various @code{@dots{}_SPECS} which are similar 304to each other, and the maintainer would like one central place to keep 305these definitions. 306 307For example, the PowerPC System V.4 targets use @code{EXTRA_SPECS} to 308define either @code{_CALL_SYSV} when the System V calling sequence is 309used or @code{_CALL_AIX} when the older AIX-based calling sequence is 310used. 311 312The @file{config/rs6000/rs6000.h} target file defines: 313 314@example 315#define EXTRA_SPECS \ 316 @{ "cpp_sysv_default", CPP_SYSV_DEFAULT @}, 317 318#define CPP_SYS_DEFAULT "" 319@end example 320 321The @file{config/rs6000/sysv.h} target file defines: 322@smallexample 323#undef CPP_SPEC 324#define CPP_SPEC \ 325"%@{posix: -D_POSIX_SOURCE @} \ 326%@{mcall-sysv: -D_CALL_SYSV @} %@{mcall-aix: -D_CALL_AIX @} \ 327%@{!mcall-sysv: %@{!mcall-aix: %(cpp_sysv_default) @}@} \ 328%@{msoft-float: -D_SOFT_FLOAT@} %@{mcpu=403: -D_SOFT_FLOAT@}" 329 330#undef CPP_SYSV_DEFAULT 331#define CPP_SYSV_DEFAULT "-D_CALL_SYSV" 332@end smallexample 333 334while the @file{config/rs6000/eabiaix.h} target file defines 335@code{CPP_SYSV_DEFAULT} as: 336 337@smallexample 338#undef CPP_SYSV_DEFAULT 339#define CPP_SYSV_DEFAULT "-D_CALL_AIX" 340@end smallexample 341 342@findex LINK_LIBGCC_SPECIAL 343@item LINK_LIBGCC_SPECIAL 344Define this macro if the driver program should find the library 345@file{libgcc.a} itself and should not pass @option{-L} options to the 346linker. If you do not define this macro, the driver program will pass 347the argument @option{-lgcc} to tell the linker to do the search and will 348pass @option{-L} options to it. 349 350@findex LINK_LIBGCC_SPECIAL_1 351@item LINK_LIBGCC_SPECIAL_1 352Define this macro if the driver program should find the library 353@file{libgcc.a}. If you do not define this macro, the driver program will pass 354the argument @option{-lgcc} to tell the linker to do the search. 355This macro is similar to @code{LINK_LIBGCC_SPECIAL}, except that it does 356not affect @option{-L} options. 357 358@findex LINK_GCC_C_SEQUENCE_SPEC 359@item LINK_GCC_C_SEQUENCE_SPEC 360The sequence in which libgcc and libc are specified to the linker. 361By default this is @code{%G %L %G}. 362 363@findex LINK_COMMAND_SPEC 364@item LINK_COMMAND_SPEC 365A C string constant giving the complete command line need to execute the 366linker. When you do this, you will need to update your port each time a 367change is made to the link command line within @file{gcc.c}. Therefore, 368define this macro only if you need to completely redefine the command 369line for invoking the linker and there is no other way to accomplish 370the effect you need. Overriding this macro may be avoidable by overriding 371@code{LINK_GCC_C_SEQUENCE_SPEC} instead. 372 373@findex LINK_ELIMINATE_DUPLICATE_LDIRECTORIES 374@item LINK_ELIMINATE_DUPLICATE_LDIRECTORIES 375A nonzero value causes @command{collect2} to remove duplicate @option{-L@var{directory}} search 376directories from linking commands. Do not give it a nonzero value if 377removing duplicate search directories changes the linker's semantics. 378 379@findex MULTILIB_DEFAULTS 380@item MULTILIB_DEFAULTS 381Define this macro as a C expression for the initializer of an array of 382string to tell the driver program which options are defaults for this 383target and thus do not need to be handled specially when using 384@code{MULTILIB_OPTIONS}. 385 386Do not define this macro if @code{MULTILIB_OPTIONS} is not defined in 387the target makefile fragment or if none of the options listed in 388@code{MULTILIB_OPTIONS} are set by default. 389@xref{Target Fragment}. 390 391@findex RELATIVE_PREFIX_NOT_LINKDIR 392@item RELATIVE_PREFIX_NOT_LINKDIR 393Define this macro to tell @command{gcc} that it should only translate 394a @option{-B} prefix into a @option{-L} linker option if the prefix 395indicates an absolute file name. 396 397@findex STANDARD_EXEC_PREFIX 398@item STANDARD_EXEC_PREFIX 399Define this macro as a C string constant if you wish to override the 400standard choice of @file{/usr/local/lib/gcc-lib/} as the default prefix to 401try when searching for the executable files of the compiler. 402 403@findex MD_EXEC_PREFIX 404@item MD_EXEC_PREFIX 405If defined, this macro is an additional prefix to try after 406@code{STANDARD_EXEC_PREFIX}. @code{MD_EXEC_PREFIX} is not searched 407when the @option{-b} option is used, or the compiler is built as a cross 408compiler. If you define @code{MD_EXEC_PREFIX}, then be sure to add it 409to the list of directories used to find the assembler in @file{configure.in}. 410 411@findex STANDARD_STARTFILE_PREFIX 412@item STANDARD_STARTFILE_PREFIX 413Define this macro as a C string constant if you wish to override the 414standard choice of @file{/usr/local/lib/} as the default prefix to 415try when searching for startup files such as @file{crt0.o}. 416 417@findex MD_STARTFILE_PREFIX 418@item MD_STARTFILE_PREFIX 419If defined, this macro supplies an additional prefix to try after the 420standard prefixes. @code{MD_EXEC_PREFIX} is not searched when the 421@option{-b} option is used, or when the compiler is built as a cross 422compiler. 423 424@findex MD_STARTFILE_PREFIX_1 425@item MD_STARTFILE_PREFIX_1 426If defined, this macro supplies yet another prefix to try after the 427standard prefixes. It is not searched when the @option{-b} option is 428used, or when the compiler is built as a cross compiler. 429 430@findex INIT_ENVIRONMENT 431@item INIT_ENVIRONMENT 432Define this macro as a C string constant if you wish to set environment 433variables for programs called by the driver, such as the assembler and 434loader. The driver passes the value of this macro to @code{putenv} to 435initialize the necessary environment variables. 436 437@findex LOCAL_INCLUDE_DIR 438@item LOCAL_INCLUDE_DIR 439Define this macro as a C string constant if you wish to override the 440standard choice of @file{/usr/local/include} as the default prefix to 441try when searching for local header files. @code{LOCAL_INCLUDE_DIR} 442comes before @code{SYSTEM_INCLUDE_DIR} in the search order. 443 444Cross compilers do not search either @file{/usr/local/include} or its 445replacement. 446 447@findex MODIFY_TARGET_NAME 448@item MODIFY_TARGET_NAME 449Define this macro if you with to define command-line switches that modify the 450default target name 451 452For each switch, you can include a string to be appended to the first 453part of the configuration name or a string to be deleted from the 454configuration name, if present. The definition should be an initializer 455for an array of structures. Each array element should have three 456elements: the switch name (a string constant, including the initial 457dash), one of the enumeration codes @code{ADD} or @code{DELETE} to 458indicate whether the string should be inserted or deleted, and the string 459to be inserted or deleted (a string constant). 460 461For example, on a machine where @samp{64} at the end of the 462configuration name denotes a 64-bit target and you want the @option{-32} 463and @option{-64} switches to select between 32- and 64-bit targets, you would 464code 465 466@smallexample 467#define MODIFY_TARGET_NAME \ 468 @{ @{ "-32", DELETE, "64"@}, \ 469 @{"-64", ADD, "64"@}@} 470@end smallexample 471 472 473@findex SYSTEM_INCLUDE_DIR 474@item SYSTEM_INCLUDE_DIR 475Define this macro as a C string constant if you wish to specify a 476system-specific directory to search for header files before the standard 477directory. @code{SYSTEM_INCLUDE_DIR} comes before 478@code{STANDARD_INCLUDE_DIR} in the search order. 479 480Cross compilers do not use this macro and do not search the directory 481specified. 482 483@findex STANDARD_INCLUDE_DIR 484@item STANDARD_INCLUDE_DIR 485Define this macro as a C string constant if you wish to override the 486standard choice of @file{/usr/include} as the default prefix to 487try when searching for header files. 488 489Cross compilers do not use this macro and do not search either 490@file{/usr/include} or its replacement. 491 492@findex STANDARD_INCLUDE_COMPONENT 493@item STANDARD_INCLUDE_COMPONENT 494The ``component'' corresponding to @code{STANDARD_INCLUDE_DIR}. 495See @code{INCLUDE_DEFAULTS}, below, for the description of components. 496If you do not define this macro, no component is used. 497 498@findex INCLUDE_DEFAULTS 499@item INCLUDE_DEFAULTS 500Define this macro if you wish to override the entire default search path 501for include files. For a native compiler, the default search path 502usually consists of @code{GCC_INCLUDE_DIR}, @code{LOCAL_INCLUDE_DIR}, 503@code{SYSTEM_INCLUDE_DIR}, @code{GPLUSPLUS_INCLUDE_DIR}, and 504@code{STANDARD_INCLUDE_DIR}. In addition, @code{GPLUSPLUS_INCLUDE_DIR} 505and @code{GCC_INCLUDE_DIR} are defined automatically by @file{Makefile}, 506and specify private search areas for GCC@. The directory 507@code{GPLUSPLUS_INCLUDE_DIR} is used only for C++ programs. 508 509The definition should be an initializer for an array of structures. 510Each array element should have four elements: the directory name (a 511string constant), the component name (also a string constant), a flag 512for C++-only directories, 513and a flag showing that the includes in the directory don't need to be 514wrapped in @code{extern @samp{C}} when compiling C++. Mark the end of 515the array with a null element. 516 517The component name denotes what GNU package the include file is part of, 518if any, in all upper-case letters. For example, it might be @samp{GCC} 519or @samp{BINUTILS}. If the package is part of a vendor-supplied 520operating system, code the component name as @samp{0}. 521 522For example, here is the definition used for VAX/VMS: 523 524@example 525#define INCLUDE_DEFAULTS \ 526@{ \ 527 @{ "GNU_GXX_INCLUDE:", "G++", 1, 1@}, \ 528 @{ "GNU_CC_INCLUDE:", "GCC", 0, 0@}, \ 529 @{ "SYS$SYSROOT:[SYSLIB.]", 0, 0, 0@}, \ 530 @{ ".", 0, 0, 0@}, \ 531 @{ 0, 0, 0, 0@} \ 532@} 533@end example 534@end table 535 536Here is the order of prefixes tried for exec files: 537 538@enumerate 539@item 540Any prefixes specified by the user with @option{-B}. 541 542@item 543The environment variable @code{GCC_EXEC_PREFIX}, if any. 544 545@item 546The directories specified by the environment variable @code{COMPILER_PATH}. 547 548@item 549The macro @code{STANDARD_EXEC_PREFIX}. 550 551@item 552@file{/usr/lib/gcc/}. 553 554@item 555The macro @code{MD_EXEC_PREFIX}, if any. 556@end enumerate 557 558Here is the order of prefixes tried for startfiles: 559 560@enumerate 561@item 562Any prefixes specified by the user with @option{-B}. 563 564@item 565The environment variable @code{GCC_EXEC_PREFIX}, if any. 566 567@item 568The directories specified by the environment variable @code{LIBRARY_PATH} 569(or port-specific name; native only, cross compilers do not use this). 570 571@item 572The macro @code{STANDARD_EXEC_PREFIX}. 573 574@item 575@file{/usr/lib/gcc/}. 576 577@item 578The macro @code{MD_EXEC_PREFIX}, if any. 579 580@item 581The macro @code{MD_STARTFILE_PREFIX}, if any. 582 583@item 584The macro @code{STANDARD_STARTFILE_PREFIX}. 585 586@item 587@file{/lib/}. 588 589@item 590@file{/usr/lib/}. 591@end enumerate 592 593@node Run-time Target 594@section Run-time Target Specification 595@cindex run-time target specification 596@cindex predefined macros 597@cindex target specifications 598 599@c prevent bad page break with this line 600Here are run-time target specifications. 601 602@table @code 603@findex TARGET_CPU_CPP_BUILTINS 604@item TARGET_CPU_CPP_BUILTINS() 605This function-like macro expands to a block of code that defines 606built-in preprocessor macros and assertions for the target cpu, using 607the functions @code{builtin_define}, @code{builtin_define_std} and 608@code{builtin_assert} defined in @file{c-common.c}. When the front end 609calls this macro it provides a trailing semicolon, and since it has 610finished command line option processing your code can use those 611results freely. 612 613@code{builtin_assert} takes a string in the form you pass to the 614command-line option @option{-A}, such as @code{cpu=mips}, and creates 615the assertion. @code{builtin_define} takes a string in the form 616accepted by option @option{-D} and unconditionally defines the macro. 617 618@code{builtin_define_std} takes a string representing the name of an 619object-like macro. If it doesn't lie in the user's namespace, 620@code{builtin_define_std} defines it unconditionally. Otherwise, it 621defines a version with two leading underscores, and another version 622with two leading and trailing underscores, and defines the original 623only if an ISO standard was not requested on the command line. For 624example, passing @code{unix} defines @code{__unix}, @code{__unix__} 625and possibly @code{unix}; passing @code{_mips} defines @code{__mips}, 626@code{__mips__} and possibly @code{_mips}, and passing @code{_ABI64} 627defines only @code{_ABI64}. 628 629You can also test for the C dialect being compiled. The variable 630@code{c_language} is set to one of @code{clk_c}, @code{clk_cplusplus} 631or @code{clk_objective_c}. Note that if we are preprocessing 632assembler, this variable will be @code{clk_c} but the function-like 633macro @code{preprocessing_asm_p()} will return true, so you might want 634to check for that first. If you need to check for strict ANSI, the 635variable @code{flag_iso} can be used. The function-like macro 636@code{preprocessing_trad_p()} can be used to check for traditional 637preprocessing. 638 639With @code{TARGET_OS_CPP_BUILTINS} this macro obsoletes the 640@code{CPP_PREDEFINES} target macro. 641 642@findex TARGET_OS_CPP_BUILTINS 643@item TARGET_OS_CPP_BUILTINS() 644Similarly to @code{TARGET_CPU_CPP_BUILTINS} but this macro is optional 645and is used for the target operating system instead. 646 647With @code{TARGET_CPU_CPP_BUILTINS} this macro obsoletes the 648@code{CPP_PREDEFINES} target macro. 649 650@findex CPP_PREDEFINES 651@item CPP_PREDEFINES 652Define this to be a string constant containing @option{-D} options to 653define the predefined macros that identify this machine and system. 654These macros will be predefined unless the @option{-ansi} option (or a 655@option{-std} option for strict ISO C conformance) is specified. 656 657In addition, a parallel set of macros are predefined, whose names are 658made by appending @samp{__} at the beginning and at the end. These 659@samp{__} macros are permitted by the ISO standard, so they are 660predefined regardless of whether @option{-ansi} or a @option{-std} option 661is specified. 662 663For example, on the Sun, one can use the following value: 664 665@smallexample 666"-Dmc68000 -Dsun -Dunix" 667@end smallexample 668 669The result is to define the macros @code{__mc68000__}, @code{__sun__} 670and @code{__unix__} unconditionally, and the macros @code{mc68000}, 671@code{sun} and @code{unix} provided @option{-ansi} is not specified. 672 673@findex extern int target_flags 674@item extern int target_flags; 675This declaration should be present. 676 677@cindex optional hardware or system features 678@cindex features, optional, in system conventions 679@item TARGET_@dots{} 680This series of macros is to allow compiler command arguments to 681enable or disable the use of optional features of the target machine. 682For example, one machine description serves both the 68000 and 683the 68020; a command argument tells the compiler whether it should 684use 68020-only instructions or not. This command argument works 685by means of a macro @code{TARGET_68020} that tests a bit in 686@code{target_flags}. 687 688Define a macro @code{TARGET_@var{featurename}} for each such option. 689Its definition should test a bit in @code{target_flags}. It is 690recommended that a helper macro @code{TARGET_MASK_@var{featurename}} 691is defined for each bit-value to test, and used in 692@code{TARGET_@var{featurename}} and @code{TARGET_SWITCHES}. For 693example: 694 695@smallexample 696#define TARGET_MASK_68020 1 697#define TARGET_68020 (target_flags & TARGET_MASK_68020) 698@end smallexample 699 700One place where these macros are used is in the condition-expressions 701of instruction patterns. Note how @code{TARGET_68020} appears 702frequently in the 68000 machine description file, @file{m68k.md}. 703Another place they are used is in the definitions of the other 704macros in the @file{@var{machine}.h} file. 705 706@findex TARGET_SWITCHES 707@item TARGET_SWITCHES 708This macro defines names of command options to set and clear 709bits in @code{target_flags}. Its definition is an initializer 710with a subgrouping for each command option. 711 712Each subgrouping contains a string constant, that defines the option 713name, a number, which contains the bits to set in 714@code{target_flags}, and a second string which is the description 715displayed by @option{--help}. If the number is negative then the bits specified 716by the number are cleared instead of being set. If the description 717string is present but empty, then no help information will be displayed 718for that option, but it will not count as an undocumented option. The 719actual option name is made by appending @samp{-m} to the specified name. 720Non-empty description strings should be marked with @code{N_(@dots{})} for 721@command{xgettext}. Please do not mark empty strings because the empty 722string is reserved by GNU gettext. @code{gettext("")} returns the header entry 723of the message catalog with meta information, not the empty string. 724 725In addition to the description for @option{--help}, 726more detailed documentation for each option should be added to 727@file{invoke.texi}. 728 729One of the subgroupings should have a null string. The number in 730this grouping is the default value for @code{target_flags}. Any 731target options act starting with that value. 732 733Here is an example which defines @option{-m68000} and @option{-m68020} 734with opposite meanings, and picks the latter as the default: 735 736@smallexample 737#define TARGET_SWITCHES \ 738 @{ @{ "68020", TARGET_MASK_68020, "" @}, \ 739 @{ "68000", -TARGET_MASK_68020, \ 740 N_("Compile for the 68000") @}, \ 741 @{ "", TARGET_MASK_68020, "" @}@} 742@end smallexample 743 744@findex TARGET_OPTIONS 745@item TARGET_OPTIONS 746This macro is similar to @code{TARGET_SWITCHES} but defines names of command 747options that have values. Its definition is an initializer with a 748subgrouping for each command option. 749 750Each subgrouping contains a string constant, that defines the fixed part 751of the option name, the address of a variable, and a description string. 752Non-empty description strings should be marked with @code{N_(@dots{})} for 753@command{xgettext}. Please do not mark empty strings because the empty 754string is reserved by GNU gettext. @code{gettext("")} returns the header entry 755of the message catalog with meta information, not the empty string. 756 757The variable, type @code{char *}, is set to the variable part of the 758given option if the fixed part matches. The actual option name is made 759by appending @samp{-m} to the specified name. Again, each option should 760also be documented in @file{invoke.texi}. 761 762Here is an example which defines @option{-mshort-data-@var{number}}. If the 763given option is @option{-mshort-data-512}, the variable @code{m88k_short_data} 764will be set to the string @code{"512"}. 765 766@smallexample 767extern char *m88k_short_data; 768#define TARGET_OPTIONS \ 769 @{ @{ "short-data-", &m88k_short_data, \ 770 N_("Specify the size of the short data section") @} @} 771@end smallexample 772 773@findex TARGET_VERSION 774@item TARGET_VERSION 775This macro is a C statement to print on @code{stderr} a string 776describing the particular machine description choice. Every machine 777description should define @code{TARGET_VERSION}. For example: 778 779@smallexample 780#ifdef MOTOROLA 781#define TARGET_VERSION \ 782 fprintf (stderr, " (68k, Motorola syntax)"); 783#else 784#define TARGET_VERSION \ 785 fprintf (stderr, " (68k, MIT syntax)"); 786#endif 787@end smallexample 788 789@findex OVERRIDE_OPTIONS 790@item OVERRIDE_OPTIONS 791Sometimes certain combinations of command options do not make sense on 792a particular target machine. You can define a macro 793@code{OVERRIDE_OPTIONS} to take account of this. This macro, if 794defined, is executed once just after all the command options have been 795parsed. 796 797Don't use this macro to turn on various extra optimizations for 798@option{-O}. That is what @code{OPTIMIZATION_OPTIONS} is for. 799 800@findex OPTIMIZATION_OPTIONS 801@item OPTIMIZATION_OPTIONS (@var{level}, @var{size}) 802Some machines may desire to change what optimizations are performed for 803various optimization levels. This macro, if defined, is executed once 804just after the optimization level is determined and before the remainder 805of the command options have been parsed. Values set in this macro are 806used as the default values for the other command line options. 807 808@var{level} is the optimization level specified; 2 if @option{-O2} is 809specified, 1 if @option{-O} is specified, and 0 if neither is specified. 810 811@var{size} is nonzero if @option{-Os} is specified and zero otherwise. 812 813You should not use this macro to change options that are not 814machine-specific. These should uniformly selected by the same 815optimization level on all supported machines. Use this macro to enable 816machine-specific optimizations. 817 818@strong{Do not examine @code{write_symbols} in 819this macro!} The debugging options are not supposed to alter the 820generated code. 821 822@findex CAN_DEBUG_WITHOUT_FP 823@item CAN_DEBUG_WITHOUT_FP 824Define this macro if debugging can be performed even without a frame 825pointer. If this macro is defined, GCC will turn on the 826@option{-fomit-frame-pointer} option whenever @option{-O} is specified. 827@end table 828 829@node Per-Function Data 830@section Defining data structures for per-function information. 831@cindex per-function data 832@cindex data structures 833 834If the target needs to store information on a per-function basis, GCC 835provides a macro and a couple of variables to allow this. Note, just 836using statics to store the information is a bad idea, since GCC supports 837nested functions, so you can be halfway through encoding one function 838when another one comes along. 839 840GCC defines a data structure called @code{struct function} which 841contains all of the data specific to an individual function. This 842structure contains a field called @code{machine} whose type is 843@code{struct machine_function *}, which can be used by targets to point 844to their own specific data. 845 846If a target needs per-function specific data it should define the type 847@code{struct machine_function} and also the macro @code{INIT_EXPANDERS}. 848This macro should be used to initialize the function pointer 849@code{init_machine_status}. This pointer is explained below. 850 851One typical use of per-function, target specific data is to create an 852RTX to hold the register containing the function's return address. This 853RTX can then be used to implement the @code{__builtin_return_address} 854function, for level 0. 855 856Note---earlier implementations of GCC used a single data area to hold 857all of the per-function information. Thus when processing of a nested 858function began the old per-function data had to be pushed onto a 859stack, and when the processing was finished, it had to be popped off the 860stack. GCC used to provide function pointers called 861@code{save_machine_status} and @code{restore_machine_status} to handle 862the saving and restoring of the target specific information. Since the 863single data area approach is no longer used, these pointers are no 864longer supported. 865 866The macro and function pointers are described below. 867 868@table @code 869@findex INIT_EXPANDERS 870@item INIT_EXPANDERS 871Macro called to initialize any target specific information. This macro 872is called once per function, before generation of any RTL has begun. 873The intention of this macro is to allow the initialization of the 874function pointers below. 875 876@findex init_machine_status 877@item init_machine_status 878This is a @code{void (*)(struct function *)} function pointer. If this 879pointer is non-@code{NULL} it will be called once per function, before function 880compilation starts, in order to allow the target to perform any target 881specific initialization of the @code{struct function} structure. It is 882intended that this would be used to initialize the @code{machine} of 883that structure. 884 885@code{struct machine_function} structures are expected to be freed by GC. 886Generally, any memory that they reference must be allocated by using 887@code{ggc_alloc}, including the structure itself. 888 889@end table 890 891@node Storage Layout 892@section Storage Layout 893@cindex storage layout 894 895Note that the definitions of the macros in this table which are sizes or 896alignments measured in bits do not need to be constant. They can be C 897expressions that refer to static variables, such as the @code{target_flags}. 898@xref{Run-time Target}. 899 900@table @code 901@findex BITS_BIG_ENDIAN 902@item BITS_BIG_ENDIAN 903Define this macro to have the value 1 if the most significant bit in a 904byte has the lowest number; otherwise define it to have the value zero. 905This means that bit-field instructions count from the most significant 906bit. If the machine has no bit-field instructions, then this must still 907be defined, but it doesn't matter which value it is defined to. This 908macro need not be a constant. 909 910This macro does not affect the way structure fields are packed into 911bytes or words; that is controlled by @code{BYTES_BIG_ENDIAN}. 912 913@findex BYTES_BIG_ENDIAN 914@item BYTES_BIG_ENDIAN 915Define this macro to have the value 1 if the most significant byte in a 916word has the lowest number. This macro need not be a constant. 917 918@findex WORDS_BIG_ENDIAN 919@item WORDS_BIG_ENDIAN 920Define this macro to have the value 1 if, in a multiword object, the 921most significant word has the lowest number. This applies to both 922memory locations and registers; GCC fundamentally assumes that the 923order of words in memory is the same as the order in registers. This 924macro need not be a constant. 925 926@findex LIBGCC2_WORDS_BIG_ENDIAN 927@item LIBGCC2_WORDS_BIG_ENDIAN 928Define this macro if @code{WORDS_BIG_ENDIAN} is not constant. This must be a 929constant value with the same meaning as @code{WORDS_BIG_ENDIAN}, which will be 930used only when compiling @file{libgcc2.c}. Typically the value will be set 931based on preprocessor defines. 932 933@findex FLOAT_WORDS_BIG_ENDIAN 934@item FLOAT_WORDS_BIG_ENDIAN 935Define this macro to have the value 1 if @code{DFmode}, @code{XFmode} or 936@code{TFmode} floating point numbers are stored in memory with the word 937containing the sign bit at the lowest address; otherwise define it to 938have the value 0. This macro need not be a constant. 939 940You need not define this macro if the ordering is the same as for 941multi-word integers. 942 943@findex BITS_PER_UNIT 944@item BITS_PER_UNIT 945Define this macro to be the number of bits in an addressable storage 946unit (byte). If you do not define this macro the default is 8. 947 948@findex BITS_PER_WORD 949@item BITS_PER_WORD 950Number of bits in a word. If you do not define this macro, the default 951is @code{BITS_PER_UNIT * UNITS_PER_WORD}. 952 953@findex MAX_BITS_PER_WORD 954@item MAX_BITS_PER_WORD 955Maximum number of bits in a word. If this is undefined, the default is 956@code{BITS_PER_WORD}. Otherwise, it is the constant value that is the 957largest value that @code{BITS_PER_WORD} can have at run-time. 958 959@findex UNITS_PER_WORD 960@item UNITS_PER_WORD 961Number of storage units in a word; normally 4. 962 963@findex MIN_UNITS_PER_WORD 964@item MIN_UNITS_PER_WORD 965Minimum number of units in a word. If this is undefined, the default is 966@code{UNITS_PER_WORD}. Otherwise, it is the constant value that is the 967smallest value that @code{UNITS_PER_WORD} can have at run-time. 968 969@findex POINTER_SIZE 970@item POINTER_SIZE 971Width of a pointer, in bits. You must specify a value no wider than the 972width of @code{Pmode}. If it is not equal to the width of @code{Pmode}, 973you must define @code{POINTERS_EXTEND_UNSIGNED}. If you do not specify 974a value the default is @code{BITS_PER_WORD}. 975 976@findex POINTERS_EXTEND_UNSIGNED 977@item POINTERS_EXTEND_UNSIGNED 978A C expression whose value is greater than zero if pointers that need to be 979extended from being @code{POINTER_SIZE} bits wide to @code{Pmode} are to 980be zero-extended and zero if they are to be sign-extended. If the value 981is less then zero then there must be an "ptr_extend" instruction that 982extends a pointer from @code{POINTER_SIZE} to @code{Pmode}. 983 984You need not define this macro if the @code{POINTER_SIZE} is equal 985to the width of @code{Pmode}. 986 987@findex PROMOTE_MODE 988@item PROMOTE_MODE (@var{m}, @var{unsignedp}, @var{type}) 989A macro to update @var{m} and @var{unsignedp} when an object whose type 990is @var{type} and which has the specified mode and signedness is to be 991stored in a register. This macro is only called when @var{type} is a 992scalar type. 993 994On most RISC machines, which only have operations that operate on a full 995register, define this macro to set @var{m} to @code{word_mode} if 996@var{m} is an integer mode narrower than @code{BITS_PER_WORD}. In most 997cases, only integer modes should be widened because wider-precision 998floating-point operations are usually more expensive than their narrower 999counterparts. 1000 1001For most machines, the macro definition does not change @var{unsignedp}. 1002However, some machines, have instructions that preferentially handle 1003either signed or unsigned quantities of certain modes. For example, on 1004the DEC Alpha, 32-bit loads from memory and 32-bit add instructions 1005sign-extend the result to 64 bits. On such machines, set 1006@var{unsignedp} according to which kind of extension is more efficient. 1007 1008Do not define this macro if it would never modify @var{m}. 1009 1010@findex PROMOTE_FUNCTION_ARGS 1011@item PROMOTE_FUNCTION_ARGS 1012Define this macro if the promotion described by @code{PROMOTE_MODE} 1013should also be done for outgoing function arguments. 1014 1015@findex PROMOTE_FUNCTION_RETURN 1016@item PROMOTE_FUNCTION_RETURN 1017Define this macro if the promotion described by @code{PROMOTE_MODE} 1018should also be done for the return value of functions. 1019 1020If this macro is defined, @code{FUNCTION_VALUE} must perform the same 1021promotions done by @code{PROMOTE_MODE}. 1022 1023@findex PROMOTE_FOR_CALL_ONLY 1024@item PROMOTE_FOR_CALL_ONLY 1025Define this macro if the promotion described by @code{PROMOTE_MODE} 1026should @emph{only} be performed for outgoing function arguments or 1027function return values, as specified by @code{PROMOTE_FUNCTION_ARGS} 1028and @code{PROMOTE_FUNCTION_RETURN}, respectively. 1029 1030@findex PARM_BOUNDARY 1031@item PARM_BOUNDARY 1032Normal alignment required for function parameters on the stack, in 1033bits. All stack parameters receive at least this much alignment 1034regardless of data type. On most machines, this is the same as the 1035size of an integer. 1036 1037@findex STACK_BOUNDARY 1038@item STACK_BOUNDARY 1039Define this macro to the minimum alignment enforced by hardware for the 1040stack pointer on this machine. The definition is a C expression for the 1041desired alignment (measured in bits). This value is used as a default 1042if @code{PREFERRED_STACK_BOUNDARY} is not defined. On most machines, 1043this should be the same as @code{PARM_BOUNDARY}. 1044 1045@findex PREFERRED_STACK_BOUNDARY 1046@item PREFERRED_STACK_BOUNDARY 1047Define this macro if you wish to preserve a certain alignment for the 1048stack pointer, greater than what the hardware enforces. The definition 1049is a C expression for the desired alignment (measured in bits). This 1050macro must evaluate to a value equal to or larger than 1051@code{STACK_BOUNDARY}. 1052 1053@findex FORCE_PREFERRED_STACK_BOUNDARY_IN_MAIN 1054@item FORCE_PREFERRED_STACK_BOUNDARY_IN_MAIN 1055A C expression that evaluates true if @code{PREFERRED_STACK_BOUNDARY} is 1056not guaranteed by the runtime and we should emit code to align the stack 1057at the beginning of @code{main}. 1058 1059@cindex @code{PUSH_ROUNDING}, interaction with @code{PREFERRED_STACK_BOUNDARY} 1060If @code{PUSH_ROUNDING} is not defined, the stack will always be aligned 1061to the specified boundary. If @code{PUSH_ROUNDING} is defined and specifies 1062a less strict alignment than @code{PREFERRED_STACK_BOUNDARY}, the stack may 1063be momentarily unaligned while pushing arguments. 1064 1065@findex FUNCTION_BOUNDARY 1066@item FUNCTION_BOUNDARY 1067Alignment required for a function entry point, in bits. 1068 1069@findex BIGGEST_ALIGNMENT 1070@item BIGGEST_ALIGNMENT 1071Biggest alignment that any data type can require on this machine, in bits. 1072 1073@findex MINIMUM_ATOMIC_ALIGNMENT 1074@item MINIMUM_ATOMIC_ALIGNMENT 1075If defined, the smallest alignment, in bits, that can be given to an 1076object that can be referenced in one operation, without disturbing any 1077nearby object. Normally, this is @code{BITS_PER_UNIT}, but may be larger 1078on machines that don't have byte or half-word store operations. 1079 1080@findex BIGGEST_FIELD_ALIGNMENT 1081@item BIGGEST_FIELD_ALIGNMENT 1082Biggest alignment that any structure or union field can require on this 1083machine, in bits. If defined, this overrides @code{BIGGEST_ALIGNMENT} for 1084structure and union fields only, unless the field alignment has been set 1085by the @code{__attribute__ ((aligned (@var{n})))} construct. 1086 1087@findex ADJUST_FIELD_ALIGN 1088@item ADJUST_FIELD_ALIGN (@var{field}, @var{computed}) 1089An expression for the alignment of a structure field @var{field} if the 1090alignment computed in the usual way (including applying of 1091@code{BIGGEST_ALIGNMENT} and @code{BIGGEST_FIELD_ALIGNMENT} to the 1092alignment) is @var{computed}. It overrides alignment only if the 1093field alignment has not been set by the 1094@code{__attribute__ ((aligned (@var{n})))} construct. 1095 1096@findex MAX_OFILE_ALIGNMENT 1097@item MAX_OFILE_ALIGNMENT 1098Biggest alignment supported by the object file format of this machine. 1099Use this macro to limit the alignment which can be specified using the 1100@code{__attribute__ ((aligned (@var{n})))} construct. If not defined, 1101the default value is @code{BIGGEST_ALIGNMENT}. 1102 1103@findex DATA_ALIGNMENT 1104@item DATA_ALIGNMENT (@var{type}, @var{basic-align}) 1105If defined, a C expression to compute the alignment for a variable in 1106the static store. @var{type} is the data type, and @var{basic-align} is 1107the alignment that the object would ordinarily have. The value of this 1108macro is used instead of that alignment to align the object. 1109 1110If this macro is not defined, then @var{basic-align} is used. 1111 1112@findex strcpy 1113One use of this macro is to increase alignment of medium-size data to 1114make it all fit in fewer cache lines. Another is to cause character 1115arrays to be word-aligned so that @code{strcpy} calls that copy 1116constants to character arrays can be done inline. 1117 1118@findex CONSTANT_ALIGNMENT 1119@item CONSTANT_ALIGNMENT (@var{constant}, @var{basic-align}) 1120If defined, a C expression to compute the alignment given to a constant 1121that is being placed in memory. @var{constant} is the constant and 1122@var{basic-align} is the alignment that the object would ordinarily 1123have. The value of this macro is used instead of that alignment to 1124align the object. 1125 1126If this macro is not defined, then @var{basic-align} is used. 1127 1128The typical use of this macro is to increase alignment for string 1129constants to be word aligned so that @code{strcpy} calls that copy 1130constants can be done inline. 1131 1132@findex LOCAL_ALIGNMENT 1133@item LOCAL_ALIGNMENT (@var{type}, @var{basic-align}) 1134If defined, a C expression to compute the alignment for a variable in 1135the local store. @var{type} is the data type, and @var{basic-align} is 1136the alignment that the object would ordinarily have. The value of this 1137macro is used instead of that alignment to align the object. 1138 1139If this macro is not defined, then @var{basic-align} is used. 1140 1141One use of this macro is to increase alignment of medium-size data to 1142make it all fit in fewer cache lines. 1143 1144@findex EMPTY_FIELD_BOUNDARY 1145@item EMPTY_FIELD_BOUNDARY 1146Alignment in bits to be given to a structure bit-field that follows an 1147empty field such as @code{int : 0;}. 1148 1149Note that @code{PCC_BITFIELD_TYPE_MATTERS} also affects the alignment 1150that results from an empty field. 1151 1152@findex STRUCTURE_SIZE_BOUNDARY 1153@item STRUCTURE_SIZE_BOUNDARY 1154Number of bits which any structure or union's size must be a multiple of. 1155Each structure or union's size is rounded up to a multiple of this. 1156 1157If you do not define this macro, the default is the same as 1158@code{BITS_PER_UNIT}. 1159 1160@findex STRICT_ALIGNMENT 1161@item STRICT_ALIGNMENT 1162Define this macro to be the value 1 if instructions will fail to work 1163if given data not on the nominal alignment. If instructions will merely 1164go slower in that case, define this macro as 0. 1165 1166@findex PCC_BITFIELD_TYPE_MATTERS 1167@item PCC_BITFIELD_TYPE_MATTERS 1168Define this if you wish to imitate the way many other C compilers handle 1169alignment of bit-fields and the structures that contain them. 1170 1171The behavior is that the type written for a bit-field (@code{int}, 1172@code{short}, or other integer type) imposes an alignment for the 1173entire structure, as if the structure really did contain an ordinary 1174field of that type. In addition, the bit-field is placed within the 1175structure so that it would fit within such a field, not crossing a 1176boundary for it. 1177 1178Thus, on most machines, a bit-field whose type is written as @code{int} 1179would not cross a four-byte boundary, and would force four-byte 1180alignment for the whole structure. (The alignment used may not be four 1181bytes; it is controlled by the other alignment parameters.) 1182 1183If the macro is defined, its definition should be a C expression; 1184a nonzero value for the expression enables this behavior. 1185 1186Note that if this macro is not defined, or its value is zero, some 1187bit-fields may cross more than one alignment boundary. The compiler can 1188support such references if there are @samp{insv}, @samp{extv}, and 1189@samp{extzv} insns that can directly reference memory. 1190 1191The other known way of making bit-fields work is to define 1192@code{STRUCTURE_SIZE_BOUNDARY} as large as @code{BIGGEST_ALIGNMENT}. 1193Then every structure can be accessed with fullwords. 1194 1195Unless the machine has bit-field instructions or you define 1196@code{STRUCTURE_SIZE_BOUNDARY} that way, you must define 1197@code{PCC_BITFIELD_TYPE_MATTERS} to have a nonzero value. 1198 1199If your aim is to make GCC use the same conventions for laying out 1200bit-fields as are used by another compiler, here is how to investigate 1201what the other compiler does. Compile and run this program: 1202 1203@example 1204struct foo1 1205@{ 1206 char x; 1207 char :0; 1208 char y; 1209@}; 1210 1211struct foo2 1212@{ 1213 char x; 1214 int :0; 1215 char y; 1216@}; 1217 1218main () 1219@{ 1220 printf ("Size of foo1 is %d\n", 1221 sizeof (struct foo1)); 1222 printf ("Size of foo2 is %d\n", 1223 sizeof (struct foo2)); 1224 exit (0); 1225@} 1226@end example 1227 1228If this prints 2 and 5, then the compiler's behavior is what you would 1229get from @code{PCC_BITFIELD_TYPE_MATTERS}. 1230 1231@findex BITFIELD_NBYTES_LIMITED 1232@item BITFIELD_NBYTES_LIMITED 1233Like @code{PCC_BITFIELD_TYPE_MATTERS} except that its effect is limited 1234to aligning a bit-field within the structure. 1235 1236@findex MEMBER_TYPE_FORCES_BLK 1237@item MEMBER_TYPE_FORCES_BLK (@var{field}, @var{mode}) 1238Return 1 if a structure or array containing @var{field} should be accessed using 1239@code{BLKMODE}. 1240 1241If @var{field} is the only field in the structure, @var{mode} is its 1242mode, otherwise @var{mode} is VOIDmode. @var{mode} is provided in the 1243case where structures of one field would require the structure's mode to 1244retain the field's mode. 1245 1246Normally, this is not needed. See the file @file{c4x.h} for an example 1247of how to use this macro to prevent a structure having a floating point 1248field from being accessed in an integer mode. 1249 1250@findex ROUND_TYPE_SIZE 1251@item ROUND_TYPE_SIZE (@var{type}, @var{computed}, @var{specified}) 1252Define this macro as an expression for the overall size of a type 1253(given by @var{type} as a tree node) when the size computed in the 1254usual way is @var{computed} and the alignment is @var{specified}. 1255 1256The default is to round @var{computed} up to a multiple of @var{specified}. 1257 1258@findex ROUND_TYPE_SIZE_UNIT 1259@item ROUND_TYPE_SIZE_UNIT (@var{type}, @var{computed}, @var{specified}) 1260Similar to @code{ROUND_TYPE_SIZE}, but sizes and alignments are 1261specified in units (bytes). If you define @code{ROUND_TYPE_SIZE}, 1262you must also define this macro and they must be defined consistently 1263with each other. 1264 1265@findex ROUND_TYPE_ALIGN 1266@item ROUND_TYPE_ALIGN (@var{type}, @var{computed}, @var{specified}) 1267Define this macro as an expression for the alignment of a type (given 1268by @var{type} as a tree node) if the alignment computed in the usual 1269way is @var{computed} and the alignment explicitly specified was 1270@var{specified}. 1271 1272The default is to use @var{specified} if it is larger; otherwise, use 1273the smaller of @var{computed} and @code{BIGGEST_ALIGNMENT} 1274 1275@findex MAX_FIXED_MODE_SIZE 1276@item MAX_FIXED_MODE_SIZE 1277An integer expression for the size in bits of the largest integer 1278machine mode that should actually be used. All integer machine modes of 1279this size or smaller can be used for structures and unions with the 1280appropriate sizes. If this macro is undefined, @code{GET_MODE_BITSIZE 1281(DImode)} is assumed. 1282 1283@findex VECTOR_MODE_SUPPORTED_P 1284@item VECTOR_MODE_SUPPORTED_P(@var{mode}) 1285Define this macro to be nonzero if the port is prepared to handle insns 1286involving vector mode @var{mode}. At the very least, it must have move 1287patterns for this mode. 1288 1289@findex STACK_SAVEAREA_MODE 1290@item STACK_SAVEAREA_MODE (@var{save_level}) 1291If defined, an expression of type @code{enum machine_mode} that 1292specifies the mode of the save area operand of a 1293@code{save_stack_@var{level}} named pattern (@pxref{Standard Names}). 1294@var{save_level} is one of @code{SAVE_BLOCK}, @code{SAVE_FUNCTION}, or 1295@code{SAVE_NONLOCAL} and selects which of the three named patterns is 1296having its mode specified. 1297 1298You need not define this macro if it always returns @code{Pmode}. You 1299would most commonly define this macro if the 1300@code{save_stack_@var{level}} patterns need to support both a 32- and a 130164-bit mode. 1302 1303@findex STACK_SIZE_MODE 1304@item STACK_SIZE_MODE 1305If defined, an expression of type @code{enum machine_mode} that 1306specifies the mode of the size increment operand of an 1307@code{allocate_stack} named pattern (@pxref{Standard Names}). 1308 1309You need not define this macro if it always returns @code{word_mode}. 1310You would most commonly define this macro if the @code{allocate_stack} 1311pattern needs to support both a 32- and a 64-bit mode. 1312 1313@findex TARGET_FLOAT_FORMAT 1314@item TARGET_FLOAT_FORMAT 1315A code distinguishing the floating point format of the target machine. 1316There are five defined values: 1317 1318@table @code 1319@findex IEEE_FLOAT_FORMAT 1320@item IEEE_FLOAT_FORMAT 1321This code indicates IEEE floating point. It is the default; there is no 1322need to define this macro when the format is IEEE@. 1323 1324@findex VAX_FLOAT_FORMAT 1325@item VAX_FLOAT_FORMAT 1326This code indicates the ``F float'' (for @code{float}) and ``D float'' 1327or ``G float'' formats (for @code{double}) used on the VAX and PDP-11@. 1328 1329@findex IBM_FLOAT_FORMAT 1330@item IBM_FLOAT_FORMAT 1331This code indicates the format used on the IBM System/370. 1332 1333@findex C4X_FLOAT_FORMAT 1334@item C4X_FLOAT_FORMAT 1335This code indicates the format used on the TMS320C3x/C4x. 1336 1337@findex UNKNOWN_FLOAT_FORMAT 1338@item UNKNOWN_FLOAT_FORMAT 1339This code indicates any other format. 1340@end table 1341 1342If any other 1343formats are actually in use on supported machines, new codes should be 1344defined for them. 1345 1346The ordering of the component words of floating point values stored in 1347memory is controlled by @code{FLOAT_WORDS_BIG_ENDIAN}. 1348 1349@findex MODE_HAS_NANS 1350@item MODE_HAS_NANS (@var{mode}) 1351When defined, this macro should be true if @var{mode} has a NaN 1352representation. The compiler assumes that NaNs are not equal to 1353anything (including themselves) and that addition, subtraction, 1354multiplication and division all return NaNs when one operand is 1355NaN@. 1356 1357By default, this macro is true if @var{mode} is a floating-point 1358mode and the target floating-point format is IEEE@. 1359 1360@findex MODE_HAS_INFINITIES 1361@item MODE_HAS_INFINITIES (@var{mode}) 1362This macro should be true if @var{mode} can represent infinity. At 1363present, the compiler uses this macro to decide whether @samp{x - x} 1364is always defined. By default, the macro is true when @var{mode} 1365is a floating-point mode and the target format is IEEE@. 1366 1367@findex MODE_HAS_SIGNED_ZEROS 1368@item MODE_HAS_SIGNED_ZEROS (@var{mode}) 1369True if @var{mode} distinguishes between positive and negative zero. 1370The rules are expected to follow the IEEE standard: 1371 1372@itemize @bullet 1373@item 1374@samp{x + x} has the same sign as @samp{x}. 1375 1376@item 1377If the sum of two values with opposite sign is zero, the result is 1378positive for all rounding modes expect towards @minus{}infinity, for 1379which it is negative. 1380 1381@item 1382The sign of a product or quotient is negative when exactly one 1383of the operands is negative. 1384@end itemize 1385 1386The default definition is true if @var{mode} is a floating-point 1387mode and the target format is IEEE@. 1388 1389@findex MODE_HAS_SIGN_DEPENDENT_ROUNDING 1390@item MODE_HAS_SIGN_DEPENDENT_ROUNDING (@var{mode}) 1391If defined, this macro should be true for @var{mode} if it has at 1392least one rounding mode in which @samp{x} and @samp{-x} can be 1393rounded to numbers of different magnitude. Two such modes are 1394towards @minus{}infinity and towards +infinity. 1395 1396The default definition of this macro is true if @var{mode} is 1397a floating-point mode and the target format is IEEE@. 1398 1399@findex ROUND_TOWARDS_ZERO 1400@item ROUND_TOWARDS_ZERO 1401If defined, this macro should be true if the prevailing rounding 1402mode is towards zero. A true value has the following effects: 1403 1404@itemize @bullet 1405@item 1406@code{MODE_HAS_SIGN_DEPENDENT_ROUNDING} will be false for all modes. 1407 1408@item 1409@file{libgcc.a}'s floating-point emulator will round towards zero 1410rather than towards nearest. 1411 1412@item 1413The compiler's floating-point emulator will round towards zero after 1414doing arithmetic, and when converting from the internal float format to 1415the target format. 1416@end itemize 1417 1418The macro does not affect the parsing of string literals. When the 1419primary rounding mode is towards zero, library functions like 1420@code{strtod} might still round towards nearest, and the compiler's 1421parser should behave like the target's @code{strtod} where possible. 1422 1423Not defining this macro is equivalent to returning zero. 1424 1425@findex LARGEST_EXPONENT_IS_NORMAL 1426@item LARGEST_EXPONENT_IS_NORMAL (@var{size}) 1427This macro should return true if floats with @var{size} 1428bits do not have a NaN or infinity representation, but use the largest 1429exponent for normal numbers instead. 1430 1431Defining this macro to true for @var{size} causes @code{MODE_HAS_NANS} 1432and @code{MODE_HAS_INFINITIES} to be false for @var{size}-bit modes. 1433It also affects the way @file{libgcc.a} and @file{real.c} emulate 1434floating-point arithmetic. 1435 1436The default definition of this macro returns false for all sizes. 1437@end table 1438 1439@deftypefn {Target Hook} bool TARGET_MS_BITFIELD_LAYOUT_P (tree @var{record_type}) 1440This target hook returns @code{true} if bit-fields in the given 1441@var{record_type} are to be laid out following the rules of Microsoft 1442Visual C/C++, namely: (i) a bit-field won't share the same storage 1443unit with the previous bit-field if their underlying types have 1444different sizes, and the bit-field will be aligned to the highest 1445alignment of the underlying types of itself and of the previous 1446bit-field; (ii) a zero-sized bit-field will affect the alignment of 1447the whole enclosing structure, even if it is unnamed; except that 1448(iii) a zero-sized bit-field will be disregarded unless it follows 1449another bit-field of nonzero size. If this hook returns @code{true}, 1450other macros that control bit-field layout are ignored. 1451 1452When a bit-field is inserted into a packed record, the whole size 1453of the underlying type is used by one or more same-size adjacent 1454bit-fields (that is, if its long:3, 32 bits is used in the record, 1455and any additional adjacent long bit-fields are packed into the same 1456chunk of 32 bits. However, if the size changes, a new field of that 1457size is allocated). In an unpacked record, this is the same as using 1458alignment, but not equivalent when packing. 1459 1460If both MS bit-fields and @samp{__attribute__((packed))} are used, 1461the latter will take precedence. If @samp{__attribute__((packed))} is 1462used on a single field when MS bit-fields are in use, it will take 1463precedence for that field, but the alignment of the rest of the structure 1464may affect its placement. 1465@end deftypefn 1466 1467@node Type Layout 1468@section Layout of Source Language Data Types 1469 1470These macros define the sizes and other characteristics of the standard 1471basic data types used in programs being compiled. Unlike the macros in 1472the previous section, these apply to specific features of C and related 1473languages, rather than to fundamental aspects of storage layout. 1474 1475@table @code 1476@findex INT_TYPE_SIZE 1477@item INT_TYPE_SIZE 1478A C expression for the size in bits of the type @code{int} on the 1479target machine. If you don't define this, the default is one word. 1480 1481@findex SHORT_TYPE_SIZE 1482@item SHORT_TYPE_SIZE 1483A C expression for the size in bits of the type @code{short} on the 1484target machine. If you don't define this, the default is half a word. 1485(If this would be less than one storage unit, it is rounded up to one 1486unit.) 1487 1488@findex LONG_TYPE_SIZE 1489@item LONG_TYPE_SIZE 1490A C expression for the size in bits of the type @code{long} on the 1491target machine. If you don't define this, the default is one word. 1492 1493@findex ADA_LONG_TYPE_SIZE 1494@item ADA_LONG_TYPE_SIZE 1495On some machines, the size used for the Ada equivalent of the type 1496@code{long} by a native Ada compiler differs from that used by C. In 1497that situation, define this macro to be a C expression to be used for 1498the size of that type. If you don't define this, the default is the 1499value of @code{LONG_TYPE_SIZE}. 1500 1501@findex MAX_LONG_TYPE_SIZE 1502@item MAX_LONG_TYPE_SIZE 1503Maximum number for the size in bits of the type @code{long} on the 1504target machine. If this is undefined, the default is 1505@code{LONG_TYPE_SIZE}. Otherwise, it is the constant value that is the 1506largest value that @code{LONG_TYPE_SIZE} can have at run-time. This is 1507used in @code{cpp}. 1508 1509@findex LONG_LONG_TYPE_SIZE 1510@item LONG_LONG_TYPE_SIZE 1511A C expression for the size in bits of the type @code{long long} on the 1512target machine. If you don't define this, the default is two 1513words. If you want to support GNU Ada on your machine, the value of this 1514macro must be at least 64. 1515 1516@findex CHAR_TYPE_SIZE 1517@item CHAR_TYPE_SIZE 1518A C expression for the size in bits of the type @code{char} on the 1519target machine. If you don't define this, the default is 1520@code{BITS_PER_UNIT}. 1521 1522@findex BOOL_TYPE_SIZE 1523@item BOOL_TYPE_SIZE 1524A C expression for the size in bits of the C++ type @code{bool} and 1525C99 type @code{_Bool} on the target machine. If you don't define 1526this, and you probably shouldn't, the default is @code{CHAR_TYPE_SIZE}. 1527 1528@findex FLOAT_TYPE_SIZE 1529@item FLOAT_TYPE_SIZE 1530A C expression for the size in bits of the type @code{float} on the 1531target machine. If you don't define this, the default is one word. 1532 1533@findex DOUBLE_TYPE_SIZE 1534@item DOUBLE_TYPE_SIZE 1535A C expression for the size in bits of the type @code{double} on the 1536target machine. If you don't define this, the default is two 1537words. 1538 1539@findex LONG_DOUBLE_TYPE_SIZE 1540@item LONG_DOUBLE_TYPE_SIZE 1541A C expression for the size in bits of the type @code{long double} on 1542the target machine. If you don't define this, the default is two 1543words. 1544 1545@findex MAX_LONG_DOUBLE_TYPE_SIZE 1546Maximum number for the size in bits of the type @code{long double} on the 1547target machine. If this is undefined, the default is 1548@code{LONG_DOUBLE_TYPE_SIZE}. Otherwise, it is the constant value that is 1549the largest value that @code{LONG_DOUBLE_TYPE_SIZE} can have at run-time. 1550This is used in @code{cpp}. 1551 1552@findex TARGET_FLT_EVAL_METHOD 1553@item TARGET_FLT_EVAL_METHOD 1554A C expression for the value for @code{FLT_EVAL_METHOD} in @file{float.h}, 1555assuming, if applicable, that the floating-point control word is in its 1556default state. If you do not define this macro the value of 1557@code{FLT_EVAL_METHOD} will be zero. 1558 1559@findex WIDEST_HARDWARE_FP_SIZE 1560@item WIDEST_HARDWARE_FP_SIZE 1561A C expression for the size in bits of the widest floating-point format 1562supported by the hardware. If you define this macro, you must specify a 1563value less than or equal to the value of @code{LONG_DOUBLE_TYPE_SIZE}. 1564If you do not define this macro, the value of @code{LONG_DOUBLE_TYPE_SIZE} 1565is the default. 1566 1567@findex DEFAULT_SIGNED_CHAR 1568@item DEFAULT_SIGNED_CHAR 1569An expression whose value is 1 or 0, according to whether the type 1570@code{char} should be signed or unsigned by default. The user can 1571always override this default with the options @option{-fsigned-char} 1572and @option{-funsigned-char}. 1573 1574@findex DEFAULT_SHORT_ENUMS 1575@item DEFAULT_SHORT_ENUMS 1576A C expression to determine whether to give an @code{enum} type 1577only as many bytes as it takes to represent the range of possible values 1578of that type. A nonzero value means to do that; a zero value means all 1579@code{enum} types should be allocated like @code{int}. 1580 1581If you don't define the macro, the default is 0. 1582 1583@findex SIZE_TYPE 1584@item SIZE_TYPE 1585A C expression for a string describing the name of the data type to use 1586for size values. The typedef name @code{size_t} is defined using the 1587contents of the string. 1588 1589The string can contain more than one keyword. If so, separate them with 1590spaces, and write first any length keyword, then @code{unsigned} if 1591appropriate, and finally @code{int}. The string must exactly match one 1592of the data type names defined in the function 1593@code{init_decl_processing} in the file @file{c-decl.c}. You may not 1594omit @code{int} or change the order---that would cause the compiler to 1595crash on startup. 1596 1597If you don't define this macro, the default is @code{"long unsigned 1598int"}. 1599 1600@findex PTRDIFF_TYPE 1601@item PTRDIFF_TYPE 1602A C expression for a string describing the name of the data type to use 1603for the result of subtracting two pointers. The typedef name 1604@code{ptrdiff_t} is defined using the contents of the string. See 1605@code{SIZE_TYPE} above for more information. 1606 1607If you don't define this macro, the default is @code{"long int"}. 1608 1609@findex WCHAR_TYPE 1610@item WCHAR_TYPE 1611A C expression for a string describing the name of the data type to use 1612for wide characters. The typedef name @code{wchar_t} is defined using 1613the contents of the string. See @code{SIZE_TYPE} above for more 1614information. 1615 1616If you don't define this macro, the default is @code{"int"}. 1617 1618@findex WCHAR_TYPE_SIZE 1619@item WCHAR_TYPE_SIZE 1620A C expression for the size in bits of the data type for wide 1621characters. This is used in @code{cpp}, which cannot make use of 1622@code{WCHAR_TYPE}. 1623 1624@findex MAX_WCHAR_TYPE_SIZE 1625@item MAX_WCHAR_TYPE_SIZE 1626Maximum number for the size in bits of the data type for wide 1627characters. If this is undefined, the default is 1628@code{WCHAR_TYPE_SIZE}. Otherwise, it is the constant value that is the 1629largest value that @code{WCHAR_TYPE_SIZE} can have at run-time. This is 1630used in @code{cpp}. 1631 1632@findex GCOV_TYPE_SIZE 1633@item GCOV_TYPE_SIZE 1634A C expression for the size in bits of the type used for gcov counters on the 1635target machine. If you don't define this, the default is one 1636@code{LONG_TYPE_SIZE} in case it is greater or equal to 64-bit and 1637@code{LONG_LONG_TYPE_SIZE} otherwise. You may want to re-define the type to 1638ensure atomicity for counters in multithreaded programs. 1639 1640@findex WINT_TYPE 1641@item WINT_TYPE 1642A C expression for a string describing the name of the data type to 1643use for wide characters passed to @code{printf} and returned from 1644@code{getwc}. The typedef name @code{wint_t} is defined using the 1645contents of the string. See @code{SIZE_TYPE} above for more 1646information. 1647 1648If you don't define this macro, the default is @code{"unsigned int"}. 1649 1650@findex INTMAX_TYPE 1651@item INTMAX_TYPE 1652A C expression for a string describing the name of the data type that 1653can represent any value of any standard or extended signed integer type. 1654The typedef name @code{intmax_t} is defined using the contents of the 1655string. See @code{SIZE_TYPE} above for more information. 1656 1657If you don't define this macro, the default is the first of 1658@code{"int"}, @code{"long int"}, or @code{"long long int"} that has as 1659much precision as @code{long long int}. 1660 1661@findex UINTMAX_TYPE 1662@item UINTMAX_TYPE 1663A C expression for a string describing the name of the data type that 1664can represent any value of any standard or extended unsigned integer 1665type. The typedef name @code{uintmax_t} is defined using the contents 1666of the string. See @code{SIZE_TYPE} above for more information. 1667 1668If you don't define this macro, the default is the first of 1669@code{"unsigned int"}, @code{"long unsigned int"}, or @code{"long long 1670unsigned int"} that has as much precision as @code{long long unsigned 1671int}. 1672 1673@findex TARGET_PTRMEMFUNC_VBIT_LOCATION 1674@item TARGET_PTRMEMFUNC_VBIT_LOCATION 1675The C++ compiler represents a pointer-to-member-function with a struct 1676that looks like: 1677 1678@example 1679 struct @{ 1680 union @{ 1681 void (*fn)(); 1682 ptrdiff_t vtable_index; 1683 @}; 1684 ptrdiff_t delta; 1685 @}; 1686@end example 1687 1688@noindent 1689The C++ compiler must use one bit to indicate whether the function that 1690will be called through a pointer-to-member-function is virtual. 1691Normally, we assume that the low-order bit of a function pointer must 1692always be zero. Then, by ensuring that the vtable_index is odd, we can 1693distinguish which variant of the union is in use. But, on some 1694platforms function pointers can be odd, and so this doesn't work. In 1695that case, we use the low-order bit of the @code{delta} field, and shift 1696the remainder of the @code{delta} field to the left. 1697 1698GCC will automatically make the right selection about where to store 1699this bit using the @code{FUNCTION_BOUNDARY} setting for your platform. 1700However, some platforms such as ARM/Thumb have @code{FUNCTION_BOUNDARY} 1701set such that functions always start at even addresses, but the lowest 1702bit of pointers to functions indicate whether the function at that 1703address is in ARM or Thumb mode. If this is the case of your 1704architecture, you should define this macro to 1705@code{ptrmemfunc_vbit_in_delta}. 1706 1707In general, you should not have to define this macro. On architectures 1708in which function addresses are always even, according to 1709@code{FUNCTION_BOUNDARY}, GCC will automatically define this macro to 1710@code{ptrmemfunc_vbit_in_pfn}. 1711 1712@findex TARGET_VTABLE_USES_DESCRIPTORS 1713@item TARGET_VTABLE_USES_DESCRIPTORS 1714Normally, the C++ compiler uses function pointers in vtables. This 1715macro allows the target to change to use ``function descriptors'' 1716instead. Function descriptors are found on targets for whom a 1717function pointer is actually a small data structure. Normally the 1718data structure consists of the actual code address plus a data 1719pointer to which the function's data is relative. 1720 1721If vtables are used, the value of this macro should be the number 1722of words that the function descriptor occupies. 1723 1724@findex TARGET_VTABLE_ENTRY_ALIGN 1725@item TARGET_VTABLE_ENTRY_ALIGN 1726By default, the vtable entries are void pointers, the so the alignment 1727is the same as pointer alignment. The value of this macro specifies 1728the alignment of the vtable entry in bits. It should be defined only 1729when special alignment is necessary. */ 1730 1731@findex TARGET_VTABLE_DATA_ENTRY_DISTANCE 1732@item TARGET_VTABLE_DATA_ENTRY_DISTANCE 1733There are a few non-descriptor entries in the vtable at offsets below 1734zero. If these entries must be padded (say, to preserve the alignment 1735specified by @code{TARGET_VTABLE_ENTRY_ALIGN}), set this to the number 1736of words in each data entry. 1737@end table 1738 1739@node Escape Sequences 1740@section Target Character Escape Sequences 1741@cindex escape sequences 1742 1743By default, GCC assumes that the C character escape sequences take on 1744their ASCII values for the target. If this is not correct, you must 1745explicitly define all of the macros below. 1746 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_CONSTANT_NAME 6593@item ASM_DECLARE_CONSTANT_NAME (@var{stream}, @var{name}, @var{exp}, @var{size}) 6594A C statement (sans semicolon) to output to the stdio stream 6595@var{stream} any text necessary for declaring the name @var{name} of a 6596constant which is being defined. This macro is responsible for 6597outputting the label definition (perhaps using 6598@code{ASM_OUTPUT_LABEL}). The argument @var{exp} is the 6599value of the constant, and @var{size} is the size of the constant 6600in bytes. @var{name} will be an internal label. 6601 6602If this macro is not defined, then the @var{name} is defined in the 6603usual manner as a label (by means of @code{ASM_OUTPUT_LABEL}). 6604 6605You may wish to use @code{ASM_OUTPUT_TYPE_DIRECTIVE} in the definition 6606of this macro. 6607 6608@findex ASM_DECLARE_REGISTER_GLOBAL 6609@item ASM_DECLARE_REGISTER_GLOBAL (@var{stream}, @var{decl}, @var{regno}, @var{name}) 6610A C statement (sans semicolon) to output to the stdio stream 6611@var{stream} any text necessary for claiming a register @var{regno} 6612for a global variable @var{decl} with name @var{name}. 6613 6614If you don't define this macro, that is equivalent to defining it to do 6615nothing. 6616 6617@findex ASM_FINISH_DECLARE_OBJECT 6618@item ASM_FINISH_DECLARE_OBJECT (@var{stream}, @var{decl}, @var{toplevel}, @var{atend}) 6619A C statement (sans semicolon) to finish up declaring a variable name 6620once the compiler has processed its initializer fully and thus has had a 6621chance to determine the size of an array when controlled by an 6622initializer. This is used on systems where it's necessary to declare 6623something about the size of the object. 6624 6625If you don't define this macro, that is equivalent to defining it to do 6626nothing. 6627 6628You may wish to use @code{ASM_OUTPUT_SIZE_DIRECTIVE} and/or 6629@code{ASM_OUTPUT_MEASURED_SIZE} in the definition of this macro. 6630@end table 6631 6632@deftypefn {Target Hook} void TARGET_ASM_GLOBALIZE_LABEL (FILE *@var{stream}, const char *@var{name}) 6633This target hook is a function to output to the stdio stream 6634@var{stream} some commands that will make the label @var{name} global; 6635that is, available for reference from other files. 6636 6637The default implementation relies on a proper definition of 6638@code{GLOBAL_ASM_OP}. 6639@end deftypefn 6640 6641@table @code 6642@findex ASM_WEAKEN_LABEL 6643@item ASM_WEAKEN_LABEL (@var{stream}, @var{name}) 6644A C statement (sans semicolon) to output to the stdio stream 6645@var{stream} some commands that will make the label @var{name} weak; 6646that is, available for reference from other files but only used if 6647no other definition is available. Use the expression 6648@code{assemble_name (@var{stream}, @var{name})} to output the name 6649itself; before and after that, output the additional assembler syntax 6650for making that name weak, and a newline. 6651 6652If you don't define this macro or @code{ASM_WEAKEN_DECL}, GCC will not 6653support weak symbols and you should not define the @code{SUPPORTS_WEAK} 6654macro. 6655 6656@findex ASM_WEAKEN_DECL 6657@item ASM_WEAKEN_DECL (@var{stream}, @var{decl}, @var{name}, @var{value}) 6658Combines (and replaces) the function of @code{ASM_WEAKEN_LABEL} and 6659@code{ASM_OUTPUT_WEAK_ALIAS}, allowing access to the associated function 6660or variable decl. If @var{value} is not @code{NULL}, this C statement 6661should output to the stdio stream @var{stream} assembler code which 6662defines (equates) the weak symbol @var{name} to have the value 6663@var{value}. If @var{value} is @code{NULL}, it should output commands 6664to make @var{name} weak. 6665 6666@findex SUPPORTS_WEAK 6667@item SUPPORTS_WEAK 6668A C expression which evaluates to true if the target supports weak symbols. 6669 6670If you don't define this macro, @file{defaults.h} provides a default 6671definition. If either @code{ASM_WEAKEN_LABEL} or @code{ASM_WEAKEN_DECL} 6672is defined, the default definition is @samp{1}; otherwise, it is 6673@samp{0}. Define this macro if you want to control weak symbol support 6674with a compiler flag such as @option{-melf}. 6675 6676@findex MAKE_DECL_ONE_ONLY (@var{decl}) 6677@item MAKE_DECL_ONE_ONLY 6678A C statement (sans semicolon) to mark @var{decl} to be emitted as a 6679public symbol such that extra copies in multiple translation units will 6680be discarded by the linker. Define this macro if your object file 6681format provides support for this concept, such as the @samp{COMDAT} 6682section flags in the Microsoft Windows PE/COFF format, and this support 6683requires changes to @var{decl}, such as putting it in a separate section. 6684 6685@findex SUPPORTS_ONE_ONLY 6686@item SUPPORTS_ONE_ONLY 6687A C expression which evaluates to true if the target supports one-only 6688semantics. 6689 6690If you don't define this macro, @file{varasm.c} provides a default 6691definition. If @code{MAKE_DECL_ONE_ONLY} is defined, the default 6692definition is @samp{1}; otherwise, it is @samp{0}. Define this macro if 6693you want to control one-only symbol support with a compiler flag, or if 6694setting the @code{DECL_ONE_ONLY} flag is enough to mark a declaration to 6695be emitted as one-only. 6696 6697@deftypefn {Target Hook} void TARGET_ASM_ASSEMBLE_VISIBILITY (tree @var{decl}, const char *@var{visibility}) 6698This target hook is a function to output to @var{asm_out_file} some 6699commands that will make the symbol(s) associated with @var{decl} have 6700hidden, protected or internal visibility as specified by @var{visibility}. 6701@end deftypefn 6702 6703@findex ASM_OUTPUT_EXTERNAL 6704@item ASM_OUTPUT_EXTERNAL (@var{stream}, @var{decl}, @var{name}) 6705A C statement (sans semicolon) to output to the stdio stream 6706@var{stream} any text necessary for declaring the name of an external 6707symbol named @var{name} which is referenced in this compilation but 6708not defined. The value of @var{decl} is the tree node for the 6709declaration. 6710 6711This macro need not be defined if it does not need to output anything. 6712The GNU assembler and most Unix assemblers don't require anything. 6713 6714@findex ASM_OUTPUT_EXTERNAL_LIBCALL 6715@item ASM_OUTPUT_EXTERNAL_LIBCALL (@var{stream}, @var{symref}) 6716A C statement (sans semicolon) to output on @var{stream} an assembler 6717pseudo-op to declare a library function name external. The name of the 6718library function is given by @var{symref}, which has type @code{rtx} and 6719is a @code{symbol_ref}. 6720 6721This macro need not be defined if it does not need to output anything. 6722The GNU assembler and most Unix assemblers don't require anything. 6723 6724@findex ASM_OUTPUT_LABELREF 6725@item ASM_OUTPUT_LABELREF (@var{stream}, @var{name}) 6726A C statement (sans semicolon) to output to the stdio stream 6727@var{stream} a reference in assembler syntax to a label named 6728@var{name}. This should add @samp{_} to the front of the name, if that 6729is customary on your operating system, as it is in most Berkeley Unix 6730systems. This macro is used in @code{assemble_name}. 6731 6732@findex ASM_OUTPUT_SYMBOL_REF 6733@item ASM_OUTPUT_SYMBOL_REF (@var{stream}, @var{sym}) 6734A C statement (sans semicolon) to output a reference to 6735@code{SYMBOL_REF} @var{sym}. If not defined, @code{assemble_name} 6736will be used to output the name of the symbol. This macro may be used 6737to modify the way a symbol is referenced depending on information 6738encoded by @code{TARGET_ENCODE_SECTION_INFO}. 6739 6740@findex ASM_OUTPUT_LABEL_REF 6741@item ASM_OUTPUT_LABEL_REF (@var{stream}, @var{buf}) 6742A C statement (sans semicolon) to output a reference to @var{buf}, the 6743result of @code{ASM_GENERATE_INTERNAL_LABEL}. If not defined, 6744@code{assemble_name} will be used to output the name of the symbol. 6745This macro is not used by @code{output_asm_label}, or the @code{%l} 6746specifier that calls it; the intention is that this macro should be set 6747when it is necessary to output a label differently when its address is 6748being taken. 6749 6750@findex ASM_OUTPUT_INTERNAL_LABEL 6751@item ASM_OUTPUT_INTERNAL_LABEL (@var{stream}, @var{prefix}, @var{num}) 6752A C statement to output to the stdio stream @var{stream} a label whose 6753name is made from the string @var{prefix} and the number @var{num}. 6754 6755It is absolutely essential that these labels be distinct from the labels 6756used for user-level functions and variables. Otherwise, certain programs 6757will have name conflicts with internal labels. 6758 6759It is desirable to exclude internal labels from the symbol table of the 6760object file. Most assemblers have a naming convention for labels that 6761should be excluded; on many systems, the letter @samp{L} at the 6762beginning of a label has this effect. You should find out what 6763convention your system uses, and follow it. 6764 6765The usual definition of this macro is as follows: 6766 6767@example 6768fprintf (@var{stream}, "L%s%d:\n", @var{prefix}, @var{num}) 6769@end example 6770 6771@findex ASM_OUTPUT_DEBUG_LABEL 6772@item ASM_OUTPUT_DEBUG_LABEL (@var{stream}, @var{prefix}, @var{num}) 6773A C statement to output to the stdio stream @var{stream} a debug info 6774label whose name is made from the string @var{prefix} and the number 6775@var{num}. This is useful for VLIW targets, where debug info labels 6776may need to be treated differently than branch target labels. On some 6777systems, branch target labels must be at the beginning of instruction 6778bundles, but debug info labels can occur in the middle of instruction 6779bundles. 6780 6781If this macro is not defined, then @code{ASM_OUTPUT_INTERNAL_LABEL} will be 6782used. 6783 6784@findex ASM_GENERATE_INTERNAL_LABEL 6785@item ASM_GENERATE_INTERNAL_LABEL (@var{string}, @var{prefix}, @var{num}) 6786A C statement to store into the string @var{string} a label whose name 6787is made from the string @var{prefix} and the number @var{num}. 6788 6789This string, when output subsequently by @code{assemble_name}, should 6790produce the output that @code{ASM_OUTPUT_INTERNAL_LABEL} would produce 6791with the same @var{prefix} and @var{num}. 6792 6793If the string begins with @samp{*}, then @code{assemble_name} will 6794output the rest of the string unchanged. It is often convenient for 6795@code{ASM_GENERATE_INTERNAL_LABEL} to use @samp{*} in this way. If the 6796string doesn't start with @samp{*}, then @code{ASM_OUTPUT_LABELREF} gets 6797to output the string, and may change it. (Of course, 6798@code{ASM_OUTPUT_LABELREF} is also part of your machine description, so 6799you should know what it does on your machine.) 6800 6801@findex ASM_FORMAT_PRIVATE_NAME 6802@item ASM_FORMAT_PRIVATE_NAME (@var{outvar}, @var{name}, @var{number}) 6803A C expression to assign to @var{outvar} (which is a variable of type 6804@code{char *}) a newly allocated string made from the string 6805@var{name} and the number @var{number}, with some suitable punctuation 6806added. Use @code{alloca} to get space for the string. 6807 6808The string will be used as an argument to @code{ASM_OUTPUT_LABELREF} to 6809produce an assembler label for an internal static variable whose name is 6810@var{name}. Therefore, the string must be such as to result in valid 6811assembler code. The argument @var{number} is different each time this 6812macro is executed; it prevents conflicts between similarly-named 6813internal static variables in different scopes. 6814 6815Ideally this string should not be a valid C identifier, to prevent any 6816conflict with the user's own symbols. Most assemblers allow periods 6817or percent signs in assembler symbols; putting at least one of these 6818between the name and the number will suffice. 6819 6820@findex ASM_OUTPUT_DEF 6821@item ASM_OUTPUT_DEF (@var{stream}, @var{name}, @var{value}) 6822A C statement to output to the stdio stream @var{stream} assembler code 6823which defines (equates) the symbol @var{name} to have the value @var{value}. 6824 6825@findex SET_ASM_OP 6826If @code{SET_ASM_OP} is defined, a default definition is provided which is 6827correct for most systems. 6828 6829@findex ASM_OUTPUT_DEF_FROM_DECLS 6830@item ASM_OUTPUT_DEF_FROM_DECLS (@var{stream}, @var{decl_of_name}, @var{decl_of_value}) 6831A C statement to output to the stdio stream @var{stream} assembler code 6832which defines (equates) the symbol whose tree node is @var{decl_of_name} 6833to have the value of the tree node @var{decl_of_value}. This macro will 6834be used in preference to @samp{ASM_OUTPUT_DEF} if it is defined and if 6835the tree nodes are available. 6836 6837@findex SET_ASM_OP 6838If @code{SET_ASM_OP} is defined, a default definition is provided which is 6839correct for most systems. 6840 6841@findex ASM_OUTPUT_WEAK_ALIAS 6842@item ASM_OUTPUT_WEAK_ALIAS (@var{stream}, @var{name}, @var{value}) 6843A C statement to output to the stdio stream @var{stream} assembler code 6844which defines (equates) the weak symbol @var{name} to have the value 6845@var{value}. If @var{value} is @code{NULL}, it defines @var{name} as 6846an undefined weak symbol. 6847 6848Define this macro if the target only supports weak aliases; define 6849@code{ASM_OUTPUT_DEF} instead if possible. 6850 6851@findex OBJC_GEN_METHOD_LABEL 6852@item OBJC_GEN_METHOD_LABEL (@var{buf}, @var{is_inst}, @var{class_name}, @var{cat_name}, @var{sel_name}) 6853Define this macro to override the default assembler names used for 6854Objective-C methods. 6855 6856The default name is a unique method number followed by the name of the 6857class (e.g.@: @samp{_1_Foo}). For methods in categories, the name of 6858the category is also included in the assembler name (e.g.@: 6859@samp{_1_Foo_Bar}). 6860 6861These names are safe on most systems, but make debugging difficult since 6862the method's selector is not present in the name. Therefore, particular 6863systems define other ways of computing names. 6864 6865@var{buf} is an expression of type @code{char *} which gives you a 6866buffer in which to store the name; its length is as long as 6867@var{class_name}, @var{cat_name} and @var{sel_name} put together, plus 686850 characters extra. 6869 6870The argument @var{is_inst} specifies whether the method is an instance 6871method or a class method; @var{class_name} is the name of the class; 6872@var{cat_name} is the name of the category (or @code{NULL} if the method is not 6873in a category); and @var{sel_name} is the name of the selector. 6874 6875On systems where the assembler can handle quoted names, you can use this 6876macro to provide more human-readable names. 6877 6878@findex ASM_DECLARE_CLASS_REFERENCE 6879@item ASM_DECLARE_CLASS_REFERENCE (@var{stream}, @var{name}) 6880A C statement (sans semicolon) to output to the stdio stream 6881@var{stream} commands to declare that the label @var{name} is an 6882Objective-C class reference. This is only needed for targets whose 6883linkers have special support for NeXT-style runtimes. 6884 6885@findex ASM_DECLARE_UNRESOLVED_REFERENCE 6886@item ASM_DECLARE_UNRESOLVED_REFERENCE (@var{stream}, @var{name}) 6887A C statement (sans semicolon) to output to the stdio stream 6888@var{stream} commands to declare that the label @var{name} is an 6889unresolved Objective-C class reference. This is only needed for targets 6890whose linkers have special support for NeXT-style runtimes. 6891@end table 6892 6893@node Initialization 6894@subsection How Initialization Functions Are Handled 6895@cindex initialization routines 6896@cindex termination routines 6897@cindex constructors, output of 6898@cindex destructors, output of 6899 6900The compiled code for certain languages includes @dfn{constructors} 6901(also called @dfn{initialization routines})---functions to initialize 6902data in the program when the program is started. These functions need 6903to be called before the program is ``started''---that is to say, before 6904@code{main} is called. 6905 6906Compiling some languages generates @dfn{destructors} (also called 6907@dfn{termination routines}) that should be called when the program 6908terminates. 6909 6910To make the initialization and termination functions work, the compiler 6911must output something in the assembler code to cause those functions to 6912be called at the appropriate time. When you port the compiler to a new 6913system, you need to specify how to do this. 6914 6915There are two major ways that GCC currently supports the execution of 6916initialization and termination functions. Each way has two variants. 6917Much of the structure is common to all four variations. 6918 6919@findex __CTOR_LIST__ 6920@findex __DTOR_LIST__ 6921The linker must build two lists of these functions---a list of 6922initialization functions, called @code{__CTOR_LIST__}, and a list of 6923termination functions, called @code{__DTOR_LIST__}. 6924 6925Each list always begins with an ignored function pointer (which may hold 69260, @minus{}1, or a count of the function pointers after it, depending on 6927the environment). This is followed by a series of zero or more function 6928pointers to constructors (or destructors), followed by a function 6929pointer containing zero. 6930 6931Depending on the operating system and its executable file format, either 6932@file{crtstuff.c} or @file{libgcc2.c} traverses these lists at startup 6933time and exit time. Constructors are called in reverse order of the 6934list; destructors in forward order. 6935 6936The best way to handle static constructors works only for object file 6937formats which provide arbitrarily-named sections. A section is set 6938aside for a list of constructors, and another for a list of destructors. 6939Traditionally these are called @samp{.ctors} and @samp{.dtors}. Each 6940object file that defines an initialization function also puts a word in 6941the constructor section to point to that function. The linker 6942accumulates all these words into one contiguous @samp{.ctors} section. 6943Termination functions are handled similarly. 6944 6945This method will be chosen as the default by @file{target-def.h} if 6946@code{TARGET_ASM_NAMED_SECTION} is defined. A target that does not 6947support arbitrary sections, but does support special designated 6948constructor and destructor sections may define @code{CTORS_SECTION_ASM_OP} 6949and @code{DTORS_SECTION_ASM_OP} to achieve the same effect. 6950 6951When arbitrary sections are available, there are two variants, depending 6952upon how the code in @file{crtstuff.c} is called. On systems that 6953support a @dfn{.init} section which is executed at program startup, 6954parts of @file{crtstuff.c} are compiled into that section. The 6955program is linked by the @command{gcc} driver like this: 6956 6957@example 6958ld -o @var{output_file} crti.o crtbegin.o @dots{} -lgcc crtend.o crtn.o 6959@end example 6960 6961The prologue of a function (@code{__init}) appears in the @code{.init} 6962section of @file{crti.o}; the epilogue appears in @file{crtn.o}. Likewise 6963for the function @code{__fini} in the @dfn{.fini} section. Normally these 6964files are provided by the operating system or by the GNU C library, but 6965are provided by GCC for a few targets. 6966 6967The objects @file{crtbegin.o} and @file{crtend.o} are (for most targets) 6968compiled from @file{crtstuff.c}. They contain, among other things, code 6969fragments within the @code{.init} and @code{.fini} sections that branch 6970to routines in the @code{.text} section. The linker will pull all parts 6971of a section together, which results in a complete @code{__init} function 6972that invokes the routines we need at startup. 6973 6974To use this variant, you must define the @code{INIT_SECTION_ASM_OP} 6975macro properly. 6976 6977If no init section is available, when GCC compiles any function called 6978@code{main} (or more accurately, any function designated as a program 6979entry point by the language front end calling @code{expand_main_function}), 6980it inserts a procedure call to @code{__main} as the first executable code 6981after the function prologue. The @code{__main} function is defined 6982in @file{libgcc2.c} and runs the global constructors. 6983 6984In file formats that don't support arbitrary sections, there are again 6985two variants. In the simplest variant, the GNU linker (GNU @code{ld}) 6986and an `a.out' format must be used. In this case, 6987@code{TARGET_ASM_CONSTRUCTOR} is defined to produce a @code{.stabs} 6988entry of type @samp{N_SETT}, referencing the name @code{__CTOR_LIST__}, 6989and with the address of the void function containing the initialization 6990code as its value. The GNU linker recognizes this as a request to add 6991the value to a @dfn{set}; the values are accumulated, and are eventually 6992placed in the executable as a vector in the format described above, with 6993a leading (ignored) count and a trailing zero element. 6994@code{TARGET_ASM_DESTRUCTOR} is handled similarly. Since no init 6995section is available, the absence of @code{INIT_SECTION_ASM_OP} causes 6996the compilation of @code{main} to call @code{__main} as above, starting 6997the initialization process. 6998 6999The last variant uses neither arbitrary sections nor the GNU linker. 7000This is preferable when you want to do dynamic linking and when using 7001file formats which the GNU linker does not support, such as `ECOFF'@. In 7002this case, @code{TARGET_HAVE_CTORS_DTORS} is false, initialization and 7003termination functions are recognized simply by their names. This requires 7004an extra program in the linkage step, called @command{collect2}. This program 7005pretends to be the linker, for use with GCC; it does its job by running 7006the ordinary linker, but also arranges to include the vectors of 7007initialization and termination functions. These functions are called 7008via @code{__main} as described above. In order to use this method, 7009@code{use_collect2} must be defined in the target in @file{config.gcc}. 7010 7011@ifinfo 7012The following section describes the specific macros that control and 7013customize the handling of initialization and termination functions. 7014@end ifinfo 7015 7016@node Macros for Initialization 7017@subsection Macros Controlling Initialization Routines 7018 7019Here are the macros that control how the compiler handles initialization 7020and termination functions: 7021 7022@table @code 7023@findex INIT_SECTION_ASM_OP 7024@item INIT_SECTION_ASM_OP 7025If defined, a C string constant, including spacing, for the assembler 7026operation to identify the following data as initialization code. If not 7027defined, GCC will assume such a section does not exist. When you are 7028using special sections for initialization and termination functions, this 7029macro also controls how @file{crtstuff.c} and @file{libgcc2.c} arrange to 7030run the initialization functions. 7031 7032@item HAS_INIT_SECTION 7033@findex HAS_INIT_SECTION 7034If defined, @code{main} will not call @code{__main} as described above. 7035This macro should be defined for systems that control start-up code 7036on a symbol-by-symbol basis, such as OSF/1, and should not 7037be defined explicitly for systems that support @code{INIT_SECTION_ASM_OP}. 7038 7039@item LD_INIT_SWITCH 7040@findex LD_INIT_SWITCH 7041If defined, a C string constant for a switch that tells the linker that 7042the following symbol is an initialization routine. 7043 7044@item LD_FINI_SWITCH 7045@findex LD_FINI_SWITCH 7046If defined, a C string constant for a switch that tells the linker that 7047the following symbol is a finalization routine. 7048 7049@item COLLECT_SHARED_INIT_FUNC (@var{stream}, @var{func}) 7050If defined, a C statement that will write a function that can be 7051automatically called when a shared library is loaded. The function 7052should call @var{func}, which takes no arguments. If not defined, and 7053the object format requires an explicit initialization function, then a 7054function called @code{_GLOBAL__DI} will be generated. 7055 7056This function and the following one are used by collect2 when linking a 7057shared library that needs constructors or destructors, or has DWARF2 7058exception tables embedded in the code. 7059 7060@item COLLECT_SHARED_FINI_FUNC (@var{stream}, @var{func}) 7061If defined, a C statement that will write a function that can be 7062automatically called when a shared library is unloaded. The function 7063should call @var{func}, which takes no arguments. If not defined, and 7064the object format requires an explicit finalization function, then a 7065function called @code{_GLOBAL__DD} will be generated. 7066 7067@item INVOKE__main 7068@findex INVOKE__main 7069If defined, @code{main} will call @code{__main} despite the presence of 7070@code{INIT_SECTION_ASM_OP}. This macro should be defined for systems 7071where the init section is not actually run automatically, but is still 7072useful for collecting the lists of constructors and destructors. 7073 7074@item SUPPORTS_INIT_PRIORITY 7075@findex SUPPORTS_INIT_PRIORITY 7076If nonzero, the C++ @code{init_priority} attribute is supported and the 7077compiler should emit instructions to control the order of initialization 7078of objects. If zero, the compiler will issue an error message upon 7079encountering an @code{init_priority} attribute. 7080@end table 7081 7082@deftypefn {Target Hook} bool TARGET_HAVE_CTORS_DTORS 7083This value is true if the target supports some ``native'' method of 7084collecting constructors and destructors to be run at startup and exit. 7085It is false if we must use @command{collect2}. 7086@end deftypefn 7087 7088@deftypefn {Target Hook} void TARGET_ASM_CONSTRUCTOR (rtx @var{symbol}, int @var{priority}) 7089If defined, a function that outputs assembler code to arrange to call 7090the function referenced by @var{symbol} at initialization time. 7091 7092Assume that @var{symbol} is a @code{SYMBOL_REF} for a function taking 7093no arguments and with no return value. If the target supports initialization 7094priorities, @var{priority} is a value between 0 and @code{MAX_INIT_PRIORITY}; 7095otherwise it must be @code{DEFAULT_INIT_PRIORITY}. 7096 7097If this macro is not defined by the target, a suitable default will 7098be chosen if (1) the target supports arbitrary section names, (2) the 7099target defines @code{CTORS_SECTION_ASM_OP}, or (3) @code{USE_COLLECT2} 7100is not defined. 7101@end deftypefn 7102 7103@deftypefn {Target Hook} void TARGET_ASM_DESTRUCTOR (rtx @var{symbol}, int @var{priority}) 7104This is like @code{TARGET_ASM_CONSTRUCTOR} but used for termination 7105functions rather than initialization functions. 7106@end deftypefn 7107 7108If @code{TARGET_HAVE_CTORS_DTORS} is true, the initialization routine 7109generated for the generated object file will have static linkage. 7110 7111If your system uses @command{collect2} as the means of processing 7112constructors, then that program normally uses @command{nm} to scan 7113an object file for constructor functions to be called. 7114 7115On certain kinds of systems, you can define these macros to make 7116@command{collect2} work faster (and, in some cases, make it work at all): 7117 7118@table @code 7119@findex OBJECT_FORMAT_COFF 7120@item OBJECT_FORMAT_COFF 7121Define this macro if the system uses COFF (Common Object File Format) 7122object files, so that @command{collect2} can assume this format and scan 7123object files directly for dynamic constructor/destructor functions. 7124 7125@findex OBJECT_FORMAT_ROSE 7126@item OBJECT_FORMAT_ROSE 7127Define this macro if the system uses ROSE format object files, so that 7128@command{collect2} can assume this format and scan object files directly 7129for dynamic constructor/destructor functions. 7130 7131These macros are effective only in a native compiler; @command{collect2} as 7132part of a cross compiler always uses @command{nm} for the target machine. 7133 7134@findex REAL_NM_FILE_NAME 7135@item REAL_NM_FILE_NAME 7136Define this macro as a C string constant containing the file name to use 7137to execute @command{nm}. The default is to search the path normally for 7138@command{nm}. 7139 7140If your system supports shared libraries and has a program to list the 7141dynamic dependencies of a given library or executable, you can define 7142these macros to enable support for running initialization and 7143termination functions in shared libraries: 7144 7145@findex LDD_SUFFIX 7146@item LDD_SUFFIX 7147Define this macro to a C string constant containing the name of the program 7148which lists dynamic dependencies, like @command{"ldd"} under SunOS 4. 7149 7150@findex PARSE_LDD_OUTPUT 7151@item PARSE_LDD_OUTPUT (@var{ptr}) 7152Define this macro to be C code that extracts filenames from the output 7153of the program denoted by @code{LDD_SUFFIX}. @var{ptr} is a variable 7154of type @code{char *} that points to the beginning of a line of output 7155from @code{LDD_SUFFIX}. If the line lists a dynamic dependency, the 7156code must advance @var{ptr} to the beginning of the filename on that 7157line. Otherwise, it must set @var{ptr} to @code{NULL}. 7158@end table 7159 7160@node Instruction Output 7161@subsection Output of Assembler Instructions 7162 7163@c prevent bad page break with this line 7164This describes assembler instruction output. 7165 7166@table @code 7167@findex REGISTER_NAMES 7168@item REGISTER_NAMES 7169A C initializer containing the assembler's names for the machine 7170registers, each one as a C string constant. This is what translates 7171register numbers in the compiler into assembler language. 7172 7173@findex ADDITIONAL_REGISTER_NAMES 7174@item ADDITIONAL_REGISTER_NAMES 7175If defined, a C initializer for an array of structures containing a name 7176and a register number. This macro defines additional names for hard 7177registers, thus allowing the @code{asm} option in declarations to refer 7178to registers using alternate names. 7179 7180@findex ASM_OUTPUT_OPCODE 7181@item ASM_OUTPUT_OPCODE (@var{stream}, @var{ptr}) 7182Define this macro if you are using an unusual assembler that 7183requires different names for the machine instructions. 7184 7185The definition is a C statement or statements which output an 7186assembler instruction opcode to the stdio stream @var{stream}. The 7187macro-operand @var{ptr} is a variable of type @code{char *} which 7188points to the opcode name in its ``internal'' form---the form that is 7189written in the machine description. The definition should output the 7190opcode name to @var{stream}, performing any translation you desire, and 7191increment the variable @var{ptr} to point at the end of the opcode 7192so that it will not be output twice. 7193 7194In fact, your macro definition may process less than the entire opcode 7195name, or more than the opcode name; but if you want to process text 7196that includes @samp{%}-sequences to substitute operands, you must take 7197care of the substitution yourself. Just be sure to increment 7198@var{ptr} over whatever text should not be output normally. 7199 7200@findex recog_data.operand 7201If you need to look at the operand values, they can be found as the 7202elements of @code{recog_data.operand}. 7203 7204If the macro definition does nothing, the instruction is output 7205in the usual way. 7206 7207@findex FINAL_PRESCAN_INSN 7208@item FINAL_PRESCAN_INSN (@var{insn}, @var{opvec}, @var{noperands}) 7209If defined, a C statement to be executed just prior to the output of 7210assembler code for @var{insn}, to modify the extracted operands so 7211they will be output differently. 7212 7213Here the argument @var{opvec} is the vector containing the operands 7214extracted from @var{insn}, and @var{noperands} is the number of 7215elements of the vector which contain meaningful data for this insn. 7216The contents of this vector are what will be used to convert the insn 7217template into assembler code, so you can change the assembler output 7218by changing the contents of the vector. 7219 7220This macro is useful when various assembler syntaxes share a single 7221file of instruction patterns; by defining this macro differently, you 7222can cause a large class of instructions to be output differently (such 7223as with rearranged operands). Naturally, variations in assembler 7224syntax affecting individual insn patterns ought to be handled by 7225writing conditional output routines in those patterns. 7226 7227If this macro is not defined, it is equivalent to a null statement. 7228 7229@findex FINAL_PRESCAN_LABEL 7230@item FINAL_PRESCAN_LABEL 7231If defined, @code{FINAL_PRESCAN_INSN} will be called on each 7232@code{CODE_LABEL}. In that case, @var{opvec} will be a null pointer and 7233@var{noperands} will be zero. 7234 7235@findex PRINT_OPERAND 7236@item PRINT_OPERAND (@var{stream}, @var{x}, @var{code}) 7237A C compound statement to output to stdio stream @var{stream} the 7238assembler syntax for an instruction operand @var{x}. @var{x} is an 7239RTL expression. 7240 7241@var{code} is a value that can be used to specify one of several ways 7242of printing the operand. It is used when identical operands must be 7243printed differently depending on the context. @var{code} comes from 7244the @samp{%} specification that was used to request printing of the 7245operand. If the specification was just @samp{%@var{digit}} then 7246@var{code} is 0; if the specification was @samp{%@var{ltr} 7247@var{digit}} then @var{code} is the ASCII code for @var{ltr}. 7248 7249@findex reg_names 7250If @var{x} is a register, this macro should print the register's name. 7251The names can be found in an array @code{reg_names} whose type is 7252@code{char *[]}. @code{reg_names} is initialized from 7253@code{REGISTER_NAMES}. 7254 7255When the machine description has a specification @samp{%@var{punct}} 7256(a @samp{%} followed by a punctuation character), this macro is called 7257with a null pointer for @var{x} and the punctuation character for 7258@var{code}. 7259 7260@findex PRINT_OPERAND_PUNCT_VALID_P 7261@item PRINT_OPERAND_PUNCT_VALID_P (@var{code}) 7262A C expression which evaluates to true if @var{code} is a valid 7263punctuation character for use in the @code{PRINT_OPERAND} macro. If 7264@code{PRINT_OPERAND_PUNCT_VALID_P} is not defined, it means that no 7265punctuation characters (except for the standard one, @samp{%}) are used 7266in this way. 7267 7268@findex PRINT_OPERAND_ADDRESS 7269@item PRINT_OPERAND_ADDRESS (@var{stream}, @var{x}) 7270A C compound statement to output to stdio stream @var{stream} the 7271assembler syntax for an instruction operand that is a memory reference 7272whose address is @var{x}. @var{x} is an RTL expression. 7273 7274@cindex @code{TARGET_ENCODE_SECTION_INFO} usage 7275On some machines, the syntax for a symbolic address depends on the 7276section that the address refers to. On these machines, define the hook 7277@code{TARGET_ENCODE_SECTION_INFO} to store the information into the 7278@code{symbol_ref}, and then check for it here. @xref{Assembler Format}. 7279 7280@findex DBR_OUTPUT_SEQEND 7281@findex dbr_sequence_length 7282@item DBR_OUTPUT_SEQEND(@var{file}) 7283A C statement, to be executed after all slot-filler instructions have 7284been output. If necessary, call @code{dbr_sequence_length} to 7285determine the number of slots filled in a sequence (zero if not 7286currently outputting a sequence), to decide how many no-ops to output, 7287or whatever. 7288 7289Don't define this macro if it has nothing to do, but it is helpful in 7290reading assembly output if the extent of the delay sequence is made 7291explicit (e.g.@: with white space). 7292 7293@findex final_sequence 7294Note that output routines for instructions with delay slots must be 7295prepared to deal with not being output as part of a sequence 7296(i.e.@: when the scheduling pass is not run, or when no slot fillers could be 7297found.) The variable @code{final_sequence} is null when not 7298processing a sequence, otherwise it contains the @code{sequence} rtx 7299being output. 7300 7301@findex REGISTER_PREFIX 7302@findex LOCAL_LABEL_PREFIX 7303@findex USER_LABEL_PREFIX 7304@findex IMMEDIATE_PREFIX 7305@findex asm_fprintf 7306@item REGISTER_PREFIX 7307@itemx LOCAL_LABEL_PREFIX 7308@itemx USER_LABEL_PREFIX 7309@itemx IMMEDIATE_PREFIX 7310If defined, C string expressions to be used for the @samp{%R}, @samp{%L}, 7311@samp{%U}, and @samp{%I} options of @code{asm_fprintf} (see 7312@file{final.c}). These are useful when a single @file{md} file must 7313support multiple assembler formats. In that case, the various @file{tm.h} 7314files can define these macros differently. 7315 7316@item ASM_FPRINTF_EXTENSIONS(@var{file}, @var{argptr}, @var{format}) 7317@findex ASM_FPRINTF_EXTENSIONS 7318If defined this macro should expand to a series of @code{case} 7319statements which will be parsed inside the @code{switch} statement of 7320the @code{asm_fprintf} function. This allows targets to define extra 7321printf formats which may useful when generating their assembler 7322statements. Note that upper case letters are reserved for future 7323generic extensions to asm_fprintf, and so are not available to target 7324specific code. The output file is given by the parameter @var{file}. 7325The varargs input pointer is @var{argptr} and the rest of the format 7326string, starting the character after the one that is being switched 7327upon, is pointed to by @var{format}. 7328 7329@findex ASSEMBLER_DIALECT 7330@item ASSEMBLER_DIALECT 7331If your target supports multiple dialects of assembler language (such as 7332different opcodes), define this macro as a C expression that gives the 7333numeric index of the assembler language dialect to use, with zero as the 7334first variant. 7335 7336If this macro is defined, you may use constructs of the form 7337@smallexample 7338@samp{@{option0|option1|option2@dots{}@}} 7339@end smallexample 7340@noindent 7341in the output templates of patterns (@pxref{Output Template}) or in the 7342first argument of @code{asm_fprintf}. This construct outputs 7343@samp{option0}, @samp{option1}, @samp{option2}, etc., if the value of 7344@code{ASSEMBLER_DIALECT} is zero, one, two, etc. Any special characters 7345within these strings retain their usual meaning. If there are fewer 7346alternatives within the braces than the value of 7347@code{ASSEMBLER_DIALECT}, the construct outputs nothing. 7348 7349If you do not define this macro, the characters @samp{@{}, @samp{|} and 7350@samp{@}} do not have any special meaning when used in templates or 7351operands to @code{asm_fprintf}. 7352 7353Define the macros @code{REGISTER_PREFIX}, @code{LOCAL_LABEL_PREFIX}, 7354@code{USER_LABEL_PREFIX} and @code{IMMEDIATE_PREFIX} if you can express 7355the variations in assembler language syntax with that mechanism. Define 7356@code{ASSEMBLER_DIALECT} and use the @samp{@{option0|option1@}} syntax 7357if the syntax variant are larger and involve such things as different 7358opcodes or operand order. 7359 7360@findex ASM_OUTPUT_REG_PUSH 7361@item ASM_OUTPUT_REG_PUSH (@var{stream}, @var{regno}) 7362A C expression to output to @var{stream} some assembler code 7363which will push hard register number @var{regno} onto the stack. 7364The code need not be optimal, since this macro is used only when 7365profiling. 7366 7367@findex ASM_OUTPUT_REG_POP 7368@item ASM_OUTPUT_REG_POP (@var{stream}, @var{regno}) 7369A C expression to output to @var{stream} some assembler code 7370which will pop hard register number @var{regno} off of the stack. 7371The code need not be optimal, since this macro is used only when 7372profiling. 7373@end table 7374 7375@node Dispatch Tables 7376@subsection Output of Dispatch Tables 7377 7378@c prevent bad page break with this line 7379This concerns dispatch tables. 7380 7381@table @code 7382@cindex dispatch table 7383@findex ASM_OUTPUT_ADDR_DIFF_ELT 7384@item ASM_OUTPUT_ADDR_DIFF_ELT (@var{stream}, @var{body}, @var{value}, @var{rel}) 7385A C statement to output to the stdio stream @var{stream} an assembler 7386pseudo-instruction to generate a difference between two labels. 7387@var{value} and @var{rel} are the numbers of two internal labels. The 7388definitions of these labels are output using 7389@code{ASM_OUTPUT_INTERNAL_LABEL}, and they must be printed in the same 7390way here. For example, 7391 7392@example 7393fprintf (@var{stream}, "\t.word L%d-L%d\n", 7394 @var{value}, @var{rel}) 7395@end example 7396 7397You must provide this macro on machines where the addresses in a 7398dispatch table are relative to the table's own address. If defined, GCC 7399will also use this macro on all machines when producing PIC@. 7400@var{body} is the body of the @code{ADDR_DIFF_VEC}; it is provided so that the 7401mode and flags can be read. 7402 7403@findex ASM_OUTPUT_ADDR_VEC_ELT 7404@item ASM_OUTPUT_ADDR_VEC_ELT (@var{stream}, @var{value}) 7405This macro should be provided on machines where the addresses 7406in a dispatch table are absolute. 7407 7408The definition should be a C statement to output to the stdio stream 7409@var{stream} an assembler pseudo-instruction to generate a reference to 7410a label. @var{value} is the number of an internal label whose 7411definition is output using @code{ASM_OUTPUT_INTERNAL_LABEL}. 7412For example, 7413 7414@example 7415fprintf (@var{stream}, "\t.word L%d\n", @var{value}) 7416@end example 7417 7418@findex ASM_OUTPUT_CASE_LABEL 7419@item ASM_OUTPUT_CASE_LABEL (@var{stream}, @var{prefix}, @var{num}, @var{table}) 7420Define this if the label before a jump-table needs to be output 7421specially. The first three arguments are the same as for 7422@code{ASM_OUTPUT_INTERNAL_LABEL}; the fourth argument is the 7423jump-table which follows (a @code{jump_insn} containing an 7424@code{addr_vec} or @code{addr_diff_vec}). 7425 7426This feature is used on system V to output a @code{swbeg} statement 7427for the table. 7428 7429If this macro is not defined, these labels are output with 7430@code{ASM_OUTPUT_INTERNAL_LABEL}. 7431 7432@findex ASM_OUTPUT_CASE_END 7433@item ASM_OUTPUT_CASE_END (@var{stream}, @var{num}, @var{table}) 7434Define this if something special must be output at the end of a 7435jump-table. The definition should be a C statement to be executed 7436after the assembler code for the table is written. It should write 7437the appropriate code to stdio stream @var{stream}. The argument 7438@var{table} is the jump-table insn, and @var{num} is the label-number 7439of the preceding label. 7440 7441If this macro is not defined, nothing special is output at the end of 7442the jump-table. 7443@end table 7444 7445@node Exception Region Output 7446@subsection Assembler Commands for Exception Regions 7447 7448@c prevent bad page break with this line 7449 7450This describes commands marking the start and the end of an exception 7451region. 7452 7453@table @code 7454@findex EH_FRAME_SECTION_NAME 7455@item EH_FRAME_SECTION_NAME 7456If defined, a C string constant for the name of the section containing 7457exception handling frame unwind information. If not defined, GCC will 7458provide a default definition if the target supports named sections. 7459@file{crtstuff.c} uses this macro to switch to the appropriate section. 7460 7461You should define this symbol if your target supports DWARF 2 frame 7462unwind information and the default definition does not work. 7463 7464@findex EH_FRAME_IN_DATA_SECTION 7465@item EH_FRAME_IN_DATA_SECTION 7466If defined, DWARF 2 frame unwind information will be placed in the 7467data section even though the target supports named sections. This 7468might be necessary, for instance, if the system linker does garbage 7469collection and sections cannot be marked as not to be collected. 7470 7471Do not define this macro unless @code{TARGET_ASM_NAMED_SECTION} is 7472also defined. 7473 7474@findex MASK_RETURN_ADDR 7475@item MASK_RETURN_ADDR 7476An rtx used to mask the return address found via @code{RETURN_ADDR_RTX}, so 7477that it does not contain any extraneous set bits in it. 7478 7479@findex DWARF2_UNWIND_INFO 7480@item DWARF2_UNWIND_INFO 7481Define this macro to 0 if your target supports DWARF 2 frame unwind 7482information, but it does not yet work with exception handling. 7483Otherwise, if your target supports this information (if it defines 7484@samp{INCOMING_RETURN_ADDR_RTX} and either @samp{UNALIGNED_INT_ASM_OP} 7485or @samp{OBJECT_FORMAT_ELF}), GCC will provide a default definition of 74861. 7487 7488If this macro is defined to 1, the DWARF 2 unwinder will be the default 7489exception handling mechanism; otherwise, @code{setjmp}/@code{longjmp} will be used by 7490default. 7491 7492If this macro is defined to anything, the DWARF 2 unwinder will be used 7493instead of inline unwinders and @code{__unwind_function} in the non-@code{setjmp} case. 7494 7495@findex DWARF_CIE_DATA_ALIGNMENT 7496@item DWARF_CIE_DATA_ALIGNMENT 7497This macro need only be defined if the target might save registers in the 7498function prologue at an offset to the stack pointer that is not aligned to 7499@code{UNITS_PER_WORD}. The definition should be the negative minimum 7500alignment if @code{STACK_GROWS_DOWNWARD} is defined, and the positive 7501minimum alignment otherwise. @xref{SDB and DWARF}. Only applicable if 7502the target supports DWARF 2 frame unwind information. 7503 7504@end table 7505 7506@deftypefn {Target Hook} void TARGET_ASM_EXCEPTION_SECTION () 7507If defined, a function that switches to the section in which the main 7508exception table is to be placed (@pxref{Sections}). The default is a 7509function that switches to a section named @code{.gcc_except_table} on 7510machines that support named sections via 7511@code{TARGET_ASM_NAMED_SECTION}, otherwise if @option{-fpic} or 7512@option{-fPIC} is in effect, the @code{data_section}, otherwise the 7513@code{readonly_data_section}. 7514@end deftypefn 7515 7516@deftypefn {Target Hook} void TARGET_ASM_EH_FRAME_SECTION () 7517If defined, a function that switches to the section in which the DWARF 2 7518frame unwind information to be placed (@pxref{Sections}). The default 7519is a function that outputs a standard GAS section directive, if 7520@code{EH_FRAME_SECTION_NAME} is defined, or else a data section 7521directive followed by a synthetic label. 7522@end deftypefn 7523 7524@deftypevar {Target Hook} bool TARGET_TERMINATE_DW2_EH_FRAME_INFO 7525Contains the value true if the target should add a zero word onto the 7526end of a Dwarf-2 frame info section when used for exception handling. 7527Default value is false if @code{EH_FRAME_SECTION_NAME} is defined, and 7528true otherwise. 7529@end deftypevar 7530 7531@node Alignment Output 7532@subsection Assembler Commands for Alignment 7533 7534@c prevent bad page break with this line 7535This describes commands for alignment. 7536 7537@table @code 7538@findex JUMP_ALIGN 7539@item JUMP_ALIGN (@var{label}) 7540The alignment (log base 2) to put in front of @var{label}, which is 7541a common destination of jumps and has no fallthru incoming edge. 7542 7543This macro need not be defined if you don't want any special alignment 7544to be done at such a time. Most machine descriptions do not currently 7545define the macro. 7546 7547Unless it's necessary to inspect the @var{label} parameter, it is better 7548to set the variable @var{align_jumps} in the target's 7549@code{OVERRIDE_OPTIONS}. Otherwise, you should try to honor the user's 7550selection in @var{align_jumps} in a @code{JUMP_ALIGN} implementation. 7551 7552@findex LABEL_ALIGN_AFTER_BARRIER 7553@item LABEL_ALIGN_AFTER_BARRIER (@var{label}) 7554The alignment (log base 2) to put in front of @var{label}, which follows 7555a @code{BARRIER}. 7556 7557This macro need not be defined if you don't want any special alignment 7558to be done at such a time. Most machine descriptions do not currently 7559define the macro. 7560 7561@findex LABEL_ALIGN_AFTER_BARRIER_MAX_SKIP 7562@item LABEL_ALIGN_AFTER_BARRIER_MAX_SKIP 7563The maximum number of bytes to skip when applying 7564@code{LABEL_ALIGN_AFTER_BARRIER}. This works only if 7565@code{ASM_OUTPUT_MAX_SKIP_ALIGN} is defined. 7566 7567@findex LOOP_ALIGN 7568@item LOOP_ALIGN (@var{label}) 7569The alignment (log base 2) to put in front of @var{label}, which follows 7570a @code{NOTE_INSN_LOOP_BEG} note. 7571 7572This macro need not be defined if you don't want any special alignment 7573to be done at such a time. Most machine descriptions do not currently 7574define the macro. 7575 7576Unless it's necessary to inspect the @var{label} parameter, it is better 7577to set the variable @code{align_loops} in the target's 7578@code{OVERRIDE_OPTIONS}. Otherwise, you should try to honor the user's 7579selection in @code{align_loops} in a @code{LOOP_ALIGN} implementation. 7580 7581@findex LOOP_ALIGN_MAX_SKIP 7582@item LOOP_ALIGN_MAX_SKIP 7583The maximum number of bytes to skip when applying @code{LOOP_ALIGN}. 7584This works only if @code{ASM_OUTPUT_MAX_SKIP_ALIGN} is defined. 7585 7586@findex LABEL_ALIGN 7587@item LABEL_ALIGN (@var{label}) 7588The alignment (log base 2) to put in front of @var{label}. 7589If @code{LABEL_ALIGN_AFTER_BARRIER} / @code{LOOP_ALIGN} specify a different alignment, 7590the maximum of the specified values is used. 7591 7592Unless it's necessary to inspect the @var{label} parameter, it is better 7593to set the variable @code{align_labels} in the target's 7594@code{OVERRIDE_OPTIONS}. Otherwise, you should try to honor the user's 7595selection in @code{align_labels} in a @code{LABEL_ALIGN} implementation. 7596 7597@findex LABEL_ALIGN_MAX_SKIP 7598@item LABEL_ALIGN_MAX_SKIP 7599The maximum number of bytes to skip when applying @code{LABEL_ALIGN}. 7600This works only if @code{ASM_OUTPUT_MAX_SKIP_ALIGN} is defined. 7601 7602@findex ASM_OUTPUT_SKIP 7603@item ASM_OUTPUT_SKIP (@var{stream}, @var{nbytes}) 7604A C statement to output to the stdio stream @var{stream} an assembler 7605instruction to advance the location counter by @var{nbytes} bytes. 7606Those bytes should be zero when loaded. @var{nbytes} will be a C 7607expression of type @code{int}. 7608 7609@findex ASM_NO_SKIP_IN_TEXT 7610@item ASM_NO_SKIP_IN_TEXT 7611Define this macro if @code{ASM_OUTPUT_SKIP} should not be used in the 7612text section because it fails to put zeros in the bytes that are skipped. 7613This is true on many Unix systems, where the pseudo--op to skip bytes 7614produces no-op instructions rather than zeros when used in the text 7615section. 7616 7617@findex ASM_OUTPUT_ALIGN 7618@item ASM_OUTPUT_ALIGN (@var{stream}, @var{power}) 7619A C statement to output to the stdio stream @var{stream} an assembler 7620command to advance the location counter to a multiple of 2 to the 7621@var{power} bytes. @var{power} will be a C expression of type @code{int}. 7622 7623@findex ASM_OUTPUT_ALIGN_WITH_NOP 7624@item ASM_OUTPUT_ALIGN_WITH_NOP (@var{stream}, @var{power}) 7625Like @code{ASM_OUTPUT_ALIGN}, except that the ``nop'' instruction is used 7626for padding, if necessary. 7627 7628@findex ASM_OUTPUT_MAX_SKIP_ALIGN 7629@item ASM_OUTPUT_MAX_SKIP_ALIGN (@var{stream}, @var{power}, @var{max_skip}) 7630A C statement to output to the stdio stream @var{stream} an assembler 7631command to advance the location counter to a multiple of 2 to the 7632@var{power} bytes, but only if @var{max_skip} or fewer bytes are needed to 7633satisfy the alignment request. @var{power} and @var{max_skip} will be 7634a C expression of type @code{int}. 7635@end table 7636 7637@need 3000 7638@node Debugging Info 7639@section Controlling Debugging Information Format 7640 7641@c prevent bad page break with this line 7642This describes how to specify debugging information. 7643 7644@menu 7645* All Debuggers:: Macros that affect all debugging formats uniformly. 7646* DBX Options:: Macros enabling specific options in DBX format. 7647* DBX Hooks:: Hook macros for varying DBX format. 7648* File Names and DBX:: Macros controlling output of file names in DBX format. 7649* SDB and DWARF:: Macros for SDB (COFF) and DWARF formats. 7650* VMS Debug:: Macros for VMS debug format. 7651@end menu 7652 7653@node All Debuggers 7654@subsection Macros Affecting All Debugging Formats 7655 7656@c prevent bad page break with this line 7657These macros affect all debugging formats. 7658 7659@table @code 7660@findex DBX_REGISTER_NUMBER 7661@item DBX_REGISTER_NUMBER (@var{regno}) 7662A C expression that returns the DBX register number for the compiler 7663register number @var{regno}. In the default macro provided, the value 7664of this expression will be @var{regno} itself. But sometimes there are 7665some registers that the compiler knows about and DBX does not, or vice 7666versa. In such cases, some register may need to have one number in the 7667compiler and another for DBX@. 7668 7669If two registers have consecutive numbers inside GCC, and they can be 7670used as a pair to hold a multiword value, then they @emph{must} have 7671consecutive numbers after renumbering with @code{DBX_REGISTER_NUMBER}. 7672Otherwise, debuggers will be unable to access such a pair, because they 7673expect register pairs to be consecutive in their own numbering scheme. 7674 7675If you find yourself defining @code{DBX_REGISTER_NUMBER} in way that 7676does not preserve register pairs, then what you must do instead is 7677redefine the actual register numbering scheme. 7678 7679@findex DEBUGGER_AUTO_OFFSET 7680@item DEBUGGER_AUTO_OFFSET (@var{x}) 7681A C expression that returns the integer offset value for an automatic 7682variable having address @var{x} (an RTL expression). The default 7683computation assumes that @var{x} is based on the frame-pointer and 7684gives the offset from the frame-pointer. This is required for targets 7685that produce debugging output for DBX or COFF-style debugging output 7686for SDB and allow the frame-pointer to be eliminated when the 7687@option{-g} options is used. 7688 7689@findex DEBUGGER_ARG_OFFSET 7690@item DEBUGGER_ARG_OFFSET (@var{offset}, @var{x}) 7691A C expression that returns the integer offset value for an argument 7692having address @var{x} (an RTL expression). The nominal offset is 7693@var{offset}. 7694 7695@findex PREFERRED_DEBUGGING_TYPE 7696@item PREFERRED_DEBUGGING_TYPE 7697A C expression that returns the type of debugging output GCC should 7698produce when the user specifies just @option{-g}. Define 7699this if you have arranged for GCC to support more than one format of 7700debugging output. Currently, the allowable values are @code{DBX_DEBUG}, 7701@code{SDB_DEBUG}, @code{DWARF_DEBUG}, @code{DWARF2_DEBUG}, 7702@code{XCOFF_DEBUG}, @code{VMS_DEBUG}, and @code{VMS_AND_DWARF2_DEBUG}. 7703 7704When the user specifies @option{-ggdb}, GCC normally also uses the 7705value of this macro to select the debugging output format, but with two 7706exceptions. If @code{DWARF2_DEBUGGING_INFO} is defined and 7707@code{LINKER_DOES_NOT_WORK_WITH_DWARF2} is not defined, GCC uses the 7708value @code{DWARF2_DEBUG}. Otherwise, if @code{DBX_DEBUGGING_INFO} is 7709defined, GCC uses @code{DBX_DEBUG}. 7710 7711The value of this macro only affects the default debugging output; the 7712user can always get a specific type of output by using @option{-gstabs}, 7713@option{-gcoff}, @option{-gdwarf-1}, @option{-gdwarf-2}, @option{-gxcoff}, 7714or @option{-gvms}. 7715@end table 7716 7717@node DBX Options 7718@subsection Specific Options for DBX Output 7719 7720@c prevent bad page break with this line 7721These are specific options for DBX output. 7722 7723@table @code 7724@findex DBX_DEBUGGING_INFO 7725@item DBX_DEBUGGING_INFO 7726Define this macro if GCC should produce debugging output for DBX 7727in response to the @option{-g} option. 7728 7729@findex XCOFF_DEBUGGING_INFO 7730@item XCOFF_DEBUGGING_INFO 7731Define this macro if GCC should produce XCOFF format debugging output 7732in response to the @option{-g} option. This is a variant of DBX format. 7733 7734@findex DEFAULT_GDB_EXTENSIONS 7735@item DEFAULT_GDB_EXTENSIONS 7736Define this macro to control whether GCC should by default generate 7737GDB's extended version of DBX debugging information (assuming DBX-format 7738debugging information is enabled at all). If you don't define the 7739macro, the default is 1: always generate the extended information 7740if there is any occasion to. 7741 7742@findex DEBUG_SYMS_TEXT 7743@item DEBUG_SYMS_TEXT 7744Define this macro if all @code{.stabs} commands should be output while 7745in the text section. 7746 7747@findex ASM_STABS_OP 7748@item ASM_STABS_OP 7749A C string constant, including spacing, naming the assembler pseudo op to 7750use instead of @code{"\t.stabs\t"} to define an ordinary debugging symbol. 7751If you don't define this macro, @code{"\t.stabs\t"} is used. This macro 7752applies only to DBX debugging information format. 7753 7754@findex ASM_STABD_OP 7755@item ASM_STABD_OP 7756A C string constant, including spacing, naming the assembler pseudo op to 7757use instead of @code{"\t.stabd\t"} to define a debugging symbol whose 7758value is the current location. If you don't define this macro, 7759@code{"\t.stabd\t"} is used. This macro applies only to DBX debugging 7760information format. 7761 7762@findex ASM_STABN_OP 7763@item ASM_STABN_OP 7764A C string constant, including spacing, naming the assembler pseudo op to 7765use instead of @code{"\t.stabn\t"} to define a debugging symbol with no 7766name. If you don't define this macro, @code{"\t.stabn\t"} is used. This 7767macro applies only to DBX debugging information format. 7768 7769@findex DBX_NO_XREFS 7770@item DBX_NO_XREFS 7771Define this macro if DBX on your system does not support the construct 7772@samp{xs@var{tagname}}. On some systems, this construct is used to 7773describe a forward reference to a structure named @var{tagname}. 7774On other systems, this construct is not supported at all. 7775 7776@findex DBX_CONTIN_LENGTH 7777@item DBX_CONTIN_LENGTH 7778A symbol name in DBX-format debugging information is normally 7779continued (split into two separate @code{.stabs} directives) when it 7780exceeds a certain length (by default, 80 characters). On some 7781operating systems, DBX requires this splitting; on others, splitting 7782must not be done. You can inhibit splitting by defining this macro 7783with the value zero. You can override the default splitting-length by 7784defining this macro as an expression for the length you desire. 7785 7786@findex DBX_CONTIN_CHAR 7787@item DBX_CONTIN_CHAR 7788Normally continuation is indicated by adding a @samp{\} character to 7789the end of a @code{.stabs} string when a continuation follows. To use 7790a different character instead, define this macro as a character 7791constant for the character you want to use. Do not define this macro 7792if backslash is correct for your system. 7793 7794@findex DBX_STATIC_STAB_DATA_SECTION 7795@item DBX_STATIC_STAB_DATA_SECTION 7796Define this macro if it is necessary to go to the data section before 7797outputting the @samp{.stabs} pseudo-op for a non-global static 7798variable. 7799 7800@findex DBX_TYPE_DECL_STABS_CODE 7801@item DBX_TYPE_DECL_STABS_CODE 7802The value to use in the ``code'' field of the @code{.stabs} directive 7803for a typedef. The default is @code{N_LSYM}. 7804 7805@findex DBX_STATIC_CONST_VAR_CODE 7806@item DBX_STATIC_CONST_VAR_CODE 7807The value to use in the ``code'' field of the @code{.stabs} directive 7808for a static variable located in the text section. DBX format does not 7809provide any ``right'' way to do this. The default is @code{N_FUN}. 7810 7811@findex DBX_REGPARM_STABS_CODE 7812@item DBX_REGPARM_STABS_CODE 7813The value to use in the ``code'' field of the @code{.stabs} directive 7814for a parameter passed in registers. DBX format does not provide any 7815``right'' way to do this. The default is @code{N_RSYM}. 7816 7817@findex DBX_REGPARM_STABS_LETTER 7818@item DBX_REGPARM_STABS_LETTER 7819The letter to use in DBX symbol data to identify a symbol as a parameter 7820passed in registers. DBX format does not customarily provide any way to 7821do this. The default is @code{'P'}. 7822 7823@findex DBX_MEMPARM_STABS_LETTER 7824@item DBX_MEMPARM_STABS_LETTER 7825The letter to use in DBX symbol data to identify a symbol as a stack 7826parameter. The default is @code{'p'}. 7827 7828@findex DBX_FUNCTION_FIRST 7829@item DBX_FUNCTION_FIRST 7830Define this macro if the DBX information for a function and its 7831arguments should precede the assembler code for the function. Normally, 7832in DBX format, the debugging information entirely follows the assembler 7833code. 7834 7835@findex DBX_LBRAC_FIRST 7836@item DBX_LBRAC_FIRST 7837Define this macro if the @code{N_LBRAC} symbol for a block should 7838precede the debugging information for variables and functions defined in 7839that block. Normally, in DBX format, the @code{N_LBRAC} symbol comes 7840first. 7841 7842@findex DBX_BLOCKS_FUNCTION_RELATIVE 7843@item DBX_BLOCKS_FUNCTION_RELATIVE 7844Define this macro if the value of a symbol describing the scope of a 7845block (@code{N_LBRAC} or @code{N_RBRAC}) should be relative to the start 7846of the enclosing function. Normally, GCC uses an absolute address. 7847 7848@findex DBX_USE_BINCL 7849@item DBX_USE_BINCL 7850Define this macro if GCC should generate @code{N_BINCL} and 7851@code{N_EINCL} stabs for included header files, as on Sun systems. This 7852macro also directs GCC to output a type number as a pair of a file 7853number and a type number within the file. Normally, GCC does not 7854generate @code{N_BINCL} or @code{N_EINCL} stabs, and it outputs a single 7855number for a type number. 7856@end table 7857 7858@node DBX Hooks 7859@subsection Open-Ended Hooks for DBX Format 7860 7861@c prevent bad page break with this line 7862These are hooks for DBX format. 7863 7864@table @code 7865@findex DBX_OUTPUT_LBRAC 7866@item DBX_OUTPUT_LBRAC (@var{stream}, @var{name}) 7867Define this macro to say how to output to @var{stream} the debugging 7868information for the start of a scope level for variable names. The 7869argument @var{name} is the name of an assembler symbol (for use with 7870@code{assemble_name}) whose value is the address where the scope begins. 7871 7872@findex DBX_OUTPUT_RBRAC 7873@item DBX_OUTPUT_RBRAC (@var{stream}, @var{name}) 7874Like @code{DBX_OUTPUT_LBRAC}, but for the end of a scope level. 7875 7876@findex DBX_OUTPUT_NFUN 7877@item DBX_OUTPUT_NFUN (@var{stream}, @var{lscope_label}, @var{decl}) 7878Define this macro if the target machine requires special handling to 7879output an @code{N_FUN} entry for the function @var{decl}. 7880 7881@findex DBX_OUTPUT_ENUM 7882@item DBX_OUTPUT_ENUM (@var{stream}, @var{type}) 7883Define this macro if the target machine requires special handling to 7884output an enumeration type. The definition should be a C statement 7885(sans semicolon) to output the appropriate information to @var{stream} 7886for the type @var{type}. 7887 7888@findex DBX_OUTPUT_FUNCTION_END 7889@item DBX_OUTPUT_FUNCTION_END (@var{stream}, @var{function}) 7890Define this macro if the target machine requires special output at the 7891end of the debugging information for a function. The definition should 7892be a C statement (sans semicolon) to output the appropriate information 7893to @var{stream}. @var{function} is the @code{FUNCTION_DECL} node for 7894the function. 7895 7896@findex DBX_OUTPUT_STANDARD_TYPES 7897@item DBX_OUTPUT_STANDARD_TYPES (@var{syms}) 7898Define this macro if you need to control the order of output of the 7899standard data types at the beginning of compilation. The argument 7900@var{syms} is a @code{tree} which is a chain of all the predefined 7901global symbols, including names of data types. 7902 7903Normally, DBX output starts with definitions of the types for integers 7904and characters, followed by all the other predefined types of the 7905particular language in no particular order. 7906 7907On some machines, it is necessary to output different particular types 7908first. To do this, define @code{DBX_OUTPUT_STANDARD_TYPES} to output 7909those symbols in the necessary order. Any predefined types that you 7910don't explicitly output will be output afterward in no particular order. 7911 7912Be careful not to define this macro so that it works only for C@. There 7913are no global variables to access most of the built-in types, because 7914another language may have another set of types. The way to output a 7915particular type is to look through @var{syms} to see if you can find it. 7916Here is an example: 7917 7918@smallexample 7919@{ 7920 tree decl; 7921 for (decl = syms; decl; decl = TREE_CHAIN (decl)) 7922 if (!strcmp (IDENTIFIER_POINTER (DECL_NAME (decl)), 7923 "long int")) 7924 dbxout_symbol (decl); 7925 @dots{} 7926@} 7927@end smallexample 7928 7929@noindent 7930This does nothing if the expected type does not exist. 7931 7932See the function @code{init_decl_processing} in @file{c-decl.c} to find 7933the names to use for all the built-in C types. 7934 7935Here is another way of finding a particular type: 7936 7937@c this is still overfull. --mew 10feb93 7938@smallexample 7939@{ 7940 tree decl; 7941 for (decl = syms; decl; decl = TREE_CHAIN (decl)) 7942 if (TREE_CODE (decl) == TYPE_DECL 7943 && (TREE_CODE (TREE_TYPE (decl)) 7944 == INTEGER_CST) 7945 && TYPE_PRECISION (TREE_TYPE (decl)) == 16 7946 && TYPE_UNSIGNED (TREE_TYPE (decl))) 7947@group 7948 /* @r{This must be @code{unsigned short}.} */ 7949 dbxout_symbol (decl); 7950 @dots{} 7951@} 7952@end group 7953@end smallexample 7954 7955@findex NO_DBX_FUNCTION_END 7956@item NO_DBX_FUNCTION_END 7957Some stabs encapsulation formats (in particular ECOFF), cannot handle the 7958@code{.stabs "",N_FUN,,0,0,Lscope-function-1} gdb dbx extension construct. 7959On those machines, define this macro to turn this feature off without 7960disturbing the rest of the gdb extensions. 7961 7962@end table 7963 7964@node File Names and DBX 7965@subsection File Names in DBX Format 7966 7967@c prevent bad page break with this line 7968This describes file names in DBX format. 7969 7970@table @code 7971@findex DBX_WORKING_DIRECTORY 7972@item DBX_WORKING_DIRECTORY 7973Define this if DBX wants to have the current directory recorded in each 7974object file. 7975 7976Note that the working directory is always recorded if GDB extensions are 7977enabled. 7978 7979@findex DBX_OUTPUT_MAIN_SOURCE_FILENAME 7980@item DBX_OUTPUT_MAIN_SOURCE_FILENAME (@var{stream}, @var{name}) 7981A C statement to output DBX debugging information to the stdio stream 7982@var{stream} which indicates that file @var{name} is the main source 7983file---the file specified as the input file for compilation. 7984This macro is called only once, at the beginning of compilation. 7985 7986This macro need not be defined if the standard form of output 7987for DBX debugging information is appropriate. 7988 7989@findex DBX_OUTPUT_MAIN_SOURCE_DIRECTORY 7990@item DBX_OUTPUT_MAIN_SOURCE_DIRECTORY (@var{stream}, @var{name}) 7991A C statement to output DBX debugging information to the stdio stream 7992@var{stream} which indicates that the current directory during 7993compilation is named @var{name}. 7994 7995This macro need not be defined if the standard form of output 7996for DBX debugging information is appropriate. 7997 7998@findex DBX_OUTPUT_MAIN_SOURCE_FILE_END 7999@item DBX_OUTPUT_MAIN_SOURCE_FILE_END (@var{stream}, @var{name}) 8000A C statement to output DBX debugging information at the end of 8001compilation of the main source file @var{name}. 8002 8003If you don't define this macro, nothing special is output at the end 8004of compilation, which is correct for most machines. 8005 8006@findex DBX_OUTPUT_SOURCE_FILENAME 8007@item DBX_OUTPUT_SOURCE_FILENAME (@var{stream}, @var{name}) 8008A C statement to output DBX debugging information to the stdio stream 8009@var{stream} which indicates that file @var{name} is the current source 8010file. This output is generated each time input shifts to a different 8011source file as a result of @samp{#include}, the end of an included file, 8012or a @samp{#line} command. 8013 8014This macro need not be defined if the standard form of output 8015for DBX debugging information is appropriate. 8016@end table 8017 8018@need 2000 8019@node SDB and DWARF 8020@subsection Macros for SDB and DWARF Output 8021 8022@c prevent bad page break with this line 8023Here are macros for SDB and DWARF output. 8024 8025@table @code 8026@findex SDB_DEBUGGING_INFO 8027@item SDB_DEBUGGING_INFO 8028Define this macro if GCC should produce COFF-style debugging output 8029for SDB in response to the @option{-g} option. 8030 8031@findex DWARF_DEBUGGING_INFO 8032@item DWARF_DEBUGGING_INFO 8033Define this macro if GCC should produce dwarf format debugging output 8034in response to the @option{-g} option. 8035 8036@findex DWARF2_DEBUGGING_INFO 8037@item DWARF2_DEBUGGING_INFO 8038Define this macro if GCC should produce dwarf version 2 format 8039debugging output in response to the @option{-g} option. 8040 8041To support optional call frame debugging information, you must also 8042define @code{INCOMING_RETURN_ADDR_RTX} and either set 8043@code{RTX_FRAME_RELATED_P} on the prologue insns if you use RTL for the 8044prologue, or call @code{dwarf2out_def_cfa} and @code{dwarf2out_reg_save} 8045as appropriate from @code{TARGET_ASM_FUNCTION_PROLOGUE} if you don't. 8046 8047@findex DWARF2_FRAME_INFO 8048@item DWARF2_FRAME_INFO 8049Define this macro to a nonzero value if GCC should always output 8050Dwarf 2 frame information. If @code{DWARF2_UNWIND_INFO} 8051(@pxref{Exception Region Output} is nonzero, GCC will output this 8052information not matter how you define @code{DWARF2_FRAME_INFO}. 8053 8054@findex LINKER_DOES_NOT_WORK_WITH_DWARF2 8055@item LINKER_DOES_NOT_WORK_WITH_DWARF2 8056Define this macro if the linker does not work with Dwarf version 2. 8057Normally, if the user specifies only @option{-ggdb} GCC will use Dwarf 8058version 2 if available; this macro disables this. See the description 8059of the @code{PREFERRED_DEBUGGING_TYPE} macro for more details. 8060 8061@findex DWARF2_GENERATE_TEXT_SECTION_LABEL 8062@item DWARF2_GENERATE_TEXT_SECTION_LABEL 8063By default, the Dwarf 2 debugging information generator will generate a 8064label to mark the beginning of the text section. If it is better simply 8065to use the name of the text section itself, rather than an explicit label, 8066to indicate the beginning of the text section, define this macro to zero. 8067 8068@findex DWARF2_ASM_LINE_DEBUG_INFO 8069@item DWARF2_ASM_LINE_DEBUG_INFO 8070Define this macro to be a nonzero value if the assembler can generate Dwarf 2 8071line debug info sections. This will result in much more compact line number 8072tables, and hence is desirable if it works. 8073 8074@findex ASM_OUTPUT_DWARF_DELTA 8075@item ASM_OUTPUT_DWARF_DELTA (@var{stream}, @var{size}, @var{label1}, @var{label2}) 8076A C statement to issue assembly directives that create a difference 8077between the two given labels, using an integer of the given size. 8078 8079@findex ASM_OUTPUT_DWARF_OFFSET 8080@item ASM_OUTPUT_DWARF_OFFSET (@var{stream}, @var{size}, @var{label}) 8081A C statement to issue assembly directives that create a 8082section-relative reference to the given label, using an integer of the 8083given size. 8084 8085@findex ASM_OUTPUT_DWARF_PCREL 8086@item ASM_OUTPUT_DWARF_PCREL (@var{stream}, @var{size}, @var{label}) 8087A C statement to issue assembly directives that create a self-relative 8088reference to the given label, using an integer of the given size. 8089 8090@findex PUT_SDB_@dots{} 8091@item PUT_SDB_@dots{} 8092Define these macros to override the assembler syntax for the special 8093SDB assembler directives. See @file{sdbout.c} for a list of these 8094macros and their arguments. If the standard syntax is used, you need 8095not define them yourself. 8096 8097@findex SDB_DELIM 8098@item SDB_DELIM 8099Some assemblers do not support a semicolon as a delimiter, even between 8100SDB assembler directives. In that case, define this macro to be the 8101delimiter to use (usually @samp{\n}). It is not necessary to define 8102a new set of @code{PUT_SDB_@var{op}} macros if this is the only change 8103required. 8104 8105@findex SDB_GENERATE_FAKE 8106@item SDB_GENERATE_FAKE 8107Define this macro to override the usual method of constructing a dummy 8108name for anonymous structure and union types. See @file{sdbout.c} for 8109more information. 8110 8111@findex SDB_ALLOW_UNKNOWN_REFERENCES 8112@item SDB_ALLOW_UNKNOWN_REFERENCES 8113Define this macro to allow references to unknown structure, 8114union, or enumeration tags to be emitted. Standard COFF does not 8115allow handling of unknown references, MIPS ECOFF has support for 8116it. 8117 8118@findex SDB_ALLOW_FORWARD_REFERENCES 8119@item SDB_ALLOW_FORWARD_REFERENCES 8120Define this macro to allow references to structure, union, or 8121enumeration tags that have not yet been seen to be handled. Some 8122assemblers choke if forward tags are used, while some require it. 8123@end table 8124 8125@need 2000 8126@node VMS Debug 8127@subsection Macros for VMS Debug Format 8128 8129@c prevent bad page break with this line 8130Here are macros for VMS debug format. 8131 8132@table @code 8133@findex VMS_DEBUGGING_INFO 8134@item VMS_DEBUGGING_INFO 8135Define this macro if GCC should produce debugging output for VMS 8136in response to the @option{-g} option. The default behavior for VMS 8137is to generate minimal debug info for a traceback in the absence of 8138@option{-g} unless explicitly overridden with @option{-g0}. This 8139behavior is controlled by @code{OPTIMIZATION_OPTIONS} and 8140@code{OVERRIDE_OPTIONS}. 8141@end table 8142 8143@node Floating Point 8144@section Cross Compilation and Floating Point 8145@cindex cross compilation and floating point 8146@cindex floating point and cross compilation 8147 8148While all modern machines use twos-complement representation for integers, 8149there are a variety of representations for floating point numbers. This 8150means that in a cross-compiler the representation of floating point numbers 8151in the compiled program may be different from that used in the machine 8152doing the compilation. 8153 8154Because different representation systems may offer different amounts of 8155range and precision, all floating point constants must be represented in 8156the target machine's format. Therefore, the cross compiler cannot 8157safely use the host machine's floating point arithmetic; it must emulate 8158the target's arithmetic. To ensure consistency, GCC always uses 8159emulation to work with floating point values, even when the host and 8160target floating point formats are identical. 8161 8162The following macros are provided by @file{real.h} for the compiler to 8163use. All parts of the compiler which generate or optimize 8164floating-point calculations must use these macros. They may evaluate 8165their operands more than once, so operands must not have side effects. 8166 8167@defmac REAL_VALUE_TYPE 8168The C data type to be used to hold a floating point value in the target 8169machine's format. Typically this is a @code{struct} containing an 8170array of @code{HOST_WIDE_INT}, but all code should treat it as an opaque 8171quantity. 8172@end defmac 8173 8174@deftypefn Macro int REAL_VALUES_EQUAL (REAL_VALUE_TYPE @var{x}, REAL_VALUE_TYPE @var{y}) 8175Compares for equality the two values, @var{x} and @var{y}. If the target 8176floating point format supports negative zeroes and/or NaNs, 8177@samp{REAL_VALUES_EQUAL (-0.0, 0.0)} is true, and 8178@samp{REAL_VALUES_EQUAL (NaN, NaN)} is false. 8179@end deftypefn 8180 8181@deftypefn Macro int REAL_VALUES_LESS (REAL_VALUE_TYPE @var{x}, REAL_VALUE_TYPE @var{y}) 8182Tests whether @var{x} is less than @var{y}. 8183@end deftypefn 8184 8185@deftypefn Macro HOST_WIDE_INT REAL_VALUE_FIX (REAL_VALUE_TYPE @var{x}) 8186Truncates @var{x} to a signed integer, rounding toward zero. 8187@end deftypefn 8188 8189@deftypefn Macro {unsigned HOST_WIDE_INT} REAL_VALUE_UNSIGNED_FIX (REAL_VALUE_TYPE @var{x}) 8190Truncates @var{x} to an unsigned integer, rounding toward zero. If 8191@var{x} is negative, returns zero. 8192@end deftypefn 8193 8194@deftypefn Macro REAL_VALUE_TYPE REAL_VALUE_ATOF (const char *@var{string}, enum machine_mode @var{mode}) 8195Converts @var{string} into a floating point number in the target machine's 8196representation for mode @var{mode}. This routine can handle both 8197decimal and hexadecimal floating point constants, using the syntax 8198defined by the C language for both. 8199@end deftypefn 8200 8201@deftypefn Macro int REAL_VALUE_NEGATIVE (REAL_VALUE_TYPE @var{x}) 8202Returns 1 if @var{x} is negative (including negative zero), 0 otherwise. 8203@end deftypefn 8204 8205@deftypefn Macro int REAL_VALUE_ISINF (REAL_VALUE_TYPE @var{x}) 8206Determines whether @var{x} represents infinity (positive or negative). 8207@end deftypefn 8208 8209@deftypefn Macro int REAL_VALUE_ISNAN (REAL_VALUE_TYPE @var{x}) 8210Determines whether @var{x} represents a ``NaN'' (not-a-number). 8211@end deftypefn 8212 8213@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}) 8214Calculates an arithmetic operation on the two floating point values 8215@var{x} and @var{y}, storing the result in @var{output} (which must be a 8216variable). 8217 8218The operation to be performed is specified by @var{code}. Only the 8219following codes are supported: @code{PLUS_EXPR}, @code{MINUS_EXPR}, 8220@code{MULT_EXPR}, @code{RDIV_EXPR}, @code{MAX_EXPR}, @code{MIN_EXPR}. 8221 8222If @code{REAL_ARITHMETIC} is asked to evaluate division by zero and the 8223target's floating point format cannot represent infinity, it will call 8224@code{abort}. Callers should check for this situation first, using 8225@code{MODE_HAS_INFINITIES}. @xref{Storage Layout}. 8226@end deftypefn 8227 8228@deftypefn Macro REAL_VALUE_TYPE REAL_VALUE_NEGATE (REAL_VALUE_TYPE @var{x}) 8229Returns the negative of the floating point value @var{x}. 8230@end deftypefn 8231 8232@deftypefn Macro REAL_VALUE_TYPE REAL_VALUE_ABS (REAL_VALUE_TYPE @var{x}) 8233Returns the absolute value of @var{x}. 8234@end deftypefn 8235 8236@deftypefn Macro REAL_VALUE_TYPE REAL_VALUE_TRUNCATE (REAL_VALUE_TYPE @var{mode}, enum machine_mode @var{x}) 8237Truncates the floating point value @var{x} to fit in @var{mode}. The 8238return value is still a full-size @code{REAL_VALUE_TYPE}, but it has an 8239appropriate bit pattern to be output asa floating constant whose 8240precision accords with mode @var{mode}. 8241@end deftypefn 8242 8243@deftypefn Macro void REAL_VALUE_TO_INT (HOST_WIDE_INT @var{low}, HOST_WIDE_INT @var{high}, REAL_VALUE_TYPE @var{x}) 8244Converts a floating point value @var{x} into a double-precision integer 8245which is then stored into @var{low} and @var{high}. If the value is not 8246integral, it is truncated. 8247@end deftypefn 8248 8249@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}) 8250@findex REAL_VALUE_FROM_INT 8251Converts a double-precision integer found in @var{low} and @var{high}, 8252into a floating point value which is then stored into @var{x}. The 8253value is truncated to fit in mode @var{mode}. 8254@end deftypefn 8255 8256@node Mode Switching 8257@section Mode Switching Instructions 8258@cindex mode switching 8259The following macros control mode switching optimizations: 8260 8261@table @code 8262@findex OPTIMIZE_MODE_SWITCHING 8263@item OPTIMIZE_MODE_SWITCHING (@var{entity}) 8264Define this macro if the port needs extra instructions inserted for mode 8265switching in an optimizing compilation. 8266 8267For an example, the SH4 can perform both single and double precision 8268floating point operations, but to perform a single precision operation, 8269the FPSCR PR bit has to be cleared, while for a double precision 8270operation, this bit has to be set. Changing the PR bit requires a general 8271purpose register as a scratch register, hence these FPSCR sets have to 8272be inserted before reload, i.e.@: you can't put this into instruction emitting 8273or @code{MACHINE_DEPENDENT_REORG}. 8274 8275You can have multiple entities that are mode-switched, and select at run time 8276which entities actually need it. @code{OPTIMIZE_MODE_SWITCHING} should 8277return nonzero for any @var{entity} that needs mode-switching. 8278If you define this macro, you also have to define 8279@code{NUM_MODES_FOR_MODE_SWITCHING}, @code{MODE_NEEDED}, 8280@code{MODE_PRIORITY_TO_MODE} and @code{EMIT_MODE_SET}. 8281@code{NORMAL_MODE} is optional. 8282 8283@findex NUM_MODES_FOR_MODE_SWITCHING 8284@item NUM_MODES_FOR_MODE_SWITCHING 8285If you define @code{OPTIMIZE_MODE_SWITCHING}, you have to define this as 8286initializer for an array of integers. Each initializer element 8287N refers to an entity that needs mode switching, and specifies the number 8288of different modes that might need to be set for this entity. 8289The position of the initializer in the initializer - starting counting at 8290zero - determines the integer that is used to refer to the mode-switched 8291entity in question. 8292In macros that take mode arguments / yield a mode result, modes are 8293represented as numbers 0 @dots{} N @minus{} 1. N is used to specify that no mode 8294switch is needed / supplied. 8295 8296@findex MODE_NEEDED 8297@item MODE_NEEDED (@var{entity}, @var{insn}) 8298@var{entity} is an integer specifying a mode-switched entity. If 8299@code{OPTIMIZE_MODE_SWITCHING} is defined, you must define this macro to 8300return an integer value not larger than the corresponding element in 8301@code{NUM_MODES_FOR_MODE_SWITCHING}, to denote the mode that @var{entity} must 8302be switched into prior to the execution of @var{insn}. 8303 8304@findex NORMAL_MODE 8305@item NORMAL_MODE (@var{entity}) 8306If this macro is defined, it is evaluated for every @var{entity} that needs 8307mode switching. It should evaluate to an integer, which is a mode that 8308@var{entity} is assumed to be switched to at function entry and exit. 8309 8310@findex MODE_PRIORITY_TO_MODE 8311@item MODE_PRIORITY_TO_MODE (@var{entity}, @var{n}) 8312This macro specifies the order in which modes for @var{entity} are processed. 83130 is the highest priority, @code{NUM_MODES_FOR_MODE_SWITCHING[@var{entity}] - 1} the 8314lowest. The value of the macro should be an integer designating a mode 8315for @var{entity}. For any fixed @var{entity}, @code{mode_priority_to_mode} 8316(@var{entity}, @var{n}) shall be a bijection in 0 @dots{} 8317@code{num_modes_for_mode_switching[@var{entity}] - 1}. 8318 8319@findex EMIT_MODE_SET 8320@item EMIT_MODE_SET (@var{entity}, @var{mode}, @var{hard_regs_live}) 8321Generate one or more insns to set @var{entity} to @var{mode}. 8322@var{hard_reg_live} is the set of hard registers live at the point where 8323the insn(s) are to be inserted. 8324@end table 8325 8326@node Target Attributes 8327@section Defining target-specific uses of @code{__attribute__} 8328@cindex target attributes 8329@cindex machine attributes 8330@cindex attributes, target-specific 8331 8332Target-specific attributes may be defined for functions, data and types. 8333These are described using the following target hooks; they also need to 8334be documented in @file{extend.texi}. 8335 8336@deftypevr {Target Hook} {const struct attribute_spec *} TARGET_ATTRIBUTE_TABLE 8337If defined, this target hook points to an array of @samp{struct 8338attribute_spec} (defined in @file{tree.h}) specifying the machine 8339specific attributes for this target and some of the restrictions on the 8340entities to which these attributes are applied and the arguments they 8341take. 8342@end deftypevr 8343 8344@deftypefn {Target Hook} int TARGET_COMP_TYPE_ATTRIBUTES (tree @var{type1}, tree @var{type2}) 8345If defined, this target hook is a function which returns zero if the attributes on 8346@var{type1} and @var{type2} are incompatible, one if they are compatible, 8347and two if they are nearly compatible (which causes a warning to be 8348generated). If this is not defined, machine-specific attributes are 8349supposed always to be compatible. 8350@end deftypefn 8351 8352@deftypefn {Target Hook} void TARGET_SET_DEFAULT_TYPE_ATTRIBUTES (tree @var{type}) 8353If defined, this target hook is a function which assigns default attributes to 8354newly defined @var{type}. 8355@end deftypefn 8356 8357@deftypefn {Target Hook} tree TARGET_MERGE_TYPE_ATTRIBUTES (tree @var{type1}, tree @var{type2}) 8358Define this target hook if the merging of type attributes needs special 8359handling. If defined, the result is a list of the combined 8360@code{TYPE_ATTRIBUTES} of @var{type1} and @var{type2}. It is assumed 8361that @code{comptypes} has already been called and returned 1. This 8362function may call @code{merge_attributes} to handle machine-independent 8363merging. 8364@end deftypefn 8365 8366@deftypefn {Target Hook} tree TARGET_MERGE_DECL_ATTRIBUTES (tree @var{olddecl}, tree @var{newdecl}) 8367Define this target hook if the merging of decl attributes needs special 8368handling. If defined, the result is a list of the combined 8369@code{DECL_ATTRIBUTES} of @var{olddecl} and @var{newdecl}. 8370@var{newdecl} is a duplicate declaration of @var{olddecl}. Examples of 8371when this is needed are when one attribute overrides another, or when an 8372attribute is nullified by a subsequent definition. This function may 8373call @code{merge_attributes} to handle machine-independent merging. 8374 8375@findex TARGET_DLLIMPORT_DECL_ATTRIBUTES 8376If the only target-specific handling you require is @samp{dllimport} for 8377Windows targets, you should define the macro 8378@code{TARGET_DLLIMPORT_DECL_ATTRIBUTES}. This links in a function 8379called @code{merge_dllimport_decl_attributes} which can then be defined 8380as the expansion of @code{TARGET_MERGE_DECL_ATTRIBUTES}. This is done 8381in @file{i386/cygwin.h} and @file{i386/i386.c}, for example. 8382@end deftypefn 8383 8384@deftypefn {Target Hook} void TARGET_INSERT_ATTRIBUTES (tree @var{node}, tree *@var{attr_ptr}) 8385Define this target hook if you want to be able to add attributes to a decl 8386when it is being created. This is normally useful for back ends which 8387wish to implement a pragma by using the attributes which correspond to 8388the pragma's effect. The @var{node} argument is the decl which is being 8389created. The @var{attr_ptr} argument is a pointer to the attribute list 8390for this decl. The list itself should not be modified, since it may be 8391shared with other decls, but attributes may be chained on the head of 8392the list and @code{*@var{attr_ptr}} modified to point to the new 8393attributes, or a copy of the list may be made if further changes are 8394needed. 8395@end deftypefn 8396 8397@deftypefn {Target Hook} bool TARGET_FUNCTION_ATTRIBUTE_INLINABLE_P (tree @var{fndecl}) 8398@cindex inlining 8399This target hook returns @code{true} if it is ok to inline @var{fndecl} 8400into the current function, despite its having target-specific 8401attributes, @code{false} otherwise. By default, if a function has a 8402target specific attribute attached to it, it will not be inlined. 8403@end deftypefn 8404 8405@node MIPS Coprocessors 8406@section Defining coprocessor specifics for MIPS targets. 8407@cindex MIPS coprocessor-definition macros 8408 8409The MIPS specification allows MIPS implementations to have as many as 4 8410coprocessors, each with as many as 32 private registers. gcc supports 8411accessing these registers and transferring values between the registers 8412and memory using asm-ized variables. For example: 8413 8414@smallexample 8415 register unsigned int cp0count asm ("c0r1"); 8416 unsigned int d; 8417 8418 d = cp0count + 3; 8419@end smallexample 8420 8421(``c0r1'' is the default name of register 1 in coprocessor 0; alternate 8422names may be added as described below, or the default names may be 8423overridden entirely in @code{SUBTARGET_CONDITIONAL_REGISTER_USAGE}.) 8424 8425Coprocessor registers are assumed to be epilogue-used; sets to them will 8426be preserved even if it does not appear that the register is used again 8427later in the function. 8428 8429Another note: according to the MIPS spec, coprocessor 1 (if present) is 8430the FPU. One accesses COP1 registers through standard mips 8431floating-point support; they are not included in this mechanism. 8432 8433There is one macro used in defining the MIPS coprocessor interface which 8434you may want to override in subtargets; it is described below. 8435 8436@table @code 8437 8438@item ALL_COP_ADDITIONAL_REGISTER_NAMES 8439@findex ALL_COP_ADDITIONAL_REGISTER_NAMES 8440A comma-separated list (with leading comma) of pairs describing the 8441alternate names of coprocessor registers. The format of each entry should be 8442@smallexample 8443@{ @var{alternatename}, @var{register_number}@} 8444@end smallexample 8445Default: empty. 8446 8447@end table 8448 8449@node Misc 8450@section Miscellaneous Parameters 8451@cindex parameters, miscellaneous 8452 8453@c prevent bad page break with this line 8454Here are several miscellaneous parameters. 8455 8456@table @code 8457@item PREDICATE_CODES 8458@findex PREDICATE_CODES 8459Define this if you have defined special-purpose predicates in the file 8460@file{@var{machine}.c}. This macro is called within an initializer of an 8461array of structures. The first field in the structure is the name of a 8462predicate and the second field is an array of rtl codes. For each 8463predicate, list all rtl codes that can be in expressions matched by the 8464predicate. The list should have a trailing comma. Here is an example 8465of two entries in the list for a typical RISC machine: 8466 8467@smallexample 8468#define PREDICATE_CODES \ 8469 @{"gen_reg_rtx_operand", @{SUBREG, REG@}@}, \ 8470 @{"reg_or_short_cint_operand", @{SUBREG, REG, CONST_INT@}@}, 8471@end smallexample 8472 8473Defining this macro does not affect the generated code (however, 8474incorrect definitions that omit an rtl code that may be matched by the 8475predicate can cause the compiler to malfunction). Instead, it allows 8476the table built by @file{genrecog} to be more compact and efficient, 8477thus speeding up the compiler. The most important predicates to include 8478in the list specified by this macro are those used in the most insn 8479patterns. 8480 8481For each predicate function named in @code{PREDICATE_CODES}, a 8482declaration will be generated in @file{insn-codes.h}. 8483 8484@item SPECIAL_MODE_PREDICATES 8485@findex SPECIAL_MODE_PREDICATES 8486Define this if you have special predicates that know special things 8487about modes. Genrecog will warn about certain forms of 8488@code{match_operand} without a mode; if the operand predicate is 8489listed in @code{SPECIAL_MODE_PREDICATES}, the warning will be 8490suppressed. 8491 8492Here is an example from the IA-32 port (@code{ext_register_operand} 8493specially checks for @code{HImode} or @code{SImode} in preparation 8494for a byte extraction from @code{%ah} etc.). 8495 8496@smallexample 8497#define SPECIAL_MODE_PREDICATES \ 8498 "ext_register_operand", 8499@end smallexample 8500 8501@findex CASE_VECTOR_MODE 8502@item CASE_VECTOR_MODE 8503An alias for a machine mode name. This is the machine mode that 8504elements of a jump-table should have. 8505 8506@findex CASE_VECTOR_SHORTEN_MODE 8507@item CASE_VECTOR_SHORTEN_MODE (@var{min_offset}, @var{max_offset}, @var{body}) 8508Optional: return the preferred mode for an @code{addr_diff_vec} 8509when the minimum and maximum offset are known. If you define this, 8510it enables extra code in branch shortening to deal with @code{addr_diff_vec}. 8511To make this work, you also have to define @code{INSN_ALIGN} and 8512make the alignment for @code{addr_diff_vec} explicit. 8513The @var{body} argument is provided so that the offset_unsigned and scale 8514flags can be updated. 8515 8516@findex CASE_VECTOR_PC_RELATIVE 8517@item CASE_VECTOR_PC_RELATIVE 8518Define this macro to be a C expression to indicate when jump-tables 8519should contain relative addresses. If jump-tables never contain 8520relative addresses, then you need not define this macro. 8521 8522@findex CASE_DROPS_THROUGH 8523@item CASE_DROPS_THROUGH 8524Define this if control falls through a @code{case} insn when the index 8525value is out of range. This means the specified default-label is 8526actually ignored by the @code{case} insn proper. 8527 8528@findex CASE_VALUES_THRESHOLD 8529@item CASE_VALUES_THRESHOLD 8530Define this to be the smallest number of different values for which it 8531is best to use a jump-table instead of a tree of conditional branches. 8532The default is four for machines with a @code{casesi} instruction and 8533five otherwise. This is best for most machines. 8534 8535@findex WORD_REGISTER_OPERATIONS 8536@item WORD_REGISTER_OPERATIONS 8537Define this macro if operations between registers with integral mode 8538smaller than a word are always performed on the entire register. 8539Most RISC machines have this property and most CISC machines do not. 8540 8541@findex LOAD_EXTEND_OP 8542@item LOAD_EXTEND_OP (@var{mode}) 8543Define this macro to be a C expression indicating when insns that read 8544memory in @var{mode}, an integral mode narrower than a word, set the 8545bits outside of @var{mode} to be either the sign-extension or the 8546zero-extension of the data read. Return @code{SIGN_EXTEND} for values 8547of @var{mode} for which the 8548insn sign-extends, @code{ZERO_EXTEND} for which it zero-extends, and 8549@code{NIL} for other modes. 8550 8551This macro is not called with @var{mode} non-integral or with a width 8552greater than or equal to @code{BITS_PER_WORD}, so you may return any 8553value in this case. Do not define this macro if it would always return 8554@code{NIL}. On machines where this macro is defined, you will normally 8555define it as the constant @code{SIGN_EXTEND} or @code{ZERO_EXTEND}. 8556 8557@findex SHORT_IMMEDIATES_SIGN_EXTEND 8558@item SHORT_IMMEDIATES_SIGN_EXTEND 8559Define this macro if loading short immediate values into registers sign 8560extends. 8561 8562@findex FIXUNS_TRUNC_LIKE_FIX_TRUNC 8563@item FIXUNS_TRUNC_LIKE_FIX_TRUNC 8564Define this macro if the same instructions that convert a floating 8565point number to a signed fixed point number also convert validly to an 8566unsigned one. 8567 8568@findex MOVE_MAX 8569@item MOVE_MAX 8570The maximum number of bytes that a single instruction can move quickly 8571between memory and registers or between two memory locations. 8572 8573@findex MAX_MOVE_MAX 8574@item MAX_MOVE_MAX 8575The maximum number of bytes that a single instruction can move quickly 8576between memory and registers or between two memory locations. If this 8577is undefined, the default is @code{MOVE_MAX}. Otherwise, it is the 8578constant value that is the largest value that @code{MOVE_MAX} can have 8579at run-time. 8580 8581@findex SHIFT_COUNT_TRUNCATED 8582@item SHIFT_COUNT_TRUNCATED 8583A C expression that is nonzero if on this machine the number of bits 8584actually used for the count of a shift operation is equal to the number 8585of bits needed to represent the size of the object being shifted. When 8586this macro is nonzero, the compiler will assume that it is safe to omit 8587a sign-extend, zero-extend, and certain bitwise `and' instructions that 8588truncates the count of a shift operation. On machines that have 8589instructions that act on bit-fields at variable positions, which may 8590include `bit test' instructions, a nonzero @code{SHIFT_COUNT_TRUNCATED} 8591also enables deletion of truncations of the values that serve as 8592arguments to bit-field instructions. 8593 8594If both types of instructions truncate the count (for shifts) and 8595position (for bit-field operations), or if no variable-position bit-field 8596instructions exist, you should define this macro. 8597 8598However, on some machines, such as the 80386 and the 680x0, truncation 8599only applies to shift operations and not the (real or pretended) 8600bit-field operations. Define @code{SHIFT_COUNT_TRUNCATED} to be zero on 8601such machines. Instead, add patterns to the @file{md} file that include 8602the implied truncation of the shift instructions. 8603 8604You need not define this macro if it would always have the value of zero. 8605 8606@findex TRULY_NOOP_TRUNCATION 8607@item TRULY_NOOP_TRUNCATION (@var{outprec}, @var{inprec}) 8608A C expression which is nonzero if on this machine it is safe to 8609``convert'' an integer of @var{inprec} bits to one of @var{outprec} 8610bits (where @var{outprec} is smaller than @var{inprec}) by merely 8611operating on it as if it had only @var{outprec} bits. 8612 8613On many machines, this expression can be 1. 8614 8615@c rearranged this, removed the phrase "it is reported that". this was 8616@c to fix an overfull hbox. --mew 10feb93 8617When @code{TRULY_NOOP_TRUNCATION} returns 1 for a pair of sizes for 8618modes for which @code{MODES_TIEABLE_P} is 0, suboptimal code can result. 8619If this is the case, making @code{TRULY_NOOP_TRUNCATION} return 0 in 8620such cases may improve things. 8621 8622@findex STORE_FLAG_VALUE 8623@item STORE_FLAG_VALUE 8624A C expression describing the value returned by a comparison operator 8625with an integral mode and stored by a store-flag instruction 8626(@samp{s@var{cond}}) when the condition is true. This description must 8627apply to @emph{all} the @samp{s@var{cond}} patterns and all the 8628comparison operators whose results have a @code{MODE_INT} mode. 8629 8630A value of 1 or @minus{}1 means that the instruction implementing the 8631comparison operator returns exactly 1 or @minus{}1 when the comparison is true 8632and 0 when the comparison is false. Otherwise, the value indicates 8633which bits of the result are guaranteed to be 1 when the comparison is 8634true. This value is interpreted in the mode of the comparison 8635operation, which is given by the mode of the first operand in the 8636@samp{s@var{cond}} pattern. Either the low bit or the sign bit of 8637@code{STORE_FLAG_VALUE} be on. Presently, only those bits are used by 8638the compiler. 8639 8640If @code{STORE_FLAG_VALUE} is neither 1 or @minus{}1, the compiler will 8641generate code that depends only on the specified bits. It can also 8642replace comparison operators with equivalent operations if they cause 8643the required bits to be set, even if the remaining bits are undefined. 8644For example, on a machine whose comparison operators return an 8645@code{SImode} value and where @code{STORE_FLAG_VALUE} is defined as 8646@samp{0x80000000}, saying that just the sign bit is relevant, the 8647expression 8648 8649@smallexample 8650(ne:SI (and:SI @var{x} (const_int @var{power-of-2})) (const_int 0)) 8651@end smallexample 8652 8653@noindent 8654can be converted to 8655 8656@smallexample 8657(ashift:SI @var{x} (const_int @var{n})) 8658@end smallexample 8659 8660@noindent 8661where @var{n} is the appropriate shift count to move the bit being 8662tested into the sign bit. 8663 8664There is no way to describe a machine that always sets the low-order bit 8665for a true value, but does not guarantee the value of any other bits, 8666but we do not know of any machine that has such an instruction. If you 8667are trying to port GCC to such a machine, include an instruction to 8668perform a logical-and of the result with 1 in the pattern for the 8669comparison operators and let us know at @email{gcc@@gcc.gnu.org}. 8670 8671Often, a machine will have multiple instructions that obtain a value 8672from a comparison (or the condition codes). Here are rules to guide the 8673choice of value for @code{STORE_FLAG_VALUE}, and hence the instructions 8674to be used: 8675 8676@itemize @bullet 8677@item 8678Use the shortest sequence that yields a valid definition for 8679@code{STORE_FLAG_VALUE}. It is more efficient for the compiler to 8680``normalize'' the value (convert it to, e.g., 1 or 0) than for the 8681comparison operators to do so because there may be opportunities to 8682combine the normalization with other operations. 8683 8684@item 8685For equal-length sequences, use a value of 1 or @minus{}1, with @minus{}1 being 8686slightly preferred on machines with expensive jumps and 1 preferred on 8687other machines. 8688 8689@item 8690As a second choice, choose a value of @samp{0x80000001} if instructions 8691exist that set both the sign and low-order bits but do not define the 8692others. 8693 8694@item 8695Otherwise, use a value of @samp{0x80000000}. 8696@end itemize 8697 8698Many machines can produce both the value chosen for 8699@code{STORE_FLAG_VALUE} and its negation in the same number of 8700instructions. On those machines, you should also define a pattern for 8701those cases, e.g., one matching 8702 8703@smallexample 8704(set @var{A} (neg:@var{m} (ne:@var{m} @var{B} @var{C}))) 8705@end smallexample 8706 8707Some machines can also perform @code{and} or @code{plus} operations on 8708condition code values with less instructions than the corresponding 8709@samp{s@var{cond}} insn followed by @code{and} or @code{plus}. On those 8710machines, define the appropriate patterns. Use the names @code{incscc} 8711and @code{decscc}, respectively, for the patterns which perform 8712@code{plus} or @code{minus} operations on condition code values. See 8713@file{rs6000.md} for some examples. The GNU Superoptizer can be used to 8714find such instruction sequences on other machines. 8715 8716You need not define @code{STORE_FLAG_VALUE} if the machine has no store-flag 8717instructions. 8718 8719@findex FLOAT_STORE_FLAG_VALUE 8720@item FLOAT_STORE_FLAG_VALUE (@var{mode}) 8721A C expression that gives a nonzero @code{REAL_VALUE_TYPE} value that is 8722returned when comparison operators with floating-point results are true. 8723Define this macro on machine that have comparison operations that return 8724floating-point values. If there are no such operations, do not define 8725this macro. 8726 8727@findex Pmode 8728@item Pmode 8729An alias for the machine mode for pointers. On most machines, define 8730this to be the integer mode corresponding to the width of a hardware 8731pointer; @code{SImode} on 32-bit machine or @code{DImode} on 64-bit machines. 8732On some machines you must define this to be one of the partial integer 8733modes, such as @code{PSImode}. 8734 8735The width of @code{Pmode} must be at least as large as the value of 8736@code{POINTER_SIZE}. If it is not equal, you must define the macro 8737@code{POINTERS_EXTEND_UNSIGNED} to specify how pointers are extended 8738to @code{Pmode}. 8739 8740@findex FUNCTION_MODE 8741@item FUNCTION_MODE 8742An alias for the machine mode used for memory references to functions 8743being called, in @code{call} RTL expressions. On most machines this 8744should be @code{QImode}. 8745 8746@findex INTEGRATE_THRESHOLD 8747@item INTEGRATE_THRESHOLD (@var{decl}) 8748A C expression for the maximum number of instructions above which the 8749function @var{decl} should not be inlined. @var{decl} is a 8750@code{FUNCTION_DECL} node. 8751 8752The default definition of this macro is 64 plus 8 times the number of 8753arguments that the function accepts. Some people think a larger 8754threshold should be used on RISC machines. 8755 8756@findex STDC_0_IN_SYSTEM_HEADERS 8757@item STDC_0_IN_SYSTEM_HEADERS 8758In normal operation, the preprocessor expands @code{__STDC__} to the 8759constant 1, to signify that GCC conforms to ISO Standard C@. On some 8760hosts, like Solaris, the system compiler uses a different convention, 8761where @code{__STDC__} is normally 0, but is 1 if the user specifies 8762strict conformance to the C Standard. 8763 8764Defining @code{STDC_0_IN_SYSTEM_HEADERS} makes GNU CPP follows the host 8765convention when processing system header files, but when processing user 8766files @code{__STDC__} will always expand to 1. 8767 8768@findex NO_IMPLICIT_EXTERN_C 8769@item NO_IMPLICIT_EXTERN_C 8770Define this macro if the system header files support C++ as well as C@. 8771This macro inhibits the usual method of using system header files in 8772C++, which is to pretend that the file's contents are enclosed in 8773@samp{extern "C" @{@dots{}@}}. 8774 8775@findex HANDLE_PRAGMA 8776@item HANDLE_PRAGMA (@var{getc}, @var{ungetc}, @var{name}) 8777This macro is no longer supported. You must use 8778@code{REGISTER_TARGET_PRAGMAS} instead. 8779 8780@findex REGISTER_TARGET_PRAGMAS 8781@findex #pragma 8782@findex pragma 8783@item REGISTER_TARGET_PRAGMAS (@var{pfile}) 8784Define this macro if you want to implement any target-specific pragmas. 8785If defined, it is a C expression which makes a series of calls to 8786@code{cpp_register_pragma} for each pragma, with @var{pfile} passed as 8787the first argument to to these functions. The macro may also do any 8788setup required for the pragmas. 8789 8790The primary reason to define this macro is to provide compatibility with 8791other compilers for the same target. In general, we discourage 8792definition of target-specific pragmas for GCC@. 8793 8794If the pragma can be implemented by attributes then you should consider 8795defining the target hook @samp{TARGET_INSERT_ATTRIBUTES} as well. 8796 8797Preprocessor macros that appear on pragma lines are not expanded. All 8798@samp{#pragma} directives that do not match any registered pragma are 8799silently ignored, unless the user specifies @option{-Wunknown-pragmas}. 8800 8801@deftypefun void cpp_register_pragma (cpp_reader *@var{pfile}, const char *@var{space}, const char *@var{name}, void (*@var{callback}) (cpp_reader *)) 8802 8803Each call to @code{cpp_register_pragma} establishes one pragma. The 8804@var{callback} routine will be called when the preprocessor encounters a 8805pragma of the form 8806 8807@smallexample 8808#pragma [@var{space}] @var{name} @dots{} 8809@end smallexample 8810 8811@var{space} is the case-sensitive namespace of the pragma, or 8812@code{NULL} to put the pragma in the global namespace. The callback 8813routine receives @var{pfile} as its first argument, which can be passed 8814on to cpplib's functions if necessary. You can lex tokens after the 8815@var{name} by calling @code{c_lex}. Tokens that are not read by the 8816callback will be silently ignored. The end of the line is indicated by 8817a token of type @code{CPP_EOF}. 8818 8819For an example use of this routine, see @file{c4x.h} and the callback 8820routines defined in @file{c4x-c.c}. 8821 8822Note that the use of @code{c_lex} is specific to the C and C++ 8823compilers. It will not work in the Java or Fortran compilers, or any 8824other language compilers for that matter. Thus if @code{c_lex} is going 8825to be called from target-specific code, it must only be done so when 8826building the C and C++ compilers. This can be done by defining the 8827variables @code{c_target_objs} and @code{cxx_target_objs} in the 8828target entry in the @file{config.gcc} file. These variables should name 8829the target-specific, language-specific object file which contains the 8830code that uses @code{c_lex}. Note it will also be necessary to add a 8831rule to the makefile fragment pointed to by @code{tmake_file} that shows 8832how to build this object file. 8833@end deftypefun 8834 8835@findex HANDLE_SYSV_PRAGMA 8836@findex #pragma 8837@findex pragma 8838@item HANDLE_SYSV_PRAGMA 8839Define this macro (to a value of 1) if you want the System V style 8840pragmas @samp{#pragma pack(<n>)} and @samp{#pragma weak <name> 8841[=<value>]} to be supported by gcc. 8842 8843The pack pragma specifies the maximum alignment (in bytes) of fields 8844within a structure, in much the same way as the @samp{__aligned__} and 8845@samp{__packed__} @code{__attribute__}s do. A pack value of zero resets 8846the behavior to the default. 8847 8848A subtlety for Microsoft Visual C/C++ style bit-field packing 8849(e.g. -mms-bitfields) for targets that support it: 8850When a bit-field is inserted into a packed record, the whole size 8851of the underlying type is used by one or more same-size adjacent 8852bit-fields (that is, if its long:3, 32 bits is used in the record, 8853and any additional adjacent long bit-fields are packed into the same 8854chunk of 32 bits. However, if the size changes, a new field of that 8855size is allocated). 8856 8857If both MS bit-fields and @samp{__attribute__((packed))} are used, 8858the latter will take precedence. If @samp{__attribute__((packed))} is 8859used on a single field when MS bit-fields are in use, it will take 8860precedence for that field, but the alignment of the rest of the structure 8861may affect its placement. 8862 8863The weak pragma only works if @code{SUPPORTS_WEAK} and 8864@code{ASM_WEAKEN_LABEL} are defined. If enabled it allows the creation 8865of specifically named weak labels, optionally with a value. 8866 8867@findex HANDLE_PRAGMA_PACK_PUSH_POP 8868@findex #pragma 8869@findex pragma 8870@item HANDLE_PRAGMA_PACK_PUSH_POP 8871Define this macro (to a value of 1) if you want to support the Win32 8872style pragmas @samp{#pragma pack(push,@var{n})} and @samp{#pragma 8873pack(pop)}. The @samp{pack(push,@var{n})} pragma specifies the maximum alignment 8874(in bytes) of fields within a structure, in much the same way as the 8875@samp{__aligned__} and @samp{__packed__} @code{__attribute__}s do. A 8876pack value of zero resets the behavior to the default. Successive 8877invocations of this pragma cause the previous values to be stacked, so 8878that invocations of @samp{#pragma pack(pop)} will return to the previous 8879value. 8880 8881@findex DOLLARS_IN_IDENTIFIERS 8882@item DOLLARS_IN_IDENTIFIERS 8883Define this macro to control use of the character @samp{$} in identifier 8884names. 0 means @samp{$} is not allowed by default; 1 means it is allowed. 88851 is the default; there is no need to define this macro in that case. 8886This macro controls the compiler proper; it does not affect the preprocessor. 8887 8888@findex NO_DOLLAR_IN_LABEL 8889@item NO_DOLLAR_IN_LABEL 8890Define this macro if the assembler does not accept the character 8891@samp{$} in label names. By default constructors and destructors in 8892G++ have @samp{$} in the identifiers. If this macro is defined, 8893@samp{.} is used instead. 8894 8895@findex NO_DOT_IN_LABEL 8896@item NO_DOT_IN_LABEL 8897Define this macro if the assembler does not accept the character 8898@samp{.} in label names. By default constructors and destructors in G++ 8899have names that use @samp{.}. If this macro is defined, these names 8900are rewritten to avoid @samp{.}. 8901 8902@findex DEFAULT_MAIN_RETURN 8903@item DEFAULT_MAIN_RETURN 8904Define this macro if the target system expects every program's @code{main} 8905function to return a standard ``success'' value by default (if no other 8906value is explicitly returned). 8907 8908The definition should be a C statement (sans semicolon) to generate the 8909appropriate rtl instructions. It is used only when compiling the end of 8910@code{main}. 8911 8912@item NEED_ATEXIT 8913@findex NEED_ATEXIT 8914Define this if the target system lacks the function @code{atexit} 8915from the ISO C standard. If this macro is defined, a default definition 8916will be provided to support C++. If @code{ON_EXIT} is not defined, 8917a default @code{exit} function will also be provided. 8918 8919@item ON_EXIT 8920@findex ON_EXIT 8921Define this macro if the target has another way to implement atexit 8922functionality without replacing @code{exit}. For instance, SunOS 4 has 8923a similar @code{on_exit} library function. 8924 8925The definition should be a functional macro which can be used just like 8926the @code{atexit} function. 8927 8928@item EXIT_BODY 8929@findex EXIT_BODY 8930Define this if your @code{exit} function needs to do something 8931besides calling an external function @code{_cleanup} before 8932terminating with @code{_exit}. The @code{EXIT_BODY} macro is 8933only needed if @code{NEED_ATEXIT} is defined and @code{ON_EXIT} is not 8934defined. 8935 8936@findex INSN_SETS_ARE_DELAYED 8937@item INSN_SETS_ARE_DELAYED (@var{insn}) 8938Define this macro as a C expression that is nonzero if it is safe for the 8939delay slot scheduler to place instructions in the delay slot of @var{insn}, 8940even if they appear to use a resource set or clobbered in @var{insn}. 8941@var{insn} is always a @code{jump_insn} or an @code{insn}; GCC knows that 8942every @code{call_insn} has this behavior. On machines where some @code{insn} 8943or @code{jump_insn} is really a function call and hence has this behavior, 8944you should define this macro. 8945 8946You need not define this macro if it would always return zero. 8947 8948@findex INSN_REFERENCES_ARE_DELAYED 8949@item INSN_REFERENCES_ARE_DELAYED (@var{insn}) 8950Define this macro as a C expression that is nonzero if it is safe for the 8951delay slot scheduler to place instructions in the delay slot of @var{insn}, 8952even if they appear to set or clobber a resource referenced in @var{insn}. 8953@var{insn} is always a @code{jump_insn} or an @code{insn}. On machines where 8954some @code{insn} or @code{jump_insn} is really a function call and its operands 8955are registers whose use is actually in the subroutine it calls, you should 8956define this macro. Doing so allows the delay slot scheduler to move 8957instructions which copy arguments into the argument registers into the delay 8958slot of @var{insn}. 8959 8960You need not define this macro if it would always return zero. 8961 8962@findex MACHINE_DEPENDENT_REORG 8963@item MACHINE_DEPENDENT_REORG (@var{insn}) 8964In rare cases, correct code generation requires extra machine 8965dependent processing between the second jump optimization pass and 8966delayed branch scheduling. On those machines, define this macro as a C 8967statement to act on the code starting at @var{insn}. 8968 8969@findex MULTIPLE_SYMBOL_SPACES 8970@item MULTIPLE_SYMBOL_SPACES 8971Define this macro if in some cases global symbols from one translation 8972unit may not be bound to undefined symbols in another translation unit 8973without user intervention. For instance, under Microsoft Windows 8974symbols must be explicitly imported from shared libraries (DLLs). 8975 8976@findex MD_ASM_CLOBBERS 8977@item MD_ASM_CLOBBERS (@var{clobbers}) 8978A C statement that adds to @var{clobbers} @code{STRING_CST} trees for 8979any hard regs the port wishes to automatically clobber for all asms. 8980 8981@findex MAX_INTEGER_COMPUTATION_MODE 8982@item MAX_INTEGER_COMPUTATION_MODE 8983Define this to the largest integer machine mode which can be used for 8984operations other than load, store and copy operations. 8985 8986You need only define this macro if the target holds values larger than 8987@code{word_mode} in general purpose registers. Most targets should not define 8988this macro. 8989 8990@findex MATH_LIBRARY 8991@item MATH_LIBRARY 8992Define this macro as a C string constant for the linker argument to link 8993in the system math library, or @samp{""} if the target does not have a 8994separate math library. 8995 8996You need only define this macro if the default of @samp{"-lm"} is wrong. 8997 8998@findex LIBRARY_PATH_ENV 8999@item LIBRARY_PATH_ENV 9000Define this macro as a C string constant for the environment variable that 9001specifies where the linker should look for libraries. 9002 9003You need only define this macro if the default of @samp{"LIBRARY_PATH"} 9004is wrong. 9005 9006@findex TARGET_HAS_F_SETLKW 9007@item TARGET_HAS_F_SETLKW 9008Define this macro if the target supports file locking with fcntl / F_SETLKW@. 9009Note that this functionality is part of POSIX@. 9010Defining @code{TARGET_HAS_F_SETLKW} will enable the test coverage code 9011to use file locking when exiting a program, which avoids race conditions 9012if the program has forked. 9013 9014@findex MAX_CONDITIONAL_EXECUTE 9015@item MAX_CONDITIONAL_EXECUTE 9016 9017A C expression for the maximum number of instructions to execute via 9018conditional execution instructions instead of a branch. A value of 9019@code{BRANCH_COST}+1 is the default if the machine does not use cc0, and 90201 if it does use cc0. 9021 9022@findex IFCVT_MODIFY_TESTS 9023@item IFCVT_MODIFY_TESTS(@var{ce_info}, @var{true_expr}, @var{false_expr}) 9024Used if the target needs to perform machine-dependent modifications on the 9025conditionals used for turning basic blocks into conditionally executed code. 9026@var{ce_info} points to a data structure, @code{struct ce_if_block}, which 9027contains information about the currently processed blocks. @var{true_expr} 9028and @var{false_expr} are the tests that are used for converting the 9029then-block and the else-block, respectively. Set either @var{true_expr} or 9030@var{false_expr} to a null pointer if the tests cannot be converted. 9031 9032@findex IFCVT_MODIFY_MULTIPLE_TESTS 9033@item IFCVT_MODIFY_MULTIPLE_TESTS(@var{ce_info}, @var{bb}, @var{true_expr}, @var{false_expr}) 9034Like @code{IFCVT_MODIFY_TESTS}, but used when converting more complicated 9035if-statements into conditions combined by @code{and} and @code{or} operations. 9036@var{bb} contains the basic block that contains the test that is currently 9037being processed and about to be turned into a condition. 9038 9039@findex IFCVT_MODIFY_INSN 9040@item IFCVT_MODIFY_INSN(@var{ce_info}, @var{pattern}, @var{insn}) 9041A C expression to modify the @var{PATTERN} of an @var{INSN} that is to 9042be converted to conditional execution format. @var{ce_info} points to 9043a data structure, @code{struct ce_if_block}, which contains information 9044about the currently processed blocks. 9045 9046@findex IFCVT_MODIFY_FINAL 9047@item IFCVT_MODIFY_FINAL(@var{ce_info}) 9048A C expression to perform any final machine dependent modifications in 9049converting code to conditional execution. The involved basic blocks 9050can be found in the @code{struct ce_if_block} structure that is pointed 9051to by @var{ce_info}. 9052 9053@findex IFCVT_MODIFY_CANCEL 9054@item IFCVT_MODIFY_CANCEL(@var{ce_info}) 9055A C expression to cancel any machine dependent modifications in 9056converting code to conditional execution. The involved basic blocks 9057can be found in the @code{struct ce_if_block} structure that is pointed 9058to by @var{ce_info}. 9059 9060@findex IFCVT_INIT_EXTRA_FIELDS 9061@item IFCVT_INIT_EXTRA_FIELDS(@var{ce_info}) 9062A C expression to initialize any extra fields in a @code{struct ce_if_block} 9063structure, which are defined by the @code{IFCVT_EXTRA_FIELDS} macro. 9064 9065@findex IFCVT_EXTRA_FIELDS 9066@item IFCVT_EXTRA_FIELDS 9067If defined, it should expand to a set of field declarations that will be 9068added to the @code{struct ce_if_block} structure. These should be initialized 9069by the @code{IFCVT_INIT_EXTRA_FIELDS} macro. 9070 9071@end table 9072 9073@deftypefn {Target Hook} void TARGET_INIT_BUILTINS () 9074Define this hook if you have any machine-specific built-in functions 9075that need to be defined. It should be a function that performs the 9076necessary setup. 9077 9078Machine specific built-in functions can be useful to expand special machine 9079instructions that would otherwise not normally be generated because 9080they have no equivalent in the source language (for example, SIMD vector 9081instructions or prefetch instructions). 9082 9083To create a built-in function, call the function @code{builtin_function} 9084which is defined by the language front end. You can use any type nodes set 9085up by @code{build_common_tree_nodes} and @code{build_common_tree_nodes_2}; 9086only language front ends that use those two functions will call 9087@samp{TARGET_INIT_BUILTINS}. 9088@end deftypefn 9089 9090@deftypefn {Target Hook} rtx TARGET_EXPAND_BUILTIN (tree @var{exp}, rtx @var{target}, rtx @var{subtarget}, enum machine_mode @var{mode}, int @var{ignore}) 9091 9092Expand a call to a machine specific built-in function that was set up by 9093@samp{TARGET_INIT_BUILTINS}. @var{exp} is the expression for the 9094function call; the result should go to @var{target} if that is 9095convenient, and have mode @var{mode} if that is convenient. 9096@var{subtarget} may be used as the target for computing one of 9097@var{exp}'s operands. @var{ignore} is nonzero if the value is to be 9098ignored. This function should return the result of the call to the 9099built-in function. 9100@end deftypefn 9101 9102@table @code 9103@findex MD_CAN_REDIRECT_BRANCH 9104@item MD_CAN_REDIRECT_BRANCH(@var{branch1}, @var{branch2}) 9105 9106Take a branch insn in @var{branch1} and another in @var{branch2}. 9107Return true if redirecting @var{branch1} to the destination of 9108@var{branch2} is possible. 9109 9110On some targets, branches may have a limited range. Optimizing the 9111filling of delay slots can result in branches being redirected, and this 9112may in turn cause a branch offset to overflow. 9113 9114@findex ALLOCATE_INITIAL_VALUE 9115@item ALLOCATE_INITIAL_VALUE(@var{hard_reg}) 9116 9117When the initial value of a hard register has been copied in a pseudo 9118register, it is often not necessary to actually allocate another register 9119to this pseudo register, because the original hard register or a stack slot 9120it has been saved into can be used. @code{ALLOCATE_INITIAL_VALUE}, if 9121defined, is called at the start of register allocation once for each 9122hard register that had its initial value copied by using 9123@code{get_func_hard_reg_initial_val} or @code{get_hard_reg_initial_val}. 9124Possible values are @code{NULL_RTX}, if you don't want 9125to do any special allocation, a @code{REG} rtx---that would typically be 9126the hard register itself, if it is known not to be clobbered---or a 9127@code{MEM}. 9128If you are returning a @code{MEM}, this is only a hint for the allocator; 9129it might decide to use another register anyways. 9130You may use @code{current_function_leaf_function} in the definition of the 9131macro, functions that use @code{REG_N_SETS}, to determine if the hard 9132register in question will not be clobbered. 9133 9134@findex TARGET_OBJECT_SUFFIX 9135@item TARGET_OBJECT_SUFFIX 9136Define this macro to be a C string representing the suffix for object 9137files on your target machine. If you do not define this macro, GCC will 9138use @samp{.o} as the suffix for object files. 9139 9140@findex TARGET_EXECUTABLE_SUFFIX 9141@item TARGET_EXECUTABLE_SUFFIX 9142Define this macro to be a C string representing the suffix to be 9143automatically added to executable files on your target machine. If you 9144do not define this macro, GCC will use the null string as the suffix for 9145executable files. 9146 9147@findex COLLECT_EXPORT_LIST 9148@item COLLECT_EXPORT_LIST 9149If defined, @code{collect2} will scan the individual object files 9150specified on its command line and create an export list for the linker. 9151Define this macro for systems like AIX, where the linker discards 9152object files that are not referenced from @code{main} and uses export 9153lists. 9154 9155@findex MODIFY_JNI_METHOD_CALL 9156@item MODIFY_JNI_METHOD_CALL (@var{mdecl}) 9157Define this macro to a C expression representing a variant of the 9158method call @var{mdecl}, if Java Native Interface (JNI) methods 9159must be invoked differently from other methods on your target. 9160For example, on 32-bit Windows, JNI methods must be invoked using 9161the @code{stdcall} calling convention and this macro is then 9162defined as this expression: 9163 9164@smallexample 9165build_type_attribute_variant (@var{mdecl}, 9166 build_tree_list 9167 (get_identifier ("stdcall"), 9168 NULL)) 9169@end smallexample 9170 9171@end table 9172 9173@deftypefn {Target Hook} bool TARGET_CANNOT_MODIFY_JUMPS_P (void) 9174This target hook returns @code{true} past the point in which new jump 9175instructions could be created. On machines that require a register for 9176every jump such as the SHmedia ISA of SH5, this point would typically be 9177reload, so this target hook should be defined to a function such as: 9178 9179@smallexample 9180static bool 9181cannot_modify_jumps_past_reload_p () 9182@{ 9183 return (reload_completed || reload_in_progress); 9184@} 9185@end smallexample 9186@end deftypefn 9187