tm.texi revision 96263
1@c Copyright (C) 1988,1989,1992,1993,1994,1995,1996,1997,1998,1999,2000,2001,2002 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* Cross-compilation:: 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* Misc:: Everything else. 53@end menu 54 55@node Target Structure 56@section The Global @code{targetm} Variable 57@cindex target hooks 58@cindex target functions 59 60@deftypevar {struct gcc_target} targetm 61The target @file{.c} file must define the global @code{targetm} variable 62which contains pointers to functions and data relating to the target 63machine. The variable is declared in @file{target.h}; 64@file{target-def.h} defines the macro @code{TARGET_INITIALIZER} which is 65used to initialize the variable, and macros for the default initializers 66for elements of the structure. The @file{.c} file should override those 67macros for which the default definition is inappropriate. For example: 68@smallexample 69#include "target.h" 70#include "target-def.h" 71 72/* @r{Initialize the GCC target structure.} */ 73 74#undef TARGET_COMP_TYPE_ATTRIBUTES 75#define TARGET_COMP_TYPE_ATTRIBUTES @var{machine}_comp_type_attributes 76 77struct gcc_target targetm = TARGET_INITIALIZER; 78@end smallexample 79@end deftypevar 80 81Where a macro should be defined in the @file{.c} file in this manner to 82form part of the @code{targetm} structure, it is documented below as a 83``Target Hook'' with a prototype. Many macros will change in future 84from being defined in the @file{.h} file to being part of the 85@code{targetm} structure. 86 87@node Driver 88@section Controlling the Compilation Driver, @file{gcc} 89@cindex driver 90@cindex controlling the compilation driver 91 92@c prevent bad page break with this line 93You can control the compilation driver. 94 95@table @code 96@findex SWITCH_TAKES_ARG 97@item SWITCH_TAKES_ARG (@var{char}) 98A C expression which determines whether the option @option{-@var{char}} 99takes arguments. The value should be the number of arguments that 100option takes--zero, for many options. 101 102By default, this macro is defined as 103@code{DEFAULT_SWITCH_TAKES_ARG}, which handles the standard options 104properly. You need not define @code{SWITCH_TAKES_ARG} unless you 105wish to add additional options which take arguments. Any redefinition 106should call @code{DEFAULT_SWITCH_TAKES_ARG} and then check for 107additional options. 108 109@findex WORD_SWITCH_TAKES_ARG 110@item WORD_SWITCH_TAKES_ARG (@var{name}) 111A C expression which determines whether the option @option{-@var{name}} 112takes arguments. The value should be the number of arguments that 113option takes--zero, for many options. This macro rather than 114@code{SWITCH_TAKES_ARG} is used for multi-character option names. 115 116By default, this macro is defined as 117@code{DEFAULT_WORD_SWITCH_TAKES_ARG}, which handles the standard options 118properly. You need not define @code{WORD_SWITCH_TAKES_ARG} unless you 119wish to add additional options which take arguments. Any redefinition 120should call @code{DEFAULT_WORD_SWITCH_TAKES_ARG} and then check for 121additional options. 122 123@findex SWITCH_CURTAILS_COMPILATION 124@item SWITCH_CURTAILS_COMPILATION (@var{char}) 125A C expression which determines whether the option @option{-@var{char}} 126stops compilation before the generation of an executable. The value is 127boolean, nonzero if the option does stop an executable from being 128generated, zero otherwise. 129 130By default, this macro is defined as 131@code{DEFAULT_SWITCH_CURTAILS_COMPILATION}, which handles the standard 132options properly. You need not define 133@code{SWITCH_CURTAILS_COMPILATION} unless you wish to add additional 134options which affect the generation of an executable. Any redefinition 135should call @code{DEFAULT_SWITCH_CURTAILS_COMPILATION} and then check 136for additional options. 137 138@findex SWITCHES_NEED_SPACES 139@item SWITCHES_NEED_SPACES 140A string-valued C expression which enumerates the options for which 141the linker needs a space between the option and its argument. 142 143If this macro is not defined, the default value is @code{""}. 144 145@findex TARGET_OPTION_TRANSLATE_TABLE 146@item TARGET_OPTION_TRANSLATE_TABLE 147If defined, a list of pairs of strings, the first of which is a 148potential command line target to the @file{gcc} driver program, and the 149second of which is a space-separated (tabs and other whitespace are not 150supported) list of options with which to replace the first option. The 151target defining this list is responsible for assuring that the results 152are valid. Replacement options may not be the @code{--opt} style, they 153must be the @code{-opt} style. It is the intention of this macro to 154provide a mechanism for substitution that affects the multilibs chosen, 155such as one option that enables many options, some of which select 156multilibs. Example nonsensical definition, where @code{-malt-abi}, 157@code{-EB}, and @code{-mspoo} cause different multilibs to be chosen: 158 159@example 160#define TARGET_OPTION_TRANSLATE_TABLE \ 161@{ "-fast", "-march=fast-foo -malt-abi -I/usr/fast-foo" @}, \ 162@{ "-compat", "-EB -malign=4 -mspoo" @} 163@end example 164 165@findex CPP_SPEC 166@item CPP_SPEC 167A C string constant that tells the GCC driver program options to 168pass to CPP@. It can also specify how to translate options you 169give to GCC into options for GCC to pass to the CPP@. 170 171Do not define this macro if it does not need to do anything. 172 173@findex CPLUSPLUS_CPP_SPEC 174@item CPLUSPLUS_CPP_SPEC 175This macro is just like @code{CPP_SPEC}, but is used for C++, rather 176than C@. If you do not define this macro, then the value of 177@code{CPP_SPEC} (if any) will be used instead. 178 179@findex NO_BUILTIN_SIZE_TYPE 180@item NO_BUILTIN_SIZE_TYPE 181If this macro is defined, the preprocessor will not define the built-in macro 182@code{__SIZE_TYPE__}. The macro @code{__SIZE_TYPE__} must then be defined 183by @code{CPP_SPEC} instead. 184 185This should be defined if @code{SIZE_TYPE} depends on target dependent flags 186which are not accessible to the preprocessor. Otherwise, it should not 187be defined. 188 189@findex NO_BUILTIN_PTRDIFF_TYPE 190@item NO_BUILTIN_PTRDIFF_TYPE 191If this macro is defined, the preprocessor will not define the built-in macro 192@code{__PTRDIFF_TYPE__}. The macro @code{__PTRDIFF_TYPE__} must then be 193defined by @code{CPP_SPEC} instead. 194 195This should be defined if @code{PTRDIFF_TYPE} depends on target dependent flags 196which are not accessible to the preprocessor. Otherwise, it should not 197be defined. 198 199@findex NO_BUILTIN_WCHAR_TYPE 200@item NO_BUILTIN_WCHAR_TYPE 201If this macro is defined, the preprocessor will not define the built-in macro 202@code{__WCHAR_TYPE__}. The macro @code{__WCHAR_TYPE__} must then be 203defined by @code{CPP_SPEC} instead. 204 205This should be defined if @code{WCHAR_TYPE} depends on target dependent flags 206which are not accessible to the preprocessor. Otherwise, it should not 207be defined. 208 209@findex NO_BUILTIN_WINT_TYPE 210@item NO_BUILTIN_WINT_TYPE 211If this macro is defined, the preprocessor will not define the built-in macro 212@code{__WINT_TYPE__}. The macro @code{__WINT_TYPE__} must then be 213defined by @code{CPP_SPEC} instead. 214 215This should be defined if @code{WINT_TYPE} depends on target dependent flags 216which are not accessible to the preprocessor. Otherwise, it should not 217be defined. 218 219@findex CC1_SPEC 220@item CC1_SPEC 221A C string constant that tells the GCC driver program options to 222pass to @code{cc1}, @code{cc1plus}, @code{f771}, and the other language 223front ends. 224It can also specify how to translate options you give to GCC into options 225for GCC to pass to front ends. 226 227Do not define this macro if it does not need to do anything. 228 229@findex CC1PLUS_SPEC 230@item CC1PLUS_SPEC 231A C string constant that tells the GCC driver program options to 232pass to @code{cc1plus}. It can also specify how to translate options you 233give to GCC into options for GCC to pass to the @code{cc1plus}. 234 235Do not define this macro if it does not need to do anything. 236Note that everything defined in CC1_SPEC is already passed to 237@code{cc1plus} so there is no need to duplicate the contents of 238CC1_SPEC in CC1PLUS_SPEC@. 239 240@findex ASM_SPEC 241@item ASM_SPEC 242A C string constant that tells the GCC driver program options to 243pass to the assembler. It can also specify how to translate options 244you give to GCC into options for GCC to pass to the assembler. 245See the file @file{sun3.h} for an example of this. 246 247Do not define this macro if it does not need to do anything. 248 249@findex ASM_FINAL_SPEC 250@item ASM_FINAL_SPEC 251A C string constant that tells the GCC driver program how to 252run any programs which cleanup after the normal assembler. 253Normally, this is not needed. See the file @file{mips.h} for 254an example of this. 255 256Do not define this macro if it does not need to do anything. 257 258@findex LINK_SPEC 259@item LINK_SPEC 260A C string constant that tells the GCC driver program options to 261pass to the linker. It can also specify how to translate options you 262give to GCC into options for GCC to pass to the linker. 263 264Do not define this macro if it does not need to do anything. 265 266@findex LIB_SPEC 267@item LIB_SPEC 268Another C string constant used much like @code{LINK_SPEC}. The difference 269between the two is that @code{LIB_SPEC} is used at the end of the 270command given to the linker. 271 272If this macro is not defined, a default is provided that 273loads the standard C library from the usual place. See @file{gcc.c}. 274 275@findex LIBGCC_SPEC 276@item LIBGCC_SPEC 277Another C string constant that tells the GCC driver program 278how and when to place a reference to @file{libgcc.a} into the 279linker command line. This constant is placed both before and after 280the value of @code{LIB_SPEC}. 281 282If this macro is not defined, the GCC driver provides a default that 283passes the string @option{-lgcc} to the linker. 284 285@findex STARTFILE_SPEC 286@item STARTFILE_SPEC 287Another C string constant used much like @code{LINK_SPEC}. The 288difference between the two is that @code{STARTFILE_SPEC} is used at 289the very beginning of the command given to the linker. 290 291If this macro is not defined, a default is provided that loads the 292standard C startup file from the usual place. See @file{gcc.c}. 293 294@findex ENDFILE_SPEC 295@item ENDFILE_SPEC 296Another C string constant used much like @code{LINK_SPEC}. The 297difference between the two is that @code{ENDFILE_SPEC} is used at 298the very end of the command given to the linker. 299 300Do not define this macro if it does not need to do anything. 301 302@findex THREAD_MODEL_SPEC 303@item THREAD_MODEL_SPEC 304GCC @code{-v} will print the thread model GCC was configured to use. 305However, this doesn't work on platforms that are multilibbed on thread 306models, such as AIX 4.3. On such platforms, define 307@code{THREAD_MODEL_SPEC} such that it evaluates to a string without 308blanks that names one of the recognized thread models. @code{%*}, the 309default value of this macro, will expand to the value of 310@code{thread_file} set in @file{config.gcc}. 311 312@findex EXTRA_SPECS 313@item EXTRA_SPECS 314Define this macro to provide additional specifications to put in the 315@file{specs} file that can be used in various specifications like 316@code{CC1_SPEC}. 317 318The definition should be an initializer for an array of structures, 319containing a string constant, that defines the specification name, and a 320string constant that provides the specification. 321 322Do not define this macro if it does not need to do anything. 323 324@code{EXTRA_SPECS} is useful when an architecture contains several 325related targets, which have various @code{@dots{}_SPECS} which are similar 326to each other, and the maintainer would like one central place to keep 327these definitions. 328 329For example, the PowerPC System V.4 targets use @code{EXTRA_SPECS} to 330define either @code{_CALL_SYSV} when the System V calling sequence is 331used or @code{_CALL_AIX} when the older AIX-based calling sequence is 332used. 333 334The @file{config/rs6000/rs6000.h} target file defines: 335 336@example 337#define EXTRA_SPECS \ 338 @{ "cpp_sysv_default", CPP_SYSV_DEFAULT @}, 339 340#define CPP_SYS_DEFAULT "" 341@end example 342 343The @file{config/rs6000/sysv.h} target file defines: 344@smallexample 345#undef CPP_SPEC 346#define CPP_SPEC \ 347"%@{posix: -D_POSIX_SOURCE @} \ 348%@{mcall-sysv: -D_CALL_SYSV @} %@{mcall-aix: -D_CALL_AIX @} \ 349%@{!mcall-sysv: %@{!mcall-aix: %(cpp_sysv_default) @}@} \ 350%@{msoft-float: -D_SOFT_FLOAT@} %@{mcpu=403: -D_SOFT_FLOAT@}" 351 352#undef CPP_SYSV_DEFAULT 353#define CPP_SYSV_DEFAULT "-D_CALL_SYSV" 354@end smallexample 355 356while the @file{config/rs6000/eabiaix.h} target file defines 357@code{CPP_SYSV_DEFAULT} as: 358 359@smallexample 360#undef CPP_SYSV_DEFAULT 361#define CPP_SYSV_DEFAULT "-D_CALL_AIX" 362@end smallexample 363 364@findex LINK_LIBGCC_SPECIAL 365@item LINK_LIBGCC_SPECIAL 366Define this macro if the driver program should find the library 367@file{libgcc.a} itself and should not pass @option{-L} options to the 368linker. If you do not define this macro, the driver program will pass 369the argument @option{-lgcc} to tell the linker to do the search and will 370pass @option{-L} options to it. 371 372@findex LINK_LIBGCC_SPECIAL_1 373@item LINK_LIBGCC_SPECIAL_1 374Define this macro if the driver program should find the library 375@file{libgcc.a}. If you do not define this macro, the driver program will pass 376the argument @option{-lgcc} to tell the linker to do the search. 377This macro is similar to @code{LINK_LIBGCC_SPECIAL}, except that it does 378not affect @option{-L} options. 379 380@findex LINK_GCC_C_SEQUENCE_SPEC 381@item LINK_GCC_C_SEQUENCE_SPEC 382The sequence in which libgcc and libc are specified to the linker. 383By default this is @code{%G %L %G}. 384 385@findex LINK_COMMAND_SPEC 386@item LINK_COMMAND_SPEC 387A C string constant giving the complete command line need to execute the 388linker. When you do this, you will need to update your port each time a 389change is made to the link command line within @file{gcc.c}. Therefore, 390define this macro only if you need to completely redefine the command 391line for invoking the linker and there is no other way to accomplish 392the effect you need. Overriding this macro may be avoidable by overriding 393@code{LINK_GCC_C_SEQUENCE_SPEC} instead. 394 395@findex LINK_ELIMINATE_DUPLICATE_LDIRECTORIES 396@item LINK_ELIMINATE_DUPLICATE_LDIRECTORIES 397A nonzero value causes @command{collect2} to remove duplicate @option{-L@var{directory}} search 398directories from linking commands. Do not give it a nonzero value if 399removing duplicate search directories changes the linker's semantics. 400 401@findex MULTILIB_DEFAULTS 402@item MULTILIB_DEFAULTS 403Define this macro as a C expression for the initializer of an array of 404string to tell the driver program which options are defaults for this 405target and thus do not need to be handled specially when using 406@code{MULTILIB_OPTIONS}. 407 408Do not define this macro if @code{MULTILIB_OPTIONS} is not defined in 409the target makefile fragment or if none of the options listed in 410@code{MULTILIB_OPTIONS} are set by default. 411@xref{Target Fragment}. 412 413@findex RELATIVE_PREFIX_NOT_LINKDIR 414@item RELATIVE_PREFIX_NOT_LINKDIR 415Define this macro to tell @code{gcc} that it should only translate 416a @option{-B} prefix into a @option{-L} linker option if the prefix 417indicates an absolute file name. 418 419@findex STANDARD_EXEC_PREFIX 420@item STANDARD_EXEC_PREFIX 421Define this macro as a C string constant if you wish to override the 422standard choice of @file{/usr/local/lib/gcc-lib/} as the default prefix to 423try when searching for the executable files of the compiler. 424 425@findex MD_EXEC_PREFIX 426@item MD_EXEC_PREFIX 427If defined, this macro is an additional prefix to try after 428@code{STANDARD_EXEC_PREFIX}. @code{MD_EXEC_PREFIX} is not searched 429when the @option{-b} option is used, or the compiler is built as a cross 430compiler. If you define @code{MD_EXEC_PREFIX}, then be sure to add it 431to the list of directories used to find the assembler in @file{configure.in}. 432 433@findex STANDARD_STARTFILE_PREFIX 434@item STANDARD_STARTFILE_PREFIX 435Define this macro as a C string constant if you wish to override the 436standard choice of @file{/usr/local/lib/} as the default prefix to 437try when searching for startup files such as @file{crt0.o}. 438 439@findex MD_STARTFILE_PREFIX 440@item MD_STARTFILE_PREFIX 441If defined, this macro supplies an additional prefix to try after the 442standard prefixes. @code{MD_EXEC_PREFIX} is not searched when the 443@option{-b} option is used, or when the compiler is built as a cross 444compiler. 445 446@findex MD_STARTFILE_PREFIX_1 447@item MD_STARTFILE_PREFIX_1 448If defined, this macro supplies yet another prefix to try after the 449standard prefixes. It is not searched when the @option{-b} option is 450used, or when the compiler is built as a cross compiler. 451 452@findex INIT_ENVIRONMENT 453@item INIT_ENVIRONMENT 454Define this macro as a C string constant if you wish to set environment 455variables for programs called by the driver, such as the assembler and 456loader. The driver passes the value of this macro to @code{putenv} to 457initialize the necessary environment variables. 458 459@findex LOCAL_INCLUDE_DIR 460@item LOCAL_INCLUDE_DIR 461Define this macro as a C string constant if you wish to override the 462standard choice of @file{/usr/local/include} as the default prefix to 463try when searching for local header files. @code{LOCAL_INCLUDE_DIR} 464comes before @code{SYSTEM_INCLUDE_DIR} in the search order. 465 466Cross compilers do not search either @file{/usr/local/include} or its 467replacement. 468 469@findex MODIFY_TARGET_NAME 470@item MODIFY_TARGET_NAME 471Define this macro if you with to define command-line switches that modify the 472default target name 473 474For each switch, you can include a string to be appended to the first 475part of the configuration name or a string to be deleted from the 476configuration name, if present. The definition should be an initializer 477for an array of structures. Each array element should have three 478elements: the switch name (a string constant, including the initial 479dash), one of the enumeration codes @code{ADD} or @code{DELETE} to 480indicate whether the string should be inserted or deleted, and the string 481to be inserted or deleted (a string constant). 482 483For example, on a machine where @samp{64} at the end of the 484configuration name denotes a 64-bit target and you want the @option{-32} 485and @option{-64} switches to select between 32- and 64-bit targets, you would 486code 487 488@smallexample 489#define MODIFY_TARGET_NAME \ 490 @{ @{ "-32", DELETE, "64"@}, \ 491 @{"-64", ADD, "64"@}@} 492@end smallexample 493 494 495@findex SYSTEM_INCLUDE_DIR 496@item SYSTEM_INCLUDE_DIR 497Define this macro as a C string constant if you wish to specify a 498system-specific directory to search for header files before the standard 499directory. @code{SYSTEM_INCLUDE_DIR} comes before 500@code{STANDARD_INCLUDE_DIR} in the search order. 501 502Cross compilers do not use this macro and do not search the directory 503specified. 504 505@findex STANDARD_INCLUDE_DIR 506@item STANDARD_INCLUDE_DIR 507Define this macro as a C string constant if you wish to override the 508standard choice of @file{/usr/include} as the default prefix to 509try when searching for header files. 510 511Cross compilers do not use this macro and do not search either 512@file{/usr/include} or its replacement. 513 514@findex STANDARD_INCLUDE_COMPONENT 515@item STANDARD_INCLUDE_COMPONENT 516The ``component'' corresponding to @code{STANDARD_INCLUDE_DIR}. 517See @code{INCLUDE_DEFAULTS}, below, for the description of components. 518If you do not define this macro, no component is used. 519 520@findex INCLUDE_DEFAULTS 521@item INCLUDE_DEFAULTS 522Define this macro if you wish to override the entire default search path 523for include files. For a native compiler, the default search path 524usually consists of @code{GCC_INCLUDE_DIR}, @code{LOCAL_INCLUDE_DIR}, 525@code{SYSTEM_INCLUDE_DIR}, @code{GPLUSPLUS_INCLUDE_DIR}, and 526@code{STANDARD_INCLUDE_DIR}. In addition, @code{GPLUSPLUS_INCLUDE_DIR} 527and @code{GCC_INCLUDE_DIR} are defined automatically by @file{Makefile}, 528and specify private search areas for GCC@. The directory 529@code{GPLUSPLUS_INCLUDE_DIR} is used only for C++ programs. 530 531The definition should be an initializer for an array of structures. 532Each array element should have four elements: the directory name (a 533string constant), the component name (also a string constant), a flag 534for C++-only directories, 535and a flag showing that the includes in the directory don't need to be 536wrapped in @code{extern @samp{C}} when compiling C++. Mark the end of 537the array with a null element. 538 539The component name denotes what GNU package the include file is part of, 540if any, in all upper-case letters. For example, it might be @samp{GCC} 541or @samp{BINUTILS}. If the package is part of a vendor-supplied 542operating system, code the component name as @samp{0}. 543 544For example, here is the definition used for VAX/VMS: 545 546@example 547#define INCLUDE_DEFAULTS \ 548@{ \ 549 @{ "GNU_GXX_INCLUDE:", "G++", 1, 1@}, \ 550 @{ "GNU_CC_INCLUDE:", "GCC", 0, 0@}, \ 551 @{ "SYS$SYSROOT:[SYSLIB.]", 0, 0, 0@}, \ 552 @{ ".", 0, 0, 0@}, \ 553 @{ 0, 0, 0, 0@} \ 554@} 555@end example 556@end table 557 558Here is the order of prefixes tried for exec files: 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{COMPILER_PATH}. 569 570@item 571The macro @code{STANDARD_EXEC_PREFIX}. 572 573@item 574@file{/usr/lib/gcc/}. 575 576@item 577The macro @code{MD_EXEC_PREFIX}, if any. 578@end enumerate 579 580Here is the order of prefixes tried for startfiles: 581 582@enumerate 583@item 584Any prefixes specified by the user with @option{-B}. 585 586@item 587The environment variable @code{GCC_EXEC_PREFIX}, if any. 588 589@item 590The directories specified by the environment variable @code{LIBRARY_PATH} 591(or port-specific name; native only, cross compilers do not use this). 592 593@item 594The macro @code{STANDARD_EXEC_PREFIX}. 595 596@item 597@file{/usr/lib/gcc/}. 598 599@item 600The macro @code{MD_EXEC_PREFIX}, if any. 601 602@item 603The macro @code{MD_STARTFILE_PREFIX}, if any. 604 605@item 606The macro @code{STANDARD_STARTFILE_PREFIX}. 607 608@item 609@file{/lib/}. 610 611@item 612@file{/usr/lib/}. 613@end enumerate 614 615@node Run-time Target 616@section Run-time Target Specification 617@cindex run-time target specification 618@cindex predefined macros 619@cindex target specifications 620 621@c prevent bad page break with this line 622Here are run-time target specifications. 623 624@table @code 625@findex CPP_PREDEFINES 626@item CPP_PREDEFINES 627Define this to be a string constant containing @option{-D} options to 628define the predefined macros that identify this machine and system. 629These macros will be predefined unless the @option{-ansi} option (or a 630@option{-std} option for strict ISO C conformance) is specified. 631 632In addition, a parallel set of macros are predefined, whose names are 633made by appending @samp{__} at the beginning and at the end. These 634@samp{__} macros are permitted by the ISO standard, so they are 635predefined regardless of whether @option{-ansi} or a @option{-std} option 636is specified. 637 638For example, on the Sun, one can use the following value: 639 640@smallexample 641"-Dmc68000 -Dsun -Dunix" 642@end smallexample 643 644The result is to define the macros @code{__mc68000__}, @code{__sun__} 645and @code{__unix__} unconditionally, and the macros @code{mc68000}, 646@code{sun} and @code{unix} provided @option{-ansi} is not specified. 647 648@findex extern int target_flags 649@item extern int target_flags; 650This declaration should be present. 651 652@cindex optional hardware or system features 653@cindex features, optional, in system conventions 654@item TARGET_@dots{} 655This series of macros is to allow compiler command arguments to 656enable or disable the use of optional features of the target machine. 657For example, one machine description serves both the 68000 and 658the 68020; a command argument tells the compiler whether it should 659use 68020-only instructions or not. This command argument works 660by means of a macro @code{TARGET_68020} that tests a bit in 661@code{target_flags}. 662 663Define a macro @code{TARGET_@var{featurename}} for each such option. 664Its definition should test a bit in @code{target_flags}. It is 665recommended that a helper macro @code{TARGET_MASK_@var{featurename}} 666is defined for each bit-value to test, and used in 667@code{TARGET_@var{featurename}} and @code{TARGET_SWITCHES}. For 668example: 669 670@smallexample 671#define TARGET_MASK_68020 1 672#define TARGET_68020 (target_flags & TARGET_MASK_68020) 673@end smallexample 674 675One place where these macros are used is in the condition-expressions 676of instruction patterns. Note how @code{TARGET_68020} appears 677frequently in the 68000 machine description file, @file{m68k.md}. 678Another place they are used is in the definitions of the other 679macros in the @file{@var{machine}.h} file. 680 681@findex TARGET_SWITCHES 682@item TARGET_SWITCHES 683This macro defines names of command options to set and clear 684bits in @code{target_flags}. Its definition is an initializer 685with a subgrouping for each command option. 686 687Each subgrouping contains a string constant, that defines the option 688name, a number, which contains the bits to set in 689@code{target_flags}, and a second string which is the description 690displayed by @option{--help}. If the number is negative then the bits specified 691by the number are cleared instead of being set. If the description 692string is present but empty, then no help information will be displayed 693for that option, but it will not count as an undocumented option. The 694actual option name is made by appending @samp{-m} to the specified name. 695Non-empty description strings should be marked with @code{N_(@dots{})} for 696@command{xgettext}. Please do not mark empty strings because the empty 697string is reserved by GNU gettext. @code{gettext("")} returns the header entry 698of the message catalog with meta information, not the empty string. 699 700In addition to the description for @option{--help}, 701more detailed documentation for each option should be added to 702@file{invoke.texi}. 703 704One of the subgroupings should have a null string. The number in 705this grouping is the default value for @code{target_flags}. Any 706target options act starting with that value. 707 708Here is an example which defines @option{-m68000} and @option{-m68020} 709with opposite meanings, and picks the latter as the default: 710 711@smallexample 712#define TARGET_SWITCHES \ 713 @{ @{ "68020", TARGET_MASK_68020, "" @}, \ 714 @{ "68000", -TARGET_MASK_68020, \ 715 N_("Compile for the 68000") @}, \ 716 @{ "", TARGET_MASK_68020, "" @}@} 717@end smallexample 718 719@findex TARGET_OPTIONS 720@item TARGET_OPTIONS 721This macro is similar to @code{TARGET_SWITCHES} but defines names of command 722options that have values. Its definition is an initializer with a 723subgrouping for each command option. 724 725Each subgrouping contains a string constant, that defines the fixed part 726of the option name, the address of a variable, and a description string. 727Non-empty description strings should be marked with @code{N_(@dots{})} for 728@command{xgettext}. Please do not mark empty strings because the empty 729string is reserved by GNU gettext. @code{gettext("")} returns the header entry 730of the message catalog with meta information, not the empty string. 731 732The variable, type @code{char *}, is set to the variable part of the 733given option if the fixed part matches. The actual option name is made 734by appending @samp{-m} to the specified name. Again, each option should 735also be documented in @file{invoke.texi}. 736 737Here is an example which defines @option{-mshort-data-@var{number}}. If the 738given option is @option{-mshort-data-512}, the variable @code{m88k_short_data} 739will be set to the string @code{"512"}. 740 741@smallexample 742extern char *m88k_short_data; 743#define TARGET_OPTIONS \ 744 @{ @{ "short-data-", &m88k_short_data, \ 745 N_("Specify the size of the short data section") @} @} 746@end smallexample 747 748@findex TARGET_VERSION 749@item TARGET_VERSION 750This macro is a C statement to print on @code{stderr} a string 751describing the particular machine description choice. Every machine 752description should define @code{TARGET_VERSION}. For example: 753 754@smallexample 755#ifdef MOTOROLA 756#define TARGET_VERSION \ 757 fprintf (stderr, " (68k, Motorola syntax)"); 758#else 759#define TARGET_VERSION \ 760 fprintf (stderr, " (68k, MIT syntax)"); 761#endif 762@end smallexample 763 764@findex OVERRIDE_OPTIONS 765@item OVERRIDE_OPTIONS 766Sometimes certain combinations of command options do not make sense on 767a particular target machine. You can define a macro 768@code{OVERRIDE_OPTIONS} to take account of this. This macro, if 769defined, is executed once just after all the command options have been 770parsed. 771 772Don't use this macro to turn on various extra optimizations for 773@option{-O}. That is what @code{OPTIMIZATION_OPTIONS} is for. 774 775@findex OPTIMIZATION_OPTIONS 776@item OPTIMIZATION_OPTIONS (@var{level}, @var{size}) 777Some machines may desire to change what optimizations are performed for 778various optimization levels. This macro, if defined, is executed once 779just after the optimization level is determined and before the remainder 780of the command options have been parsed. Values set in this macro are 781used as the default values for the other command line options. 782 783@var{level} is the optimization level specified; 2 if @option{-O2} is 784specified, 1 if @option{-O} is specified, and 0 if neither is specified. 785 786@var{size} is nonzero if @option{-Os} is specified and zero otherwise. 787 788You should not use this macro to change options that are not 789machine-specific. These should uniformly selected by the same 790optimization level on all supported machines. Use this macro to enable 791machine-specific optimizations. 792 793@strong{Do not examine @code{write_symbols} in 794this macro!} The debugging options are not supposed to alter the 795generated code. 796 797@findex CAN_DEBUG_WITHOUT_FP 798@item CAN_DEBUG_WITHOUT_FP 799Define this macro if debugging can be performed even without a frame 800pointer. If this macro is defined, GCC will turn on the 801@option{-fomit-frame-pointer} option whenever @option{-O} is specified. 802@end table 803 804@node Per-Function Data 805@section Defining data structures for per-function information. 806@cindex per-function data 807@cindex data structures 808 809If the target needs to store information on a per-function basis, GCC 810provides a macro and a couple of variables to allow this. Note, just 811using statics to store the information is a bad idea, since GCC supports 812nested functions, so you can be halfway through encoding one function 813when another one comes along. 814 815GCC defines a data structure called @code{struct function} which 816contains all of the data specific to an individual function. This 817structure contains a field called @code{machine} whose type is 818@code{struct machine_function *}, which can be used by targets to point 819to their own specific data. 820 821If a target needs per-function specific data it should define the type 822@code{struct machine_function} and also the macro 823@code{INIT_EXPANDERS}. This macro should be used to initialize some or 824all of the function pointers @code{init_machine_status}, 825@code{free_machine_status} and @code{mark_machine_status}. These 826pointers are explained below. 827 828One typical use of per-function, target specific data is to create an 829RTX to hold the register containing the function's return address. This 830RTX can then be used to implement the @code{__builtin_return_address} 831function, for level 0. 832 833Note---earlier implementations of GCC used a single data area to hold 834all of the per-function information. Thus when processing of a nested 835function began the old per-function data had to be pushed onto a 836stack, and when the processing was finished, it had to be popped off the 837stack. GCC used to provide function pointers called 838@code{save_machine_status} and @code{restore_machine_status} to handle 839the saving and restoring of the target specific information. Since the 840single data area approach is no longer used, these pointers are no 841longer supported. 842 843The macro and function pointers are described below. 844 845@table @code 846@findex INIT_EXPANDERS 847@item INIT_EXPANDERS 848Macro called to initialize any target specific information. This macro 849is called once per function, before generation of any RTL has begun. 850The intention of this macro is to allow the initialization of the 851function pointers below. 852 853@findex init_machine_status 854@item init_machine_status 855This is a @code{void (*)(struct function *)} function pointer. If this 856pointer is non-@code{NULL} it will be called once per function, before function 857compilation starts, in order to allow the target to perform any target 858specific initialization of the @code{struct function} structure. It is 859intended that this would be used to initialize the @code{machine} of 860that structure. 861 862@findex free_machine_status 863@item free_machine_status 864This is a @code{void (*)(struct function *)} function pointer. If this 865pointer is non-@code{NULL} it will be called once per function, after the 866function has been compiled, in order to allow any memory allocated 867during the @code{init_machine_status} function call to be freed. 868 869@findex mark_machine_status 870@item mark_machine_status 871This is a @code{void (*)(struct function *)} function pointer. If this 872pointer is non-@code{NULL} it will be called once per function in order to mark 873any data items in the @code{struct machine_function} structure which 874need garbage collection. 875 876@end table 877 878@node Storage Layout 879@section Storage Layout 880@cindex storage layout 881 882Note that the definitions of the macros in this table which are sizes or 883alignments measured in bits do not need to be constant. They can be C 884expressions that refer to static variables, such as the @code{target_flags}. 885@xref{Run-time Target}. 886 887@table @code 888@findex BITS_BIG_ENDIAN 889@item BITS_BIG_ENDIAN 890Define this macro to have the value 1 if the most significant bit in a 891byte has the lowest number; otherwise define it to have the value zero. 892This means that bit-field instructions count from the most significant 893bit. If the machine has no bit-field instructions, then this must still 894be defined, but it doesn't matter which value it is defined to. This 895macro need not be a constant. 896 897This macro does not affect the way structure fields are packed into 898bytes or words; that is controlled by @code{BYTES_BIG_ENDIAN}. 899 900@findex BYTES_BIG_ENDIAN 901@item BYTES_BIG_ENDIAN 902Define this macro to have the value 1 if the most significant byte in a 903word has the lowest number. This macro need not be a constant. 904 905@findex WORDS_BIG_ENDIAN 906@item WORDS_BIG_ENDIAN 907Define this macro to have the value 1 if, in a multiword object, the 908most significant word has the lowest number. This applies to both 909memory locations and registers; GCC fundamentally assumes that the 910order of words in memory is the same as the order in registers. This 911macro need not be a constant. 912 913@findex LIBGCC2_WORDS_BIG_ENDIAN 914@item LIBGCC2_WORDS_BIG_ENDIAN 915Define this macro if @code{WORDS_BIG_ENDIAN} is not constant. This must be a 916constant value with the same meaning as @code{WORDS_BIG_ENDIAN}, which will be 917used only when compiling @file{libgcc2.c}. Typically the value will be set 918based on preprocessor defines. 919 920@findex FLOAT_WORDS_BIG_ENDIAN 921@item FLOAT_WORDS_BIG_ENDIAN 922Define this macro to have the value 1 if @code{DFmode}, @code{XFmode} or 923@code{TFmode} floating point numbers are stored in memory with the word 924containing the sign bit at the lowest address; otherwise define it to 925have the value 0. This macro need not be a constant. 926 927You need not define this macro if the ordering is the same as for 928multi-word integers. 929 930@findex BITS_PER_UNIT 931@item BITS_PER_UNIT 932Define this macro to be the number of bits in an addressable storage 933unit (byte); normally 8. 934 935@findex BITS_PER_WORD 936@item BITS_PER_WORD 937Number of bits in a word; normally 32. 938 939@findex MAX_BITS_PER_WORD 940@item MAX_BITS_PER_WORD 941Maximum number of bits in a word. If this is undefined, the default is 942@code{BITS_PER_WORD}. Otherwise, it is the constant value that is the 943largest value that @code{BITS_PER_WORD} can have at run-time. 944 945@findex UNITS_PER_WORD 946@item UNITS_PER_WORD 947Number of storage units in a word; normally 4. 948 949@findex MIN_UNITS_PER_WORD 950@item MIN_UNITS_PER_WORD 951Minimum number of units in a word. If this is undefined, the default is 952@code{UNITS_PER_WORD}. Otherwise, it is the constant value that is the 953smallest value that @code{UNITS_PER_WORD} can have at run-time. 954 955@findex POINTER_SIZE 956@item POINTER_SIZE 957Width of a pointer, in bits. You must specify a value no wider than the 958width of @code{Pmode}. If it is not equal to the width of @code{Pmode}, 959you must define @code{POINTERS_EXTEND_UNSIGNED}. 960 961@findex POINTERS_EXTEND_UNSIGNED 962@item POINTERS_EXTEND_UNSIGNED 963A C expression whose value is greater than zero if pointers that need to be 964extended from being @code{POINTER_SIZE} bits wide to @code{Pmode} are to 965be zero-extended and zero if they are to be sign-extended. If the value 966is less then zero then there must be an "ptr_extend" instruction that 967extends a pointer from @code{POINTER_SIZE} to @code{Pmode}. 968 969You need not define this macro if the @code{POINTER_SIZE} is equal 970to the width of @code{Pmode}. 971 972@findex PROMOTE_MODE 973@item PROMOTE_MODE (@var{m}, @var{unsignedp}, @var{type}) 974A macro to update @var{m} and @var{unsignedp} when an object whose type 975is @var{type} and which has the specified mode and signedness is to be 976stored in a register. This macro is only called when @var{type} is a 977scalar type. 978 979On most RISC machines, which only have operations that operate on a full 980register, define this macro to set @var{m} to @code{word_mode} if 981@var{m} is an integer mode narrower than @code{BITS_PER_WORD}. In most 982cases, only integer modes should be widened because wider-precision 983floating-point operations are usually more expensive than their narrower 984counterparts. 985 986For most machines, the macro definition does not change @var{unsignedp}. 987However, some machines, have instructions that preferentially handle 988either signed or unsigned quantities of certain modes. For example, on 989the DEC Alpha, 32-bit loads from memory and 32-bit add instructions 990sign-extend the result to 64 bits. On such machines, set 991@var{unsignedp} according to which kind of extension is more efficient. 992 993Do not define this macro if it would never modify @var{m}. 994 995@findex PROMOTE_FUNCTION_ARGS 996@item PROMOTE_FUNCTION_ARGS 997Define this macro if the promotion described by @code{PROMOTE_MODE} 998should also be done for outgoing function arguments. 999 1000@findex PROMOTE_FUNCTION_RETURN 1001@item PROMOTE_FUNCTION_RETURN 1002Define this macro if the promotion described by @code{PROMOTE_MODE} 1003should also be done for the return value of functions. 1004 1005If this macro is defined, @code{FUNCTION_VALUE} must perform the same 1006promotions done by @code{PROMOTE_MODE}. 1007 1008@findex PROMOTE_FOR_CALL_ONLY 1009@item PROMOTE_FOR_CALL_ONLY 1010Define this macro if the promotion described by @code{PROMOTE_MODE} 1011should @emph{only} be performed for outgoing function arguments or 1012function return values, as specified by @code{PROMOTE_FUNCTION_ARGS} 1013and @code{PROMOTE_FUNCTION_RETURN}, respectively. 1014 1015@findex PARM_BOUNDARY 1016@item PARM_BOUNDARY 1017Normal alignment required for function parameters on the stack, in 1018bits. All stack parameters receive at least this much alignment 1019regardless of data type. On most machines, this is the same as the 1020size of an integer. 1021 1022@findex STACK_BOUNDARY 1023@item STACK_BOUNDARY 1024Define this macro to the minimum alignment enforced by hardware for the 1025stack pointer on this machine. The definition is a C expression for the 1026desired alignment (measured in bits). This value is used as a default 1027if @code{PREFERRED_STACK_BOUNDARY} is not defined. On most machines, 1028this should be the same as @code{PARM_BOUNDARY}. 1029 1030@findex PREFERRED_STACK_BOUNDARY 1031@item PREFERRED_STACK_BOUNDARY 1032Define this macro if you wish to preserve a certain alignment for the 1033stack pointer, greater than what the hardware enforces. The definition 1034is a C expression for the desired alignment (measured in bits). This 1035macro must evaluate to a value equal to or larger than 1036@code{STACK_BOUNDARY}. 1037 1038@findex FORCE_PREFERRED_STACK_BOUNDARY_IN_MAIN 1039@item FORCE_PREFERRED_STACK_BOUNDARY_IN_MAIN 1040A C expression that evaluates true if @code{PREFERRED_STACK_BOUNDARY} is 1041not guaranteed by the runtime and we should emit code to align the stack 1042at the beginning of @code{main}. 1043 1044@cindex @code{PUSH_ROUNDING}, interaction with @code{PREFERRED_STACK_BOUNDARY} 1045If @code{PUSH_ROUNDING} is not defined, the stack will always be aligned 1046to the specified boundary. If @code{PUSH_ROUNDING} is defined and specifies 1047a less strict alignment than @code{PREFERRED_STACK_BOUNDARY}, the stack may 1048be momentarily unaligned while pushing arguments. 1049 1050@findex FUNCTION_BOUNDARY 1051@item FUNCTION_BOUNDARY 1052Alignment required for a function entry point, in bits. 1053 1054@findex BIGGEST_ALIGNMENT 1055@item BIGGEST_ALIGNMENT 1056Biggest alignment that any data type can require on this machine, in bits. 1057 1058@findex MINIMUM_ATOMIC_ALIGNMENT 1059@item MINIMUM_ATOMIC_ALIGNMENT 1060If defined, the smallest alignment, in bits, that can be given to an 1061object that can be referenced in one operation, without disturbing any 1062nearby object. Normally, this is @code{BITS_PER_UNIT}, but may be larger 1063on machines that don't have byte or half-word store operations. 1064 1065@findex BIGGEST_FIELD_ALIGNMENT 1066@item BIGGEST_FIELD_ALIGNMENT 1067Biggest alignment that any structure or union field can require on this 1068machine, in bits. If defined, this overrides @code{BIGGEST_ALIGNMENT} for 1069structure and union fields only, unless the field alignment has been set 1070by the @code{__attribute__ ((aligned (@var{n})))} construct. 1071 1072@findex ADJUST_FIELD_ALIGN 1073@item ADJUST_FIELD_ALIGN (@var{field}, @var{computed}) 1074An expression for the alignment of a structure field @var{field} if the 1075alignment computed in the usual way is @var{computed}. GCC uses 1076this value instead of the value in @code{BIGGEST_ALIGNMENT} or 1077@code{BIGGEST_FIELD_ALIGNMENT}, if defined. 1078 1079@findex MAX_OFILE_ALIGNMENT 1080@item MAX_OFILE_ALIGNMENT 1081Biggest alignment supported by the object file format of this machine. 1082Use this macro to limit the alignment which can be specified using the 1083@code{__attribute__ ((aligned (@var{n})))} construct. If not defined, 1084the default value is @code{BIGGEST_ALIGNMENT}. 1085 1086@findex DATA_ALIGNMENT 1087@item DATA_ALIGNMENT (@var{type}, @var{basic-align}) 1088If defined, a C expression to compute the alignment for a variable in 1089the static store. @var{type} is the data type, and @var{basic-align} is 1090the alignment that the object would ordinarily have. The value of this 1091macro is used instead of that alignment to align the object. 1092 1093If this macro is not defined, then @var{basic-align} is used. 1094 1095@findex strcpy 1096One use of this macro is to increase alignment of medium-size data to 1097make it all fit in fewer cache lines. Another is to cause character 1098arrays to be word-aligned so that @code{strcpy} calls that copy 1099constants to character arrays can be done inline. 1100 1101@findex CONSTANT_ALIGNMENT 1102@item CONSTANT_ALIGNMENT (@var{constant}, @var{basic-align}) 1103If defined, a C expression to compute the alignment given to a constant 1104that is being placed in memory. @var{constant} is the constant and 1105@var{basic-align} is the alignment that the object would ordinarily 1106have. The value of this macro is used instead of that alignment to 1107align the object. 1108 1109If this macro is not defined, then @var{basic-align} is used. 1110 1111The typical use of this macro is to increase alignment for string 1112constants to be word aligned so that @code{strcpy} calls that copy 1113constants can be done inline. 1114 1115@findex LOCAL_ALIGNMENT 1116@item LOCAL_ALIGNMENT (@var{type}, @var{basic-align}) 1117If defined, a C expression to compute the alignment for a variable in 1118the local store. @var{type} is the data type, and @var{basic-align} is 1119the alignment that the object would ordinarily have. The value of this 1120macro is used instead of that alignment to align the object. 1121 1122If this macro is not defined, then @var{basic-align} is used. 1123 1124One use of this macro is to increase alignment of medium-size data to 1125make it all fit in fewer cache lines. 1126 1127@findex EMPTY_FIELD_BOUNDARY 1128@item EMPTY_FIELD_BOUNDARY 1129Alignment in bits to be given to a structure bit-field that follows an 1130empty field such as @code{int : 0;}. 1131 1132Note that @code{PCC_BITFIELD_TYPE_MATTERS} also affects the alignment 1133that results from an empty field. 1134 1135@findex STRUCTURE_SIZE_BOUNDARY 1136@item STRUCTURE_SIZE_BOUNDARY 1137Number of bits which any structure or union's size must be a multiple of. 1138Each structure or union's size is rounded up to a multiple of this. 1139 1140If you do not define this macro, the default is the same as 1141@code{BITS_PER_UNIT}. 1142 1143@findex STRICT_ALIGNMENT 1144@item STRICT_ALIGNMENT 1145Define this macro to be the value 1 if instructions will fail to work 1146if given data not on the nominal alignment. If instructions will merely 1147go slower in that case, define this macro as 0. 1148 1149@findex PCC_BITFIELD_TYPE_MATTERS 1150@item PCC_BITFIELD_TYPE_MATTERS 1151Define this if you wish to imitate the way many other C compilers handle 1152alignment of bit-fields and the structures that contain them. 1153 1154The behavior is that the type written for a bit-field (@code{int}, 1155@code{short}, or other integer type) imposes an alignment for the 1156entire structure, as if the structure really did contain an ordinary 1157field of that type. In addition, the bit-field is placed within the 1158structure so that it would fit within such a field, not crossing a 1159boundary for it. 1160 1161Thus, on most machines, a bit-field whose type is written as @code{int} 1162would not cross a four-byte boundary, and would force four-byte 1163alignment for the whole structure. (The alignment used may not be four 1164bytes; it is controlled by the other alignment parameters.) 1165 1166If the macro is defined, its definition should be a C expression; 1167a nonzero value for the expression enables this behavior. 1168 1169Note that if this macro is not defined, or its value is zero, some 1170bit-fields may cross more than one alignment boundary. The compiler can 1171support such references if there are @samp{insv}, @samp{extv}, and 1172@samp{extzv} insns that can directly reference memory. 1173 1174The other known way of making bit-fields work is to define 1175@code{STRUCTURE_SIZE_BOUNDARY} as large as @code{BIGGEST_ALIGNMENT}. 1176Then every structure can be accessed with fullwords. 1177 1178Unless the machine has bit-field instructions or you define 1179@code{STRUCTURE_SIZE_BOUNDARY} that way, you must define 1180@code{PCC_BITFIELD_TYPE_MATTERS} to have a nonzero value. 1181 1182If your aim is to make GCC use the same conventions for laying out 1183bit-fields as are used by another compiler, here is how to investigate 1184what the other compiler does. Compile and run this program: 1185 1186@example 1187struct foo1 1188@{ 1189 char x; 1190 char :0; 1191 char y; 1192@}; 1193 1194struct foo2 1195@{ 1196 char x; 1197 int :0; 1198 char y; 1199@}; 1200 1201main () 1202@{ 1203 printf ("Size of foo1 is %d\n", 1204 sizeof (struct foo1)); 1205 printf ("Size of foo2 is %d\n", 1206 sizeof (struct foo2)); 1207 exit (0); 1208@} 1209@end example 1210 1211If this prints 2 and 5, then the compiler's behavior is what you would 1212get from @code{PCC_BITFIELD_TYPE_MATTERS}. 1213 1214@findex BITFIELD_NBYTES_LIMITED 1215@item BITFIELD_NBYTES_LIMITED 1216Like @code{PCC_BITFIELD_TYPE_MATTERS} except that its effect is limited 1217to aligning a bit-field within the structure. 1218 1219@findex MEMBER_TYPE_FORCES_BLK 1220@item MEMBER_TYPE_FORCES_BLK (@var{field}) 1221Return 1 if a structure or array containing @var{field} should be accessed using 1222@code{BLKMODE}. 1223 1224Normally, this is not needed. See the file @file{c4x.h} for an example 1225of how to use this macro to prevent a structure having a floating point 1226field from being accessed in an integer mode. 1227 1228@findex ROUND_TYPE_SIZE 1229@item ROUND_TYPE_SIZE (@var{type}, @var{computed}, @var{specified}) 1230Define this macro as an expression for the overall size of a type 1231(given by @var{type} as a tree node) when the size computed in the 1232usual way is @var{computed} and the alignment is @var{specified}. 1233 1234The default is to round @var{computed} up to a multiple of @var{specified}. 1235 1236@findex ROUND_TYPE_SIZE_UNIT 1237@item ROUND_TYPE_SIZE_UNIT (@var{type}, @var{computed}, @var{specified}) 1238Similar to @code{ROUND_TYPE_SIZE}, but sizes and alignments are 1239specified in units (bytes). If you define @code{ROUND_TYPE_SIZE}, 1240you must also define this macro and they must be defined consistently 1241with each other. 1242 1243@findex ROUND_TYPE_ALIGN 1244@item ROUND_TYPE_ALIGN (@var{type}, @var{computed}, @var{specified}) 1245Define this macro as an expression for the alignment of a type (given 1246by @var{type} as a tree node) if the alignment computed in the usual 1247way is @var{computed} and the alignment explicitly specified was 1248@var{specified}. 1249 1250The default is to use @var{specified} if it is larger; otherwise, use 1251the smaller of @var{computed} and @code{BIGGEST_ALIGNMENT} 1252 1253@findex MAX_FIXED_MODE_SIZE 1254@item MAX_FIXED_MODE_SIZE 1255An integer expression for the size in bits of the largest integer 1256machine mode that should actually be used. All integer machine modes of 1257this size or smaller can be used for structures and unions with the 1258appropriate sizes. If this macro is undefined, @code{GET_MODE_BITSIZE 1259(DImode)} is assumed. 1260 1261@findex VECTOR_MODE_SUPPORTED_P 1262@item VECTOR_MODE_SUPPORTED_P(@var{mode}) 1263Define this macro to be nonzero if the port is prepared to handle insns 1264involving vector mode @var{mode}. At the very least, it must have move 1265patterns for this mode. 1266 1267@findex STACK_SAVEAREA_MODE 1268@item STACK_SAVEAREA_MODE (@var{save_level}) 1269If defined, an expression of type @code{enum machine_mode} that 1270specifies the mode of the save area operand of a 1271@code{save_stack_@var{level}} named pattern (@pxref{Standard Names}). 1272@var{save_level} is one of @code{SAVE_BLOCK}, @code{SAVE_FUNCTION}, or 1273@code{SAVE_NONLOCAL} and selects which of the three named patterns is 1274having its mode specified. 1275 1276You need not define this macro if it always returns @code{Pmode}. You 1277would most commonly define this macro if the 1278@code{save_stack_@var{level}} patterns need to support both a 32- and a 127964-bit mode. 1280 1281@findex STACK_SIZE_MODE 1282@item STACK_SIZE_MODE 1283If defined, an expression of type @code{enum machine_mode} that 1284specifies the mode of the size increment operand of an 1285@code{allocate_stack} named pattern (@pxref{Standard Names}). 1286 1287You need not define this macro if it always returns @code{word_mode}. 1288You would most commonly define this macro if the @code{allocate_stack} 1289pattern needs to support both a 32- and a 64-bit mode. 1290 1291@findex CHECK_FLOAT_VALUE 1292@item CHECK_FLOAT_VALUE (@var{mode}, @var{value}, @var{overflow}) 1293A C statement to validate the value @var{value} (of type 1294@code{double}) for mode @var{mode}. This means that you check whether 1295@var{value} fits within the possible range of values for mode 1296@var{mode} on this target machine. The mode @var{mode} is always 1297a mode of class @code{MODE_FLOAT}. @var{overflow} is nonzero if 1298the value is already known to be out of range. 1299 1300If @var{value} is not valid or if @var{overflow} is nonzero, you should 1301set @var{overflow} to 1 and then assign some valid value to @var{value}. 1302Allowing an invalid value to go through the compiler can produce 1303incorrect assembler code which may even cause Unix assemblers to crash. 1304 1305This macro need not be defined if there is no work for it to do. 1306 1307@findex TARGET_FLOAT_FORMAT 1308@item TARGET_FLOAT_FORMAT 1309A code distinguishing the floating point format of the target machine. 1310There are five defined values: 1311 1312@table @code 1313@findex IEEE_FLOAT_FORMAT 1314@item IEEE_FLOAT_FORMAT 1315This code indicates IEEE floating point. It is the default; there is no 1316need to define this macro when the format is IEEE@. 1317 1318@findex VAX_FLOAT_FORMAT 1319@item VAX_FLOAT_FORMAT 1320This code indicates the ``D float'' format used on the VAX@. 1321 1322@findex IBM_FLOAT_FORMAT 1323@item IBM_FLOAT_FORMAT 1324This code indicates the format used on the IBM System/370. 1325 1326@findex C4X_FLOAT_FORMAT 1327@item C4X_FLOAT_FORMAT 1328This code indicates the format used on the TMS320C3x/C4x. 1329 1330@findex UNKNOWN_FLOAT_FORMAT 1331@item UNKNOWN_FLOAT_FORMAT 1332This code indicates any other format. 1333@end table 1334 1335The value of this macro is compared with @code{HOST_FLOAT_FORMAT}, which 1336is defined by the @command{configure} script, to determine whether the 1337target machine has the same format as the host machine. If any other 1338formats are actually in use on supported machines, new codes should be 1339defined for them. 1340 1341The ordering of the component words of floating point values stored in 1342memory is controlled by @code{FLOAT_WORDS_BIG_ENDIAN}. 1343 1344@end table 1345 1346@deftypefn {Target Hook} bool TARGET_MS_BITFIELD_LAYOUT_P (tree @var{record_type}) 1347This target hook returns @code{true} if bit-fields in the given 1348@var{record_type} are to be laid out following the rules of Microsoft 1349Visual C/C++, namely: (i) a bit-field won't share the same storage 1350unit with the previous bit-field if their underlying types have 1351different sizes, and the bit-field will be aligned to the highest 1352alignment of the underlying types of itself and of the previous 1353bit-field; (ii) a zero-sized bit-field will affect the alignment of 1354the whole enclosing structure, even if it is unnamed; except that 1355(iii) a zero-sized bit-field will be disregarded unless it follows 1356another bit-field of non-zero size. If this hook returns @code{true}, 1357other macros that control bit-field layout are ignored. 1358@end deftypefn 1359 1360@node Type Layout 1361@section Layout of Source Language Data Types 1362 1363These macros define the sizes and other characteristics of the standard 1364basic data types used in programs being compiled. Unlike the macros in 1365the previous section, these apply to specific features of C and related 1366languages, rather than to fundamental aspects of storage layout. 1367 1368@table @code 1369@findex INT_TYPE_SIZE 1370@item INT_TYPE_SIZE 1371A C expression for the size in bits of the type @code{int} on the 1372target machine. If you don't define this, the default is one word. 1373 1374@findex SHORT_TYPE_SIZE 1375@item SHORT_TYPE_SIZE 1376A C expression for the size in bits of the type @code{short} on the 1377target machine. If you don't define this, the default is half a word. 1378(If this would be less than one storage unit, it is rounded up to one 1379unit.) 1380 1381@findex LONG_TYPE_SIZE 1382@item LONG_TYPE_SIZE 1383A C expression for the size in bits of the type @code{long} on the 1384target machine. If you don't define this, the default is one word. 1385 1386@findex ADA_LONG_TYPE_SIZE 1387@item ADA_LONG_TYPE_SIZE 1388On some machines, the size used for the Ada equivalent of the type 1389@code{long} by a native Ada compiler differs from that used by C. In 1390that situation, define this macro to be a C expression to be used for 1391the size of that type. If you don't define this, the default is the 1392value of @code{LONG_TYPE_SIZE}. 1393 1394@findex MAX_LONG_TYPE_SIZE 1395@item MAX_LONG_TYPE_SIZE 1396Maximum number for the size in bits of the type @code{long} on the 1397target machine. If this is undefined, the default is 1398@code{LONG_TYPE_SIZE}. Otherwise, it is the constant value that is the 1399largest value that @code{LONG_TYPE_SIZE} can have at run-time. This is 1400used in @code{cpp}. 1401 1402@findex LONG_LONG_TYPE_SIZE 1403@item LONG_LONG_TYPE_SIZE 1404A C expression for the size in bits of the type @code{long long} on the 1405target machine. If you don't define this, the default is two 1406words. If you want to support GNU Ada on your machine, the value of this 1407macro must be at least 64. 1408 1409@findex CHAR_TYPE_SIZE 1410@item CHAR_TYPE_SIZE 1411A C expression for the size in bits of the type @code{char} on the 1412target machine. If you don't define this, the default is 1413@code{BITS_PER_UNIT}. 1414 1415@findex MAX_CHAR_TYPE_SIZE 1416@item MAX_CHAR_TYPE_SIZE 1417Maximum number for the size in bits of the type @code{char} on the 1418target machine. If this is undefined, the default is 1419@code{CHAR_TYPE_SIZE}. Otherwise, it is the constant value that is the 1420largest value that @code{CHAR_TYPE_SIZE} can have at run-time. This is 1421used in @code{cpp}. 1422 1423@findex BOOL_TYPE_SIZE 1424@item BOOL_TYPE_SIZE 1425A C expression for the size in bits of the C++ type @code{bool} and 1426C99 type @code{_Bool} on the target machine. If you don't define 1427this, and you probably shouldn't, the default is @code{CHAR_TYPE_SIZE}. 1428 1429@findex FLOAT_TYPE_SIZE 1430@item FLOAT_TYPE_SIZE 1431A C expression for the size in bits of the type @code{float} on the 1432target machine. If you don't define this, the default is one word. 1433 1434@findex DOUBLE_TYPE_SIZE 1435@item DOUBLE_TYPE_SIZE 1436A C expression for the size in bits of the type @code{double} on the 1437target machine. If you don't define this, the default is two 1438words. 1439 1440@findex LONG_DOUBLE_TYPE_SIZE 1441@item LONG_DOUBLE_TYPE_SIZE 1442A C expression for the size in bits of the type @code{long double} on 1443the target machine. If you don't define this, the default is two 1444words. 1445 1446@findex MAX_LONG_DOUBLE_TYPE_SIZE 1447Maximum number for the size in bits of the type @code{long double} on the 1448target machine. If this is undefined, the default is 1449@code{LONG_DOUBLE_TYPE_SIZE}. Otherwise, it is the constant value that is 1450the largest value that @code{LONG_DOUBLE_TYPE_SIZE} can have at run-time. 1451This is used in @code{cpp}. 1452 1453@findex INTEL_EXTENDED_IEEE_FORMAT 1454Define this macro to be 1 if the target machine uses 80-bit floating-point 1455values with 128-bit size and alignment. This is used in @file{real.c}. 1456 1457@findex WIDEST_HARDWARE_FP_SIZE 1458@item WIDEST_HARDWARE_FP_SIZE 1459A C expression for the size in bits of the widest floating-point format 1460supported by the hardware. If you define this macro, you must specify a 1461value less than or equal to the value of @code{LONG_DOUBLE_TYPE_SIZE}. 1462If you do not define this macro, the value of @code{LONG_DOUBLE_TYPE_SIZE} 1463is the default. 1464 1465@findex DEFAULT_SIGNED_CHAR 1466@item DEFAULT_SIGNED_CHAR 1467An expression whose value is 1 or 0, according to whether the type 1468@code{char} should be signed or unsigned by default. The user can 1469always override this default with the options @option{-fsigned-char} 1470and @option{-funsigned-char}. 1471 1472@findex DEFAULT_SHORT_ENUMS 1473@item DEFAULT_SHORT_ENUMS 1474A C expression to determine whether to give an @code{enum} type 1475only as many bytes as it takes to represent the range of possible values 1476of that type. A nonzero value means to do that; a zero value means all 1477@code{enum} types should be allocated like @code{int}. 1478 1479If you don't define the macro, the default is 0. 1480 1481@findex SIZE_TYPE 1482@item SIZE_TYPE 1483A C expression for a string describing the name of the data type to use 1484for size values. The typedef name @code{size_t} is defined using the 1485contents of the string. 1486 1487The string can contain more than one keyword. If so, separate them with 1488spaces, and write first any length keyword, then @code{unsigned} if 1489appropriate, and finally @code{int}. The string must exactly match one 1490of the data type names defined in the function 1491@code{init_decl_processing} in the file @file{c-decl.c}. You may not 1492omit @code{int} or change the order---that would cause the compiler to 1493crash on startup. 1494 1495If you don't define this macro, the default is @code{"long unsigned 1496int"}. 1497 1498@findex PTRDIFF_TYPE 1499@item PTRDIFF_TYPE 1500A C expression for a string describing the name of the data type to use 1501for the result of subtracting two pointers. The typedef name 1502@code{ptrdiff_t} is defined using the contents of the string. See 1503@code{SIZE_TYPE} above for more information. 1504 1505If you don't define this macro, the default is @code{"long int"}. 1506 1507@findex WCHAR_TYPE 1508@item WCHAR_TYPE 1509A C expression for a string describing the name of the data type to use 1510for wide characters. The typedef name @code{wchar_t} is defined using 1511the contents of the string. See @code{SIZE_TYPE} above for more 1512information. 1513 1514If you don't define this macro, the default is @code{"int"}. 1515 1516@findex WCHAR_TYPE_SIZE 1517@item WCHAR_TYPE_SIZE 1518A C expression for the size in bits of the data type for wide 1519characters. This is used in @code{cpp}, which cannot make use of 1520@code{WCHAR_TYPE}. 1521 1522@findex MAX_WCHAR_TYPE_SIZE 1523@item MAX_WCHAR_TYPE_SIZE 1524Maximum number for the size in bits of the data type for wide 1525characters. If this is undefined, the default is 1526@code{WCHAR_TYPE_SIZE}. Otherwise, it is the constant value that is the 1527largest value that @code{WCHAR_TYPE_SIZE} can have at run-time. This is 1528used in @code{cpp}. 1529 1530@findex GCOV_TYPE_SIZE 1531@item GCOV_TYPE_SIZE 1532A C expression for the size in bits of the type used for gcov counters on the 1533target machine. If you don't define this, the default is one 1534@code{LONG_TYPE_SIZE} in case it is greater or equal to 64-bit and 1535@code{LONG_LONG_TYPE_SIZE} otherwise. You may want to re-define the type to 1536ensure atomicity for counters in multithreaded programs. 1537 1538@findex WINT_TYPE 1539@item WINT_TYPE 1540A C expression for a string describing the name of the data type to 1541use for wide characters passed to @code{printf} and returned from 1542@code{getwc}. The typedef name @code{wint_t} is defined using the 1543contents of the string. See @code{SIZE_TYPE} above for more 1544information. 1545 1546If you don't define this macro, the default is @code{"unsigned int"}. 1547 1548@findex INTMAX_TYPE 1549@item INTMAX_TYPE 1550A C expression for a string describing the name of the data type that 1551can represent any value of any standard or extended signed integer type. 1552The typedef name @code{intmax_t} is defined using the contents of the 1553string. See @code{SIZE_TYPE} above for more information. 1554 1555If you don't define this macro, the default is the first of 1556@code{"int"}, @code{"long int"}, or @code{"long long int"} that has as 1557much precision as @code{long long int}. 1558 1559@findex UINTMAX_TYPE 1560@item UINTMAX_TYPE 1561A C expression for a string describing the name of the data type that 1562can represent any value of any standard or extended unsigned integer 1563type. The typedef name @code{uintmax_t} is defined using the contents 1564of the string. See @code{SIZE_TYPE} above for more information. 1565 1566If you don't define this macro, the default is the first of 1567@code{"unsigned int"}, @code{"long unsigned int"}, or @code{"long long 1568unsigned int"} that has as much precision as @code{long long unsigned 1569int}. 1570 1571@findex TARGET_PTRMEMFUNC_VBIT_LOCATION 1572@item TARGET_PTRMEMFUNC_VBIT_LOCATION 1573The C++ compiler represents a pointer-to-member-function with a struct 1574that looks like: 1575 1576@example 1577 struct @{ 1578 union @{ 1579 void (*fn)(); 1580 ptrdiff_t vtable_index; 1581 @}; 1582 ptrdiff_t delta; 1583 @}; 1584@end example 1585 1586@noindent 1587The C++ compiler must use one bit to indicate whether the function that 1588will be called through a pointer-to-member-function is virtual. 1589Normally, we assume that the low-order bit of a function pointer must 1590always be zero. Then, by ensuring that the vtable_index is odd, we can 1591distinguish which variant of the union is in use. But, on some 1592platforms function pointers can be odd, and so this doesn't work. In 1593that case, we use the low-order bit of the @code{delta} field, and shift 1594the remainder of the @code{delta} field to the left. 1595 1596GCC will automatically make the right selection about where to store 1597this bit using the @code{FUNCTION_BOUNDARY} setting for your platform. 1598However, some platforms such as ARM/Thumb have @code{FUNCTION_BOUNDARY} 1599set such that functions always start at even addresses, but the lowest 1600bit of pointers to functions indicate whether the function at that 1601address is in ARM or Thumb mode. If this is the case of your 1602architecture, you should define this macro to 1603@code{ptrmemfunc_vbit_in_delta}. 1604 1605In general, you should not have to define this macro. On architectures 1606in which function addresses are always even, according to 1607@code{FUNCTION_BOUNDARY}, GCC will automatically define this macro to 1608@code{ptrmemfunc_vbit_in_pfn}. 1609 1610@findex TARGET_VTABLE_USES_DESCRIPTORS 1611@item TARGET_VTABLE_USES_DESCRIPTORS 1612Normally, the C++ compiler uses function pointers in vtables. This 1613macro allows the target to change to use ``function descriptors'' 1614instead. Function descriptors are found on targets for whom a 1615function pointer is actually a small data structure. Normally the 1616data structure consists of the actual code address plus a data 1617pointer to which the function's data is relative. 1618 1619If vtables are used, the value of this macro should be the number 1620of words that the function descriptor occupies. 1621@end table 1622 1623@node Escape Sequences 1624@section Target Character Escape Sequences 1625@cindex escape sequences 1626 1627By default, GCC assumes that the C character escape sequences take on 1628their ASCII values for the target. If this is not correct, you must 1629explicitly define all of the macros below. 1630 1631@table @code 1632@findex TARGET_BELL 1633@item TARGET_BELL 1634A C constant expression for the integer value for escape sequence 1635@samp{\a}. 1636 1637@findex TARGET_ESC 1638@item TARGET_ESC 1639A C constant expression for the integer value of the target escape 1640character. As an extension, GCC evaluates the escape sequences 1641@samp{\e} and @samp{\E} to this. 1642 1643@findex TARGET_TAB 1644@findex TARGET_BS 1645@findex TARGET_NEWLINE 1646@item TARGET_BS 1647@itemx TARGET_TAB 1648@itemx TARGET_NEWLINE 1649C constant expressions for the integer values for escape sequences 1650@samp{\b}, @samp{\t} and @samp{\n}. 1651 1652@findex TARGET_VT 1653@findex TARGET_FF 1654@findex TARGET_CR 1655@item TARGET_VT 1656@itemx TARGET_FF 1657@itemx TARGET_CR 1658C constant expressions for the integer values for escape sequences 1659@samp{\v}, @samp{\f} and @samp{\r}. 1660@end table 1661 1662@node Registers 1663@section Register Usage 1664@cindex register usage 1665 1666This section explains how to describe what registers the target machine 1667has, and how (in general) they can be used. 1668 1669The description of which registers a specific instruction can use is 1670done with register classes; see @ref{Register Classes}. For information 1671on using registers to access a stack frame, see @ref{Frame Registers}. 1672For passing values in registers, see @ref{Register Arguments}. 1673For returning values in registers, see @ref{Scalar Return}. 1674 1675@menu 1676* Register Basics:: Number and kinds of registers. 1677* Allocation Order:: Order in which registers are allocated. 1678* Values in Registers:: What kinds of values each reg can hold. 1679* Leaf Functions:: Renumbering registers for leaf functions. 1680* Stack Registers:: Handling a register stack such as 80387. 1681@end menu 1682 1683@node Register Basics 1684@subsection Basic Characteristics of Registers 1685 1686@c prevent bad page break with this line 1687Registers have various characteristics. 1688 1689@table @code 1690@findex FIRST_PSEUDO_REGISTER 1691@item FIRST_PSEUDO_REGISTER 1692Number of hardware registers known to the compiler. They receive 1693numbers 0 through @code{FIRST_PSEUDO_REGISTER-1}; thus, the first 1694pseudo register's number really is assigned the number 1695@code{FIRST_PSEUDO_REGISTER}. 1696 1697@item FIXED_REGISTERS 1698@findex FIXED_REGISTERS 1699@cindex fixed register 1700An initializer that says which registers are used for fixed purposes 1701all throughout the compiled code and are therefore not available for 1702general allocation. These would include the stack pointer, the frame 1703pointer (except on machines where that can be used as a general 1704register when no frame pointer is needed), the program counter on 1705machines where that is considered one of the addressable registers, 1706and any other numbered register with a standard use. 1707 1708This information is expressed as a sequence of numbers, separated by 1709commas and surrounded by braces. The @var{n}th number is 1 if 1710register @var{n} is fixed, 0 otherwise. 1711 1712The table initialized from this macro, and the table initialized by 1713the following one, may be overridden at run time either automatically, 1714by the actions of the macro @code{CONDITIONAL_REGISTER_USAGE}, or by 1715the user with the command options @option{-ffixed-@var{reg}}, 1716@option{-fcall-used-@var{reg}} and @option{-fcall-saved-@var{reg}}. 1717 1718@findex CALL_USED_REGISTERS 1719@item CALL_USED_REGISTERS 1720@cindex call-used register 1721@cindex call-clobbered register 1722@cindex call-saved register 1723Like @code{FIXED_REGISTERS} but has 1 for each register that is 1724clobbered (in general) by function calls as well as for fixed 1725registers. This macro therefore identifies the registers that are not 1726available for general allocation of values that must live across 1727function calls. 1728 1729If a register has 0 in @code{CALL_USED_REGISTERS}, the compiler 1730automatically saves it on function entry and restores it on function 1731exit, if the register is used within the function. 1732 1733@findex CALL_REALLY_USED_REGISTERS 1734@item CALL_REALLY_USED_REGISTERS 1735@cindex call-used register 1736@cindex call-clobbered register 1737@cindex call-saved register 1738Like @code{CALL_USED_REGISTERS} except this macro doesn't require 1739that the entire set of @code{FIXED_REGISTERS} be included. 1740(@code{CALL_USED_REGISTERS} must be a superset of @code{FIXED_REGISTERS}). 1741This macro is optional. If not specified, it defaults to the value 1742of @code{CALL_USED_REGISTERS}. 1743 1744@findex HARD_REGNO_CALL_PART_CLOBBERED 1745@item HARD_REGNO_CALL_PART_CLOBBERED (@var{regno}, @var{mode}) 1746@cindex call-used register 1747@cindex call-clobbered register 1748@cindex call-saved register 1749A C expression that is nonzero if it is not permissible to store a 1750value of mode @var{mode} in hard register number @var{regno} across a 1751call without some part of it being clobbered. For most machines this 1752macro need not be defined. It is only required for machines that do not 1753preserve the entire contents of a register across a call. 1754 1755@findex CONDITIONAL_REGISTER_USAGE 1756@findex fixed_regs 1757@findex call_used_regs 1758@item CONDITIONAL_REGISTER_USAGE 1759Zero or more C statements that may conditionally modify five variables 1760@code{fixed_regs}, @code{call_used_regs}, @code{global_regs}, 1761@code{reg_names}, and @code{reg_class_contents}, to take into account 1762any dependence of these register sets on target flags. The first three 1763of these are of type @code{char []} (interpreted as Boolean vectors). 1764@code{global_regs} is a @code{const char *[]}, and 1765@code{reg_class_contents} is a @code{HARD_REG_SET}. Before the macro is 1766called, @code{fixed_regs}, @code{call_used_regs}, 1767@code{reg_class_contents}, and @code{reg_names} have been initialized 1768from @code{FIXED_REGISTERS}, @code{CALL_USED_REGISTERS}, 1769@code{REG_CLASS_CONTENTS}, and @code{REGISTER_NAMES}, respectively. 1770@code{global_regs} has been cleared, and any @option{-ffixed-@var{reg}}, 1771@option{-fcall-used-@var{reg}} and @option{-fcall-saved-@var{reg}} 1772command options have been applied. 1773 1774You need not define this macro if it has no work to do. 1775 1776@cindex disabling certain registers 1777@cindex controlling register usage 1778If the usage of an entire class of registers depends on the target 1779flags, you may indicate this to GCC by using this macro to modify 1780@code{fixed_regs} and @code{call_used_regs} to 1 for each of the 1781registers in the classes which should not be used by GCC@. Also define 1782the macro @code{REG_CLASS_FROM_LETTER} to return @code{NO_REGS} if it 1783is called with a letter for a class that shouldn't be used. 1784 1785(However, if this class is not included in @code{GENERAL_REGS} and all 1786of the insn patterns whose constraints permit this class are 1787controlled by target switches, then GCC will automatically avoid using 1788these registers when the target switches are opposed to them.) 1789 1790@findex NON_SAVING_SETJMP 1791@item NON_SAVING_SETJMP 1792If this macro is defined and has a nonzero value, it means that 1793@code{setjmp} and related functions fail to save the registers, or that 1794@code{longjmp} fails to restore them. To compensate, the compiler 1795avoids putting variables in registers in functions that use 1796@code{setjmp}. 1797 1798@findex INCOMING_REGNO 1799@item INCOMING_REGNO (@var{out}) 1800Define this macro if the target machine has register windows. This C 1801expression returns the register number as seen by the called function 1802corresponding to the register number @var{out} as seen by the calling 1803function. Return @var{out} if register number @var{out} is not an 1804outbound register. 1805 1806@findex OUTGOING_REGNO 1807@item OUTGOING_REGNO (@var{in}) 1808Define this macro if the target machine has register windows. This C 1809expression returns the register number as seen by the calling function 1810corresponding to the register number @var{in} as seen by the called 1811function. Return @var{in} if register number @var{in} is not an inbound 1812register. 1813 1814@findex LOCAL_REGNO 1815@item LOCAL_REGNO (@var{regno}) 1816Define this macro if the target machine has register windows. This C 1817expression returns true if the register is call-saved but is in the 1818register window. Unlike most call-saved registers, such registers 1819need not be explicitly restored on function exit or during non-local 1820gotos. 1821 1822@ignore 1823@findex PC_REGNUM 1824@item PC_REGNUM 1825If the program counter has a register number, define this as that 1826register number. Otherwise, do not define it. 1827@end ignore 1828@end table 1829 1830@node Allocation Order 1831@subsection Order of Allocation of Registers 1832@cindex order of register allocation 1833@cindex register allocation order 1834 1835@c prevent bad page break with this line 1836Registers are allocated in order. 1837 1838@table @code 1839@findex REG_ALLOC_ORDER 1840@item REG_ALLOC_ORDER 1841If defined, an initializer for a vector of integers, containing the 1842numbers of hard registers in the order in which GCC should prefer 1843to use them (from most preferred to least). 1844 1845If this macro is not defined, registers are used lowest numbered first 1846(all else being equal). 1847 1848One use of this macro is on machines where the highest numbered 1849registers must always be saved and the save-multiple-registers 1850instruction supports only sequences of consecutive registers. On such 1851machines, define @code{REG_ALLOC_ORDER} to be an initializer that lists 1852the highest numbered allocable register first. 1853 1854@findex ORDER_REGS_FOR_LOCAL_ALLOC 1855@item ORDER_REGS_FOR_LOCAL_ALLOC 1856A C statement (sans semicolon) to choose the order in which to allocate 1857hard registers for pseudo-registers local to a basic block. 1858 1859Store the desired register order in the array @code{reg_alloc_order}. 1860Element 0 should be the register to allocate first; element 1, the next 1861register; and so on. 1862 1863The macro body should not assume anything about the contents of 1864@code{reg_alloc_order} before execution of the macro. 1865 1866On most machines, it is not necessary to define this macro. 1867@end table 1868 1869@node Values in Registers 1870@subsection How Values Fit in Registers 1871 1872This section discusses the macros that describe which kinds of values 1873(specifically, which machine modes) each register can hold, and how many 1874consecutive registers are needed for a given mode. 1875 1876@table @code 1877@findex HARD_REGNO_NREGS 1878@item HARD_REGNO_NREGS (@var{regno}, @var{mode}) 1879A C expression for the number of consecutive hard registers, starting 1880at register number @var{regno}, required to hold a value of mode 1881@var{mode}. 1882 1883On a machine where all registers are exactly one word, a suitable 1884definition of this macro is 1885 1886@smallexample 1887#define HARD_REGNO_NREGS(REGNO, MODE) \ 1888 ((GET_MODE_SIZE (MODE) + UNITS_PER_WORD - 1) \ 1889 / UNITS_PER_WORD) 1890@end smallexample 1891 1892@findex HARD_REGNO_MODE_OK 1893@item HARD_REGNO_MODE_OK (@var{regno}, @var{mode}) 1894A C expression that is nonzero if it is permissible to store a value 1895of mode @var{mode} in hard register number @var{regno} (or in several 1896registers starting with that one). For a machine where all registers 1897are equivalent, a suitable definition is 1898 1899@smallexample 1900#define HARD_REGNO_MODE_OK(REGNO, MODE) 1 1901@end smallexample 1902 1903You need not include code to check for the numbers of fixed registers, 1904because the allocation mechanism considers them to be always occupied. 1905 1906@cindex register pairs 1907On some machines, double-precision values must be kept in even/odd 1908register pairs. You can implement that by defining this macro to reject 1909odd register numbers for such modes. 1910 1911The minimum requirement for a mode to be OK in a register is that the 1912@samp{mov@var{mode}} instruction pattern support moves between the 1913register and other hard register in the same class and that moving a 1914value into the register and back out not alter it. 1915 1916Since the same instruction used to move @code{word_mode} will work for 1917all narrower integer modes, it is not necessary on any machine for 1918@code{HARD_REGNO_MODE_OK} to distinguish between these modes, provided 1919you define patterns @samp{movhi}, etc., to take advantage of this. This 1920is useful because of the interaction between @code{HARD_REGNO_MODE_OK} 1921and @code{MODES_TIEABLE_P}; it is very desirable for all integer modes 1922to be tieable. 1923 1924Many machines have special registers for floating point arithmetic. 1925Often people assume that floating point machine modes are allowed only 1926in floating point registers. This is not true. Any registers that 1927can hold integers can safely @emph{hold} a floating point machine 1928mode, whether or not floating arithmetic can be done on it in those 1929registers. Integer move instructions can be used to move the values. 1930 1931On some machines, though, the converse is true: fixed-point machine 1932modes may not go in floating registers. This is true if the floating 1933registers normalize any value stored in them, because storing a 1934non-floating value there would garble it. In this case, 1935@code{HARD_REGNO_MODE_OK} should reject fixed-point machine modes in 1936floating registers. But if the floating registers do not automatically 1937normalize, if you can store any bit pattern in one and retrieve it 1938unchanged without a trap, then any machine mode may go in a floating 1939register, so you can define this macro to say so. 1940 1941The primary significance of special floating registers is rather that 1942they are the registers acceptable in floating point arithmetic 1943instructions. However, this is of no concern to 1944@code{HARD_REGNO_MODE_OK}. You handle it by writing the proper 1945constraints for those instructions. 1946 1947On some machines, the floating registers are especially slow to access, 1948so that it is better to store a value in a stack frame than in such a 1949register if floating point arithmetic is not being done. As long as the 1950floating registers are not in class @code{GENERAL_REGS}, they will not 1951be used unless some pattern's constraint asks for one. 1952 1953@findex MODES_TIEABLE_P 1954@item MODES_TIEABLE_P (@var{mode1}, @var{mode2}) 1955A C expression that is nonzero if a value of mode 1956@var{mode1} is accessible in mode @var{mode2} without copying. 1957 1958If @code{HARD_REGNO_MODE_OK (@var{r}, @var{mode1})} and 1959@code{HARD_REGNO_MODE_OK (@var{r}, @var{mode2})} are always the same for 1960any @var{r}, then @code{MODES_TIEABLE_P (@var{mode1}, @var{mode2})} 1961should be nonzero. If they differ for any @var{r}, you should define 1962this macro to return zero unless some other mechanism ensures the 1963accessibility of the value in a narrower mode. 1964 1965You should define this macro to return nonzero in as many cases as 1966possible since doing so will allow GCC to perform better register 1967allocation. 1968 1969@findex AVOID_CCMODE_COPIES 1970@item AVOID_CCMODE_COPIES 1971Define this macro if the compiler should avoid copies to/from @code{CCmode} 1972registers. You should only define this macro if support for copying to/from 1973@code{CCmode} is incomplete. 1974@end table 1975 1976@node Leaf Functions 1977@subsection Handling Leaf Functions 1978 1979@cindex leaf functions 1980@cindex functions, leaf 1981On some machines, a leaf function (i.e., one which makes no calls) can run 1982more efficiently if it does not make its own register window. Often this 1983means it is required to receive its arguments in the registers where they 1984are passed by the caller, instead of the registers where they would 1985normally arrive. 1986 1987The special treatment for leaf functions generally applies only when 1988other conditions are met; for example, often they may use only those 1989registers for its own variables and temporaries. We use the term ``leaf 1990function'' to mean a function that is suitable for this special 1991handling, so that functions with no calls are not necessarily ``leaf 1992functions''. 1993 1994GCC assigns register numbers before it knows whether the function is 1995suitable for leaf function treatment. So it needs to renumber the 1996registers in order to output a leaf function. The following macros 1997accomplish this. 1998 1999@table @code 2000@findex LEAF_REGISTERS 2001@item LEAF_REGISTERS 2002Name of a char vector, indexed by hard register number, which 2003contains 1 for a register that is allowable in a candidate for leaf 2004function treatment. 2005 2006If leaf function treatment involves renumbering the registers, then the 2007registers marked here should be the ones before renumbering---those that 2008GCC would ordinarily allocate. The registers which will actually be 2009used in the assembler code, after renumbering, should not be marked with 1 2010in this vector. 2011 2012Define this macro only if the target machine offers a way to optimize 2013the treatment of leaf functions. 2014 2015@findex LEAF_REG_REMAP 2016@item LEAF_REG_REMAP (@var{regno}) 2017A C expression whose value is the register number to which @var{regno} 2018should be renumbered, when a function is treated as a leaf function. 2019 2020If @var{regno} is a register number which should not appear in a leaf 2021function before renumbering, then the expression should yield @minus{}1, which 2022will cause the compiler to abort. 2023 2024Define this macro only if the target machine offers a way to optimize the 2025treatment of leaf functions, and registers need to be renumbered to do 2026this. 2027@end table 2028 2029@findex current_function_is_leaf 2030@findex current_function_uses_only_leaf_regs 2031@code{TARGET_ASM_FUNCTION_PROLOGUE} and 2032@code{TARGET_ASM_FUNCTION_EPILOGUE} must usually treat leaf functions 2033specially. They can test the C variable @code{current_function_is_leaf} 2034which is nonzero for leaf functions. @code{current_function_is_leaf} is 2035set prior to local register allocation and is valid for the remaining 2036compiler passes. They can also test the C variable 2037@code{current_function_uses_only_leaf_regs} which is nonzero for leaf 2038functions which only use leaf registers. 2039@code{current_function_uses_only_leaf_regs} is valid after reload and is 2040only useful if @code{LEAF_REGISTERS} is defined. 2041@c changed this to fix overfull. ALSO: why the "it" at the beginning 2042@c of the next paragraph?! --mew 2feb93 2043 2044@node Stack Registers 2045@subsection Registers That Form a Stack 2046 2047There are special features to handle computers where some of the 2048``registers'' form a stack, as in the 80387 coprocessor for the 80386. 2049Stack registers are normally written by pushing onto the stack, and are 2050numbered relative to the top of the stack. 2051 2052Currently, GCC can only handle one group of stack-like registers, and 2053they must be consecutively numbered. 2054 2055@table @code 2056@findex STACK_REGS 2057@item STACK_REGS 2058Define this if the machine has any stack-like registers. 2059 2060@findex FIRST_STACK_REG 2061@item FIRST_STACK_REG 2062The number of the first stack-like register. This one is the top 2063of the stack. 2064 2065@findex LAST_STACK_REG 2066@item LAST_STACK_REG 2067The number of the last stack-like register. This one is the bottom of 2068the stack. 2069@end table 2070 2071@node Register Classes 2072@section Register Classes 2073@cindex register class definitions 2074@cindex class definitions, register 2075 2076On many machines, the numbered registers are not all equivalent. 2077For example, certain registers may not be allowed for indexed addressing; 2078certain registers may not be allowed in some instructions. These machine 2079restrictions are described to the compiler using @dfn{register classes}. 2080 2081You define a number of register classes, giving each one a name and saying 2082which of the registers belong to it. Then you can specify register classes 2083that are allowed as operands to particular instruction patterns. 2084 2085@findex ALL_REGS 2086@findex NO_REGS 2087In general, each register will belong to several classes. In fact, one 2088class must be named @code{ALL_REGS} and contain all the registers. Another 2089class must be named @code{NO_REGS} and contain no registers. Often the 2090union of two classes will be another class; however, this is not required. 2091 2092@findex GENERAL_REGS 2093One of the classes must be named @code{GENERAL_REGS}. There is nothing 2094terribly special about the name, but the operand constraint letters 2095@samp{r} and @samp{g} specify this class. If @code{GENERAL_REGS} is 2096the same as @code{ALL_REGS}, just define it as a macro which expands 2097to @code{ALL_REGS}. 2098 2099Order the classes so that if class @var{x} is contained in class @var{y} 2100then @var{x} has a lower class number than @var{y}. 2101 2102The way classes other than @code{GENERAL_REGS} are specified in operand 2103constraints is through machine-dependent operand constraint letters. 2104You can define such letters to correspond to various classes, then use 2105them in operand constraints. 2106 2107You should define a class for the union of two classes whenever some 2108instruction allows both classes. For example, if an instruction allows 2109either a floating point (coprocessor) register or a general register for a 2110certain operand, you should define a class @code{FLOAT_OR_GENERAL_REGS} 2111which includes both of them. Otherwise you will get suboptimal code. 2112 2113You must also specify certain redundant information about the register 2114classes: for each class, which classes contain it and which ones are 2115contained in it; for each pair of classes, the largest class contained 2116in their union. 2117 2118When a value occupying several consecutive registers is expected in a 2119certain class, all the registers used must belong to that class. 2120Therefore, register classes cannot be used to enforce a requirement for 2121a register pair to start with an even-numbered register. The way to 2122specify this requirement is with @code{HARD_REGNO_MODE_OK}. 2123 2124Register classes used for input-operands of bitwise-and or shift 2125instructions have a special requirement: each such class must have, for 2126each fixed-point machine mode, a subclass whose registers can transfer that 2127mode to or from memory. For example, on some machines, the operations for 2128single-byte values (@code{QImode}) are limited to certain registers. When 2129this is so, each register class that is used in a bitwise-and or shift 2130instruction must have a subclass consisting of registers from which 2131single-byte values can be loaded or stored. This is so that 2132@code{PREFERRED_RELOAD_CLASS} can always have a possible value to return. 2133 2134@table @code 2135@findex enum reg_class 2136@item enum reg_class 2137An enumeral type that must be defined with all the register class names 2138as enumeral values. @code{NO_REGS} must be first. @code{ALL_REGS} 2139must be the last register class, followed by one more enumeral value, 2140@code{LIM_REG_CLASSES}, which is not a register class but rather 2141tells how many classes there are. 2142 2143Each register class has a number, which is the value of casting 2144the class name to type @code{int}. The number serves as an index 2145in many of the tables described below. 2146 2147@findex N_REG_CLASSES 2148@item N_REG_CLASSES 2149The number of distinct register classes, defined as follows: 2150 2151@example 2152#define N_REG_CLASSES (int) LIM_REG_CLASSES 2153@end example 2154 2155@findex REG_CLASS_NAMES 2156@item REG_CLASS_NAMES 2157An initializer containing the names of the register classes as C string 2158constants. These names are used in writing some of the debugging dumps. 2159 2160@findex REG_CLASS_CONTENTS 2161@item REG_CLASS_CONTENTS 2162An initializer containing the contents of the register classes, as integers 2163which are bit masks. The @var{n}th integer specifies the contents of class 2164@var{n}. The way the integer @var{mask} is interpreted is that 2165register @var{r} is in the class if @code{@var{mask} & (1 << @var{r})} is 1. 2166 2167When the machine has more than 32 registers, an integer does not suffice. 2168Then the integers are replaced by sub-initializers, braced groupings containing 2169several integers. Each sub-initializer must be suitable as an initializer 2170for the type @code{HARD_REG_SET} which is defined in @file{hard-reg-set.h}. 2171In this situation, the first integer in each sub-initializer corresponds to 2172registers 0 through 31, the second integer to registers 32 through 63, and 2173so on. 2174 2175@findex REGNO_REG_CLASS 2176@item REGNO_REG_CLASS (@var{regno}) 2177A C expression whose value is a register class containing hard register 2178@var{regno}. In general there is more than one such class; choose a class 2179which is @dfn{minimal}, meaning that no smaller class also contains the 2180register. 2181 2182@findex BASE_REG_CLASS 2183@item BASE_REG_CLASS 2184A macro whose definition is the name of the class to which a valid 2185base register must belong. A base register is one used in an address 2186which is the register value plus a displacement. 2187 2188@findex MODE_BASE_REG_CLASS 2189@item MODE_BASE_REG_CLASS (@var{mode}) 2190This is a variation of the @code{BASE_REG_CLASS} macro which allows 2191the selection of a base register in a mode depenedent manner. If 2192@var{mode} is VOIDmode then it should return the same value as 2193@code{BASE_REG_CLASS}. 2194 2195@findex INDEX_REG_CLASS 2196@item INDEX_REG_CLASS 2197A macro whose definition is the name of the class to which a valid 2198index register must belong. An index register is one used in an 2199address where its value is either multiplied by a scale factor or 2200added to another register (as well as added to a displacement). 2201 2202@findex REG_CLASS_FROM_LETTER 2203@item REG_CLASS_FROM_LETTER (@var{char}) 2204A C expression which defines the machine-dependent operand constraint 2205letters for register classes. If @var{char} is such a letter, the 2206value should be the register class corresponding to it. Otherwise, 2207the value should be @code{NO_REGS}. The register letter @samp{r}, 2208corresponding to class @code{GENERAL_REGS}, will not be passed 2209to this macro; you do not need to handle it. 2210 2211@findex REGNO_OK_FOR_BASE_P 2212@item REGNO_OK_FOR_BASE_P (@var{num}) 2213A C expression which is nonzero if register number @var{num} is 2214suitable for use as a base register in operand addresses. It may be 2215either a suitable hard register or a pseudo register that has been 2216allocated such a hard register. 2217 2218@findex REGNO_MODE_OK_FOR_BASE_P 2219@item REGNO_MODE_OK_FOR_BASE_P (@var{num}, @var{mode}) 2220A C expression that is just like @code{REGNO_OK_FOR_BASE_P}, except that 2221that expression may examine the mode of the memory reference in 2222@var{mode}. You should define this macro if the mode of the memory 2223reference affects whether a register may be used as a base register. If 2224you define this macro, the compiler will use it instead of 2225@code{REGNO_OK_FOR_BASE_P}. 2226 2227@findex REGNO_OK_FOR_INDEX_P 2228@item REGNO_OK_FOR_INDEX_P (@var{num}) 2229A C expression which is nonzero if register number @var{num} is 2230suitable for use as an index register in operand addresses. It may be 2231either a suitable hard register or a pseudo register that has been 2232allocated such a hard register. 2233 2234The difference between an index register and a base register is that 2235the index register may be scaled. If an address involves the sum of 2236two registers, neither one of them scaled, then either one may be 2237labeled the ``base'' and the other the ``index''; but whichever 2238labeling is used must fit the machine's constraints of which registers 2239may serve in each capacity. The compiler will try both labelings, 2240looking for one that is valid, and will reload one or both registers 2241only if neither labeling works. 2242 2243@findex PREFERRED_RELOAD_CLASS 2244@item PREFERRED_RELOAD_CLASS (@var{x}, @var{class}) 2245A C expression that places additional restrictions on the register class 2246to use when it is necessary to copy value @var{x} into a register in class 2247@var{class}. The value is a register class; perhaps @var{class}, or perhaps 2248another, smaller class. On many machines, the following definition is 2249safe: 2250 2251@example 2252#define PREFERRED_RELOAD_CLASS(X,CLASS) CLASS 2253@end example 2254 2255Sometimes returning a more restrictive class makes better code. For 2256example, on the 68000, when @var{x} is an integer constant that is in range 2257for a @samp{moveq} instruction, the value of this macro is always 2258@code{DATA_REGS} as long as @var{class} includes the data registers. 2259Requiring a data register guarantees that a @samp{moveq} will be used. 2260 2261If @var{x} is a @code{const_double}, by returning @code{NO_REGS} 2262you can force @var{x} into a memory constant. This is useful on 2263certain machines where immediate floating values cannot be loaded into 2264certain kinds of registers. 2265 2266@findex PREFERRED_OUTPUT_RELOAD_CLASS 2267@item PREFERRED_OUTPUT_RELOAD_CLASS (@var{x}, @var{class}) 2268Like @code{PREFERRED_RELOAD_CLASS}, but for output reloads instead of 2269input reloads. If you don't define this macro, the default is to use 2270@var{class}, unchanged. 2271 2272@findex LIMIT_RELOAD_CLASS 2273@item LIMIT_RELOAD_CLASS (@var{mode}, @var{class}) 2274A C expression that places additional restrictions on the register class 2275to use when it is necessary to be able to hold a value of mode 2276@var{mode} in a reload register for which class @var{class} would 2277ordinarily be used. 2278 2279Unlike @code{PREFERRED_RELOAD_CLASS}, this macro should be used when 2280there are certain modes that simply can't go in certain reload classes. 2281 2282The value is a register class; perhaps @var{class}, or perhaps another, 2283smaller class. 2284 2285Don't define this macro unless the target machine has limitations which 2286require the macro to do something nontrivial. 2287 2288@findex SECONDARY_RELOAD_CLASS 2289@findex SECONDARY_INPUT_RELOAD_CLASS 2290@findex SECONDARY_OUTPUT_RELOAD_CLASS 2291@item SECONDARY_RELOAD_CLASS (@var{class}, @var{mode}, @var{x}) 2292@itemx SECONDARY_INPUT_RELOAD_CLASS (@var{class}, @var{mode}, @var{x}) 2293@itemx SECONDARY_OUTPUT_RELOAD_CLASS (@var{class}, @var{mode}, @var{x}) 2294Many machines have some registers that cannot be copied directly to or 2295from memory or even from other types of registers. An example is the 2296@samp{MQ} register, which on most machines, can only be copied to or 2297from general registers, but not memory. Some machines allow copying all 2298registers to and from memory, but require a scratch register for stores 2299to some memory locations (e.g., those with symbolic address on the RT, 2300and those with certain symbolic address on the Sparc when compiling 2301PIC)@. In some cases, both an intermediate and a scratch register are 2302required. 2303 2304You should define these macros to indicate to the reload phase that it may 2305need to allocate at least one register for a reload in addition to the 2306register to contain the data. Specifically, if copying @var{x} to a 2307register @var{class} in @var{mode} requires an intermediate register, 2308you should define @code{SECONDARY_INPUT_RELOAD_CLASS} to return the 2309largest register class all of whose registers can be used as 2310intermediate registers or scratch registers. 2311 2312If copying a register @var{class} in @var{mode} to @var{x} requires an 2313intermediate or scratch register, @code{SECONDARY_OUTPUT_RELOAD_CLASS} 2314should be defined to return the largest register class required. If the 2315requirements for input and output reloads are the same, the macro 2316@code{SECONDARY_RELOAD_CLASS} should be used instead of defining both 2317macros identically. 2318 2319The values returned by these macros are often @code{GENERAL_REGS}. 2320Return @code{NO_REGS} if no spare register is needed; i.e., if @var{x} 2321can be directly copied to or from a register of @var{class} in 2322@var{mode} without requiring a scratch register. Do not define this 2323macro if it would always return @code{NO_REGS}. 2324 2325If a scratch register is required (either with or without an 2326intermediate register), you should define patterns for 2327@samp{reload_in@var{m}} or @samp{reload_out@var{m}}, as required 2328(@pxref{Standard Names}. These patterns, which will normally be 2329implemented with a @code{define_expand}, should be similar to the 2330@samp{mov@var{m}} patterns, except that operand 2 is the scratch 2331register. 2332 2333Define constraints for the reload register and scratch register that 2334contain a single register class. If the original reload register (whose 2335class is @var{class}) can meet the constraint given in the pattern, the 2336value returned by these macros is used for the class of the scratch 2337register. Otherwise, two additional reload registers are required. 2338Their classes are obtained from the constraints in the insn pattern. 2339 2340@var{x} might be a pseudo-register or a @code{subreg} of a 2341pseudo-register, which could either be in a hard register or in memory. 2342Use @code{true_regnum} to find out; it will return @minus{}1 if the pseudo is 2343in memory and the hard register number if it is in a register. 2344 2345These macros should not be used in the case where a particular class of 2346registers can only be copied to memory and not to another class of 2347registers. In that case, secondary reload registers are not needed and 2348would not be helpful. Instead, a stack location must be used to perform 2349the copy and the @code{mov@var{m}} pattern should use memory as an 2350intermediate storage. This case often occurs between floating-point and 2351general registers. 2352 2353@findex SECONDARY_MEMORY_NEEDED 2354@item SECONDARY_MEMORY_NEEDED (@var{class1}, @var{class2}, @var{m}) 2355Certain machines have the property that some registers cannot be copied 2356to some other registers without using memory. Define this macro on 2357those machines to be a C expression that is nonzero if objects of mode 2358@var{m} in registers of @var{class1} can only be copied to registers of 2359class @var{class2} by storing a register of @var{class1} into memory 2360and loading that memory location into a register of @var{class2}. 2361 2362Do not define this macro if its value would always be zero. 2363 2364@findex SECONDARY_MEMORY_NEEDED_RTX 2365@item SECONDARY_MEMORY_NEEDED_RTX (@var{mode}) 2366Normally when @code{SECONDARY_MEMORY_NEEDED} is defined, the compiler 2367allocates a stack slot for a memory location needed for register copies. 2368If this macro is defined, the compiler instead uses the memory location 2369defined by this macro. 2370 2371Do not define this macro if you do not define 2372@code{SECONDARY_MEMORY_NEEDED}. 2373 2374@findex SECONDARY_MEMORY_NEEDED_MODE 2375@item SECONDARY_MEMORY_NEEDED_MODE (@var{mode}) 2376When the compiler needs a secondary memory location to copy between two 2377registers of mode @var{mode}, it normally allocates sufficient memory to 2378hold a quantity of @code{BITS_PER_WORD} bits and performs the store and 2379load operations in a mode that many bits wide and whose class is the 2380same as that of @var{mode}. 2381 2382This is right thing to do on most machines because it ensures that all 2383bits of the register are copied and prevents accesses to the registers 2384in a narrower mode, which some machines prohibit for floating-point 2385registers. 2386 2387However, this default behavior is not correct on some machines, such as 2388the DEC Alpha, that store short integers in floating-point registers 2389differently than in integer registers. On those machines, the default 2390widening will not work correctly and you must define this macro to 2391suppress that widening in some cases. See the file @file{alpha.h} for 2392details. 2393 2394Do not define this macro if you do not define 2395@code{SECONDARY_MEMORY_NEEDED} or if widening @var{mode} to a mode that 2396is @code{BITS_PER_WORD} bits wide is correct for your machine. 2397 2398@findex SMALL_REGISTER_CLASSES 2399@item SMALL_REGISTER_CLASSES 2400On some machines, it is risky to let hard registers live across arbitrary 2401insns. Typically, these machines have instructions that require values 2402to be in specific registers (like an accumulator), and reload will fail 2403if the required hard register is used for another purpose across such an 2404insn. 2405 2406Define @code{SMALL_REGISTER_CLASSES} to be an expression with a nonzero 2407value on these machines. When this macro has a nonzero value, the 2408compiler will try to minimize the lifetime of hard registers. 2409 2410It is always safe to define this macro with a nonzero value, but if you 2411unnecessarily define it, you will reduce the amount of optimizations 2412that can be performed in some cases. If you do not define this macro 2413with a nonzero value when it is required, the compiler will run out of 2414spill registers and print a fatal error message. For most machines, you 2415should not define this macro at all. 2416 2417@findex CLASS_LIKELY_SPILLED_P 2418@item CLASS_LIKELY_SPILLED_P (@var{class}) 2419A C expression whose value is nonzero if pseudos that have been assigned 2420to registers of class @var{class} would likely be spilled because 2421registers of @var{class} are needed for spill registers. 2422 2423The default value of this macro returns 1 if @var{class} has exactly one 2424register and zero otherwise. On most machines, this default should be 2425used. Only define this macro to some other expression if pseudos 2426allocated by @file{local-alloc.c} end up in memory because their hard 2427registers were needed for spill registers. If this macro returns nonzero 2428for those classes, those pseudos will only be allocated by 2429@file{global.c}, which knows how to reallocate the pseudo to another 2430register. If there would not be another register available for 2431reallocation, you should not change the definition of this macro since 2432the only effect of such a definition would be to slow down register 2433allocation. 2434 2435@findex CLASS_MAX_NREGS 2436@item CLASS_MAX_NREGS (@var{class}, @var{mode}) 2437A C expression for the maximum number of consecutive registers 2438of class @var{class} needed to hold a value of mode @var{mode}. 2439 2440This is closely related to the macro @code{HARD_REGNO_NREGS}. In fact, 2441the value of the macro @code{CLASS_MAX_NREGS (@var{class}, @var{mode})} 2442should be the maximum value of @code{HARD_REGNO_NREGS (@var{regno}, 2443@var{mode})} for all @var{regno} values in the class @var{class}. 2444 2445This macro helps control the handling of multiple-word values 2446in the reload pass. 2447 2448@item CLASS_CANNOT_CHANGE_MODE 2449If defined, a C expression for a class that contains registers for 2450which the compiler may not change modes arbitrarily. 2451 2452@item CLASS_CANNOT_CHANGE_MODE_P(@var{from}, @var{to}) 2453A C expression that is true if, for a register in 2454@code{CLASS_CANNOT_CHANGE_MODE}, the requested mode punning is invalid. 2455 2456For the example, loading 32-bit integer or floating-point objects into 2457floating-point registers on the Alpha extends them to 64-bits. 2458Therefore loading a 64-bit object and then storing it as a 32-bit object 2459does not store the low-order 32-bits, as would be the case for a normal 2460register. Therefore, @file{alpha.h} defines @code{CLASS_CANNOT_CHANGE_MODE} 2461as @code{FLOAT_REGS} and @code{CLASS_CANNOT_CHANGE_MODE_P} restricts 2462mode changes to same-size modes. 2463 2464Compare this to IA-64, which extends floating-point values to 82-bits, 2465and stores 64-bit integers in a different format than 64-bit doubles. 2466Therefore @code{CLASS_CANNOT_CHANGE_MODE_P} is always true. 2467@end table 2468 2469Three other special macros describe which operands fit which constraint 2470letters. 2471 2472@table @code 2473@findex CONST_OK_FOR_LETTER_P 2474@item CONST_OK_FOR_LETTER_P (@var{value}, @var{c}) 2475A C expression that defines the machine-dependent operand constraint 2476letters (@samp{I}, @samp{J}, @samp{K}, @dots{} @samp{P}) that specify 2477particular ranges of integer values. If @var{c} is one of those 2478letters, the expression should check that @var{value}, an integer, is in 2479the appropriate range and return 1 if so, 0 otherwise. If @var{c} is 2480not one of those letters, the value should be 0 regardless of 2481@var{value}. 2482 2483@findex CONST_DOUBLE_OK_FOR_LETTER_P 2484@item CONST_DOUBLE_OK_FOR_LETTER_P (@var{value}, @var{c}) 2485A C expression that defines the machine-dependent operand constraint 2486letters that specify particular ranges of @code{const_double} values 2487(@samp{G} or @samp{H}). 2488 2489If @var{c} is one of those letters, the expression should check that 2490@var{value}, an RTX of code @code{const_double}, is in the appropriate 2491range and return 1 if so, 0 otherwise. If @var{c} is not one of those 2492letters, the value should be 0 regardless of @var{value}. 2493 2494@code{const_double} is used for all floating-point constants and for 2495@code{DImode} fixed-point constants. A given letter can accept either 2496or both kinds of values. It can use @code{GET_MODE} to distinguish 2497between these kinds. 2498 2499@findex EXTRA_CONSTRAINT 2500@item EXTRA_CONSTRAINT (@var{value}, @var{c}) 2501A C expression that defines the optional machine-dependent constraint 2502letters that can be used to segregate specific types of operands, usually 2503memory references, for the target machine. Any letter that is not 2504elsewhere defined and not matched by @code{REG_CLASS_FROM_LETTER} 2505may be used. Normally this macro will not be defined. 2506 2507If it is required for a particular target machine, it should return 1 2508if @var{value} corresponds to the operand type represented by the 2509constraint letter @var{c}. If @var{c} is not defined as an extra 2510constraint, the value returned should be 0 regardless of @var{value}. 2511 2512For example, on the ROMP, load instructions cannot have their output 2513in r0 if the memory reference contains a symbolic address. Constraint 2514letter @samp{Q} is defined as representing a memory address that does 2515@emph{not} contain a symbolic address. An alternative is specified with 2516a @samp{Q} constraint on the input and @samp{r} on the output. The next 2517alternative specifies @samp{m} on the input and a register class that 2518does not include r0 on the output. 2519@end table 2520 2521@node Stack and Calling 2522@section Stack Layout and Calling Conventions 2523@cindex calling conventions 2524 2525@c prevent bad page break with this line 2526This describes the stack layout and calling conventions. 2527 2528@menu 2529* Frame Layout:: 2530* Exception Handling:: 2531* Stack Checking:: 2532* Frame Registers:: 2533* Elimination:: 2534* Stack Arguments:: 2535* Register Arguments:: 2536* Scalar Return:: 2537* Aggregate Return:: 2538* Caller Saves:: 2539* Function Entry:: 2540* Profiling:: 2541* Tail Calls:: 2542@end menu 2543 2544@node Frame Layout 2545@subsection Basic Stack Layout 2546@cindex stack frame layout 2547@cindex frame layout 2548 2549@c prevent bad page break with this line 2550Here is the basic stack layout. 2551 2552@table @code 2553@findex STACK_GROWS_DOWNWARD 2554@item STACK_GROWS_DOWNWARD 2555Define this macro if pushing a word onto the stack moves the stack 2556pointer to a smaller address. 2557 2558When we say, ``define this macro if @dots{},'' it means that the 2559compiler checks this macro only with @code{#ifdef} so the precise 2560definition used does not matter. 2561 2562@findex STACK_PUSH_CODE 2563@item STACK_PUSH_CODE 2564 2565This macro defines the operation used when something is pushed 2566on the stack. In RTL, a push operation will be 2567@code{(set (mem (STACK_PUSH_CODE (reg sp))) ...)} 2568 2569The choices are @code{PRE_DEC}, @code{POST_DEC}, @code{PRE_INC}, 2570and @code{POST_INC}. Which of these is correct depends on 2571the stack direction and on whether the stack pointer points 2572to the last item on the stack or whether it points to the 2573space for the next item on the stack. 2574 2575The default is @code{PRE_DEC} when @code{STACK_GROWS_DOWNWARD} is 2576defined, which is almost always right, and @code{PRE_INC} otherwise, 2577which is often wrong. 2578 2579@findex FRAME_GROWS_DOWNWARD 2580@item FRAME_GROWS_DOWNWARD 2581Define this macro if the addresses of local variable slots are at negative 2582offsets from the frame pointer. 2583 2584@findex ARGS_GROW_DOWNWARD 2585@item ARGS_GROW_DOWNWARD 2586Define this macro if successive arguments to a function occupy decreasing 2587addresses on the stack. 2588 2589@findex STARTING_FRAME_OFFSET 2590@item STARTING_FRAME_OFFSET 2591Offset from the frame pointer to the first local variable slot to be allocated. 2592 2593If @code{FRAME_GROWS_DOWNWARD}, find the next slot's offset by 2594subtracting the first slot's length from @code{STARTING_FRAME_OFFSET}. 2595Otherwise, it is found by adding the length of the first slot to the 2596value @code{STARTING_FRAME_OFFSET}. 2597@c i'm not sure if the above is still correct.. had to change it to get 2598@c rid of an overfull. --mew 2feb93 2599 2600@findex STACK_POINTER_OFFSET 2601@item STACK_POINTER_OFFSET 2602Offset from the stack pointer register to the first location at which 2603outgoing arguments are placed. If not specified, the default value of 2604zero is used. This is the proper value for most machines. 2605 2606If @code{ARGS_GROW_DOWNWARD}, this is the offset to the location above 2607the first location at which outgoing arguments are placed. 2608 2609@findex FIRST_PARM_OFFSET 2610@item FIRST_PARM_OFFSET (@var{fundecl}) 2611Offset from the argument pointer register to the first argument's 2612address. On some machines it may depend on the data type of the 2613function. 2614 2615If @code{ARGS_GROW_DOWNWARD}, this is the offset to the location above 2616the first argument's address. 2617 2618@findex STACK_DYNAMIC_OFFSET 2619@item STACK_DYNAMIC_OFFSET (@var{fundecl}) 2620Offset from the stack pointer register to an item dynamically allocated 2621on the stack, e.g., by @code{alloca}. 2622 2623The default value for this macro is @code{STACK_POINTER_OFFSET} plus the 2624length of the outgoing arguments. The default is correct for most 2625machines. See @file{function.c} for details. 2626 2627@findex DYNAMIC_CHAIN_ADDRESS 2628@item DYNAMIC_CHAIN_ADDRESS (@var{frameaddr}) 2629A C expression whose value is RTL representing the address in a stack 2630frame where the pointer to the caller's frame is stored. Assume that 2631@var{frameaddr} is an RTL expression for the address of the stack frame 2632itself. 2633 2634If you don't define this macro, the default is to return the value 2635of @var{frameaddr}---that is, the stack frame address is also the 2636address of the stack word that points to the previous frame. 2637 2638@findex SETUP_FRAME_ADDRESSES 2639@item SETUP_FRAME_ADDRESSES 2640If defined, a C expression that produces the machine-specific code to 2641setup the stack so that arbitrary frames can be accessed. For example, 2642on the Sparc, we must flush all of the register windows to the stack 2643before we can access arbitrary stack frames. You will seldom need to 2644define this macro. 2645 2646@findex BUILTIN_SETJMP_FRAME_VALUE 2647@item BUILTIN_SETJMP_FRAME_VALUE 2648If defined, a C expression that contains an rtx that is used to store 2649the address of the current frame into the built in @code{setjmp} buffer. 2650The default value, @code{virtual_stack_vars_rtx}, is correct for most 2651machines. One reason you may need to define this macro is if 2652@code{hard_frame_pointer_rtx} is the appropriate value on your machine. 2653 2654@findex RETURN_ADDR_RTX 2655@item RETURN_ADDR_RTX (@var{count}, @var{frameaddr}) 2656A C expression whose value is RTL representing the value of the return 2657address for the frame @var{count} steps up from the current frame, after 2658the prologue. @var{frameaddr} is the frame pointer of the @var{count} 2659frame, or the frame pointer of the @var{count} @minus{} 1 frame if 2660@code{RETURN_ADDR_IN_PREVIOUS_FRAME} is defined. 2661 2662The value of the expression must always be the correct address when 2663@var{count} is zero, but may be @code{NULL_RTX} if there is not way to 2664determine the return address of other frames. 2665 2666@findex RETURN_ADDR_IN_PREVIOUS_FRAME 2667@item RETURN_ADDR_IN_PREVIOUS_FRAME 2668Define this if the return address of a particular stack frame is accessed 2669from the frame pointer of the previous stack frame. 2670 2671@findex INCOMING_RETURN_ADDR_RTX 2672@item INCOMING_RETURN_ADDR_RTX 2673A C expression whose value is RTL representing the location of the 2674incoming return address at the beginning of any function, before the 2675prologue. This RTL is either a @code{REG}, indicating that the return 2676value is saved in @samp{REG}, or a @code{MEM} representing a location in 2677the stack. 2678 2679You only need to define this macro if you want to support call frame 2680debugging information like that provided by DWARF 2. 2681 2682If this RTL is a @code{REG}, you should also define 2683@code{DWARF_FRAME_RETURN_COLUMN} to @code{DWARF_FRAME_REGNUM (REGNO)}. 2684 2685@findex INCOMING_FRAME_SP_OFFSET 2686@item INCOMING_FRAME_SP_OFFSET 2687A C expression whose value is an integer giving the offset, in bytes, 2688from the value of the stack pointer register to the top of the stack 2689frame at the beginning of any function, before the prologue. The top of 2690the frame is defined to be the value of the stack pointer in the 2691previous frame, just before the call instruction. 2692 2693You only need to define this macro if you want to support call frame 2694debugging information like that provided by DWARF 2. 2695 2696@findex ARG_POINTER_CFA_OFFSET 2697@item ARG_POINTER_CFA_OFFSET (@var{fundecl}) 2698A C expression whose value is an integer giving the offset, in bytes, 2699from the argument pointer to the canonical frame address (cfa). The 2700final value should coincide with that calculated by 2701@code{INCOMING_FRAME_SP_OFFSET}. Which is unfortunately not usable 2702during virtual register instantiation. 2703 2704The default value for this macro is @code{FIRST_PARM_OFFSET (fundecl)}, 2705which is correct for most machines; in general, the arguments are found 2706immediately before the stack frame. Note that this is not the case on 2707some targets that save registers into the caller's frame, such as SPARC 2708and rs6000, and so such targets need to define this macro. 2709 2710You only need to define this macro if the default is incorrect, and you 2711want to support call frame debugging information like that provided by 2712DWARF 2. 2713 2714@findex SMALL_STACK 2715@item SMALL_STACK 2716Define this macro if the stack size for the target is very small. This 2717has the effect of disabling gcc's built-in @samp{alloca}, though 2718@samp{__builtin_alloca} is not affected. 2719@end table 2720 2721@node Exception Handling 2722@subsection Exception Handling Support 2723@cindex exception handling 2724 2725@table @code 2726@findex EH_RETURN_DATA_REGNO 2727@item EH_RETURN_DATA_REGNO (@var{N}) 2728A C expression whose value is the @var{N}th register number used for 2729data by exception handlers, or @code{INVALID_REGNUM} if fewer than 2730@var{N} registers are usable. 2731 2732The exception handling library routines communicate with the exception 2733handlers via a set of agreed upon registers. Ideally these registers 2734should be call-clobbered; it is possible to use call-saved registers, 2735but may negatively impact code size. The target must support at least 27362 data registers, but should define 4 if there are enough free registers. 2737 2738You must define this macro if you want to support call frame exception 2739handling like that provided by DWARF 2. 2740 2741@findex EH_RETURN_STACKADJ_RTX 2742@item EH_RETURN_STACKADJ_RTX 2743A C expression whose value is RTL representing a location in which 2744to store a stack adjustment to be applied before function return. 2745This is used to unwind the stack to an exception handler's call frame. 2746It will be assigned zero on code paths that return normally. 2747 2748Typically this is a call-clobbered hard register that is otherwise 2749untouched by the epilogue, but could also be a stack slot. 2750 2751You must define this macro if you want to support call frame exception 2752handling like that provided by DWARF 2. 2753 2754@findex EH_RETURN_HANDLER_RTX 2755@item EH_RETURN_HANDLER_RTX 2756A C expression whose value is RTL representing a location in which 2757to store the address of an exception handler to which we should 2758return. It will not be assigned on code paths that return normally. 2759 2760Typically this is the location in the call frame at which the normal 2761return address is stored. For targets that return by popping an 2762address off the stack, this might be a memory address just below 2763the @emph{target} call frame rather than inside the current call 2764frame. @code{EH_RETURN_STACKADJ_RTX} will have already been assigned, 2765so it may be used to calculate the location of the target call frame. 2766 2767Some targets have more complex requirements than storing to an 2768address calculable during initial code generation. In that case 2769the @code{eh_return} instruction pattern should be used instead. 2770 2771If you want to support call frame exception handling, you must 2772define either this macro or the @code{eh_return} instruction pattern. 2773 2774@findex ASM_PREFERRED_EH_DATA_FORMAT 2775@item ASM_PREFERRED_EH_DATA_FORMAT(@var{code}, @var{global}) 2776This macro chooses the encoding of pointers embedded in the exception 2777handling sections. If at all possible, this should be defined such 2778that the exception handling section will not require dynamic relocations, 2779and so may be read-only. 2780 2781@var{code} is 0 for data, 1 for code labels, 2 for function pointers. 2782@var{global} is true if the symbol may be affected by dynamic relocations. 2783The macro should return a combination of the @code{DW_EH_PE_*} defines 2784as found in @file{dwarf2.h}. 2785 2786If this macro is not defined, pointers will not be encoded but 2787represented directly. 2788 2789@findex ASM_MAYBE_OUTPUT_ENCODED_ADDR_RTX 2790@item ASM_MAYBE_OUTPUT_ENCODED_ADDR_RTX(@var{file}, @var{encoding}, @var{size}, @var{addr}, @var{done}) 2791This macro allows the target to emit whatever special magic is required 2792to represent the encoding chosen by @code{ASM_PREFERRED_EH_DATA_FORMAT}. 2793Generic code takes care of pc-relative and indirect encodings; this must 2794be defined if the target uses text-relative or data-relative encodings. 2795 2796This is a C statement that branches to @var{done} if the format was 2797handled. @var{encoding} is the format chosen, @var{size} is the number 2798of bytes that the format occupies, @var{addr} is the @code{SYMBOL_REF} 2799to be emitted. 2800 2801@findex MD_FALLBACK_FRAME_STATE_FOR 2802@item MD_FALLBACK_FRAME_STATE_FOR(@var{context}, @var{fs}, @var{success}) 2803This macro allows the target to add cpu and operating system specific 2804code to the call-frame unwinder for use when there is no unwind data 2805available. The most common reason to implement this macro is to unwind 2806through signal frames. 2807 2808This macro is called from @code{uw_frame_state_for} in @file{unwind-dw2.c} 2809and @file{unwind-ia64.c}. @var{context} is an @code{_Unwind_Context}; 2810@var{fs} is an @code{_Unwind_FrameState}. Examine @code{context->ra} 2811for the address of the code being executed and @code{context->cfa} for 2812the stack pointer value. If the frame can be decoded, the register save 2813addresses should be updated in @var{fs} and the macro should branch to 2814@var{success}. If the frame cannot be decoded, the macro should do 2815nothing. 2816@end table 2817 2818@node Stack Checking 2819@subsection Specifying How Stack Checking is Done 2820 2821GCC will check that stack references are within the boundaries of 2822the stack, if the @option{-fstack-check} is specified, in one of three ways: 2823 2824@enumerate 2825@item 2826If the value of the @code{STACK_CHECK_BUILTIN} macro is nonzero, GCC 2827will assume that you have arranged for stack checking to be done at 2828appropriate places in the configuration files, e.g., in 2829@code{TARGET_ASM_FUNCTION_PROLOGUE}. GCC will do not other special 2830processing. 2831 2832@item 2833If @code{STACK_CHECK_BUILTIN} is zero and you defined a named pattern 2834called @code{check_stack} in your @file{md} file, GCC will call that 2835pattern with one argument which is the address to compare the stack 2836value against. You must arrange for this pattern to report an error if 2837the stack pointer is out of range. 2838 2839@item 2840If neither of the above are true, GCC will generate code to periodically 2841``probe'' the stack pointer using the values of the macros defined below. 2842@end enumerate 2843 2844Normally, you will use the default values of these macros, so GCC 2845will use the third approach. 2846 2847@table @code 2848@findex STACK_CHECK_BUILTIN 2849@item STACK_CHECK_BUILTIN 2850A nonzero value if stack checking is done by the configuration files in a 2851machine-dependent manner. You should define this macro if stack checking 2852is require by the ABI of your machine or if you would like to have to stack 2853checking in some more efficient way than GCC's portable approach. 2854The default value of this macro is zero. 2855 2856@findex STACK_CHECK_PROBE_INTERVAL 2857@item STACK_CHECK_PROBE_INTERVAL 2858An integer representing the interval at which GCC must generate stack 2859probe instructions. You will normally define this macro to be no larger 2860than the size of the ``guard pages'' at the end of a stack area. The 2861default value of 4096 is suitable for most systems. 2862 2863@findex STACK_CHECK_PROBE_LOAD 2864@item STACK_CHECK_PROBE_LOAD 2865A integer which is nonzero if GCC should perform the stack probe 2866as a load instruction and zero if GCC should use a store instruction. 2867The default is zero, which is the most efficient choice on most systems. 2868 2869@findex STACK_CHECK_PROTECT 2870@item STACK_CHECK_PROTECT 2871The number of bytes of stack needed to recover from a stack overflow, 2872for languages where such a recovery is supported. The default value of 287375 words should be adequate for most machines. 2874 2875@findex STACK_CHECK_MAX_FRAME_SIZE 2876@item STACK_CHECK_MAX_FRAME_SIZE 2877The maximum size of a stack frame, in bytes. GCC will generate probe 2878instructions in non-leaf functions to ensure at least this many bytes of 2879stack are available. If a stack frame is larger than this size, stack 2880checking will not be reliable and GCC will issue a warning. The 2881default is chosen so that GCC only generates one instruction on most 2882systems. You should normally not change the default value of this macro. 2883 2884@findex STACK_CHECK_FIXED_FRAME_SIZE 2885@item STACK_CHECK_FIXED_FRAME_SIZE 2886GCC uses this value to generate the above warning message. It 2887represents the amount of fixed frame used by a function, not including 2888space for any callee-saved registers, temporaries and user variables. 2889You need only specify an upper bound for this amount and will normally 2890use the default of four words. 2891 2892@findex STACK_CHECK_MAX_VAR_SIZE 2893@item STACK_CHECK_MAX_VAR_SIZE 2894The maximum size, in bytes, of an object that GCC will place in the 2895fixed area of the stack frame when the user specifies 2896@option{-fstack-check}. 2897GCC computed the default from the values of the above macros and you will 2898normally not need to override that default. 2899@end table 2900 2901@need 2000 2902@node Frame Registers 2903@subsection Registers That Address the Stack Frame 2904 2905@c prevent bad page break with this line 2906This discusses registers that address the stack frame. 2907 2908@table @code 2909@findex STACK_POINTER_REGNUM 2910@item STACK_POINTER_REGNUM 2911The register number of the stack pointer register, which must also be a 2912fixed register according to @code{FIXED_REGISTERS}. On most machines, 2913the hardware determines which register this is. 2914 2915@findex FRAME_POINTER_REGNUM 2916@item FRAME_POINTER_REGNUM 2917The register number of the frame pointer register, which is used to 2918access automatic variables in the stack frame. On some machines, the 2919hardware determines which register this is. On other machines, you can 2920choose any register you wish for this purpose. 2921 2922@findex HARD_FRAME_POINTER_REGNUM 2923@item HARD_FRAME_POINTER_REGNUM 2924On some machines the offset between the frame pointer and starting 2925offset of the automatic variables is not known until after register 2926allocation has been done (for example, because the saved registers are 2927between these two locations). On those machines, define 2928@code{FRAME_POINTER_REGNUM} the number of a special, fixed register to 2929be used internally until the offset is known, and define 2930@code{HARD_FRAME_POINTER_REGNUM} to be the actual hard register number 2931used for the frame pointer. 2932 2933You should define this macro only in the very rare circumstances when it 2934is not possible to calculate the offset between the frame pointer and 2935the automatic variables until after register allocation has been 2936completed. When this macro is defined, you must also indicate in your 2937definition of @code{ELIMINABLE_REGS} how to eliminate 2938@code{FRAME_POINTER_REGNUM} into either @code{HARD_FRAME_POINTER_REGNUM} 2939or @code{STACK_POINTER_REGNUM}. 2940 2941Do not define this macro if it would be the same as 2942@code{FRAME_POINTER_REGNUM}. 2943 2944@findex ARG_POINTER_REGNUM 2945@item ARG_POINTER_REGNUM 2946The register number of the arg pointer register, which is used to access 2947the function's argument list. On some machines, this is the same as the 2948frame pointer register. On some machines, the hardware determines which 2949register this is. On other machines, you can choose any register you 2950wish for this purpose. If this is not the same register as the frame 2951pointer register, then you must mark it as a fixed register according to 2952@code{FIXED_REGISTERS}, or arrange to be able to eliminate it 2953(@pxref{Elimination}). 2954 2955@findex RETURN_ADDRESS_POINTER_REGNUM 2956@item RETURN_ADDRESS_POINTER_REGNUM 2957The register number of the return address pointer register, which is used to 2958access the current function's return address from the stack. On some 2959machines, the return address is not at a fixed offset from the frame 2960pointer or stack pointer or argument pointer. This register can be defined 2961to point to the return address on the stack, and then be converted by 2962@code{ELIMINABLE_REGS} into either the frame pointer or stack pointer. 2963 2964Do not define this macro unless there is no other way to get the return 2965address from the stack. 2966 2967@findex STATIC_CHAIN_REGNUM 2968@findex STATIC_CHAIN_INCOMING_REGNUM 2969@item STATIC_CHAIN_REGNUM 2970@itemx STATIC_CHAIN_INCOMING_REGNUM 2971Register numbers used for passing a function's static chain pointer. If 2972register windows are used, the register number as seen by the called 2973function is @code{STATIC_CHAIN_INCOMING_REGNUM}, while the register 2974number as seen by the calling function is @code{STATIC_CHAIN_REGNUM}. If 2975these registers are the same, @code{STATIC_CHAIN_INCOMING_REGNUM} need 2976not be defined. 2977 2978The static chain register need not be a fixed register. 2979 2980If the static chain is passed in memory, these macros should not be 2981defined; instead, the next two macros should be defined. 2982 2983@findex STATIC_CHAIN 2984@findex STATIC_CHAIN_INCOMING 2985@item STATIC_CHAIN 2986@itemx STATIC_CHAIN_INCOMING 2987If the static chain is passed in memory, these macros provide rtx giving 2988@code{mem} expressions that denote where they are stored. 2989@code{STATIC_CHAIN} and @code{STATIC_CHAIN_INCOMING} give the locations 2990as seen by the calling and called functions, respectively. Often the former 2991will be at an offset from the stack pointer and the latter at an offset from 2992the frame pointer. 2993 2994@findex stack_pointer_rtx 2995@findex frame_pointer_rtx 2996@findex arg_pointer_rtx 2997The variables @code{stack_pointer_rtx}, @code{frame_pointer_rtx}, and 2998@code{arg_pointer_rtx} will have been initialized prior to the use of these 2999macros and should be used to refer to those items. 3000 3001If the static chain is passed in a register, the two previous macros should 3002be defined instead. 3003 3004@findex DWARF_FRAME_REGISTERS 3005@item DWARF_FRAME_REGISTERS 3006This macro specifies the maximum number of hard registers that can be 3007saved in a call frame. This is used to size data structures used in 3008DWARF2 exception handling. 3009 3010Prior to GCC 3.0, this macro was needed in order to establish a stable 3011exception handling ABI in the face of adding new hard registers for ISA 3012extensions. In GCC 3.0 and later, the EH ABI is insulated from changes 3013in the number of hard registers. Nevertheless, this macro can still be 3014used to reduce the runtime memory requirements of the exception handling 3015routines, which can be substantial if the ISA contains a lot of 3016registers that are not call-saved. 3017 3018If this macro is not defined, it defaults to 3019@code{FIRST_PSEUDO_REGISTER}. 3020 3021@findex PRE_GCC3_DWARF_FRAME_REGISTERS 3022@item PRE_GCC3_DWARF_FRAME_REGISTERS 3023 3024This macro is similar to @code{DWARF_FRAME_REGISTERS}, but is provided 3025for backward compatibility in pre GCC 3.0 compiled code. 3026 3027If this macro is not defined, it defaults to 3028@code{DWARF_FRAME_REGISTERS}. 3029 3030@end table 3031 3032@node Elimination 3033@subsection Eliminating Frame Pointer and Arg Pointer 3034 3035@c prevent bad page break with this line 3036This is about eliminating the frame pointer and arg pointer. 3037 3038@table @code 3039@findex FRAME_POINTER_REQUIRED 3040@item FRAME_POINTER_REQUIRED 3041A C expression which is nonzero if a function must have and use a frame 3042pointer. This expression is evaluated in the reload pass. If its value is 3043nonzero the function will have a frame pointer. 3044 3045The expression can in principle examine the current function and decide 3046according to the facts, but on most machines the constant 0 or the 3047constant 1 suffices. Use 0 when the machine allows code to be generated 3048with no frame pointer, and doing so saves some time or space. Use 1 3049when there is no possible advantage to avoiding a frame pointer. 3050 3051In certain cases, the compiler does not know how to produce valid code 3052without a frame pointer. The compiler recognizes those cases and 3053automatically gives the function a frame pointer regardless of what 3054@code{FRAME_POINTER_REQUIRED} says. You don't need to worry about 3055them. 3056 3057In a function that does not require a frame pointer, the frame pointer 3058register can be allocated for ordinary usage, unless you mark it as a 3059fixed register. See @code{FIXED_REGISTERS} for more information. 3060 3061@findex INITIAL_FRAME_POINTER_OFFSET 3062@findex get_frame_size 3063@item INITIAL_FRAME_POINTER_OFFSET (@var{depth-var}) 3064A C statement to store in the variable @var{depth-var} the difference 3065between the frame pointer and the stack pointer values immediately after 3066the function prologue. The value would be computed from information 3067such as the result of @code{get_frame_size ()} and the tables of 3068registers @code{regs_ever_live} and @code{call_used_regs}. 3069 3070If @code{ELIMINABLE_REGS} is defined, this macro will be not be used and 3071need not be defined. Otherwise, it must be defined even if 3072@code{FRAME_POINTER_REQUIRED} is defined to always be true; in that 3073case, you may set @var{depth-var} to anything. 3074 3075@findex ELIMINABLE_REGS 3076@item ELIMINABLE_REGS 3077If defined, this macro specifies a table of register pairs used to 3078eliminate unneeded registers that point into the stack frame. If it is not 3079defined, the only elimination attempted by the compiler is to replace 3080references to the frame pointer with references to the stack pointer. 3081 3082The definition of this macro is a list of structure initializations, each 3083of which specifies an original and replacement register. 3084 3085On some machines, the position of the argument pointer is not known until 3086the compilation is completed. In such a case, a separate hard register 3087must be used for the argument pointer. This register can be eliminated by 3088replacing it with either the frame pointer or the argument pointer, 3089depending on whether or not the frame pointer has been eliminated. 3090 3091In this case, you might specify: 3092@example 3093#define ELIMINABLE_REGS \ 3094@{@{ARG_POINTER_REGNUM, STACK_POINTER_REGNUM@}, \ 3095 @{ARG_POINTER_REGNUM, FRAME_POINTER_REGNUM@}, \ 3096 @{FRAME_POINTER_REGNUM, STACK_POINTER_REGNUM@}@} 3097@end example 3098 3099Note that the elimination of the argument pointer with the stack pointer is 3100specified first since that is the preferred elimination. 3101 3102@findex CAN_ELIMINATE 3103@item CAN_ELIMINATE (@var{from-reg}, @var{to-reg}) 3104A C expression that returns nonzero if the compiler is allowed to try 3105to replace register number @var{from-reg} with register number 3106@var{to-reg}. This macro need only be defined if @code{ELIMINABLE_REGS} 3107is defined, and will usually be the constant 1, since most of the cases 3108preventing register elimination are things that the compiler already 3109knows about. 3110 3111@findex INITIAL_ELIMINATION_OFFSET 3112@item INITIAL_ELIMINATION_OFFSET (@var{from-reg}, @var{to-reg}, @var{offset-var}) 3113This macro is similar to @code{INITIAL_FRAME_POINTER_OFFSET}. It 3114specifies the initial difference between the specified pair of 3115registers. This macro must be defined if @code{ELIMINABLE_REGS} is 3116defined. 3117@end table 3118 3119@node Stack Arguments 3120@subsection Passing Function Arguments on the Stack 3121@cindex arguments on stack 3122@cindex stack arguments 3123 3124The macros in this section control how arguments are passed 3125on the stack. See the following section for other macros that 3126control passing certain arguments in registers. 3127 3128@table @code 3129@findex PROMOTE_PROTOTYPES 3130@item PROMOTE_PROTOTYPES 3131A C expression whose value is nonzero if an argument declared in 3132a prototype as an integral type smaller than @code{int} should 3133actually be passed as an @code{int}. In addition to avoiding 3134errors in certain cases of mismatch, it also makes for better 3135code on certain machines. If the macro is not defined in target 3136header files, it defaults to 0. 3137 3138@findex PUSH_ARGS 3139@item PUSH_ARGS 3140A C expression. If nonzero, push insns will be used to pass 3141outgoing arguments. 3142If the target machine does not have a push instruction, set it to zero. 3143That directs GCC to use an alternate strategy: to 3144allocate the entire argument block and then store the arguments into 3145it. When @code{PUSH_ARGS} is nonzero, @code{PUSH_ROUNDING} must be defined too. 3146On some machines, the definition 3147 3148@findex PUSH_ROUNDING 3149@item PUSH_ROUNDING (@var{npushed}) 3150A C expression that is the number of bytes actually pushed onto the 3151stack when an instruction attempts to push @var{npushed} bytes. 3152 3153On some machines, the definition 3154 3155@example 3156#define PUSH_ROUNDING(BYTES) (BYTES) 3157@end example 3158 3159@noindent 3160will suffice. But on other machines, instructions that appear 3161to push one byte actually push two bytes in an attempt to maintain 3162alignment. Then the definition should be 3163 3164@example 3165#define PUSH_ROUNDING(BYTES) (((BYTES) + 1) & ~1) 3166@end example 3167 3168@findex ACCUMULATE_OUTGOING_ARGS 3169@findex current_function_outgoing_args_size 3170@item ACCUMULATE_OUTGOING_ARGS 3171A C expression. If nonzero, the maximum amount of space required for outgoing arguments 3172will be computed and placed into the variable 3173@code{current_function_outgoing_args_size}. No space will be pushed 3174onto the stack for each call; instead, the function prologue should 3175increase the stack frame size by this amount. 3176 3177Setting both @code{PUSH_ARGS} and @code{ACCUMULATE_OUTGOING_ARGS} 3178is not proper. 3179 3180@findex REG_PARM_STACK_SPACE 3181@item REG_PARM_STACK_SPACE (@var{fndecl}) 3182Define this macro if functions should assume that stack space has been 3183allocated for arguments even when their values are passed in 3184registers. 3185 3186The value of this macro is the size, in bytes, of the area reserved for 3187arguments passed in registers for the function represented by @var{fndecl}, 3188which can be zero if GCC is calling a library function. 3189 3190This space can be allocated by the caller, or be a part of the 3191machine-dependent stack frame: @code{OUTGOING_REG_PARM_STACK_SPACE} says 3192which. 3193@c above is overfull. not sure what to do. --mew 5feb93 did 3194@c something, not sure if it looks good. --mew 10feb93 3195 3196@findex MAYBE_REG_PARM_STACK_SPACE 3197@findex FINAL_REG_PARM_STACK_SPACE 3198@item MAYBE_REG_PARM_STACK_SPACE 3199@itemx FINAL_REG_PARM_STACK_SPACE (@var{const_size}, @var{var_size}) 3200Define these macros in addition to the one above if functions might 3201allocate stack space for arguments even when their values are passed 3202in registers. These should be used when the stack space allocated 3203for arguments in registers is not a simple constant independent of the 3204function declaration. 3205 3206The value of the first macro is the size, in bytes, of the area that 3207we should initially assume would be reserved for arguments passed in registers. 3208 3209The value of the second macro is the actual size, in bytes, of the area 3210that will be reserved for arguments passed in registers. This takes two 3211arguments: an integer representing the number of bytes of fixed sized 3212arguments on the stack, and a tree representing the number of bytes of 3213variable sized arguments on the stack. 3214 3215When these macros are defined, @code{REG_PARM_STACK_SPACE} will only be 3216called for libcall functions, the current function, or for a function 3217being called when it is known that such stack space must be allocated. 3218In each case this value can be easily computed. 3219 3220When deciding whether a called function needs such stack space, and how 3221much space to reserve, GCC uses these two macros instead of 3222@code{REG_PARM_STACK_SPACE}. 3223 3224@findex OUTGOING_REG_PARM_STACK_SPACE 3225@item OUTGOING_REG_PARM_STACK_SPACE 3226Define this if it is the responsibility of the caller to allocate the area 3227reserved for arguments passed in registers. 3228 3229If @code{ACCUMULATE_OUTGOING_ARGS} is defined, this macro controls 3230whether the space for these arguments counts in the value of 3231@code{current_function_outgoing_args_size}. 3232 3233@findex STACK_PARMS_IN_REG_PARM_AREA 3234@item STACK_PARMS_IN_REG_PARM_AREA 3235Define this macro if @code{REG_PARM_STACK_SPACE} is defined, but the 3236stack parameters don't skip the area specified by it. 3237@c i changed this, makes more sens and it should have taken care of the 3238@c overfull.. not as specific, tho. --mew 5feb93 3239 3240Normally, when a parameter is not passed in registers, it is placed on the 3241stack beyond the @code{REG_PARM_STACK_SPACE} area. Defining this macro 3242suppresses this behavior and causes the parameter to be passed on the 3243stack in its natural location. 3244 3245@findex RETURN_POPS_ARGS 3246@item RETURN_POPS_ARGS (@var{fundecl}, @var{funtype}, @var{stack-size}) 3247A C expression that should indicate the number of bytes of its own 3248arguments that a function pops on returning, or 0 if the 3249function pops no arguments and the caller must therefore pop them all 3250after the function returns. 3251 3252@var{fundecl} is a C variable whose value is a tree node that describes 3253the function in question. Normally it is a node of type 3254@code{FUNCTION_DECL} that describes the declaration of the function. 3255From this you can obtain the @code{DECL_ATTRIBUTES} of the function. 3256 3257@var{funtype} is a C variable whose value is a tree node that 3258describes the function in question. Normally it is a node of type 3259@code{FUNCTION_TYPE} that describes the data type of the function. 3260From this it is possible to obtain the data types of the value and 3261arguments (if known). 3262 3263When a call to a library function is being considered, @var{fundecl} 3264will contain an identifier node for the library function. Thus, if 3265you need to distinguish among various library functions, you can do so 3266by their names. Note that ``library function'' in this context means 3267a function used to perform arithmetic, whose name is known specially 3268in the compiler and was not mentioned in the C code being compiled. 3269 3270@var{stack-size} is the number of bytes of arguments passed on the 3271stack. If a variable number of bytes is passed, it is zero, and 3272argument popping will always be the responsibility of the calling function. 3273 3274On the VAX, all functions always pop their arguments, so the definition 3275of this macro is @var{stack-size}. On the 68000, using the standard 3276calling convention, no functions pop their arguments, so the value of 3277the macro is always 0 in this case. But an alternative calling 3278convention is available in which functions that take a fixed number of 3279arguments pop them but other functions (such as @code{printf}) pop 3280nothing (the caller pops all). When this convention is in use, 3281@var{funtype} is examined to determine whether a function takes a fixed 3282number of arguments. 3283 3284@findex CALL_POPS_ARGS 3285@item CALL_POPS_ARGS (@var{cum}) 3286A C expression that should indicate the number of bytes a call sequence 3287pops off the stack. It is added to the value of @code{RETURN_POPS_ARGS} 3288when compiling a function call. 3289 3290@var{cum} is the variable in which all arguments to the called function 3291have been accumulated. 3292 3293On certain architectures, such as the SH5, a call trampoline is used 3294that pops certain registers off the stack, depending on the arguments 3295that have been passed to the function. Since this is a property of the 3296call site, not of the called function, @code{RETURN_POPS_ARGS} is not 3297appropriate. 3298 3299@end table 3300 3301@node Register Arguments 3302@subsection Passing Arguments in Registers 3303@cindex arguments in registers 3304@cindex registers arguments 3305 3306This section describes the macros which let you control how various 3307types of arguments are passed in registers or how they are arranged in 3308the stack. 3309 3310@table @code 3311@findex FUNCTION_ARG 3312@item FUNCTION_ARG (@var{cum}, @var{mode}, @var{type}, @var{named}) 3313A C expression that controls whether a function argument is passed 3314in a register, and which register. 3315 3316The arguments are @var{cum}, which summarizes all the previous 3317arguments; @var{mode}, the machine mode of the argument; @var{type}, 3318the data type of the argument as a tree node or 0 if that is not known 3319(which happens for C support library functions); and @var{named}, 3320which is 1 for an ordinary argument and 0 for nameless arguments that 3321correspond to @samp{@dots{}} in the called function's prototype. 3322@var{type} can be an incomplete type if a syntax error has previously 3323occurred. 3324 3325The value of the expression is usually either a @code{reg} RTX for the 3326hard register in which to pass the argument, or zero to pass the 3327argument on the stack. 3328 3329For machines like the VAX and 68000, where normally all arguments are 3330pushed, zero suffices as a definition. 3331 3332The value of the expression can also be a @code{parallel} RTX@. This is 3333used when an argument is passed in multiple locations. The mode of the 3334of the @code{parallel} should be the mode of the entire argument. The 3335@code{parallel} holds any number of @code{expr_list} pairs; each one 3336describes where part of the argument is passed. In each 3337@code{expr_list} the first operand must be a @code{reg} RTX for the hard 3338register in which to pass this part of the argument, and the mode of the 3339register RTX indicates how large this part of the argument is. The 3340second operand of the @code{expr_list} is a @code{const_int} which gives 3341the offset in bytes into the entire argument of where this part starts. 3342As a special exception the first @code{expr_list} in the @code{parallel} 3343RTX may have a first operand of zero. This indicates that the entire 3344argument is also stored on the stack. 3345 3346The last time this macro is called, it is called with @code{MODE == 3347VOIDmode}, and its result is passed to the @code{call} or @code{call_value} 3348pattern as operands 2 and 3 respectively. 3349 3350@cindex @file{stdarg.h} and register arguments 3351The usual way to make the ISO library @file{stdarg.h} work on a machine 3352where some arguments are usually passed in registers, is to cause 3353nameless arguments to be passed on the stack instead. This is done 3354by making @code{FUNCTION_ARG} return 0 whenever @var{named} is 0. 3355 3356@cindex @code{MUST_PASS_IN_STACK}, and @code{FUNCTION_ARG} 3357@cindex @code{REG_PARM_STACK_SPACE}, and @code{FUNCTION_ARG} 3358You may use the macro @code{MUST_PASS_IN_STACK (@var{mode}, @var{type})} 3359in the definition of this macro to determine if this argument is of a 3360type that must be passed in the stack. If @code{REG_PARM_STACK_SPACE} 3361is not defined and @code{FUNCTION_ARG} returns nonzero for such an 3362argument, the compiler will abort. If @code{REG_PARM_STACK_SPACE} is 3363defined, the argument will be computed in the stack and then loaded into 3364a register. 3365 3366@findex MUST_PASS_IN_STACK 3367@item MUST_PASS_IN_STACK (@var{mode}, @var{type}) 3368Define as a C expression that evaluates to nonzero if we do not know how 3369to pass TYPE solely in registers. The file @file{expr.h} defines a 3370definition that is usually appropriate, refer to @file{expr.h} for additional 3371documentation. 3372 3373@findex FUNCTION_INCOMING_ARG 3374@item FUNCTION_INCOMING_ARG (@var{cum}, @var{mode}, @var{type}, @var{named}) 3375Define this macro if the target machine has ``register windows'', so 3376that the register in which a function sees an arguments is not 3377necessarily the same as the one in which the caller passed the 3378argument. 3379 3380For such machines, @code{FUNCTION_ARG} computes the register in which 3381the caller passes the value, and @code{FUNCTION_INCOMING_ARG} should 3382be defined in a similar fashion to tell the function being called 3383where the arguments will arrive. 3384 3385If @code{FUNCTION_INCOMING_ARG} is not defined, @code{FUNCTION_ARG} 3386serves both purposes. 3387 3388@findex FUNCTION_ARG_PARTIAL_NREGS 3389@item FUNCTION_ARG_PARTIAL_NREGS (@var{cum}, @var{mode}, @var{type}, @var{named}) 3390A C expression for the number of words, at the beginning of an 3391argument, that must be put in registers. The value must be zero for 3392arguments that are passed entirely in registers or that are entirely 3393pushed on the stack. 3394 3395On some machines, certain arguments must be passed partially in 3396registers and partially in memory. On these machines, typically the 3397first @var{n} words of arguments are passed in registers, and the rest 3398on the stack. If a multi-word argument (a @code{double} or a 3399structure) crosses that boundary, its first few words must be passed 3400in registers and the rest must be pushed. This macro tells the 3401compiler when this occurs, and how many of the words should go in 3402registers. 3403 3404@code{FUNCTION_ARG} for these arguments should return the first 3405register to be used by the caller for this argument; likewise 3406@code{FUNCTION_INCOMING_ARG}, for the called function. 3407 3408@findex FUNCTION_ARG_PASS_BY_REFERENCE 3409@item FUNCTION_ARG_PASS_BY_REFERENCE (@var{cum}, @var{mode}, @var{type}, @var{named}) 3410A C expression that indicates when an argument must be passed by reference. 3411If nonzero for an argument, a copy of that argument is made in memory and a 3412pointer to the argument is passed instead of the argument itself. 3413The pointer is passed in whatever way is appropriate for passing a pointer 3414to that type. 3415 3416On machines where @code{REG_PARM_STACK_SPACE} is not defined, a suitable 3417definition of this macro might be 3418@smallexample 3419#define FUNCTION_ARG_PASS_BY_REFERENCE\ 3420(CUM, MODE, TYPE, NAMED) \ 3421 MUST_PASS_IN_STACK (MODE, TYPE) 3422@end smallexample 3423@c this is *still* too long. --mew 5feb93 3424 3425@findex FUNCTION_ARG_CALLEE_COPIES 3426@item FUNCTION_ARG_CALLEE_COPIES (@var{cum}, @var{mode}, @var{type}, @var{named}) 3427If defined, a C expression that indicates when it is the called function's 3428responsibility to make a copy of arguments passed by invisible reference. 3429Normally, the caller makes a copy and passes the address of the copy to the 3430routine being called. When @code{FUNCTION_ARG_CALLEE_COPIES} is defined and is 3431nonzero, the caller does not make a copy. Instead, it passes a pointer to the 3432``live'' value. The called function must not modify this value. If it can be 3433determined that the value won't be modified, it need not make a copy; 3434otherwise a copy must be made. 3435 3436@findex FUNCTION_ARG_REG_LITTLE_ENDIAN 3437@item FUNCTION_ARG_REG_LITTLE_ENDIAN 3438If defined TRUE on a big-endian system then structure arguments passed 3439(and returned) in registers are passed in a little-endian manner instead of 3440the big-endian manner. On the HP-UX IA64 and PA64 platforms structures are 3441aligned differently then integral values and setting this value to true will 3442allow for the special handling of structure arguments and return values. 3443 3444@findex CUMULATIVE_ARGS 3445@item CUMULATIVE_ARGS 3446A C type for declaring a variable that is used as the first argument of 3447@code{FUNCTION_ARG} and other related values. For some target machines, 3448the type @code{int} suffices and can hold the number of bytes of 3449argument so far. 3450 3451There is no need to record in @code{CUMULATIVE_ARGS} anything about the 3452arguments that have been passed on the stack. The compiler has other 3453variables to keep track of that. For target machines on which all 3454arguments are passed on the stack, there is no need to store anything in 3455@code{CUMULATIVE_ARGS}; however, the data structure must exist and 3456should not be empty, so use @code{int}. 3457 3458@findex INIT_CUMULATIVE_ARGS 3459@item INIT_CUMULATIVE_ARGS (@var{cum}, @var{fntype}, @var{libname}, @var{indirect}) 3460A C statement (sans semicolon) for initializing the variable @var{cum} 3461for the state at the beginning of the argument list. The variable has 3462type @code{CUMULATIVE_ARGS}. The value of @var{fntype} is the tree node 3463for the data type of the function which will receive the args, or 0 3464if the args are to a compiler support library function. The value of 3465@var{indirect} is nonzero when processing an indirect call, for example 3466a call through a function pointer. The value of @var{indirect} is zero 3467for a call to an explicitly named function, a library function call, or when 3468@code{INIT_CUMULATIVE_ARGS} is used to find arguments for the function 3469being compiled. 3470 3471When processing a call to a compiler support library function, 3472@var{libname} identifies which one. It is a @code{symbol_ref} rtx which 3473contains the name of the function, as a string. @var{libname} is 0 when 3474an ordinary C function call is being processed. Thus, each time this 3475macro is called, either @var{libname} or @var{fntype} is nonzero, but 3476never both of them at once. 3477 3478@findex INIT_CUMULATIVE_LIBCALL_ARGS 3479@item INIT_CUMULATIVE_LIBCALL_ARGS (@var{cum}, @var{mode}, @var{libname}) 3480Like @code{INIT_CUMULATIVE_ARGS} but only used for outgoing libcalls, 3481it gets a @code{MODE} argument instead of @var{fntype}, that would be 3482@code{NULL}. @var{indirect} would always be zero, too. If this macro 3483is not defined, @code{INIT_CUMULATIVE_ARGS (cum, NULL_RTX, libname, 34840)} is used instead. 3485 3486@findex INIT_CUMULATIVE_INCOMING_ARGS 3487@item INIT_CUMULATIVE_INCOMING_ARGS (@var{cum}, @var{fntype}, @var{libname}) 3488Like @code{INIT_CUMULATIVE_ARGS} but overrides it for the purposes of 3489finding the arguments for the function being compiled. If this macro is 3490undefined, @code{INIT_CUMULATIVE_ARGS} is used instead. 3491 3492The value passed for @var{libname} is always 0, since library routines 3493with special calling conventions are never compiled with GCC@. The 3494argument @var{libname} exists for symmetry with 3495@code{INIT_CUMULATIVE_ARGS}. 3496@c could use "this macro" in place of @code{INIT_CUMULATIVE_ARGS}, maybe. 3497@c --mew 5feb93 i switched the order of the sentences. --mew 10feb93 3498 3499@findex FUNCTION_ARG_ADVANCE 3500@item FUNCTION_ARG_ADVANCE (@var{cum}, @var{mode}, @var{type}, @var{named}) 3501A C statement (sans semicolon) to update the summarizer variable 3502@var{cum} to advance past an argument in the argument list. The 3503values @var{mode}, @var{type} and @var{named} describe that argument. 3504Once this is done, the variable @var{cum} is suitable for analyzing 3505the @emph{following} argument with @code{FUNCTION_ARG}, etc. 3506 3507This macro need not do anything if the argument in question was passed 3508on the stack. The compiler knows how to track the amount of stack space 3509used for arguments without any special help. 3510 3511@findex FUNCTION_ARG_PADDING 3512@item FUNCTION_ARG_PADDING (@var{mode}, @var{type}) 3513If defined, a C expression which determines whether, and in which direction, 3514to pad out an argument with extra space. The value should be of type 3515@code{enum direction}: either @code{upward} to pad above the argument, 3516@code{downward} to pad below, or @code{none} to inhibit padding. 3517 3518The @emph{amount} of padding is always just enough to reach the next 3519multiple of @code{FUNCTION_ARG_BOUNDARY}; this macro does not control 3520it. 3521 3522This macro has a default definition which is right for most systems. 3523For little-endian machines, the default is to pad upward. For 3524big-endian machines, the default is to pad downward for an argument of 3525constant size shorter than an @code{int}, and upward otherwise. 3526 3527@findex PAD_VARARGS_DOWN 3528@item PAD_VARARGS_DOWN 3529If defined, a C expression which determines whether the default 3530implementation of va_arg will attempt to pad down before reading the 3531next argument, if that argument is smaller than its aligned space as 3532controlled by @code{PARM_BOUNDARY}. If this macro is not defined, all such 3533arguments are padded down if @code{BYTES_BIG_ENDIAN} is true. 3534 3535@findex FUNCTION_ARG_BOUNDARY 3536@item FUNCTION_ARG_BOUNDARY (@var{mode}, @var{type}) 3537If defined, a C expression that gives the alignment boundary, in bits, 3538of an argument with the specified mode and type. If it is not defined, 3539@code{PARM_BOUNDARY} is used for all arguments. 3540 3541@findex FUNCTION_ARG_REGNO_P 3542@item FUNCTION_ARG_REGNO_P (@var{regno}) 3543A C expression that is nonzero if @var{regno} is the number of a hard 3544register in which function arguments are sometimes passed. This does 3545@emph{not} include implicit arguments such as the static chain and 3546the structure-value address. On many machines, no registers can be 3547used for this purpose since all function arguments are pushed on the 3548stack. 3549 3550@findex LOAD_ARGS_REVERSED 3551@item LOAD_ARGS_REVERSED 3552If defined, the order in which arguments are loaded into their 3553respective argument registers is reversed so that the last 3554argument is loaded first. This macro only affects arguments 3555passed in registers. 3556 3557@end table 3558 3559@node Scalar Return 3560@subsection How Scalar Function Values Are Returned 3561@cindex return values in registers 3562@cindex values, returned by functions 3563@cindex scalars, returned as values 3564 3565This section discusses the macros that control returning scalars as 3566values---values that can fit in registers. 3567 3568@table @code 3569@findex TRADITIONAL_RETURN_FLOAT 3570@item TRADITIONAL_RETURN_FLOAT 3571Define this macro if @option{-traditional} should not cause functions 3572declared to return @code{float} to convert the value to @code{double}. 3573 3574@findex FUNCTION_VALUE 3575@item FUNCTION_VALUE (@var{valtype}, @var{func}) 3576A C expression to create an RTX representing the place where a 3577function returns a value of data type @var{valtype}. @var{valtype} is 3578a tree node representing a data type. Write @code{TYPE_MODE 3579(@var{valtype})} to get the machine mode used to represent that type. 3580On many machines, only the mode is relevant. (Actually, on most 3581machines, scalar values are returned in the same place regardless of 3582mode). 3583 3584The value of the expression is usually a @code{reg} RTX for the hard 3585register where the return value is stored. The value can also be a 3586@code{parallel} RTX, if the return value is in multiple places. See 3587@code{FUNCTION_ARG} for an explanation of the @code{parallel} form. 3588 3589If @code{PROMOTE_FUNCTION_RETURN} is defined, you must apply the same 3590promotion rules specified in @code{PROMOTE_MODE} if @var{valtype} is a 3591scalar type. 3592 3593If the precise function being called is known, @var{func} is a tree 3594node (@code{FUNCTION_DECL}) for it; otherwise, @var{func} is a null 3595pointer. This makes it possible to use a different value-returning 3596convention for specific functions when all their calls are 3597known. 3598 3599@code{FUNCTION_VALUE} is not used for return vales with aggregate data 3600types, because these are returned in another way. See 3601@code{STRUCT_VALUE_REGNUM} and related macros, below. 3602 3603@findex FUNCTION_OUTGOING_VALUE 3604@item FUNCTION_OUTGOING_VALUE (@var{valtype}, @var{func}) 3605Define this macro if the target machine has ``register windows'' 3606so that the register in which a function returns its value is not 3607the same as the one in which the caller sees the value. 3608 3609For such machines, @code{FUNCTION_VALUE} computes the register in which 3610the caller will see the value. @code{FUNCTION_OUTGOING_VALUE} should be 3611defined in a similar fashion to tell the function where to put the 3612value. 3613 3614If @code{FUNCTION_OUTGOING_VALUE} is not defined, 3615@code{FUNCTION_VALUE} serves both purposes. 3616 3617@code{FUNCTION_OUTGOING_VALUE} is not used for return vales with 3618aggregate data types, because these are returned in another way. See 3619@code{STRUCT_VALUE_REGNUM} and related macros, below. 3620 3621@findex LIBCALL_VALUE 3622@item LIBCALL_VALUE (@var{mode}) 3623A C expression to create an RTX representing the place where a library 3624function returns a value of mode @var{mode}. If the precise function 3625being called is known, @var{func} is a tree node 3626(@code{FUNCTION_DECL}) for it; otherwise, @var{func} is a null 3627pointer. This makes it possible to use a different value-returning 3628convention for specific functions when all their calls are 3629known. 3630 3631Note that ``library function'' in this context means a compiler 3632support routine, used to perform arithmetic, whose name is known 3633specially by the compiler and was not mentioned in the C code being 3634compiled. 3635 3636The definition of @code{LIBRARY_VALUE} need not be concerned aggregate 3637data types, because none of the library functions returns such types. 3638 3639@findex FUNCTION_VALUE_REGNO_P 3640@item FUNCTION_VALUE_REGNO_P (@var{regno}) 3641A C expression that is nonzero if @var{regno} is the number of a hard 3642register in which the values of called function may come back. 3643 3644A register whose use for returning values is limited to serving as the 3645second of a pair (for a value of type @code{double}, say) need not be 3646recognized by this macro. So for most machines, this definition 3647suffices: 3648 3649@example 3650#define FUNCTION_VALUE_REGNO_P(N) ((N) == 0) 3651@end example 3652 3653If the machine has register windows, so that the caller and the called 3654function use different registers for the return value, this macro 3655should recognize only the caller's register numbers. 3656 3657@findex APPLY_RESULT_SIZE 3658@item APPLY_RESULT_SIZE 3659Define this macro if @samp{untyped_call} and @samp{untyped_return} 3660need more space than is implied by @code{FUNCTION_VALUE_REGNO_P} for 3661saving and restoring an arbitrary return value. 3662@end table 3663 3664@node Aggregate Return 3665@subsection How Large Values Are Returned 3666@cindex aggregates as return values 3667@cindex large return values 3668@cindex returning aggregate values 3669@cindex structure value address 3670 3671When a function value's mode is @code{BLKmode} (and in some other 3672cases), the value is not returned according to @code{FUNCTION_VALUE} 3673(@pxref{Scalar Return}). Instead, the caller passes the address of a 3674block of memory in which the value should be stored. This address 3675is called the @dfn{structure value address}. 3676 3677This section describes how to control returning structure values in 3678memory. 3679 3680@table @code 3681@findex RETURN_IN_MEMORY 3682@item RETURN_IN_MEMORY (@var{type}) 3683A C expression which can inhibit the returning of certain function 3684values in registers, based on the type of value. A nonzero value says 3685to return the function value in memory, just as large structures are 3686always returned. Here @var{type} will be a C expression of type 3687@code{tree}, representing the data type of the value. 3688 3689Note that values of mode @code{BLKmode} must be explicitly handled 3690by this macro. Also, the option @option{-fpcc-struct-return} 3691takes effect regardless of this macro. On most systems, it is 3692possible to leave the macro undefined; this causes a default 3693definition to be used, whose value is the constant 1 for @code{BLKmode} 3694values, and 0 otherwise. 3695 3696Do not use this macro to indicate that structures and unions should always 3697be returned in memory. You should instead use @code{DEFAULT_PCC_STRUCT_RETURN} 3698to indicate this. 3699 3700@findex DEFAULT_PCC_STRUCT_RETURN 3701@item DEFAULT_PCC_STRUCT_RETURN 3702Define this macro to be 1 if all structure and union return values must be 3703in memory. Since this results in slower code, this should be defined 3704only if needed for compatibility with other compilers or with an ABI@. 3705If you define this macro to be 0, then the conventions used for structure 3706and union return values are decided by the @code{RETURN_IN_MEMORY} macro. 3707 3708If not defined, this defaults to the value 1. 3709 3710@findex STRUCT_VALUE_REGNUM 3711@item STRUCT_VALUE_REGNUM 3712If the structure value address is passed in a register, then 3713@code{STRUCT_VALUE_REGNUM} should be the number of that register. 3714 3715@findex STRUCT_VALUE 3716@item STRUCT_VALUE 3717If the structure value address is not passed in a register, define 3718@code{STRUCT_VALUE} as an expression returning an RTX for the place 3719where the address is passed. If it returns 0, the address is passed as 3720an ``invisible'' first argument. 3721 3722@findex STRUCT_VALUE_INCOMING_REGNUM 3723@item STRUCT_VALUE_INCOMING_REGNUM 3724On some architectures the place where the structure value address 3725is found by the called function is not the same place that the 3726caller put it. This can be due to register windows, or it could 3727be because the function prologue moves it to a different place. 3728 3729If the incoming location of the structure value address is in a 3730register, define this macro as the register number. 3731 3732@findex STRUCT_VALUE_INCOMING 3733@item STRUCT_VALUE_INCOMING 3734If the incoming location is not a register, then you should define 3735@code{STRUCT_VALUE_INCOMING} as an expression for an RTX for where the 3736called function should find the value. If it should find the value on 3737the stack, define this to create a @code{mem} which refers to the frame 3738pointer. A definition of 0 means that the address is passed as an 3739``invisible'' first argument. 3740 3741@findex PCC_STATIC_STRUCT_RETURN 3742@item PCC_STATIC_STRUCT_RETURN 3743Define this macro if the usual system convention on the target machine 3744for returning structures and unions is for the called function to return 3745the address of a static variable containing the value. 3746 3747Do not define this if the usual system convention is for the caller to 3748pass an address to the subroutine. 3749 3750This macro has effect in @option{-fpcc-struct-return} mode, but it does 3751nothing when you use @option{-freg-struct-return} mode. 3752@end table 3753 3754@node Caller Saves 3755@subsection Caller-Saves Register Allocation 3756 3757If you enable it, GCC can save registers around function calls. This 3758makes it possible to use call-clobbered registers to hold variables that 3759must live across calls. 3760 3761@table @code 3762@findex DEFAULT_CALLER_SAVES 3763@item DEFAULT_CALLER_SAVES 3764Define this macro if function calls on the target machine do not preserve 3765any registers; in other words, if @code{CALL_USED_REGISTERS} has 1 3766for all registers. When defined, this macro enables @option{-fcaller-saves} 3767by default for all optimization levels. It has no effect for optimization 3768levels 2 and higher, where @option{-fcaller-saves} is the default. 3769 3770@findex CALLER_SAVE_PROFITABLE 3771@item CALLER_SAVE_PROFITABLE (@var{refs}, @var{calls}) 3772A C expression to determine whether it is worthwhile to consider placing 3773a pseudo-register in a call-clobbered hard register and saving and 3774restoring it around each function call. The expression should be 1 when 3775this is worth doing, and 0 otherwise. 3776 3777If you don't define this macro, a default is used which is good on most 3778machines: @code{4 * @var{calls} < @var{refs}}. 3779 3780@findex HARD_REGNO_CALLER_SAVE_MODE 3781@item HARD_REGNO_CALLER_SAVE_MODE (@var{regno}, @var{nregs}) 3782A C expression specifying which mode is required for saving @var{nregs} 3783of a pseudo-register in call-clobbered hard register @var{regno}. If 3784@var{regno} is unsuitable for caller save, @code{VOIDmode} should be 3785returned. For most machines this macro need not be defined since GCC 3786will select the smallest suitable mode. 3787@end table 3788 3789@node Function Entry 3790@subsection Function Entry and Exit 3791@cindex function entry and exit 3792@cindex prologue 3793@cindex epilogue 3794 3795This section describes the macros that output function entry 3796(@dfn{prologue}) and exit (@dfn{epilogue}) code. 3797 3798@deftypefn {Target Hook} void TARGET_ASM_FUNCTION_PROLOGUE (FILE *@var{file}, HOST_WIDE_INT @var{size}) 3799If defined, a function that outputs the assembler code for entry to a 3800function. The prologue is responsible for setting up the stack frame, 3801initializing the frame pointer register, saving registers that must be 3802saved, and allocating @var{size} additional bytes of storage for the 3803local variables. @var{size} is an integer. @var{file} is a stdio 3804stream to which the assembler code should be output. 3805 3806The label for the beginning of the function need not be output by this 3807macro. That has already been done when the macro is run. 3808 3809@findex regs_ever_live 3810To determine which registers to save, the macro can refer to the array 3811@code{regs_ever_live}: element @var{r} is nonzero if hard register 3812@var{r} is used anywhere within the function. This implies the function 3813prologue should save register @var{r}, provided it is not one of the 3814call-used registers. (@code{TARGET_ASM_FUNCTION_EPILOGUE} must likewise use 3815@code{regs_ever_live}.) 3816 3817On machines that have ``register windows'', the function entry code does 3818not save on the stack the registers that are in the windows, even if 3819they are supposed to be preserved by function calls; instead it takes 3820appropriate steps to ``push'' the register stack, if any non-call-used 3821registers are used in the function. 3822 3823@findex frame_pointer_needed 3824On machines where functions may or may not have frame-pointers, the 3825function entry code must vary accordingly; it must set up the frame 3826pointer if one is wanted, and not otherwise. To determine whether a 3827frame pointer is in wanted, the macro can refer to the variable 3828@code{frame_pointer_needed}. The variable's value will be 1 at run 3829time in a function that needs a frame pointer. @xref{Elimination}. 3830 3831The function entry code is responsible for allocating any stack space 3832required for the function. This stack space consists of the regions 3833listed below. In most cases, these regions are allocated in the 3834order listed, with the last listed region closest to the top of the 3835stack (the lowest address if @code{STACK_GROWS_DOWNWARD} is defined, and 3836the highest address if it is not defined). You can use a different order 3837for a machine if doing so is more convenient or required for 3838compatibility reasons. Except in cases where required by standard 3839or by a debugger, there is no reason why the stack layout used by GCC 3840need agree with that used by other compilers for a machine. 3841@end deftypefn 3842 3843@deftypefn {Target Hook} void TARGET_ASM_FUNCTION_END_PROLOGUE (FILE *@var{file}) 3844If defined, a function that outputs assembler code at the end of a 3845prologue. This should be used when the function prologue is being 3846emitted as RTL, and you have some extra assembler that needs to be 3847emitted. @xref{prologue instruction pattern}. 3848@end deftypefn 3849 3850@deftypefn {Target Hook} void TARGET_ASM_FUNCTION_BEGIN_EPILOGUE (FILE *@var{file}) 3851If defined, a function that outputs assembler code at the start of an 3852epilogue. This should be used when the function epilogue is being 3853emitted as RTL, and you have some extra assembler that needs to be 3854emitted. @xref{epilogue instruction pattern}. 3855@end deftypefn 3856 3857@deftypefn {Target Hook} void TARGET_ASM_FUNCTION_EPILOGUE (FILE *@var{file}, HOST_WIDE_INT @var{size}) 3858If defined, a function that outputs the assembler code for exit from a 3859function. The epilogue is responsible for restoring the saved 3860registers and stack pointer to their values when the function was 3861called, and returning control to the caller. This macro takes the 3862same arguments as the macro @code{TARGET_ASM_FUNCTION_PROLOGUE}, and the 3863registers to restore are determined from @code{regs_ever_live} and 3864@code{CALL_USED_REGISTERS} in the same way. 3865 3866On some machines, there is a single instruction that does all the work 3867of returning from the function. On these machines, give that 3868instruction the name @samp{return} and do not define the macro 3869@code{TARGET_ASM_FUNCTION_EPILOGUE} at all. 3870 3871Do not define a pattern named @samp{return} if you want the 3872@code{TARGET_ASM_FUNCTION_EPILOGUE} to be used. If you want the target 3873switches to control whether return instructions or epilogues are used, 3874define a @samp{return} pattern with a validity condition that tests the 3875target switches appropriately. If the @samp{return} pattern's validity 3876condition is false, epilogues will be used. 3877 3878On machines where functions may or may not have frame-pointers, the 3879function exit code must vary accordingly. Sometimes the code for these 3880two cases is completely different. To determine whether a frame pointer 3881is wanted, the macro can refer to the variable 3882@code{frame_pointer_needed}. The variable's value will be 1 when compiling 3883a function that needs a frame pointer. 3884 3885Normally, @code{TARGET_ASM_FUNCTION_PROLOGUE} and 3886@code{TARGET_ASM_FUNCTION_EPILOGUE} must treat leaf functions specially. 3887The C variable @code{current_function_is_leaf} is nonzero for such a 3888function. @xref{Leaf Functions}. 3889 3890On some machines, some functions pop their arguments on exit while 3891others leave that for the caller to do. For example, the 68020 when 3892given @option{-mrtd} pops arguments in functions that take a fixed 3893number of arguments. 3894 3895@findex current_function_pops_args 3896Your definition of the macro @code{RETURN_POPS_ARGS} decides which 3897functions pop their own arguments. @code{TARGET_ASM_FUNCTION_EPILOGUE} 3898needs to know what was decided. The variable that is called 3899@code{current_function_pops_args} is the number of bytes of its 3900arguments that a function should pop. @xref{Scalar Return}. 3901@c what is the "its arguments" in the above sentence referring to, pray 3902@c tell? --mew 5feb93 3903@end deftypefn 3904 3905@table @code 3906 3907@itemize @bullet 3908@item 3909@findex current_function_pretend_args_size 3910A region of @code{current_function_pretend_args_size} bytes of 3911uninitialized space just underneath the first argument arriving on the 3912stack. (This may not be at the very start of the allocated stack region 3913if the calling sequence has pushed anything else since pushing the stack 3914arguments. But usually, on such machines, nothing else has been pushed 3915yet, because the function prologue itself does all the pushing.) This 3916region is used on machines where an argument may be passed partly in 3917registers and partly in memory, and, in some cases to support the 3918features in @code{<varargs.h>} and @code{<stdarg.h>}. 3919 3920@item 3921An area of memory used to save certain registers used by the function. 3922The size of this area, which may also include space for such things as 3923the return address and pointers to previous stack frames, is 3924machine-specific and usually depends on which registers have been used 3925in the function. Machines with register windows often do not require 3926a save area. 3927 3928@item 3929A region of at least @var{size} bytes, possibly rounded up to an allocation 3930boundary, to contain the local variables of the function. On some machines, 3931this region and the save area may occur in the opposite order, with the 3932save area closer to the top of the stack. 3933 3934@item 3935@cindex @code{ACCUMULATE_OUTGOING_ARGS} and stack frames 3936Optionally, when @code{ACCUMULATE_OUTGOING_ARGS} is defined, a region of 3937@code{current_function_outgoing_args_size} bytes to be used for outgoing 3938argument lists of the function. @xref{Stack Arguments}. 3939@end itemize 3940 3941Normally, it is necessary for the macros 3942@code{TARGET_ASM_FUNCTION_PROLOGUE} and 3943@code{TARGET_ASM_FUNCTION_EPILOGUE} to treat leaf functions specially. 3944The C variable @code{current_function_is_leaf} is nonzero for such a 3945function. 3946 3947@findex EXIT_IGNORE_STACK 3948@item EXIT_IGNORE_STACK 3949Define this macro as a C expression that is nonzero if the return 3950instruction or the function epilogue ignores the value of the stack 3951pointer; in other words, if it is safe to delete an instruction to 3952adjust the stack pointer before a return from the function. 3953 3954Note that this macro's value is relevant only for functions for which 3955frame pointers are maintained. It is never safe to delete a final 3956stack adjustment in a function that has no frame pointer, and the 3957compiler knows this regardless of @code{EXIT_IGNORE_STACK}. 3958 3959@findex EPILOGUE_USES 3960@item EPILOGUE_USES (@var{regno}) 3961Define this macro as a C expression that is nonzero for registers that are 3962used by the epilogue or the @samp{return} pattern. The stack and frame 3963pointer registers are already be assumed to be used as needed. 3964 3965@findex EH_USES 3966@item EH_USES (@var{regno}) 3967Define this macro as a C expression that is nonzero for registers that are 3968used by the exception handling mechanism, and so should be considered live 3969on entry to an exception edge. 3970 3971@findex DELAY_SLOTS_FOR_EPILOGUE 3972@item DELAY_SLOTS_FOR_EPILOGUE 3973Define this macro if the function epilogue contains delay slots to which 3974instructions from the rest of the function can be ``moved''. The 3975definition should be a C expression whose value is an integer 3976representing the number of delay slots there. 3977 3978@findex ELIGIBLE_FOR_EPILOGUE_DELAY 3979@item ELIGIBLE_FOR_EPILOGUE_DELAY (@var{insn}, @var{n}) 3980A C expression that returns 1 if @var{insn} can be placed in delay 3981slot number @var{n} of the epilogue. 3982 3983The argument @var{n} is an integer which identifies the delay slot now 3984being considered (since different slots may have different rules of 3985eligibility). It is never negative and is always less than the number 3986of epilogue delay slots (what @code{DELAY_SLOTS_FOR_EPILOGUE} returns). 3987If you reject a particular insn for a given delay slot, in principle, it 3988may be reconsidered for a subsequent delay slot. Also, other insns may 3989(at least in principle) be considered for the so far unfilled delay 3990slot. 3991 3992@findex current_function_epilogue_delay_list 3993@findex final_scan_insn 3994The insns accepted to fill the epilogue delay slots are put in an RTL 3995list made with @code{insn_list} objects, stored in the variable 3996@code{current_function_epilogue_delay_list}. The insn for the first 3997delay slot comes first in the list. Your definition of the macro 3998@code{TARGET_ASM_FUNCTION_EPILOGUE} should fill the delay slots by 3999outputting the insns in this list, usually by calling 4000@code{final_scan_insn}. 4001 4002You need not define this macro if you did not define 4003@code{DELAY_SLOTS_FOR_EPILOGUE}. 4004 4005@findex ASM_OUTPUT_MI_THUNK 4006@item ASM_OUTPUT_MI_THUNK (@var{file}, @var{thunk_fndecl}, @var{delta}, @var{function}) 4007A C compound statement that outputs the assembler code for a thunk 4008function, used to implement C++ virtual function calls with multiple 4009inheritance. The thunk acts as a wrapper around a virtual function, 4010adjusting the implicit object parameter before handing control off to 4011the real function. 4012 4013First, emit code to add the integer @var{delta} to the location that 4014contains the incoming first argument. Assume that this argument 4015contains a pointer, and is the one used to pass the @code{this} pointer 4016in C++. This is the incoming argument @emph{before} the function prologue, 4017e.g.@: @samp{%o0} on a sparc. The addition must preserve the values of 4018all other incoming arguments. 4019 4020After the addition, emit code to jump to @var{function}, which is a 4021@code{FUNCTION_DECL}. This is a direct pure jump, not a call, and does 4022not touch the return address. Hence returning from @var{FUNCTION} will 4023return to whoever called the current @samp{thunk}. 4024 4025The effect must be as if @var{function} had been called directly with 4026the adjusted first argument. This macro is responsible for emitting all 4027of the code for a thunk function; @code{TARGET_ASM_FUNCTION_PROLOGUE} 4028and @code{TARGET_ASM_FUNCTION_EPILOGUE} are not invoked. 4029 4030The @var{thunk_fndecl} is redundant. (@var{delta} and @var{function} 4031have already been extracted from it.) It might possibly be useful on 4032some targets, but probably not. 4033 4034If you do not define this macro, the target-independent code in the C++ 4035front end will generate a less efficient heavyweight thunk that calls 4036@var{function} instead of jumping to it. The generic approach does 4037not support varargs. 4038@end table 4039 4040@node Profiling 4041@subsection Generating Code for Profiling 4042@cindex profiling, code generation 4043 4044These macros will help you generate code for profiling. 4045 4046@table @code 4047@findex FUNCTION_PROFILER 4048@item FUNCTION_PROFILER (@var{file}, @var{labelno}) 4049A C statement or compound statement to output to @var{file} some 4050assembler code to call the profiling subroutine @code{mcount}. 4051 4052@findex mcount 4053The details of how @code{mcount} expects to be called are determined by 4054your operating system environment, not by GCC@. To figure them out, 4055compile a small program for profiling using the system's installed C 4056compiler and look at the assembler code that results. 4057 4058Older implementations of @code{mcount} expect the address of a counter 4059variable to be loaded into some register. The name of this variable is 4060@samp{LP} followed by the number @var{labelno}, so you would generate 4061the name using @samp{LP%d} in a @code{fprintf}. 4062 4063@findex PROFILE_HOOK 4064@item PROFILE_HOOK 4065A C statement or compound statement to output to @var{file} some assembly 4066code to call the profiling subroutine @code{mcount} even the target does 4067not support profiling. 4068 4069@findex NO_PROFILE_COUNTERS 4070@item NO_PROFILE_COUNTERS 4071Define this macro if the @code{mcount} subroutine on your system does 4072not need a counter variable allocated for each function. This is true 4073for almost all modern implementations. If you define this macro, you 4074must not use the @var{labelno} argument to @code{FUNCTION_PROFILER}. 4075 4076@findex PROFILE_BEFORE_PROLOGUE 4077@item PROFILE_BEFORE_PROLOGUE 4078Define this macro if the code for function profiling should come before 4079the function prologue. Normally, the profiling code comes after. 4080 4081 4082@findex TARGET_ALLOWS_PROFILING_WITHOUT_FRAME_POINTER 4083@item TARGET_ALLOWS_PROFILING_WITHOUT_FRAME_POINTER 4084On some targets, it is impossible to use profiling when the frame 4085pointer has been omitted. For example, on x86 GNU/Linux systems, 4086the @code{mcount} routine provided by the GNU C Library finds the 4087address of the routine that called the routine that called @code{mcount} 4088by looking in the immediate caller's stack frame. If the immediate 4089caller has no frame pointer, this lookup will fail. 4090 4091By default, GCC assumes that the target does allow profiling when the 4092frame pointer is omitted. This macro should be defined to a C 4093expression that evaluates to @code{false} if the target does not allow 4094profiling when the frame pointer is omitted. 4095 4096@end table 4097 4098@node Tail Calls 4099@subsection Permitting tail calls 4100@cindex tail calls 4101 4102@table @code 4103@findex FUNCTION_OK_FOR_SIBCALL 4104@item FUNCTION_OK_FOR_SIBCALL (@var{decl}) 4105A C expression that evaluates to true if it is ok to perform a sibling 4106call to @var{decl} from the current function. 4107 4108It is not uncommon for limitations of calling conventions to prevent 4109tail calls to functions outside the current unit of translation, or 4110during PIC compilation. Use this macro to enforce these restrictions, 4111as the @code{sibcall} md pattern can not fail, or fall over to a 4112``normal'' call. 4113@end table 4114 4115@node Varargs 4116@section Implementing the Varargs Macros 4117@cindex varargs implementation 4118 4119GCC comes with an implementation of @code{<varargs.h>} and 4120@code{<stdarg.h>} that work without change on machines that pass arguments 4121on the stack. Other machines require their own implementations of 4122varargs, and the two machine independent header files must have 4123conditionals to include it. 4124 4125ISO @code{<stdarg.h>} differs from traditional @code{<varargs.h>} mainly in 4126the calling convention for @code{va_start}. The traditional 4127implementation takes just one argument, which is the variable in which 4128to store the argument pointer. The ISO implementation of 4129@code{va_start} takes an additional second argument. The user is 4130supposed to write the last named argument of the function here. 4131 4132However, @code{va_start} should not use this argument. The way to find 4133the end of the named arguments is with the built-in functions described 4134below. 4135 4136@table @code 4137@findex __builtin_saveregs 4138@item __builtin_saveregs () 4139Use this built-in function to save the argument registers in memory so 4140that the varargs mechanism can access them. Both ISO and traditional 4141versions of @code{va_start} must use @code{__builtin_saveregs}, unless 4142you use @code{SETUP_INCOMING_VARARGS} (see below) instead. 4143 4144On some machines, @code{__builtin_saveregs} is open-coded under the 4145control of the macro @code{EXPAND_BUILTIN_SAVEREGS}. On other machines, 4146it calls a routine written in assembler language, found in 4147@file{libgcc2.c}. 4148 4149Code generated for the call to @code{__builtin_saveregs} appears at the 4150beginning of the function, as opposed to where the call to 4151@code{__builtin_saveregs} is written, regardless of what the code is. 4152This is because the registers must be saved before the function starts 4153to use them for its own purposes. 4154@c i rewrote the first sentence above to fix an overfull hbox. --mew 4155@c 10feb93 4156 4157@findex __builtin_args_info 4158@item __builtin_args_info (@var{category}) 4159Use this built-in function to find the first anonymous arguments in 4160registers. 4161 4162In general, a machine may have several categories of registers used for 4163arguments, each for a particular category of data types. (For example, 4164on some machines, floating-point registers are used for floating-point 4165arguments while other arguments are passed in the general registers.) 4166To make non-varargs functions use the proper calling convention, you 4167have defined the @code{CUMULATIVE_ARGS} data type to record how many 4168registers in each category have been used so far 4169 4170@code{__builtin_args_info} accesses the same data structure of type 4171@code{CUMULATIVE_ARGS} after the ordinary argument layout is finished 4172with it, with @var{category} specifying which word to access. Thus, the 4173value indicates the first unused register in a given category. 4174 4175Normally, you would use @code{__builtin_args_info} in the implementation 4176of @code{va_start}, accessing each category just once and storing the 4177value in the @code{va_list} object. This is because @code{va_list} will 4178have to update the values, and there is no way to alter the 4179values accessed by @code{__builtin_args_info}. 4180 4181@findex __builtin_next_arg 4182@item __builtin_next_arg (@var{lastarg}) 4183This is the equivalent of @code{__builtin_args_info}, for stack 4184arguments. It returns the address of the first anonymous stack 4185argument, as type @code{void *}. If @code{ARGS_GROW_DOWNWARD}, it 4186returns the address of the location above the first anonymous stack 4187argument. Use it in @code{va_start} to initialize the pointer for 4188fetching arguments from the stack. Also use it in @code{va_start} to 4189verify that the second parameter @var{lastarg} is the last named argument 4190of the current function. 4191 4192@findex __builtin_classify_type 4193@item __builtin_classify_type (@var{object}) 4194Since each machine has its own conventions for which data types are 4195passed in which kind of register, your implementation of @code{va_arg} 4196has to embody these conventions. The easiest way to categorize the 4197specified data type is to use @code{__builtin_classify_type} together 4198with @code{sizeof} and @code{__alignof__}. 4199 4200@code{__builtin_classify_type} ignores the value of @var{object}, 4201considering only its data type. It returns an integer describing what 4202kind of type that is---integer, floating, pointer, structure, and so on. 4203 4204The file @file{typeclass.h} defines an enumeration that you can use to 4205interpret the values of @code{__builtin_classify_type}. 4206@end table 4207 4208These machine description macros help implement varargs: 4209 4210@table @code 4211@findex EXPAND_BUILTIN_SAVEREGS 4212@item EXPAND_BUILTIN_SAVEREGS () 4213If defined, is a C expression that produces the machine-specific code 4214for a call to @code{__builtin_saveregs}. This code will be moved to the 4215very beginning of the function, before any parameter access are made. 4216The return value of this function should be an RTX that contains the 4217value to use as the return of @code{__builtin_saveregs}. 4218 4219@findex SETUP_INCOMING_VARARGS 4220@item SETUP_INCOMING_VARARGS (@var{args_so_far}, @var{mode}, @var{type}, @var{pretend_args_size}, @var{second_time}) 4221This macro offers an alternative to using @code{__builtin_saveregs} and 4222defining the macro @code{EXPAND_BUILTIN_SAVEREGS}. Use it to store the 4223anonymous register arguments into the stack so that all the arguments 4224appear to have been passed consecutively on the stack. Once this is 4225done, you can use the standard implementation of varargs that works for 4226machines that pass all their arguments on the stack. 4227 4228The argument @var{args_so_far} is the @code{CUMULATIVE_ARGS} data 4229structure, containing the values that are obtained after processing the 4230named arguments. The arguments @var{mode} and @var{type} describe the 4231last named argument---its machine mode and its data type as a tree node. 4232 4233The macro implementation should do two things: first, push onto the 4234stack all the argument registers @emph{not} used for the named 4235arguments, and second, store the size of the data thus pushed into the 4236@code{int}-valued variable whose name is supplied as the argument 4237@var{pretend_args_size}. The value that you store here will serve as 4238additional offset for setting up the stack frame. 4239 4240Because you must generate code to push the anonymous arguments at 4241compile time without knowing their data types, 4242@code{SETUP_INCOMING_VARARGS} is only useful on machines that have just 4243a single category of argument register and use it uniformly for all data 4244types. 4245 4246If the argument @var{second_time} is nonzero, it means that the 4247arguments of the function are being analyzed for the second time. This 4248happens for an inline function, which is not actually compiled until the 4249end of the source file. The macro @code{SETUP_INCOMING_VARARGS} should 4250not generate any instructions in this case. 4251 4252@findex STRICT_ARGUMENT_NAMING 4253@item STRICT_ARGUMENT_NAMING 4254Define this macro to be a nonzero value if the location where a function 4255argument is passed depends on whether or not it is a named argument. 4256 4257This macro controls how the @var{named} argument to @code{FUNCTION_ARG} 4258is set for varargs and stdarg functions. If this macro returns a 4259nonzero value, the @var{named} argument is always true for named 4260arguments, and false for unnamed arguments. If it returns a value of 4261zero, but @code{SETUP_INCOMING_VARARGS} is defined, then all arguments 4262are treated as named. Otherwise, all named arguments except the last 4263are treated as named. 4264 4265You need not define this macro if it always returns zero. 4266 4267@findex PRETEND_OUTGOING_VARARGS_NAMED 4268@item PRETEND_OUTGOING_VARARGS_NAMED 4269If you need to conditionally change ABIs so that one works with 4270@code{SETUP_INCOMING_VARARGS}, but the other works like neither 4271@code{SETUP_INCOMING_VARARGS} nor @code{STRICT_ARGUMENT_NAMING} was 4272defined, then define this macro to return nonzero if 4273@code{SETUP_INCOMING_VARARGS} is used, zero otherwise. 4274Otherwise, you should not define this macro. 4275@end table 4276 4277@node Trampolines 4278@section Trampolines for Nested Functions 4279@cindex trampolines for nested functions 4280@cindex nested functions, trampolines for 4281 4282A @dfn{trampoline} is a small piece of code that is created at run time 4283when the address of a nested function is taken. It normally resides on 4284the stack, in the stack frame of the containing function. These macros 4285tell GCC how to generate code to allocate and initialize a 4286trampoline. 4287 4288The instructions in the trampoline must do two things: load a constant 4289address into the static chain register, and jump to the real address of 4290the nested function. On CISC machines such as the m68k, this requires 4291two instructions, a move immediate and a jump. Then the two addresses 4292exist in the trampoline as word-long immediate operands. On RISC 4293machines, it is often necessary to load each address into a register in 4294two parts. Then pieces of each address form separate immediate 4295operands. 4296 4297The code generated to initialize the trampoline must store the variable 4298parts---the static chain value and the function address---into the 4299immediate operands of the instructions. On a CISC machine, this is 4300simply a matter of copying each address to a memory reference at the 4301proper offset from the start of the trampoline. On a RISC machine, it 4302may be necessary to take out pieces of the address and store them 4303separately. 4304 4305@table @code 4306@findex TRAMPOLINE_TEMPLATE 4307@item TRAMPOLINE_TEMPLATE (@var{file}) 4308A C statement to output, on the stream @var{file}, assembler code for a 4309block of data that contains the constant parts of a trampoline. This 4310code should not include a label---the label is taken care of 4311automatically. 4312 4313If you do not define this macro, it means no template is needed 4314for the target. Do not define this macro on systems where the block move 4315code to copy the trampoline into place would be larger than the code 4316to generate it on the spot. 4317 4318@findex TRAMPOLINE_SECTION 4319@item TRAMPOLINE_SECTION 4320The name of a subroutine to switch to the section in which the 4321trampoline template is to be placed (@pxref{Sections}). The default is 4322a value of @samp{readonly_data_section}, which places the trampoline in 4323the section containing read-only data. 4324 4325@findex TRAMPOLINE_SIZE 4326@item TRAMPOLINE_SIZE 4327A C expression for the size in bytes of the trampoline, as an integer. 4328 4329@findex TRAMPOLINE_ALIGNMENT 4330@item TRAMPOLINE_ALIGNMENT 4331Alignment required for trampolines, in bits. 4332 4333If you don't define this macro, the value of @code{BIGGEST_ALIGNMENT} 4334is used for aligning trampolines. 4335 4336@findex INITIALIZE_TRAMPOLINE 4337@item INITIALIZE_TRAMPOLINE (@var{addr}, @var{fnaddr}, @var{static_chain}) 4338A C statement to initialize the variable parts of a trampoline. 4339@var{addr} is an RTX for the address of the trampoline; @var{fnaddr} is 4340an RTX for the address of the nested function; @var{static_chain} is an 4341RTX for the static chain value that should be passed to the function 4342when it is called. 4343 4344@findex TRAMPOLINE_ADJUST_ADDRESS 4345@item TRAMPOLINE_ADJUST_ADDRESS (@var{addr}) 4346A C statement that should perform any machine-specific adjustment in 4347the address of the trampoline. Its argument contains the address that 4348was passed to @code{INITIALIZE_TRAMPOLINE}. In case the address to be 4349used for a function call should be different from the address in which 4350the template was stored, the different address should be assigned to 4351@var{addr}. If this macro is not defined, @var{addr} will be used for 4352function calls. 4353 4354@findex ALLOCATE_TRAMPOLINE 4355@item ALLOCATE_TRAMPOLINE (@var{fp}) 4356A C expression to allocate run-time space for a trampoline. The 4357expression value should be an RTX representing a memory reference to the 4358space for the trampoline. 4359 4360@cindex @code{TARGET_ASM_FUNCTION_EPILOGUE} and trampolines 4361@cindex @code{TARGET_ASM_FUNCTION_PROLOGUE} and trampolines 4362If this macro is not defined, by default the trampoline is allocated as 4363a stack slot. This default is right for most machines. The exceptions 4364are machines where it is impossible to execute instructions in the stack 4365area. On such machines, you may have to implement a separate stack, 4366using this macro in conjunction with @code{TARGET_ASM_FUNCTION_PROLOGUE} 4367and @code{TARGET_ASM_FUNCTION_EPILOGUE}. 4368 4369@var{fp} points to a data structure, a @code{struct function}, which 4370describes the compilation status of the immediate containing function of 4371the function which the trampoline is for. Normally (when 4372@code{ALLOCATE_TRAMPOLINE} is not defined), the stack slot for the 4373trampoline is in the stack frame of this containing function. Other 4374allocation strategies probably must do something analogous with this 4375information. 4376@end table 4377 4378Implementing trampolines is difficult on many machines because they have 4379separate instruction and data caches. Writing into a stack location 4380fails to clear the memory in the instruction cache, so when the program 4381jumps to that location, it executes the old contents. 4382 4383Here are two possible solutions. One is to clear the relevant parts of 4384the instruction cache whenever a trampoline is set up. The other is to 4385make all trampolines identical, by having them jump to a standard 4386subroutine. The former technique makes trampoline execution faster; the 4387latter makes initialization faster. 4388 4389To clear the instruction cache when a trampoline is initialized, define 4390the following macros which describe the shape of the cache. 4391 4392@table @code 4393@findex INSN_CACHE_SIZE 4394@item INSN_CACHE_SIZE 4395The total size in bytes of the cache. 4396 4397@findex INSN_CACHE_LINE_WIDTH 4398@item INSN_CACHE_LINE_WIDTH 4399The length in bytes of each cache line. The cache is divided into cache 4400lines which are disjoint slots, each holding a contiguous chunk of data 4401fetched from memory. Each time data is brought into the cache, an 4402entire line is read at once. The data loaded into a cache line is 4403always aligned on a boundary equal to the line size. 4404 4405@findex INSN_CACHE_DEPTH 4406@item INSN_CACHE_DEPTH 4407The number of alternative cache lines that can hold any particular memory 4408location. 4409@end table 4410 4411Alternatively, if the machine has system calls or instructions to clear 4412the instruction cache directly, you can define the following macro. 4413 4414@table @code 4415@findex CLEAR_INSN_CACHE 4416@item CLEAR_INSN_CACHE (@var{beg}, @var{end}) 4417If defined, expands to a C expression clearing the @emph{instruction 4418cache} in the specified interval. If it is not defined, and the macro 4419@code{INSN_CACHE_SIZE} is defined, some generic code is generated to clear the 4420cache. The definition of this macro would typically be a series of 4421@code{asm} statements. Both @var{beg} and @var{end} are both pointer 4422expressions. 4423@end table 4424 4425To use a standard subroutine, define the following macro. In addition, 4426you must make sure that the instructions in a trampoline fill an entire 4427cache line with identical instructions, or else ensure that the 4428beginning of the trampoline code is always aligned at the same point in 4429its cache line. Look in @file{m68k.h} as a guide. 4430 4431@table @code 4432@findex TRANSFER_FROM_TRAMPOLINE 4433@item TRANSFER_FROM_TRAMPOLINE 4434Define this macro if trampolines need a special subroutine to do their 4435work. The macro should expand to a series of @code{asm} statements 4436which will be compiled with GCC@. They go in a library function named 4437@code{__transfer_from_trampoline}. 4438 4439If you need to avoid executing the ordinary prologue code of a compiled 4440C function when you jump to the subroutine, you can do so by placing a 4441special label of your own in the assembler code. Use one @code{asm} 4442statement to generate an assembler label, and another to make the label 4443global. Then trampolines can use that label to jump directly to your 4444special assembler code. 4445@end table 4446 4447@node Library Calls 4448@section Implicit Calls to Library Routines 4449@cindex library subroutine names 4450@cindex @file{libgcc.a} 4451 4452@c prevent bad page break with this line 4453Here is an explanation of implicit calls to library routines. 4454 4455@table @code 4456@findex MULSI3_LIBCALL 4457@item MULSI3_LIBCALL 4458A C string constant giving the name of the function to call for 4459multiplication of one signed full-word by another. If you do not 4460define this macro, the default name is used, which is @code{__mulsi3}, 4461a function defined in @file{libgcc.a}. 4462 4463@findex DIVSI3_LIBCALL 4464@item DIVSI3_LIBCALL 4465A C string constant giving the name of the function to call for 4466division of one signed full-word by another. If you do not define 4467this macro, the default name is used, which is @code{__divsi3}, a 4468function defined in @file{libgcc.a}. 4469 4470@findex UDIVSI3_LIBCALL 4471@item UDIVSI3_LIBCALL 4472A C string constant giving the name of the function to call for 4473division of one unsigned full-word by another. If you do not define 4474this macro, the default name is used, which is @code{__udivsi3}, a 4475function defined in @file{libgcc.a}. 4476 4477@findex MODSI3_LIBCALL 4478@item MODSI3_LIBCALL 4479A C string constant giving the name of the function to call for the 4480remainder in division of one signed full-word by another. If you do 4481not define this macro, the default name is used, which is 4482@code{__modsi3}, a function defined in @file{libgcc.a}. 4483 4484@findex UMODSI3_LIBCALL 4485@item UMODSI3_LIBCALL 4486A C string constant giving the name of the function to call for the 4487remainder in division of one unsigned full-word by another. If you do 4488not define this macro, the default name is used, which is 4489@code{__umodsi3}, a function defined in @file{libgcc.a}. 4490 4491@findex MULDI3_LIBCALL 4492@item MULDI3_LIBCALL 4493A C string constant giving the name of the function to call for 4494multiplication of one signed double-word by another. If you do not 4495define this macro, the default name is used, which is @code{__muldi3}, 4496a function defined in @file{libgcc.a}. 4497 4498@findex DIVDI3_LIBCALL 4499@item DIVDI3_LIBCALL 4500A C string constant giving the name of the function to call for 4501division of one signed double-word by another. If you do not define 4502this macro, the default name is used, which is @code{__divdi3}, a 4503function defined in @file{libgcc.a}. 4504 4505@findex UDIVDI3_LIBCALL 4506@item UDIVDI3_LIBCALL 4507A C string constant giving the name of the function to call for 4508division of one unsigned full-word by another. If you do not define 4509this macro, the default name is used, which is @code{__udivdi3}, a 4510function defined in @file{libgcc.a}. 4511 4512@findex MODDI3_LIBCALL 4513@item MODDI3_LIBCALL 4514A C string constant giving the name of the function to call for the 4515remainder in division of one signed double-word by another. If you do 4516not define this macro, the default name is used, which is 4517@code{__moddi3}, a function defined in @file{libgcc.a}. 4518 4519@findex UMODDI3_LIBCALL 4520@item UMODDI3_LIBCALL 4521A C string constant giving the name of the function to call for the 4522remainder in division of one unsigned full-word by another. If you do 4523not define this macro, the default name is used, which is 4524@code{__umoddi3}, a function defined in @file{libgcc.a}. 4525 4526@findex INIT_TARGET_OPTABS 4527@item INIT_TARGET_OPTABS 4528Define this macro as a C statement that declares additional library 4529routines renames existing ones. @code{init_optabs} calls this macro after 4530initializing all the normal library routines. 4531 4532@findex FLOAT_LIB_COMPARE_RETURNS_BOOL (@var{mode}, @var{comparison}) 4533@item FLOAT_LIB_COMPARE_RETURNS_BOOL 4534Define this macro as a C statement that returns nonzero if a call to 4535the floating point comparison library function will return a boolean 4536value that indicates the result of the comparison. It should return 4537zero if one of gcc's own libgcc functions is called. 4538 4539Most ports don't need to define this macro. 4540 4541@findex TARGET_EDOM 4542@cindex @code{EDOM}, implicit usage 4543@item TARGET_EDOM 4544The value of @code{EDOM} on the target machine, as a C integer constant 4545expression. If you don't define this macro, GCC does not attempt to 4546deposit the value of @code{EDOM} into @code{errno} directly. Look in 4547@file{/usr/include/errno.h} to find the value of @code{EDOM} on your 4548system. 4549 4550If you do not define @code{TARGET_EDOM}, then compiled code reports 4551domain errors by calling the library function and letting it report the 4552error. If mathematical functions on your system use @code{matherr} when 4553there is an error, then you should leave @code{TARGET_EDOM} undefined so 4554that @code{matherr} is used normally. 4555 4556@findex GEN_ERRNO_RTX 4557@cindex @code{errno}, implicit usage 4558@item GEN_ERRNO_RTX 4559Define this macro as a C expression to create an rtl expression that 4560refers to the global ``variable'' @code{errno}. (On certain systems, 4561@code{errno} may not actually be a variable.) If you don't define this 4562macro, a reasonable default is used. 4563 4564@findex TARGET_MEM_FUNCTIONS 4565@cindex @code{bcopy}, implicit usage 4566@cindex @code{memcpy}, implicit usage 4567@cindex @code{memmove}, implicit usage 4568@cindex @code{bzero}, implicit usage 4569@cindex @code{memset}, implicit usage 4570@item TARGET_MEM_FUNCTIONS 4571Define this macro if GCC should generate calls to the ISO C 4572(and System V) library functions @code{memcpy}, @code{memmove} and 4573@code{memset} rather than the BSD functions @code{bcopy} and @code{bzero}. 4574 4575@findex LIBGCC_NEEDS_DOUBLE 4576@item LIBGCC_NEEDS_DOUBLE 4577Define this macro if @code{float} arguments cannot be passed to library 4578routines (so they must be converted to @code{double}). This macro 4579affects both how library calls are generated and how the library 4580routines in @file{libgcc.a} accept their arguments. It is useful on 4581machines where floating and fixed point arguments are passed 4582differently, such as the i860. 4583 4584@findex NEXT_OBJC_RUNTIME 4585@item NEXT_OBJC_RUNTIME 4586Define this macro to generate code for Objective-C message sending using 4587the calling convention of the NeXT system. This calling convention 4588involves passing the object, the selector and the method arguments all 4589at once to the method-lookup library function. 4590 4591The default calling convention passes just the object and the selector 4592to the lookup function, which returns a pointer to the method. 4593@end table 4594 4595@node Addressing Modes 4596@section Addressing Modes 4597@cindex addressing modes 4598 4599@c prevent bad page break with this line 4600This is about addressing modes. 4601 4602@table @code 4603@findex HAVE_PRE_INCREMENT 4604@findex HAVE_PRE_DECREMENT 4605@findex HAVE_POST_INCREMENT 4606@findex HAVE_POST_DECREMENT 4607@item HAVE_PRE_INCREMENT 4608@itemx HAVE_PRE_DECREMENT 4609@itemx HAVE_POST_INCREMENT 4610@itemx HAVE_POST_DECREMENT 4611A C expression that is nonzero if the machine supports pre-increment, 4612pre-decrement, post-increment, or post-decrement addressing respectively. 4613 4614@findex HAVE_POST_MODIFY_DISP 4615@findex HAVE_PRE_MODIFY_DISP 4616@item HAVE_PRE_MODIFY_DISP 4617@itemx HAVE_POST_MODIFY_DISP 4618A C expression that is nonzero if the machine supports pre- or 4619post-address side-effect generation involving constants other than 4620the size of the memory operand. 4621 4622@findex HAVE_POST_MODIFY_REG 4623@findex HAVE_PRE_MODIFY_REG 4624@item HAVE_PRE_MODIFY_REG 4625@itemx HAVE_POST_MODIFY_REG 4626A C expression that is nonzero if the machine supports pre- or 4627post-address side-effect generation involving a register displacement. 4628 4629@findex CONSTANT_ADDRESS_P 4630@item CONSTANT_ADDRESS_P (@var{x}) 4631A C expression that is 1 if the RTX @var{x} is a constant which 4632is a valid address. On most machines, this can be defined as 4633@code{CONSTANT_P (@var{x})}, but a few machines are more restrictive 4634in which constant addresses are supported. 4635 4636@findex CONSTANT_P 4637@code{CONSTANT_P} accepts integer-values expressions whose values are 4638not explicitly known, such as @code{symbol_ref}, @code{label_ref}, and 4639@code{high} expressions and @code{const} arithmetic expressions, in 4640addition to @code{const_int} and @code{const_double} expressions. 4641 4642@findex MAX_REGS_PER_ADDRESS 4643@item MAX_REGS_PER_ADDRESS 4644A number, the maximum number of registers that can appear in a valid 4645memory address. Note that it is up to you to specify a value equal to 4646the maximum number that @code{GO_IF_LEGITIMATE_ADDRESS} would ever 4647accept. 4648 4649@findex GO_IF_LEGITIMATE_ADDRESS 4650@item GO_IF_LEGITIMATE_ADDRESS (@var{mode}, @var{x}, @var{label}) 4651A C compound statement with a conditional @code{goto @var{label};} 4652executed if @var{x} (an RTX) is a legitimate memory address on the 4653target machine for a memory operand of mode @var{mode}. 4654 4655It usually pays to define several simpler macros to serve as 4656subroutines for this one. Otherwise it may be too complicated to 4657understand. 4658 4659This macro must exist in two variants: a strict variant and a 4660non-strict one. The strict variant is used in the reload pass. It 4661must be defined so that any pseudo-register that has not been 4662allocated a hard register is considered a memory reference. In 4663contexts where some kind of register is required, a pseudo-register 4664with no hard register must be rejected. 4665 4666The non-strict variant is used in other passes. It must be defined to 4667accept all pseudo-registers in every context where some kind of 4668register is required. 4669 4670@findex REG_OK_STRICT 4671Compiler source files that want to use the strict variant of this 4672macro define the macro @code{REG_OK_STRICT}. You should use an 4673@code{#ifdef REG_OK_STRICT} conditional to define the strict variant 4674in that case and the non-strict variant otherwise. 4675 4676Subroutines to check for acceptable registers for various purposes (one 4677for base registers, one for index registers, and so on) are typically 4678among the subroutines used to define @code{GO_IF_LEGITIMATE_ADDRESS}. 4679Then only these subroutine macros need have two variants; the higher 4680levels of macros may be the same whether strict or not. 4681 4682Normally, constant addresses which are the sum of a @code{symbol_ref} 4683and an integer are stored inside a @code{const} RTX to mark them as 4684constant. Therefore, there is no need to recognize such sums 4685specifically as legitimate addresses. Normally you would simply 4686recognize any @code{const} as legitimate. 4687 4688Usually @code{PRINT_OPERAND_ADDRESS} is not prepared to handle constant 4689sums that are not marked with @code{const}. It assumes that a naked 4690@code{plus} indicates indexing. If so, then you @emph{must} reject such 4691naked constant sums as illegitimate addresses, so that none of them will 4692be given to @code{PRINT_OPERAND_ADDRESS}. 4693 4694@cindex @code{ENCODE_SECTION_INFO} and address validation 4695On some machines, whether a symbolic address is legitimate depends on 4696the section that the address refers to. On these machines, define the 4697macro @code{ENCODE_SECTION_INFO} to store the information into the 4698@code{symbol_ref}, and then check for it here. When you see a 4699@code{const}, you will have to look inside it to find the 4700@code{symbol_ref} in order to determine the section. @xref{Assembler 4701Format}. 4702 4703@findex saveable_obstack 4704The best way to modify the name string is by adding text to the 4705beginning, with suitable punctuation to prevent any ambiguity. Allocate 4706the new name in @code{saveable_obstack}. You will have to modify 4707@code{ASM_OUTPUT_LABELREF} to remove and decode the added text and 4708output the name accordingly, and define @code{STRIP_NAME_ENCODING} to 4709access the original name string. 4710 4711You can check the information stored here into the @code{symbol_ref} in 4712the definitions of the macros @code{GO_IF_LEGITIMATE_ADDRESS} and 4713@code{PRINT_OPERAND_ADDRESS}. 4714 4715@findex REG_OK_FOR_BASE_P 4716@item REG_OK_FOR_BASE_P (@var{x}) 4717A C expression that is nonzero if @var{x} (assumed to be a @code{reg} 4718RTX) is valid for use as a base register. For hard registers, it 4719should always accept those which the hardware permits and reject the 4720others. Whether the macro accepts or rejects pseudo registers must be 4721controlled by @code{REG_OK_STRICT} as described above. This usually 4722requires two variant definitions, of which @code{REG_OK_STRICT} 4723controls the one actually used. 4724 4725@findex REG_MODE_OK_FOR_BASE_P 4726@item REG_MODE_OK_FOR_BASE_P (@var{x}, @var{mode}) 4727A C expression that is just like @code{REG_OK_FOR_BASE_P}, except that 4728that expression may examine the mode of the memory reference in 4729@var{mode}. You should define this macro if the mode of the memory 4730reference affects whether a register may be used as a base register. If 4731you define this macro, the compiler will use it instead of 4732@code{REG_OK_FOR_BASE_P}. 4733 4734@findex REG_OK_FOR_INDEX_P 4735@item REG_OK_FOR_INDEX_P (@var{x}) 4736A C expression that is nonzero if @var{x} (assumed to be a @code{reg} 4737RTX) is valid for use as an index register. 4738 4739The difference between an index register and a base register is that 4740the index register may be scaled. If an address involves the sum of 4741two registers, neither one of them scaled, then either one may be 4742labeled the ``base'' and the other the ``index''; but whichever 4743labeling is used must fit the machine's constraints of which registers 4744may serve in each capacity. The compiler will try both labelings, 4745looking for one that is valid, and will reload one or both registers 4746only if neither labeling works. 4747 4748@findex FIND_BASE_TERM 4749@item FIND_BASE_TERM (@var{x}) 4750A C expression to determine the base term of address @var{x}. 4751This macro is used in only one place: `find_base_term' in alias.c. 4752 4753It is always safe for this macro to not be defined. It exists so 4754that alias analysis can understand machine-dependent addresses. 4755 4756The typical use of this macro is to handle addresses containing 4757a label_ref or symbol_ref within an UNSPEC@. 4758 4759@findex LEGITIMIZE_ADDRESS 4760@item LEGITIMIZE_ADDRESS (@var{x}, @var{oldx}, @var{mode}, @var{win}) 4761A C compound statement that attempts to replace @var{x} with a valid 4762memory address for an operand of mode @var{mode}. @var{win} will be a 4763C statement label elsewhere in the code; the macro definition may use 4764 4765@example 4766GO_IF_LEGITIMATE_ADDRESS (@var{mode}, @var{x}, @var{win}); 4767@end example 4768 4769@noindent 4770to avoid further processing if the address has become legitimate. 4771 4772@findex break_out_memory_refs 4773@var{x} will always be the result of a call to @code{break_out_memory_refs}, 4774and @var{oldx} will be the operand that was given to that function to produce 4775@var{x}. 4776 4777The code generated by this macro should not alter the substructure of 4778@var{x}. If it transforms @var{x} into a more legitimate form, it 4779should assign @var{x} (which will always be a C variable) a new value. 4780 4781It is not necessary for this macro to come up with a legitimate 4782address. The compiler has standard ways of doing so in all cases. In 4783fact, it is safe for this macro to do nothing. But often a 4784machine-dependent strategy can generate better code. 4785 4786@findex LEGITIMIZE_RELOAD_ADDRESS 4787@item LEGITIMIZE_RELOAD_ADDRESS (@var{x}, @var{mode}, @var{opnum}, @var{type}, @var{ind_levels}, @var{win}) 4788A C compound statement that attempts to replace @var{x}, which is an address 4789that needs reloading, with a valid memory address for an operand of mode 4790@var{mode}. @var{win} will be a C statement label elsewhere in the code. 4791It is not necessary to define this macro, but it might be useful for 4792performance reasons. 4793 4794For example, on the i386, it is sometimes possible to use a single 4795reload register instead of two by reloading a sum of two pseudo 4796registers into a register. On the other hand, for number of RISC 4797processors offsets are limited so that often an intermediate address 4798needs to be generated in order to address a stack slot. By defining 4799@code{LEGITIMIZE_RELOAD_ADDRESS} appropriately, the intermediate addresses 4800generated for adjacent some stack slots can be made identical, and thus 4801be shared. 4802 4803@emph{Note}: This macro should be used with caution. It is necessary 4804to know something of how reload works in order to effectively use this, 4805and it is quite easy to produce macros that build in too much knowledge 4806of reload internals. 4807 4808@emph{Note}: This macro must be able to reload an address created by a 4809previous invocation of this macro. If it fails to handle such addresses 4810then the compiler may generate incorrect code or abort. 4811 4812@findex push_reload 4813The macro definition should use @code{push_reload} to indicate parts that 4814need reloading; @var{opnum}, @var{type} and @var{ind_levels} are usually 4815suitable to be passed unaltered to @code{push_reload}. 4816 4817The code generated by this macro must not alter the substructure of 4818@var{x}. If it transforms @var{x} into a more legitimate form, it 4819should assign @var{x} (which will always be a C variable) a new value. 4820This also applies to parts that you change indirectly by calling 4821@code{push_reload}. 4822 4823@findex strict_memory_address_p 4824The macro definition may use @code{strict_memory_address_p} to test if 4825the address has become legitimate. 4826 4827@findex copy_rtx 4828If you want to change only a part of @var{x}, one standard way of doing 4829this is to use @code{copy_rtx}. Note, however, that is unshares only a 4830single level of rtl. Thus, if the part to be changed is not at the 4831top level, you'll need to replace first the top level. 4832It is not necessary for this macro to come up with a legitimate 4833address; but often a machine-dependent strategy can generate better code. 4834 4835@findex GO_IF_MODE_DEPENDENT_ADDRESS 4836@item GO_IF_MODE_DEPENDENT_ADDRESS (@var{addr}, @var{label}) 4837A C statement or compound statement with a conditional @code{goto 4838@var{label};} executed if memory address @var{x} (an RTX) can have 4839different meanings depending on the machine mode of the memory 4840reference it is used for or if the address is valid for some modes 4841but not others. 4842 4843Autoincrement and autodecrement addresses typically have mode-dependent 4844effects because the amount of the increment or decrement is the size 4845of the operand being addressed. Some machines have other mode-dependent 4846addresses. Many RISC machines have no mode-dependent addresses. 4847 4848You may assume that @var{addr} is a valid address for the machine. 4849 4850@findex LEGITIMATE_CONSTANT_P 4851@item LEGITIMATE_CONSTANT_P (@var{x}) 4852A C expression that is nonzero if @var{x} is a legitimate constant for 4853an immediate operand on the target machine. You can assume that 4854@var{x} satisfies @code{CONSTANT_P}, so you need not check this. In fact, 4855@samp{1} is a suitable definition for this macro on machines where 4856anything @code{CONSTANT_P} is valid. 4857@end table 4858 4859@node Condition Code 4860@section Condition Code Status 4861@cindex condition code status 4862 4863@c prevent bad page break with this line 4864This describes the condition code status. 4865 4866@findex cc_status 4867The file @file{conditions.h} defines a variable @code{cc_status} to 4868describe how the condition code was computed (in case the interpretation of 4869the condition code depends on the instruction that it was set by). This 4870variable contains the RTL expressions on which the condition code is 4871currently based, and several standard flags. 4872 4873Sometimes additional machine-specific flags must be defined in the machine 4874description header file. It can also add additional machine-specific 4875information by defining @code{CC_STATUS_MDEP}. 4876 4877@table @code 4878@findex CC_STATUS_MDEP 4879@item CC_STATUS_MDEP 4880C code for a data type which is used for declaring the @code{mdep} 4881component of @code{cc_status}. It defaults to @code{int}. 4882 4883This macro is not used on machines that do not use @code{cc0}. 4884 4885@findex CC_STATUS_MDEP_INIT 4886@item CC_STATUS_MDEP_INIT 4887A C expression to initialize the @code{mdep} field to ``empty''. 4888The default definition does nothing, since most machines don't use 4889the field anyway. If you want to use the field, you should probably 4890define this macro to initialize it. 4891 4892This macro is not used on machines that do not use @code{cc0}. 4893 4894@findex NOTICE_UPDATE_CC 4895@item NOTICE_UPDATE_CC (@var{exp}, @var{insn}) 4896A C compound statement to set the components of @code{cc_status} 4897appropriately for an insn @var{insn} whose body is @var{exp}. It is 4898this macro's responsibility to recognize insns that set the condition 4899code as a byproduct of other activity as well as those that explicitly 4900set @code{(cc0)}. 4901 4902This macro is not used on machines that do not use @code{cc0}. 4903 4904If there are insns that do not set the condition code but do alter 4905other machine registers, this macro must check to see whether they 4906invalidate the expressions that the condition code is recorded as 4907reflecting. For example, on the 68000, insns that store in address 4908registers do not set the condition code, which means that usually 4909@code{NOTICE_UPDATE_CC} can leave @code{cc_status} unaltered for such 4910insns. But suppose that the previous insn set the condition code 4911based on location @samp{a4@@(102)} and the current insn stores a new 4912value in @samp{a4}. Although the condition code is not changed by 4913this, it will no longer be true that it reflects the contents of 4914@samp{a4@@(102)}. Therefore, @code{NOTICE_UPDATE_CC} must alter 4915@code{cc_status} in this case to say that nothing is known about the 4916condition code value. 4917 4918The definition of @code{NOTICE_UPDATE_CC} must be prepared to deal 4919with the results of peephole optimization: insns whose patterns are 4920@code{parallel} RTXs containing various @code{reg}, @code{mem} or 4921constants which are just the operands. The RTL structure of these 4922insns is not sufficient to indicate what the insns actually do. What 4923@code{NOTICE_UPDATE_CC} should do when it sees one is just to run 4924@code{CC_STATUS_INIT}. 4925 4926A possible definition of @code{NOTICE_UPDATE_CC} is to call a function 4927that looks at an attribute (@pxref{Insn Attributes}) named, for example, 4928@samp{cc}. This avoids having detailed information about patterns in 4929two places, the @file{md} file and in @code{NOTICE_UPDATE_CC}. 4930 4931@findex EXTRA_CC_MODES 4932@item EXTRA_CC_MODES 4933A list of additional modes for condition code values in registers 4934(@pxref{Jump Patterns}). This macro should expand to a sequence of 4935calls of the macro @code{CC} separated by white space. @code{CC} takes 4936two arguments. The first is the enumeration name of the mode, which 4937should begin with @samp{CC} and end with @samp{mode}. The second is a C 4938string giving the printable name of the mode; it should be the same as 4939the first argument, but with the trailing @samp{mode} removed. 4940 4941You should only define this macro if additional modes are required. 4942 4943A sample definition of @code{EXTRA_CC_MODES} is: 4944@smallexample 4945#define EXTRA_CC_MODES \ 4946 CC(CC_NOOVmode, "CC_NOOV") \ 4947 CC(CCFPmode, "CCFP") \ 4948 CC(CCFPEmode, "CCFPE") 4949@end smallexample 4950 4951@findex SELECT_CC_MODE 4952@item SELECT_CC_MODE (@var{op}, @var{x}, @var{y}) 4953Returns a mode from class @code{MODE_CC} to be used when comparison 4954operation code @var{op} is applied to rtx @var{x} and @var{y}. For 4955example, on the Sparc, @code{SELECT_CC_MODE} is defined as (see 4956@pxref{Jump Patterns} for a description of the reason for this 4957definition) 4958 4959@smallexample 4960#define SELECT_CC_MODE(OP,X,Y) \ 4961 (GET_MODE_CLASS (GET_MODE (X)) == MODE_FLOAT \ 4962 ? ((OP == EQ || OP == NE) ? CCFPmode : CCFPEmode) \ 4963 : ((GET_CODE (X) == PLUS || GET_CODE (X) == MINUS \ 4964 || GET_CODE (X) == NEG) \ 4965 ? CC_NOOVmode : CCmode)) 4966@end smallexample 4967 4968You need not define this macro if @code{EXTRA_CC_MODES} is not defined. 4969 4970@findex CANONICALIZE_COMPARISON 4971@item CANONICALIZE_COMPARISON (@var{code}, @var{op0}, @var{op1}) 4972On some machines not all possible comparisons are defined, but you can 4973convert an invalid comparison into a valid one. For example, the Alpha 4974does not have a @code{GT} comparison, but you can use an @code{LT} 4975comparison instead and swap the order of the operands. 4976 4977On such machines, define this macro to be a C statement to do any 4978required conversions. @var{code} is the initial comparison code 4979and @var{op0} and @var{op1} are the left and right operands of the 4980comparison, respectively. You should modify @var{code}, @var{op0}, and 4981@var{op1} as required. 4982 4983GCC will not assume that the comparison resulting from this macro is 4984valid but will see if the resulting insn matches a pattern in the 4985@file{md} file. 4986 4987You need not define this macro if it would never change the comparison 4988code or operands. 4989 4990@findex REVERSIBLE_CC_MODE 4991@item REVERSIBLE_CC_MODE (@var{mode}) 4992A C expression whose value is one if it is always safe to reverse a 4993comparison whose mode is @var{mode}. If @code{SELECT_CC_MODE} 4994can ever return @var{mode} for a floating-point inequality comparison, 4995then @code{REVERSIBLE_CC_MODE (@var{mode})} must be zero. 4996 4997You need not define this macro if it would always returns zero or if the 4998floating-point format is anything other than @code{IEEE_FLOAT_FORMAT}. 4999For example, here is the definition used on the Sparc, where floating-point 5000inequality comparisons are always given @code{CCFPEmode}: 5001 5002@smallexample 5003#define REVERSIBLE_CC_MODE(MODE) ((MODE) != CCFPEmode) 5004@end smallexample 5005 5006@findex REVERSE_CONDITION (@var{code}, @var{mode}) 5007A C expression whose value is reversed condition code of the @var{code} for 5008comparison done in CC_MODE @var{mode}. The macro is used only in case 5009@code{REVERSIBLE_CC_MODE (@var{mode})} is nonzero. Define this macro in case 5010machine has some non-standard way how to reverse certain conditionals. For 5011instance in case all floating point conditions are non-trapping, compiler may 5012freely convert unordered compares to ordered one. Then definition may look 5013like: 5014 5015@smallexample 5016#define REVERSE_CONDITION(CODE, MODE) \ 5017 ((MODE) != CCFPmode ? reverse_condition (CODE) \ 5018 : reverse_condition_maybe_unordered (CODE)) 5019@end smallexample 5020 5021@findex REVERSE_CONDEXEC_PREDICATES_P 5022@item REVERSE_CONDEXEC_PREDICATES_P (@var{code1}, @var{code2}) 5023A C expression that returns true if the conditional execution predicate 5024@var{code1} is the inverse of @var{code2} and vice versa. Define this to 5025return 0 if the target has conditional execution predicates that cannot be 5026reversed safely. If no expansion is specified, this macro is defined as 5027follows: 5028 5029@smallexample 5030#define REVERSE_CONDEXEC_PREDICATES_P (x, y) \ 5031 ((x) == reverse_condition (y)) 5032@end smallexample 5033 5034@end table 5035 5036@node Costs 5037@section Describing Relative Costs of Operations 5038@cindex costs of instructions 5039@cindex relative costs 5040@cindex speed of instructions 5041 5042These macros let you describe the relative speed of various operations 5043on the target machine. 5044 5045@table @code 5046@findex CONST_COSTS 5047@item CONST_COSTS (@var{x}, @var{code}, @var{outer_code}) 5048A part of a C @code{switch} statement that describes the relative costs 5049of constant RTL expressions. It must contain @code{case} labels for 5050expression codes @code{const_int}, @code{const}, @code{symbol_ref}, 5051@code{label_ref} and @code{const_double}. Each case must ultimately 5052reach a @code{return} statement to return the relative cost of the use 5053of that kind of constant value in an expression. The cost may depend on 5054the precise value of the constant, which is available for examination in 5055@var{x}, and the rtx code of the expression in which it is contained, 5056found in @var{outer_code}. 5057 5058@var{code} is the expression code---redundant, since it can be 5059obtained with @code{GET_CODE (@var{x})}. 5060 5061@findex RTX_COSTS 5062@findex COSTS_N_INSNS 5063@item RTX_COSTS (@var{x}, @var{code}, @var{outer_code}) 5064Like @code{CONST_COSTS} but applies to nonconstant RTL expressions. 5065This can be used, for example, to indicate how costly a multiply 5066instruction is. In writing this macro, you can use the construct 5067@code{COSTS_N_INSNS (@var{n})} to specify a cost equal to @var{n} fast 5068instructions. @var{outer_code} is the code of the expression in which 5069@var{x} is contained. 5070 5071This macro is optional; do not define it if the default cost assumptions 5072are adequate for the target machine. 5073 5074@findex DEFAULT_RTX_COSTS 5075@item DEFAULT_RTX_COSTS (@var{x}, @var{code}, @var{outer_code}) 5076This macro, if defined, is called for any case not handled by the 5077@code{RTX_COSTS} or @code{CONST_COSTS} macros. This eliminates the need 5078to put case labels into the macro, but the code, or any functions it 5079calls, must assume that the RTL in @var{x} could be of any type that has 5080not already been handled. The arguments are the same as for 5081@code{RTX_COSTS}, and the macro should execute a return statement giving 5082the cost of any RTL expressions that it can handle. The default cost 5083calculation is used for any RTL for which this macro does not return a 5084value. 5085 5086This macro is optional; do not define it if the default cost assumptions 5087are adequate for the target machine. 5088 5089@findex ADDRESS_COST 5090@item ADDRESS_COST (@var{address}) 5091An expression giving the cost of an addressing mode that contains 5092@var{address}. If not defined, the cost is computed from 5093the @var{address} expression and the @code{CONST_COSTS} values. 5094 5095For most CISC machines, the default cost is a good approximation of the 5096true cost of the addressing mode. However, on RISC machines, all 5097instructions normally have the same length and execution time. Hence 5098all addresses will have equal costs. 5099 5100In cases where more than one form of an address is known, the form with 5101the lowest cost will be used. If multiple forms have the same, lowest, 5102cost, the one that is the most complex will be used. 5103 5104For example, suppose an address that is equal to the sum of a register 5105and a constant is used twice in the same basic block. When this macro 5106is not defined, the address will be computed in a register and memory 5107references will be indirect through that register. On machines where 5108the cost of the addressing mode containing the sum is no higher than 5109that of a simple indirect reference, this will produce an additional 5110instruction and possibly require an additional register. Proper 5111specification of this macro eliminates this overhead for such machines. 5112 5113Similar use of this macro is made in strength reduction of loops. 5114 5115@var{address} need not be valid as an address. In such a case, the cost 5116is not relevant and can be any value; invalid addresses need not be 5117assigned a different cost. 5118 5119On machines where an address involving more than one register is as 5120cheap as an address computation involving only one register, defining 5121@code{ADDRESS_COST} to reflect this can cause two registers to be live 5122over a region of code where only one would have been if 5123@code{ADDRESS_COST} were not defined in that manner. This effect should 5124be considered in the definition of this macro. Equivalent costs should 5125probably only be given to addresses with different numbers of registers 5126on machines with lots of registers. 5127 5128This macro will normally either not be defined or be defined as a 5129constant. 5130 5131@findex REGISTER_MOVE_COST 5132@item REGISTER_MOVE_COST (@var{mode}, @var{from}, @var{to}) 5133A C expression for the cost of moving data of mode @var{mode} from a 5134register in class @var{from} to one in class @var{to}. The classes are 5135expressed using the enumeration values such as @code{GENERAL_REGS}. A 5136value of 2 is the default; other values are interpreted relative to 5137that. 5138 5139It is not required that the cost always equal 2 when @var{from} is the 5140same as @var{to}; on some machines it is expensive to move between 5141registers if they are not general registers. 5142 5143If reload sees an insn consisting of a single @code{set} between two 5144hard registers, and if @code{REGISTER_MOVE_COST} applied to their 5145classes returns a value of 2, reload does not check to ensure that the 5146constraints of the insn are met. Setting a cost of other than 2 will 5147allow reload to verify that the constraints are met. You should do this 5148if the @samp{mov@var{m}} pattern's constraints do not allow such copying. 5149 5150@findex MEMORY_MOVE_COST 5151@item MEMORY_MOVE_COST (@var{mode}, @var{class}, @var{in}) 5152A C expression for the cost of moving data of mode @var{mode} between a 5153register of class @var{class} and memory; @var{in} is zero if the value 5154is to be written to memory, nonzero if it is to be read in. This cost 5155is relative to those in @code{REGISTER_MOVE_COST}. If moving between 5156registers and memory is more expensive than between two registers, you 5157should define this macro to express the relative cost. 5158 5159If you do not define this macro, GCC uses a default cost of 4 plus 5160the cost of copying via a secondary reload register, if one is 5161needed. If your machine requires a secondary reload register to copy 5162between memory and a register of @var{class} but the reload mechanism is 5163more complex than copying via an intermediate, define this macro to 5164reflect the actual cost of the move. 5165 5166GCC defines the function @code{memory_move_secondary_cost} if 5167secondary reloads are needed. It computes the costs due to copying via 5168a secondary register. If your machine copies from memory using a 5169secondary register in the conventional way but the default base value of 51704 is not correct for your machine, define this macro to add some other 5171value to the result of that function. The arguments to that function 5172are the same as to this macro. 5173 5174@findex BRANCH_COST 5175@item BRANCH_COST 5176A C expression for the cost of a branch instruction. A value of 1 is 5177the default; other values are interpreted relative to that. 5178@end table 5179 5180Here are additional macros which do not specify precise relative costs, 5181but only that certain actions are more expensive than GCC would 5182ordinarily expect. 5183 5184@table @code 5185@findex SLOW_BYTE_ACCESS 5186@item SLOW_BYTE_ACCESS 5187Define this macro as a C expression which is nonzero if accessing less 5188than a word of memory (i.e.@: a @code{char} or a @code{short}) is no 5189faster than accessing a word of memory, i.e., if such access 5190require more than one instruction or if there is no difference in cost 5191between byte and (aligned) word loads. 5192 5193When this macro is not defined, the compiler will access a field by 5194finding the smallest containing object; when it is defined, a fullword 5195load will be used if alignment permits. Unless bytes accesses are 5196faster than word accesses, using word accesses is preferable since it 5197may eliminate subsequent memory access if subsequent accesses occur to 5198other fields in the same word of the structure, but to different bytes. 5199 5200@findex SLOW_UNALIGNED_ACCESS 5201@item SLOW_UNALIGNED_ACCESS (@var{mode}, @var{alignment}) 5202Define this macro to be the value 1 if memory accesses described by the 5203@var{mode} and @var{alignment} parameters have a cost many times greater 5204than aligned accesses, for example if they are emulated in a trap 5205handler. 5206 5207When this macro is nonzero, the compiler will act as if 5208@code{STRICT_ALIGNMENT} were nonzero when generating code for block 5209moves. This can cause significantly more instructions to be produced. 5210Therefore, do not set this macro nonzero if unaligned accesses only add a 5211cycle or two to the time for a memory access. 5212 5213If the value of this macro is always zero, it need not be defined. If 5214this macro is defined, it should produce a nonzero value when 5215@code{STRICT_ALIGNMENT} is nonzero. 5216 5217@findex DONT_REDUCE_ADDR 5218@item DONT_REDUCE_ADDR 5219Define this macro to inhibit strength reduction of memory addresses. 5220(On some machines, such strength reduction seems to do harm rather 5221than good.) 5222 5223@findex MOVE_RATIO 5224@item MOVE_RATIO 5225The threshold of number of scalar memory-to-memory move insns, @emph{below} 5226which a sequence of insns should be generated instead of a 5227string move insn or a library call. Increasing the value will always 5228make code faster, but eventually incurs high cost in increased code size. 5229 5230Note that on machines where the corresponding move insn is a 5231@code{define_expand} that emits a sequence of insns, this macro counts 5232the number of such sequences. 5233 5234If you don't define this, a reasonable default is used. 5235 5236@findex MOVE_BY_PIECES_P 5237@item MOVE_BY_PIECES_P (@var{size}, @var{alignment}) 5238A C expression used to determine whether @code{move_by_pieces} will be used to 5239copy a chunk of memory, or whether some other block move mechanism 5240will be used. Defaults to 1 if @code{move_by_pieces_ninsns} returns less 5241than @code{MOVE_RATIO}. 5242 5243@findex MOVE_MAX_PIECES 5244@item MOVE_MAX_PIECES 5245A C expression used by @code{move_by_pieces} to determine the largest unit 5246a load or store used to copy memory is. Defaults to @code{MOVE_MAX}. 5247 5248@findex USE_LOAD_POST_INCREMENT 5249@item USE_LOAD_POST_INCREMENT (@var{mode}) 5250A C expression used to determine whether a load postincrement is a good 5251thing to use for a given mode. Defaults to the value of 5252@code{HAVE_POST_INCREMENT}. 5253 5254@findex USE_LOAD_POST_DECREMENT 5255@item USE_LOAD_POST_DECREMENT (@var{mode}) 5256A C expression used to determine whether a load postdecrement is a good 5257thing to use for a given mode. Defaults to the value of 5258@code{HAVE_POST_DECREMENT}. 5259 5260@findex USE_LOAD_PRE_INCREMENT 5261@item USE_LOAD_PRE_INCREMENT (@var{mode}) 5262A C expression used to determine whether a load preincrement is a good 5263thing to use for a given mode. Defaults to the value of 5264@code{HAVE_PRE_INCREMENT}. 5265 5266@findex USE_LOAD_PRE_DECREMENT 5267@item USE_LOAD_PRE_DECREMENT (@var{mode}) 5268A C expression used to determine whether a load predecrement is a good 5269thing to use for a given mode. Defaults to the value of 5270@code{HAVE_PRE_DECREMENT}. 5271 5272@findex USE_STORE_POST_INCREMENT 5273@item USE_STORE_POST_INCREMENT (@var{mode}) 5274A C expression used to determine whether a store postincrement is a good 5275thing to use for a given mode. Defaults to the value of 5276@code{HAVE_POST_INCREMENT}. 5277 5278@findex USE_STORE_POST_DECREMENT 5279@item USE_STORE_POST_DECREMENT (@var{mode}) 5280A C expression used to determine whether a store postdecrement is a good 5281thing to use for a given mode. Defaults to the value of 5282@code{HAVE_POST_DECREMENT}. 5283 5284@findex USE_STORE_PRE_INCREMENT 5285@item USE_STORE_PRE_INCREMENT (@var{mode}) 5286This macro is used to determine whether a store preincrement is a good 5287thing to use for a given mode. Defaults to the value of 5288@code{HAVE_PRE_INCREMENT}. 5289 5290@findex USE_STORE_PRE_DECREMENT 5291@item USE_STORE_PRE_DECREMENT (@var{mode}) 5292This macro is used to determine whether a store predecrement is a good 5293thing to use for a given mode. Defaults to the value of 5294@code{HAVE_PRE_DECREMENT}. 5295 5296@findex NO_FUNCTION_CSE 5297@item NO_FUNCTION_CSE 5298Define this macro if it is as good or better to call a constant 5299function address than to call an address kept in a register. 5300 5301@findex NO_RECURSIVE_FUNCTION_CSE 5302@item NO_RECURSIVE_FUNCTION_CSE 5303Define this macro if it is as good or better for a function to call 5304itself with an explicit address than to call an address kept in a 5305register. 5306@end table 5307 5308@node Scheduling 5309@section Adjusting the Instruction Scheduler 5310 5311The instruction scheduler may need a fair amount of machine-specific 5312adjustment in order to produce good code. GCC provides several target 5313hooks for this purpose. It is usually enough to define just a few of 5314them: try the first ones in this list first. 5315 5316@deftypefn {Target Hook} int TARGET_SCHED_ISSUE_RATE (void) 5317This hook returns the maximum number of instructions that can ever issue 5318at the same time on the target machine. The default is one. This value 5319must be constant over the entire compilation. If you need it to vary 5320depending on what the instructions are, you must use 5321@samp{TARGET_SCHED_VARIABLE_ISSUE}. 5322@end deftypefn 5323 5324@deftypefn {Target Hook} int TARGET_SCHED_VARIABLE_ISSUE (FILE *@var{file}, int @var{verbose}, rtx @var{insn}, int @var{more}) 5325This hook is executed by the scheduler after it has scheduled an insn 5326from the ready list. It should return the number of insns which can 5327still be issued in the current cycle. Normally this is 5328@samp{@w{@var{more} - 1}}. You should define this hook if some insns 5329take more machine resources than others, so that fewer insns can follow 5330them in the same cycle. @var{file} is either a null pointer, or a stdio 5331stream to write any debug output to. @var{verbose} is the verbose level 5332provided by @option{-fsched-verbose-@var{n}}. @var{insn} is the 5333instruction that was scheduled. 5334@end deftypefn 5335 5336@deftypefn {Target Hook} int TARGET_SCHED_ADJUST_COST (rtx @var{insn}, rtx @var{link}, rtx @var{dep_insn}, int @var{cost}) 5337This function corrects the value of @var{cost} based on the relationship 5338between @var{insn} and @var{dep_insn} through the dependence @var{link}. 5339It should return the new value. The default is to make no adjustment to 5340@var{cost}. This can be used for example to specify to the scheduler 5341that an output- or anti-dependence does not incur the same cost as a 5342data-dependence. 5343@end deftypefn 5344 5345@deftypefn {Target Hook} int TARGET_SCHED_ADJUST_PRIORITY (rtx @var{insn}, int @var{priority}) 5346This hook adjusts the integer scheduling priority @var{priority} of 5347@var{insn}. It should return the new priority. Reduce the priority to 5348execute @var{insn} earlier, increase the priority to execute @var{insn} 5349later. Do not define this hook if you do not need to adjust the 5350scheduling priorities of insns. 5351@end deftypefn 5352 5353@deftypefn {Target Hook} int TARGET_SCHED_REORDER (FILE *@var{file}, int @var{verbose}, rtx *@var{ready}, int *@var{n_readyp}, int @var{clock}) 5354This hook is executed by the scheduler after it has scheduled the ready 5355list, to allow the machine description to reorder it (for example to 5356combine two small instructions together on @samp{VLIW} machines). 5357@var{file} is either a null pointer, or a stdio stream to write any 5358debug output to. @var{verbose} is the verbose level provided by 5359@option{-fsched-verbose-@var{n}}. @var{ready} is a pointer to the ready 5360list of instructions that are ready to be scheduled. @var{n_readyp} is 5361a pointer to the number of elements in the ready list. The scheduler 5362reads the ready list in reverse order, starting with 5363@var{ready}[@var{*n_readyp}-1] and going to @var{ready}[0]. @var{clock} 5364is the timer tick of the scheduler. You may modify the ready list and 5365the number of ready insns. The return value is the number of insns that 5366can issue this cycle; normally this is just @code{issue_rate}. See also 5367@samp{TARGET_SCHED_REORDER2}. 5368@end deftypefn 5369 5370@deftypefn {Target Hook} int TARGET_SCHED_REORDER2 (FILE *@var{file}, int @var{verbose}, rtx *@var{ready}, int *@var{n_ready}, @var{clock}) 5371Like @samp{TARGET_SCHED_REORDER}, but called at a different time. That 5372function is called whenever the scheduler starts a new cycle. This one 5373is called once per iteration over a cycle, immediately after 5374@samp{TARGET_SCHED_VARIABLE_ISSUE}; it can reorder the ready list and 5375return the number of insns to be scheduled in the same cycle. Defining 5376this hook can be useful if there are frequent situations where 5377scheduling one insn causes other insns to become ready in the same 5378cycle. These other insns can then be taken into account properly. 5379@end deftypefn 5380 5381@deftypefn {Target Hook} void TARGET_SCHED_INIT (FILE *@var{file}, int @var{verbose}, int @var{max_ready}) 5382This hook is executed by the scheduler at the beginning of each block of 5383instructions that are to be scheduled. @var{file} is either a null 5384pointer, or a stdio stream to write any debug output to. @var{verbose} 5385is the verbose level provided by @option{-fsched-verbose-@var{n}}. 5386@var{max_ready} is the maximum number of insns in the current scheduling 5387region that can be live at the same time. This can be used to allocate 5388scratch space if it is needed, e.g. by @samp{TARGET_SCHED_REORDER}. 5389@end deftypefn 5390 5391@deftypefn {Target Hook} void TARGET_SCHED_FINISH (FILE *@var{file}, int @var{verbose}) 5392This hook is executed by the scheduler at the end of each block of 5393instructions that are to be scheduled. It can be used to perform 5394cleanup of any actions done by the other scheduling hooks. @var{file} 5395is either a null pointer, or a stdio stream to write any debug output 5396to. @var{verbose} is the verbose level provided by 5397@option{-fsched-verbose-@var{n}}. 5398@end deftypefn 5399 5400@deftypefn {Target Hook} rtx TARGET_SCHED_CYCLE_DISPLAY (int @var{clock}, rtx @var{last}) 5401This hook is called in verbose mode only, at the beginning of each pass 5402over a basic block. It should insert an insn into the chain after 5403@var{last}, which has no effect, but records the value @var{clock} in 5404RTL dumps and assembly output. Define this hook only if you need this 5405level of detail about what the scheduler is doing. 5406@end deftypefn 5407 5408@node Sections 5409@section Dividing the Output into Sections (Texts, Data, @dots{}) 5410@c the above section title is WAY too long. maybe cut the part between 5411@c the (...)? --mew 10feb93 5412 5413An object file is divided into sections containing different types of 5414data. In the most common case, there are three sections: the @dfn{text 5415section}, which holds instructions and read-only data; the @dfn{data 5416section}, which holds initialized writable data; and the @dfn{bss 5417section}, which holds uninitialized data. Some systems have other kinds 5418of sections. 5419 5420The compiler must tell the assembler when to switch sections. These 5421macros control what commands to output to tell the assembler this. You 5422can also define additional sections. 5423 5424@table @code 5425@findex TEXT_SECTION_ASM_OP 5426@item TEXT_SECTION_ASM_OP 5427A C expression whose value is a string, including spacing, containing the 5428assembler operation that should precede instructions and read-only data. 5429Normally @code{"\t.text"} is right. 5430 5431@findex TEXT_SECTION 5432@item TEXT_SECTION 5433A C statement that switches to the default section containing instructions. 5434Normally this is not needed, as simply defining @code{TEXT_SECTION_ASM_OP} 5435is enough. The MIPS port uses this to sort all functions after all data 5436declarations. 5437 5438@findex DATA_SECTION_ASM_OP 5439@item DATA_SECTION_ASM_OP 5440A C expression whose value is a string, including spacing, containing the 5441assembler operation to identify the following data as writable initialized 5442data. Normally @code{"\t.data"} is right. 5443 5444@findex SHARED_SECTION_ASM_OP 5445@item SHARED_SECTION_ASM_OP 5446If defined, a C expression whose value is a string, including spacing, 5447containing the assembler operation to identify the following data as 5448shared data. If not defined, @code{DATA_SECTION_ASM_OP} will be used. 5449 5450@findex BSS_SECTION_ASM_OP 5451@item BSS_SECTION_ASM_OP 5452If defined, a C expression whose value is a string, including spacing, 5453containing the assembler operation to identify the following data as 5454uninitialized global data. If not defined, and neither 5455@code{ASM_OUTPUT_BSS} nor @code{ASM_OUTPUT_ALIGNED_BSS} are defined, 5456uninitialized global data will be output in the data section if 5457@option{-fno-common} is passed, otherwise @code{ASM_OUTPUT_COMMON} will be 5458used. 5459 5460@findex SHARED_BSS_SECTION_ASM_OP 5461@item SHARED_BSS_SECTION_ASM_OP 5462If defined, a C expression whose value is a string, including spacing, 5463containing the assembler operation to identify the following data as 5464uninitialized global shared data. If not defined, and 5465@code{BSS_SECTION_ASM_OP} is, the latter will be used. 5466 5467@findex INIT_SECTION_ASM_OP 5468@item INIT_SECTION_ASM_OP 5469If defined, a C expression whose value is a string, including spacing, 5470containing the assembler operation to identify the following data as 5471initialization code. If not defined, GCC will assume such a section does 5472not exist. 5473 5474@findex FINI_SECTION_ASM_OP 5475@item FINI_SECTION_ASM_OP 5476If defined, a C expression whose value is a string, including spacing, 5477containing the assembler operation to identify the following data as 5478finalization code. If not defined, GCC will assume such a section does 5479not exist. 5480 5481@findex CRT_CALL_STATIC_FUNCTION 5482@item CRT_CALL_STATIC_FUNCTION (@var{section_op}, @var{function}) 5483If defined, an ASM statement that switches to a different section 5484via @var{section_op}, calls @var{function}, and switches back to 5485the text section. This is used in @file{crtstuff.c} if 5486@code{INIT_SECTION_ASM_OP} or @code{FINI_SECTION_ASM_OP} to calls 5487to initialization and finalization functions from the init and fini 5488sections. By default, this macro uses a simple function call. Some 5489ports need hand-crafted assembly code to avoid dependencies on 5490registers initialized in the function prologue or to ensure that 5491constant pools don't end up too far way in the text section. 5492 5493@findex FORCE_CODE_SECTION_ALIGN 5494@item FORCE_CODE_SECTION_ALIGN 5495If defined, an ASM statement that aligns a code section to some 5496arbitrary boundary. This is used to force all fragments of the 5497@code{.init} and @code{.fini} sections to have to same alignment 5498and thus prevent the linker from having to add any padding. 5499 5500@findex EXTRA_SECTIONS 5501@findex in_text 5502@findex in_data 5503@item EXTRA_SECTIONS 5504A list of names for sections other than the standard two, which are 5505@code{in_text} and @code{in_data}. You need not define this macro 5506on a system with no other sections (that GCC needs to use). 5507 5508@findex EXTRA_SECTION_FUNCTIONS 5509@findex text_section 5510@findex data_section 5511@item EXTRA_SECTION_FUNCTIONS 5512One or more functions to be defined in @file{varasm.c}. These 5513functions should do jobs analogous to those of @code{text_section} and 5514@code{data_section}, for your additional sections. Do not define this 5515macro if you do not define @code{EXTRA_SECTIONS}. 5516 5517@findex READONLY_DATA_SECTION 5518@item READONLY_DATA_SECTION 5519On most machines, read-only variables, constants, and jump tables are 5520placed in the text section. If this is not the case on your machine, 5521this macro should be defined to be the name of a function (either 5522@code{data_section} or a function defined in @code{EXTRA_SECTIONS}) that 5523switches to the section to be used for read-only items. 5524 5525If these items should be placed in the text section, this macro should 5526not be defined. 5527 5528@findex SELECT_SECTION 5529@item SELECT_SECTION (@var{exp}, @var{reloc}, @var{align}) 5530A C statement or statements to switch to the appropriate section for 5531output of @var{exp}. You can assume that @var{exp} is either a 5532@code{VAR_DECL} node or a constant of some sort. @var{reloc} 5533indicates whether the initial value of @var{exp} requires link-time 5534relocations. Bit 1 is set when variable contains local relocations 5535only, while bit 2 is set for global relocations. 5536Select the section by calling @code{text_section} or one 5537of the alternatives for other sections. @var{align} is the constant 5538alignment in bits. 5539 5540Do not define this macro if you put all read-only variables and 5541constants in the read-only data section (usually the text section). 5542 5543@findex SELECT_RTX_SECTION 5544@item SELECT_RTX_SECTION (@var{mode}, @var{rtx}, @var{align}) 5545A C statement or statements to switch to the appropriate section for 5546output of @var{rtx} in mode @var{mode}. You can assume that @var{rtx} 5547is some kind of constant in RTL@. The argument @var{mode} is redundant 5548except in the case of a @code{const_int} rtx. Select the section by 5549calling @code{text_section} or one of the alternatives for other 5550sections. @var{align} is the constant alignment in bits. 5551 5552Do not define this macro if you put all constants in the read-only 5553data section. 5554 5555@findex JUMP_TABLES_IN_TEXT_SECTION 5556@item JUMP_TABLES_IN_TEXT_SECTION 5557Define this macro to be an expression with a nonzero value if jump 5558tables (for @code{tablejump} insns) should be output in the text 5559section, along with the assembler instructions. Otherwise, the 5560readonly data section is used. 5561 5562This macro is irrelevant if there is no separate readonly data section. 5563 5564@findex ENCODE_SECTION_INFO 5565@item ENCODE_SECTION_INFO (@var{decl}) 5566Define this macro if references to a symbol or a constant must be 5567treated differently depending on something about the variable or 5568function named by the symbol (such as what section it is in). 5569 5570The macro definition, if any, is executed under two circumstances. One 5571is immediately after the rtl for @var{decl} that represents a variable 5572or a function has been created and stored in @code{DECL_RTL 5573(@var{decl})}. The value of the rtl will be a @code{mem} whose address 5574is a @code{symbol_ref}. The other is immediately after the rtl for 5575@var{decl} that represents a constant has been created and stored in 5576@code{TREE_CST_RTL (@var{decl})}. The macro is called once for each 5577distinct constant in a source file. 5578 5579@cindex @code{SYMBOL_REF_FLAG}, in @code{ENCODE_SECTION_INFO} 5580The usual thing for this macro to do is to record a flag in the 5581@code{symbol_ref} (such as @code{SYMBOL_REF_FLAG}) or to store a 5582modified name string in the @code{symbol_ref} (if one bit is not enough 5583information). 5584 5585@findex STRIP_NAME_ENCODING 5586@item STRIP_NAME_ENCODING (@var{var}, @var{sym_name}) 5587Decode @var{sym_name} and store the real name part in @var{var}, sans 5588the characters that encode section info. Define this macro if 5589@code{ENCODE_SECTION_INFO} alters the symbol's name string. 5590 5591@findex UNIQUE_SECTION 5592@item UNIQUE_SECTION (@var{decl}, @var{reloc}) 5593A C statement to build up a unique section name, expressed as a 5594@code{STRING_CST} node, and assign it to @samp{DECL_SECTION_NAME (@var{decl})}. 5595@var{reloc} indicates whether the initial value of @var{exp} requires 5596link-time relocations. If you do not define this macro, GCC will use 5597the symbol name prefixed by @samp{.} as the section name. Note - this 5598macro can now be called for uninitialized data items as well as 5599initialized data and functions. 5600@end table 5601 5602@node PIC 5603@section Position Independent Code 5604@cindex position independent code 5605@cindex PIC 5606 5607This section describes macros that help implement generation of position 5608independent code. Simply defining these macros is not enough to 5609generate valid PIC; you must also add support to the macros 5610@code{GO_IF_LEGITIMATE_ADDRESS} and @code{PRINT_OPERAND_ADDRESS}, as 5611well as @code{LEGITIMIZE_ADDRESS}. You must modify the definition of 5612@samp{movsi} to do something appropriate when the source operand 5613contains a symbolic address. You may also need to alter the handling of 5614switch statements so that they use relative addresses. 5615@c i rearranged the order of the macros above to try to force one of 5616@c them to the next line, to eliminate an overfull hbox. --mew 10feb93 5617 5618@table @code 5619@findex PIC_OFFSET_TABLE_REGNUM 5620@item PIC_OFFSET_TABLE_REGNUM 5621The register number of the register used to address a table of static 5622data addresses in memory. In some cases this register is defined by a 5623processor's ``application binary interface'' (ABI)@. When this macro 5624is defined, RTL is generated for this register once, as with the stack 5625pointer and frame pointer registers. If this macro is not defined, it 5626is up to the machine-dependent files to allocate such a register (if 5627necessary). Note that this register must be fixed when in use (e.g.@: 5628when @code{flag_pic} is true). 5629 5630@findex PIC_OFFSET_TABLE_REG_CALL_CLOBBERED 5631@item PIC_OFFSET_TABLE_REG_CALL_CLOBBERED 5632Define this macro if the register defined by 5633@code{PIC_OFFSET_TABLE_REGNUM} is clobbered by calls. Do not define 5634this macro if @code{PIC_OFFSET_TABLE_REGNUM} is not defined. 5635 5636@findex FINALIZE_PIC 5637@item FINALIZE_PIC 5638By generating position-independent code, when two different programs (A 5639and B) share a common library (libC.a), the text of the library can be 5640shared whether or not the library is linked at the same address for both 5641programs. In some of these environments, position-independent code 5642requires not only the use of different addressing modes, but also 5643special code to enable the use of these addressing modes. 5644 5645The @code{FINALIZE_PIC} macro serves as a hook to emit these special 5646codes once the function is being compiled into assembly code, but not 5647before. (It is not done before, because in the case of compiling an 5648inline function, it would lead to multiple PIC prologues being 5649included in functions which used inline functions and were compiled to 5650assembly language.) 5651 5652@findex LEGITIMATE_PIC_OPERAND_P 5653@item LEGITIMATE_PIC_OPERAND_P (@var{x}) 5654A C expression that is nonzero if @var{x} is a legitimate immediate 5655operand on the target machine when generating position independent code. 5656You can assume that @var{x} satisfies @code{CONSTANT_P}, so you need not 5657check this. You can also assume @var{flag_pic} is true, so you need not 5658check it either. You need not define this macro if all constants 5659(including @code{SYMBOL_REF}) can be immediate operands when generating 5660position independent code. 5661@end table 5662 5663@node Assembler Format 5664@section Defining the Output Assembler Language 5665 5666This section describes macros whose principal purpose is to describe how 5667to write instructions in assembler language---rather than what the 5668instructions do. 5669 5670@menu 5671* File Framework:: Structural information for the assembler file. 5672* Data Output:: Output of constants (numbers, strings, addresses). 5673* Uninitialized Data:: Output of uninitialized variables. 5674* Label Output:: Output and generation of labels. 5675* Initialization:: General principles of initialization 5676 and termination routines. 5677* Macros for Initialization:: 5678 Specific macros that control the handling of 5679 initialization and termination routines. 5680* Instruction Output:: Output of actual instructions. 5681* Dispatch Tables:: Output of jump tables. 5682* Exception Region Output:: Output of exception region code. 5683* Alignment Output:: Pseudo ops for alignment and skipping data. 5684@end menu 5685 5686@node File Framework 5687@subsection The Overall Framework of an Assembler File 5688@cindex assembler format 5689@cindex output of assembler code 5690 5691@c prevent bad page break with this line 5692This describes the overall framework of an assembler file. 5693 5694@table @code 5695@findex ASM_FILE_START 5696@item ASM_FILE_START (@var{stream}) 5697A C expression which outputs to the stdio stream @var{stream} 5698some appropriate text to go at the start of an assembler file. 5699 5700Normally this macro is defined to output a line containing 5701@samp{#NO_APP}, which is a comment that has no effect on most 5702assemblers but tells the GNU assembler that it can save time by not 5703checking for certain assembler constructs. 5704 5705On systems that use SDB, it is necessary to output certain commands; 5706see @file{attasm.h}. 5707 5708@findex ASM_FILE_END 5709@item ASM_FILE_END (@var{stream}) 5710A C expression which outputs to the stdio stream @var{stream} 5711some appropriate text to go at the end of an assembler file. 5712 5713If this macro is not defined, the default is to output nothing 5714special at the end of the file. Most systems don't require any 5715definition. 5716 5717On systems that use SDB, it is necessary to output certain commands; 5718see @file{attasm.h}. 5719 5720@findex ASM_COMMENT_START 5721@item ASM_COMMENT_START 5722A C string constant describing how to begin a comment in the target 5723assembler language. The compiler assumes that the comment will end at 5724the end of the line. 5725 5726@findex ASM_APP_ON 5727@item ASM_APP_ON 5728A C string constant for text to be output before each @code{asm} 5729statement or group of consecutive ones. Normally this is 5730@code{"#APP"}, which is a comment that has no effect on most 5731assemblers but tells the GNU assembler that it must check the lines 5732that follow for all valid assembler constructs. 5733 5734@findex ASM_APP_OFF 5735@item ASM_APP_OFF 5736A C string constant for text to be output after each @code{asm} 5737statement or group of consecutive ones. Normally this is 5738@code{"#NO_APP"}, which tells the GNU assembler to resume making the 5739time-saving assumptions that are valid for ordinary compiler output. 5740 5741@findex ASM_OUTPUT_SOURCE_FILENAME 5742@item ASM_OUTPUT_SOURCE_FILENAME (@var{stream}, @var{name}) 5743A C statement to output COFF information or DWARF debugging information 5744which indicates that filename @var{name} is the current source file to 5745the stdio stream @var{stream}. 5746 5747This macro need not be defined if the standard form of output 5748for the file format in use is appropriate. 5749 5750@findex OUTPUT_QUOTED_STRING 5751@item OUTPUT_QUOTED_STRING (@var{stream}, @var{string}) 5752A C statement to output the string @var{string} to the stdio stream 5753@var{stream}. If you do not call the function @code{output_quoted_string} 5754in your config files, GCC will only call it to output filenames to 5755the assembler source. So you can use it to canonicalize the format 5756of the filename using this macro. 5757 5758@findex ASM_OUTPUT_SOURCE_LINE 5759@item ASM_OUTPUT_SOURCE_LINE (@var{stream}, @var{line}) 5760A C statement to output DBX or SDB debugging information before code 5761for line number @var{line} of the current source file to the 5762stdio stream @var{stream}. 5763 5764This macro need not be defined if the standard form of debugging 5765information for the debugger in use is appropriate. 5766 5767@findex ASM_OUTPUT_IDENT 5768@item ASM_OUTPUT_IDENT (@var{stream}, @var{string}) 5769A C statement to output something to the assembler file to handle a 5770@samp{#ident} directive containing the text @var{string}. If this 5771macro is not defined, nothing is output for a @samp{#ident} directive. 5772 5773@findex OBJC_PROLOGUE 5774@item OBJC_PROLOGUE 5775A C statement to output any assembler statements which are required to 5776precede any Objective-C object definitions or message sending. The 5777statement is executed only when compiling an Objective-C program. 5778@end table 5779 5780@deftypefn {Target Hook} void TARGET_ASM_NAMED_SECTION (const char *@var{name}, unsigned int @var{flags}, unsigned int @var{align}) 5781Output assembly directives to switch to section @var{name}. The section 5782should have attributes as specified by @var{flags}, which is a bit mask 5783of the @code{SECTION_*} flags defined in @file{output.h}. If @var{align} 5784is nonzero, it contains an alignment in bytes to be used for the section, 5785otherwise some target default should be used. Only targets that must 5786specify an alignment within the section directive need pay attention to 5787@var{align} -- we will still use @code{ASM_OUTPUT_ALIGN}. 5788@end deftypefn 5789 5790@deftypefn {Target Hook} bool TARGET_HAVE_NAMED_SECTIONS 5791This flag is true if the target supports @code{TARGET_ASM_NAMED_SECTION}. 5792@end deftypefn 5793 5794@deftypefn {Target Hook} {unsigned int} TARGET_SECTION_TYPE_FLAGS (tree @var{decl}, const char *@var{name}, int @var{reloc}) 5795Choose a set of section attributes for use by @code{TARGET_ASM_NAMED_SECTION} 5796based on a variable or function decl, a section name, and whether or not the 5797declaration's initializer may contain runtime relocations. @var{decl} may be 5798 null, in which case read-write data should be assumed. 5799 5800The default version if this function handles choosing code vs data, 5801read-only vs read-write data, and @code{flag_pic}. You should only 5802need to override this if your target has special flags that might be 5803set via @code{__attribute__}. 5804@end deftypefn 5805 5806@need 2000 5807@node Data Output 5808@subsection Output of Data 5809 5810 5811@deftypevr {Target Hook} {const char *} TARGET_ASM_BYTE_OP 5812@deftypevrx {Target Hook} {const char *} TARGET_ASM_ALIGNED_HI_OP 5813@deftypevrx {Target Hook} {const char *} TARGET_ASM_ALIGNED_SI_OP 5814@deftypevrx {Target Hook} {const char *} TARGET_ASM_ALIGNED_DI_OP 5815@deftypevrx {Target Hook} {const char *} TARGET_ASM_ALIGNED_TI_OP 5816@deftypevrx {Target Hook} {const char *} TARGET_ASM_UNALIGNED_HI_OP 5817@deftypevrx {Target Hook} {const char *} TARGET_ASM_UNALIGNED_SI_OP 5818@deftypevrx {Target Hook} {const char *} TARGET_ASM_UNALIGNED_DI_OP 5819@deftypevrx {Target Hook} {const char *} TARGET_ASM_UNALIGNED_TI_OP 5820These hooks specify assembly directives for creating certain kinds 5821of integer object. The @code{TARGET_ASM_BYTE_OP} directive creates a 5822byte-sized object, the @code{TARGET_ASM_ALIGNED_HI_OP} one creates an 5823aligned two-byte object, and so on. Any of the hooks may be 5824@code{NULL}, indicating that no suitable directive is available. 5825 5826The compiler will print these strings at the start of a new line, 5827followed immediately by the object's initial value. In most cases, 5828the string should contain a tab, a pseudo-op, and then another tab. 5829@end deftypevr 5830 5831@deftypefn {Target Hook} bool TARGET_ASM_INTEGER (rtx @var{x}, unsigned int @var{size}, int @var{aligned_p}) 5832The @code{assemble_integer} function uses this hook to output an 5833integer object. @var{x} is the object's value, @var{size} is its size 5834in bytes and @var{aligned_p} indicates whether it is aligned. The 5835function should return @code{true} if it was able to output the 5836object. If it returns false, @code{assemble_integer} will try to 5837split the object into smaller parts. 5838 5839The default implementation of this hook will use the 5840@code{TARGET_ASM_BYTE_OP} family of strings, returning @code{false} 5841when the relevant string is @code{NULL}. 5842@end deftypefn 5843 5844@table @code 5845@findex OUTPUT_ADDR_CONST_EXTRA 5846@item OUTPUT_ADDR_CONST_EXTRA (@var{stream}, @var{x}, @var{fail}) 5847A C statement to recognize @var{rtx} patterns that 5848@code{output_addr_const} can't deal with, and output assembly code to 5849@var{stream} corresponding to the pattern @var{x}. This may be used to 5850allow machine-dependent @code{UNSPEC}s to appear within constants. 5851 5852If @code{OUTPUT_ADDR_CONST_EXTRA} fails to recognize a pattern, it must 5853@code{goto fail}, so that a standard error message is printed. If it 5854prints an error message itself, by calling, for example, 5855@code{output_operand_lossage}, it may just complete normally. 5856 5857@findex ASM_OUTPUT_ASCII 5858@item ASM_OUTPUT_ASCII (@var{stream}, @var{ptr}, @var{len}) 5859A C statement to output to the stdio stream @var{stream} an assembler 5860instruction to assemble a string constant containing the @var{len} 5861bytes at @var{ptr}. @var{ptr} will be a C expression of type 5862@code{char *} and @var{len} a C expression of type @code{int}. 5863 5864If the assembler has a @code{.ascii} pseudo-op as found in the 5865Berkeley Unix assembler, do not define the macro 5866@code{ASM_OUTPUT_ASCII}. 5867 5868@findex ASM_OUTPUT_FDESC 5869@item ASM_OUTPUT_FDESC (@var{stream}, @var{decl}, @var{n}) 5870A C statement to output word @var{n} of a function descriptor for 5871@var{decl}. This must be defined if @code{TARGET_VTABLE_USES_DESCRIPTORS} 5872is defined, and is otherwise unused. 5873 5874@findex CONSTANT_POOL_BEFORE_FUNCTION 5875@item CONSTANT_POOL_BEFORE_FUNCTION 5876You may define this macro as a C expression. You should define the 5877expression to have a nonzero value if GCC should output the constant 5878pool for a function before the code for the function, or a zero value if 5879GCC should output the constant pool after the function. If you do 5880not define this macro, the usual case, GCC will output the constant 5881pool before the function. 5882 5883@findex ASM_OUTPUT_POOL_PROLOGUE 5884@item ASM_OUTPUT_POOL_PROLOGUE (@var{file}, @var{funname}, @var{fundecl}, @var{size}) 5885A C statement to output assembler commands to define the start of the 5886constant pool for a function. @var{funname} is a string giving 5887the name of the function. Should the return type of the function 5888be required, it can be obtained via @var{fundecl}. @var{size} 5889is the size, in bytes, of the constant pool that will be written 5890immediately after this call. 5891 5892If no constant-pool prefix is required, the usual case, this macro need 5893not be defined. 5894 5895@findex ASM_OUTPUT_SPECIAL_POOL_ENTRY 5896@item ASM_OUTPUT_SPECIAL_POOL_ENTRY (@var{file}, @var{x}, @var{mode}, @var{align}, @var{labelno}, @var{jumpto}) 5897A C statement (with or without semicolon) to output a constant in the 5898constant pool, if it needs special treatment. (This macro need not do 5899anything for RTL expressions that can be output normally.) 5900 5901The argument @var{file} is the standard I/O stream to output the 5902assembler code on. @var{x} is the RTL expression for the constant to 5903output, and @var{mode} is the machine mode (in case @var{x} is a 5904@samp{const_int}). @var{align} is the required alignment for the value 5905@var{x}; you should output an assembler directive to force this much 5906alignment. 5907 5908The argument @var{labelno} is a number to use in an internal label for 5909the address of this pool entry. The definition of this macro is 5910responsible for outputting the label definition at the proper place. 5911Here is how to do this: 5912 5913@example 5914ASM_OUTPUT_INTERNAL_LABEL (@var{file}, "LC", @var{labelno}); 5915@end example 5916 5917When you output a pool entry specially, you should end with a 5918@code{goto} to the label @var{jumpto}. This will prevent the same pool 5919entry from being output a second time in the usual manner. 5920 5921You need not define this macro if it would do nothing. 5922 5923@findex CONSTANT_AFTER_FUNCTION_P 5924@item CONSTANT_AFTER_FUNCTION_P (@var{exp}) 5925Define this macro as a C expression which is nonzero if the constant 5926@var{exp}, of type @code{tree}, should be output after the code for a 5927function. The compiler will normally output all constants before the 5928function; you need not define this macro if this is OK@. 5929 5930@findex ASM_OUTPUT_POOL_EPILOGUE 5931@item ASM_OUTPUT_POOL_EPILOGUE (@var{file} @var{funname} @var{fundecl} @var{size}) 5932A C statement to output assembler commands to at the end of the constant 5933pool for a function. @var{funname} is a string giving the name of the 5934function. Should the return type of the function be required, you can 5935obtain it via @var{fundecl}. @var{size} is the size, in bytes, of the 5936constant pool that GCC wrote immediately before this call. 5937 5938If no constant-pool epilogue is required, the usual case, you need not 5939define this macro. 5940 5941@findex IS_ASM_LOGICAL_LINE_SEPARATOR 5942@item IS_ASM_LOGICAL_LINE_SEPARATOR (@var{C}) 5943Define this macro as a C expression which is nonzero if @var{C} is 5944used as a logical line separator by the assembler. 5945 5946If you do not define this macro, the default is that only 5947the character @samp{;} is treated as a logical line separator. 5948@end table 5949 5950@deftypevr {Target Hook} {const char *} TARGET_ASM_OPEN_PAREN 5951@deftypevrx {Target Hook} {const char *} TARGET_ASM_CLOSE_PAREN 5952These target hooks are C string constants, describing the syntax in the 5953assembler for grouping arithmetic expressions. If not overridden, they 5954default to normal parentheses, which is correct for most assemblers. 5955@end deftypevr 5956 5957 These macros are provided by @file{real.h} for writing the definitions 5958of @code{ASM_OUTPUT_DOUBLE} and the like: 5959 5960@table @code 5961@item REAL_VALUE_TO_TARGET_SINGLE (@var{x}, @var{l}) 5962@itemx REAL_VALUE_TO_TARGET_DOUBLE (@var{x}, @var{l}) 5963@itemx REAL_VALUE_TO_TARGET_LONG_DOUBLE (@var{x}, @var{l}) 5964@findex REAL_VALUE_TO_TARGET_SINGLE 5965@findex REAL_VALUE_TO_TARGET_DOUBLE 5966@findex REAL_VALUE_TO_TARGET_LONG_DOUBLE 5967These translate @var{x}, of type @code{REAL_VALUE_TYPE}, to the target's 5968floating point representation, and store its bit pattern in the array of 5969@code{long int} whose address is @var{l}. The number of elements in the 5970output array is determined by the size of the desired target floating 5971point data type: 32 bits of it go in each @code{long int} array 5972element. Each array element holds 32 bits of the result, even if 5973@code{long int} is wider than 32 bits on the host machine. 5974 5975The array element values are designed so that you can print them out 5976using @code{fprintf} in the order they should appear in the target 5977machine's memory. 5978 5979@item REAL_VALUE_TO_DECIMAL (@var{x}, @var{format}, @var{string}) 5980@findex REAL_VALUE_TO_DECIMAL 5981This macro converts @var{x}, of type @code{REAL_VALUE_TYPE}, to a 5982decimal number and stores it as a string into @var{string}. 5983You must pass, as @var{string}, the address of a long enough block 5984of space to hold the result. 5985 5986The argument @var{format} is a @code{printf}-specification that serves 5987as a suggestion for how to format the output string. 5988@end table 5989 5990@node Uninitialized Data 5991@subsection Output of Uninitialized Variables 5992 5993Each of the macros in this section is used to do the whole job of 5994outputting a single uninitialized variable. 5995 5996@table @code 5997@findex ASM_OUTPUT_COMMON 5998@item ASM_OUTPUT_COMMON (@var{stream}, @var{name}, @var{size}, @var{rounded}) 5999A C statement (sans semicolon) to output to the stdio stream 6000@var{stream} the assembler definition of a common-label named 6001@var{name} whose size is @var{size} bytes. The variable @var{rounded} 6002is the size rounded up to whatever alignment the caller wants. 6003 6004Use the expression @code{assemble_name (@var{stream}, @var{name})} to 6005output the name itself; before and after that, output the additional 6006assembler syntax for defining the name, and a newline. 6007 6008This macro controls how the assembler definitions of uninitialized 6009common global variables are output. 6010 6011@findex ASM_OUTPUT_ALIGNED_COMMON 6012@item ASM_OUTPUT_ALIGNED_COMMON (@var{stream}, @var{name}, @var{size}, @var{alignment}) 6013Like @code{ASM_OUTPUT_COMMON} except takes the required alignment as a 6014separate, explicit argument. If you define this macro, it is used in 6015place of @code{ASM_OUTPUT_COMMON}, and gives you more flexibility in 6016handling the required alignment of the variable. The alignment is specified 6017as the number of bits. 6018 6019@findex ASM_OUTPUT_ALIGNED_DECL_COMMON 6020@item ASM_OUTPUT_ALIGNED_DECL_COMMON (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{alignment}) 6021Like @code{ASM_OUTPUT_ALIGNED_COMMON} except that @var{decl} of the 6022variable to be output, if there is one, or @code{NULL_TREE} if there 6023is no corresponding variable. If you define this macro, GCC will use it 6024in place of both @code{ASM_OUTPUT_COMMON} and 6025@code{ASM_OUTPUT_ALIGNED_COMMON}. Define this macro when you need to see 6026the variable's decl in order to chose what to output. 6027 6028@findex ASM_OUTPUT_SHARED_COMMON 6029@item ASM_OUTPUT_SHARED_COMMON (@var{stream}, @var{name}, @var{size}, @var{rounded}) 6030If defined, it is similar to @code{ASM_OUTPUT_COMMON}, except that it 6031is used when @var{name} is shared. If not defined, @code{ASM_OUTPUT_COMMON} 6032will be used. 6033 6034@findex ASM_OUTPUT_BSS 6035@item ASM_OUTPUT_BSS (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{rounded}) 6036A C statement (sans semicolon) to output to the stdio stream 6037@var{stream} the assembler definition of uninitialized global @var{decl} named 6038@var{name} whose size is @var{size} bytes. The variable @var{rounded} 6039is the size rounded up to whatever alignment the caller wants. 6040 6041Try to use function @code{asm_output_bss} defined in @file{varasm.c} when 6042defining this macro. If unable, use the expression 6043@code{assemble_name (@var{stream}, @var{name})} to output the name itself; 6044before and after that, output the additional assembler syntax for defining 6045the name, and a newline. 6046 6047This macro controls how the assembler definitions of uninitialized global 6048variables are output. This macro exists to properly support languages like 6049C++ which do not have @code{common} data. However, this macro currently 6050is not defined for all targets. If this macro and 6051@code{ASM_OUTPUT_ALIGNED_BSS} are not defined then @code{ASM_OUTPUT_COMMON} 6052or @code{ASM_OUTPUT_ALIGNED_COMMON} or 6053@code{ASM_OUTPUT_ALIGNED_DECL_COMMON} is used. 6054 6055@findex ASM_OUTPUT_ALIGNED_BSS 6056@item ASM_OUTPUT_ALIGNED_BSS (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{alignment}) 6057Like @code{ASM_OUTPUT_BSS} except takes the required alignment as a 6058separate, explicit argument. If you define this macro, it is used in 6059place of @code{ASM_OUTPUT_BSS}, and gives you more flexibility in 6060handling the required alignment of the variable. The alignment is specified 6061as the number of bits. 6062 6063Try to use function @code{asm_output_aligned_bss} defined in file 6064@file{varasm.c} when defining this macro. 6065 6066@findex ASM_OUTPUT_SHARED_BSS 6067@item ASM_OUTPUT_SHARED_BSS (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{rounded}) 6068If defined, it is similar to @code{ASM_OUTPUT_BSS}, except that it 6069is used when @var{name} is shared. If not defined, @code{ASM_OUTPUT_BSS} 6070will be used. 6071 6072@findex ASM_OUTPUT_LOCAL 6073@item ASM_OUTPUT_LOCAL (@var{stream}, @var{name}, @var{size}, @var{rounded}) 6074A C statement (sans semicolon) to output to the stdio stream 6075@var{stream} the assembler definition of a local-common-label named 6076@var{name} whose size is @var{size} bytes. The variable @var{rounded} 6077is the size rounded up to whatever alignment the caller wants. 6078 6079Use the expression @code{assemble_name (@var{stream}, @var{name})} to 6080output the name itself; before and after that, output the additional 6081assembler syntax for defining the name, and a newline. 6082 6083This macro controls how the assembler definitions of uninitialized 6084static variables are output. 6085 6086@findex ASM_OUTPUT_ALIGNED_LOCAL 6087@item ASM_OUTPUT_ALIGNED_LOCAL (@var{stream}, @var{name}, @var{size}, @var{alignment}) 6088Like @code{ASM_OUTPUT_LOCAL} except takes the required alignment as a 6089separate, explicit argument. If you define this macro, it is used in 6090place of @code{ASM_OUTPUT_LOCAL}, and gives you more flexibility in 6091handling the required alignment of the variable. The alignment is specified 6092as the number of bits. 6093 6094@findex ASM_OUTPUT_ALIGNED_DECL_LOCAL 6095@item ASM_OUTPUT_ALIGNED_DECL_LOCAL (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{alignment}) 6096Like @code{ASM_OUTPUT_ALIGNED_DECL} except that @var{decl} of the 6097variable to be output, if there is one, or @code{NULL_TREE} if there 6098is no corresponding variable. If you define this macro, GCC will use it 6099in place of both @code{ASM_OUTPUT_DECL} and 6100@code{ASM_OUTPUT_ALIGNED_DECL}. Define this macro when you need to see 6101the variable's decl in order to chose what to output. 6102 6103@findex ASM_OUTPUT_SHARED_LOCAL 6104@item ASM_OUTPUT_SHARED_LOCAL (@var{stream}, @var{name}, @var{size}, @var{rounded}) 6105If defined, it is similar to @code{ASM_OUTPUT_LOCAL}, except that it 6106is used when @var{name} is shared. If not defined, @code{ASM_OUTPUT_LOCAL} 6107will be used. 6108@end table 6109 6110@node Label Output 6111@subsection Output and Generation of Labels 6112 6113@c prevent bad page break with this line 6114This is about outputting labels. 6115 6116@table @code 6117@findex ASM_OUTPUT_LABEL 6118@findex assemble_name 6119@item ASM_OUTPUT_LABEL (@var{stream}, @var{name}) 6120A C statement (sans semicolon) to output to the stdio stream 6121@var{stream} the assembler definition of a label named @var{name}. 6122Use the expression @code{assemble_name (@var{stream}, @var{name})} to 6123output the name itself; before and after that, output the additional 6124assembler syntax for defining the name, and a newline. 6125 6126@findex ASM_DECLARE_FUNCTION_NAME 6127@item ASM_DECLARE_FUNCTION_NAME (@var{stream}, @var{name}, @var{decl}) 6128A C statement (sans semicolon) to output to the stdio stream 6129@var{stream} any text necessary for declaring the name @var{name} of a 6130function which is being defined. This macro is responsible for 6131outputting the label definition (perhaps using 6132@code{ASM_OUTPUT_LABEL}). The argument @var{decl} is the 6133@code{FUNCTION_DECL} tree node representing the function. 6134 6135If this macro is not defined, then the function name is defined in the 6136usual manner as a label (by means of @code{ASM_OUTPUT_LABEL}). 6137 6138@findex ASM_DECLARE_FUNCTION_SIZE 6139@item ASM_DECLARE_FUNCTION_SIZE (@var{stream}, @var{name}, @var{decl}) 6140A C statement (sans semicolon) to output to the stdio stream 6141@var{stream} any text necessary for declaring the size of a function 6142which is being defined. The argument @var{name} is the name of the 6143function. The argument @var{decl} is the @code{FUNCTION_DECL} tree node 6144representing the function. 6145 6146If this macro is not defined, then the function size is not defined. 6147 6148@findex ASM_DECLARE_OBJECT_NAME 6149@item ASM_DECLARE_OBJECT_NAME (@var{stream}, @var{name}, @var{decl}) 6150A C statement (sans semicolon) to output to the stdio stream 6151@var{stream} any text necessary for declaring the name @var{name} of an 6152initialized variable which is being defined. This macro must output the 6153label definition (perhaps using @code{ASM_OUTPUT_LABEL}). The argument 6154@var{decl} is the @code{VAR_DECL} tree node representing the variable. 6155 6156If this macro is not defined, then the variable name is defined in the 6157usual manner as a label (by means of @code{ASM_OUTPUT_LABEL}). 6158 6159@findex ASM_DECLARE_REGISTER_GLOBAL 6160@item ASM_DECLARE_REGISTER_GLOBAL (@var{stream}, @var{decl}, @var{regno}, @var{name}) 6161A C statement (sans semicolon) to output to the stdio stream 6162@var{stream} any text necessary for claiming a register @var{regno} 6163for a global variable @var{decl} with name @var{name}. 6164 6165If you don't define this macro, that is equivalent to defining it to do 6166nothing. 6167 6168@findex ASM_FINISH_DECLARE_OBJECT 6169@item ASM_FINISH_DECLARE_OBJECT (@var{stream}, @var{decl}, @var{toplevel}, @var{atend}) 6170A C statement (sans semicolon) to finish up declaring a variable name 6171once the compiler has processed its initializer fully and thus has had a 6172chance to determine the size of an array when controlled by an 6173initializer. This is used on systems where it's necessary to declare 6174something about the size of the object. 6175 6176If you don't define this macro, that is equivalent to defining it to do 6177nothing. 6178 6179@findex ASM_GLOBALIZE_LABEL 6180@item ASM_GLOBALIZE_LABEL (@var{stream}, @var{name}) 6181A C statement (sans semicolon) to output to the stdio stream 6182@var{stream} some commands that will make the label @var{name} global; 6183that is, available for reference from other files. Use the expression 6184@code{assemble_name (@var{stream}, @var{name})} to output the name 6185itself; before and after that, output the additional assembler syntax 6186for making that name global, and a newline. 6187 6188@findex ASM_WEAKEN_LABEL 6189@item ASM_WEAKEN_LABEL (@var{stream}, @var{name}) 6190A C statement (sans semicolon) to output to the stdio stream 6191@var{stream} some commands that will make the label @var{name} weak; 6192that is, available for reference from other files but only used if 6193no other definition is available. Use the expression 6194@code{assemble_name (@var{stream}, @var{name})} to output the name 6195itself; before and after that, output the additional assembler syntax 6196for making that name weak, and a newline. 6197 6198If you don't define this macro or @code{ASM_WEAKEN_DECL}, GCC will not 6199support weak symbols and you should not define the @code{SUPPORTS_WEAK} 6200macro. 6201 6202@findex ASM_WEAKEN_DECL 6203@item ASM_WEAKEN_DECL (@var{stream}, @var{decl}, @var{name}, @var{value}) 6204Combines (and replaces) the function of @code{ASM_WEAKEN_LABEL} and 6205@code{ASM_OUTPUT_WEAK_ALIAS}, allowing access to the associated function 6206or variable decl. If @var{value} is not @code{NULL}, this C statement 6207should output to the stdio stream @var{stream} assembler code which 6208defines (equates) the weak symbol @var{name} to have the value 6209@var{value}. If @var{value} is @code{NULL}, it should output commands 6210to make @var{name} weak. 6211 6212@findex SUPPORTS_WEAK 6213@item SUPPORTS_WEAK 6214A C expression which evaluates to true if the target supports weak symbols. 6215 6216If you don't define this macro, @file{defaults.h} provides a default 6217definition. If either @code{ASM_WEAKEN_LABEL} or @code{ASM_WEAKEN_DECL} 6218is defined, the default definition is @samp{1}; otherwise, it is 6219@samp{0}. Define this macro if you want to control weak symbol support 6220with a compiler flag such as @option{-melf}. 6221 6222@findex MAKE_DECL_ONE_ONLY (@var{decl}) 6223@item MAKE_DECL_ONE_ONLY 6224A C statement (sans semicolon) to mark @var{decl} to be emitted as a 6225public symbol such that extra copies in multiple translation units will 6226be discarded by the linker. Define this macro if your object file 6227format provides support for this concept, such as the @samp{COMDAT} 6228section flags in the Microsoft Windows PE/COFF format, and this support 6229requires changes to @var{decl}, such as putting it in a separate section. 6230 6231@findex SUPPORTS_ONE_ONLY 6232@item SUPPORTS_ONE_ONLY 6233A C expression which evaluates to true if the target supports one-only 6234semantics. 6235 6236If you don't define this macro, @file{varasm.c} provides a default 6237definition. If @code{MAKE_DECL_ONE_ONLY} is defined, the default 6238definition is @samp{1}; otherwise, it is @samp{0}. Define this macro if 6239you want to control one-only symbol support with a compiler flag, or if 6240setting the @code{DECL_ONE_ONLY} flag is enough to mark a declaration to 6241be emitted as one-only. 6242 6243@findex ASM_OUTPUT_EXTERNAL 6244@item ASM_OUTPUT_EXTERNAL (@var{stream}, @var{decl}, @var{name}) 6245A C statement (sans semicolon) to output to the stdio stream 6246@var{stream} any text necessary for declaring the name of an external 6247symbol named @var{name} which is referenced in this compilation but 6248not defined. The value of @var{decl} is the tree node for the 6249declaration. 6250 6251This macro need not be defined if it does not need to output anything. 6252The GNU assembler and most Unix assemblers don't require anything. 6253 6254@findex ASM_OUTPUT_EXTERNAL_LIBCALL 6255@item ASM_OUTPUT_EXTERNAL_LIBCALL (@var{stream}, @var{symref}) 6256A C statement (sans semicolon) to output on @var{stream} an assembler 6257pseudo-op to declare a library function name external. The name of the 6258library function is given by @var{symref}, which has type @code{rtx} and 6259is a @code{symbol_ref}. 6260 6261This macro need not be defined if it does not need to output anything. 6262The GNU assembler and most Unix assemblers don't require anything. 6263 6264@findex ASM_OUTPUT_LABELREF 6265@item ASM_OUTPUT_LABELREF (@var{stream}, @var{name}) 6266A C statement (sans semicolon) to output to the stdio stream 6267@var{stream} a reference in assembler syntax to a label named 6268@var{name}. This should add @samp{_} to the front of the name, if that 6269is customary on your operating system, as it is in most Berkeley Unix 6270systems. This macro is used in @code{assemble_name}. 6271 6272@findex ASM_OUTPUT_SYMBOL_REF 6273@item ASM_OUTPUT_SYMBOL_REF (@var{stream}, @var{sym}) 6274A C statement (sans semicolon) to output a reference to 6275@code{SYMBOL_REF} @var{sym}. If not defined, @code{assemble_name} 6276will be used to output the name of the symbol. This macro may be used 6277to modify the way a symbol is referenced depending on information 6278encoded by @code{ENCODE_SECTION_INFO}. 6279 6280@findex ASM_OUTPUT_LABEL_REF 6281@item ASM_OUTPUT_LABEL_REF (@var{stream}, @var{buf}) 6282A C statement (sans semicolon) to output a reference to @var{buf}, the 6283result of ASM_GENERATE_INTERNAL_LABEL. If not defined, 6284@code{assemble_name} will be used to output the name of the symbol. 6285This macro is not used by @code{output_asm_label}, or the @code{%l} 6286specifier that calls it; the intention is that this macro should be set 6287when it is necessary to output a label differently when its address 6288is being taken. 6289 6290@findex ASM_OUTPUT_INTERNAL_LABEL 6291@item ASM_OUTPUT_INTERNAL_LABEL (@var{stream}, @var{prefix}, @var{num}) 6292A C statement to output to the stdio stream @var{stream} a label whose 6293name is made from the string @var{prefix} and the number @var{num}. 6294 6295It is absolutely essential that these labels be distinct from the labels 6296used for user-level functions and variables. Otherwise, certain programs 6297will have name conflicts with internal labels. 6298 6299It is desirable to exclude internal labels from the symbol table of the 6300object file. Most assemblers have a naming convention for labels that 6301should be excluded; on many systems, the letter @samp{L} at the 6302beginning of a label has this effect. You should find out what 6303convention your system uses, and follow it. 6304 6305The usual definition of this macro is as follows: 6306 6307@example 6308fprintf (@var{stream}, "L%s%d:\n", @var{prefix}, @var{num}) 6309@end example 6310 6311@findex ASM_OUTPUT_DEBUG_LABEL 6312@item ASM_OUTPUT_DEBUG_LABEL (@var{stream}, @var{prefix}, @var{num}) 6313A C statement to output to the stdio stream @var{stream} a debug info 6314label whose name is made from the string @var{prefix} and the number 6315@var{num}. This is useful for VLIW targets, where debug info labels 6316may need to be treated differently than branch target labels. On some 6317systems, branch target labels must be at the beginning of instruction 6318bundles, but debug info labels can occur in the middle of instruction 6319bundles. 6320 6321If this macro is not defined, then @code{ASM_OUTPUT_INTERNAL_LABEL} will be 6322used. 6323 6324@findex ASM_OUTPUT_ALTERNATE_LABEL_NAME 6325@item ASM_OUTPUT_ALTERNATE_LABEL_NAME (@var{stream}, @var{string}) 6326A C statement to output to the stdio stream @var{stream} the string 6327@var{string}. 6328 6329The default definition of this macro is as follows: 6330 6331@example 6332fprintf (@var{stream}, "%s:\n", LABEL_ALTERNATE_NAME (INSN)) 6333@end example 6334 6335@findex ASM_GENERATE_INTERNAL_LABEL 6336@item ASM_GENERATE_INTERNAL_LABEL (@var{string}, @var{prefix}, @var{num}) 6337A C statement to store into the string @var{string} a label whose name 6338is made from the string @var{prefix} and the number @var{num}. 6339 6340This string, when output subsequently by @code{assemble_name}, should 6341produce the output that @code{ASM_OUTPUT_INTERNAL_LABEL} would produce 6342with the same @var{prefix} and @var{num}. 6343 6344If the string begins with @samp{*}, then @code{assemble_name} will 6345output the rest of the string unchanged. It is often convenient for 6346@code{ASM_GENERATE_INTERNAL_LABEL} to use @samp{*} in this way. If the 6347string doesn't start with @samp{*}, then @code{ASM_OUTPUT_LABELREF} gets 6348to output the string, and may change it. (Of course, 6349@code{ASM_OUTPUT_LABELREF} is also part of your machine description, so 6350you should know what it does on your machine.) 6351 6352@findex ASM_FORMAT_PRIVATE_NAME 6353@item ASM_FORMAT_PRIVATE_NAME (@var{outvar}, @var{name}, @var{number}) 6354A C expression to assign to @var{outvar} (which is a variable of type 6355@code{char *}) a newly allocated string made from the string 6356@var{name} and the number @var{number}, with some suitable punctuation 6357added. Use @code{alloca} to get space for the string. 6358 6359The string will be used as an argument to @code{ASM_OUTPUT_LABELREF} to 6360produce an assembler label for an internal static variable whose name is 6361@var{name}. Therefore, the string must be such as to result in valid 6362assembler code. The argument @var{number} is different each time this 6363macro is executed; it prevents conflicts between similarly-named 6364internal static variables in different scopes. 6365 6366Ideally this string should not be a valid C identifier, to prevent any 6367conflict with the user's own symbols. Most assemblers allow periods 6368or percent signs in assembler symbols; putting at least one of these 6369between the name and the number will suffice. 6370 6371@findex ASM_OUTPUT_DEF 6372@item ASM_OUTPUT_DEF (@var{stream}, @var{name}, @var{value}) 6373A C statement to output to the stdio stream @var{stream} assembler code 6374which defines (equates) the symbol @var{name} to have the value @var{value}. 6375 6376@findex SET_ASM_OP 6377If @code{SET_ASM_OP} is defined, a default definition is provided which is 6378correct for most systems. 6379 6380@findex ASM_OUTPUT_DEF_FROM_DECLS 6381@item ASM_OUTPUT_DEF_FROM_DECLS (@var{stream}, @var{decl_of_name}, @var{decl_of_value}) 6382A C statement to output to the stdio stream @var{stream} assembler code 6383which defines (equates) the symbol whose tree node is @var{decl_of_name} 6384to have the value of the tree node @var{decl_of_value}. This macro will 6385be used in preference to @samp{ASM_OUTPUT_DEF} if it is defined and if 6386the tree nodes are available. 6387 6388@findex ASM_OUTPUT_DEFINE_LABEL_DIFFERENCE_SYMBOL 6389@item ASM_OUTPUT_DEFINE_LABEL_DIFFERENCE_SYMBOL (@var{stream}, @var{symbol}, @var{high}, @var{low}) 6390A C statement to output to the stdio stream @var{stream} assembler code 6391which defines (equates) the symbol @var{symbol} to have a value equal to 6392the difference of the two symbols @var{high} and @var{low}, 6393i.e.@: @var{high} minus @var{low}. GCC guarantees that the symbols @var{high} 6394and @var{low} are already known by the assembler so that the difference 6395resolves into a constant. 6396 6397@findex SET_ASM_OP 6398If @code{SET_ASM_OP} is defined, a default definition is provided which is 6399correct for most systems. 6400 6401@findex ASM_OUTPUT_WEAK_ALIAS 6402@item ASM_OUTPUT_WEAK_ALIAS (@var{stream}, @var{name}, @var{value}) 6403A C statement to output to the stdio stream @var{stream} assembler code 6404which defines (equates) the weak symbol @var{name} to have the value 6405@var{value}. If @var{value} is @code{NULL}, it defines @var{name} as 6406an undefined weak symbol. 6407 6408Define this macro if the target only supports weak aliases; define 6409@code{ASM_OUTPUT_DEF} instead if possible. 6410 6411@findex OBJC_GEN_METHOD_LABEL 6412@item OBJC_GEN_METHOD_LABEL (@var{buf}, @var{is_inst}, @var{class_name}, @var{cat_name}, @var{sel_name}) 6413Define this macro to override the default assembler names used for 6414Objective-C methods. 6415 6416The default name is a unique method number followed by the name of the 6417class (e.g.@: @samp{_1_Foo}). For methods in categories, the name of 6418the category is also included in the assembler name (e.g.@: 6419@samp{_1_Foo_Bar}). 6420 6421These names are safe on most systems, but make debugging difficult since 6422the method's selector is not present in the name. Therefore, particular 6423systems define other ways of computing names. 6424 6425@var{buf} is an expression of type @code{char *} which gives you a 6426buffer in which to store the name; its length is as long as 6427@var{class_name}, @var{cat_name} and @var{sel_name} put together, plus 642850 characters extra. 6429 6430The argument @var{is_inst} specifies whether the method is an instance 6431method or a class method; @var{class_name} is the name of the class; 6432@var{cat_name} is the name of the category (or @code{NULL} if the method is not 6433in a category); and @var{sel_name} is the name of the selector. 6434 6435On systems where the assembler can handle quoted names, you can use this 6436macro to provide more human-readable names. 6437 6438@findex ASM_DECLARE_CLASS_REFERENCE 6439@item ASM_DECLARE_CLASS_REFERENCE (@var{stream}, @var{name}) 6440A C statement (sans semicolon) to output to the stdio stream 6441@var{stream} commands to declare that the label @var{name} is an 6442Objective-C class reference. This is only needed for targets whose 6443linkers have special support for NeXT-style runtimes. 6444 6445@findex ASM_DECLARE_UNRESOLVED_REFERENCE 6446@item ASM_DECLARE_UNRESOLVED_REFERENCE (@var{stream}, @var{name}) 6447A C statement (sans semicolon) to output to the stdio stream 6448@var{stream} commands to declare that the label @var{name} is an 6449unresolved Objective-C class reference. This is only needed for targets 6450whose linkers have special support for NeXT-style runtimes. 6451@end table 6452 6453@node Initialization 6454@subsection How Initialization Functions Are Handled 6455@cindex initialization routines 6456@cindex termination routines 6457@cindex constructors, output of 6458@cindex destructors, output of 6459 6460The compiled code for certain languages includes @dfn{constructors} 6461(also called @dfn{initialization routines})---functions to initialize 6462data in the program when the program is started. These functions need 6463to be called before the program is ``started''---that is to say, before 6464@code{main} is called. 6465 6466Compiling some languages generates @dfn{destructors} (also called 6467@dfn{termination routines}) that should be called when the program 6468terminates. 6469 6470To make the initialization and termination functions work, the compiler 6471must output something in the assembler code to cause those functions to 6472be called at the appropriate time. When you port the compiler to a new 6473system, you need to specify how to do this. 6474 6475There are two major ways that GCC currently supports the execution of 6476initialization and termination functions. Each way has two variants. 6477Much of the structure is common to all four variations. 6478 6479@findex __CTOR_LIST__ 6480@findex __DTOR_LIST__ 6481The linker must build two lists of these functions---a list of 6482initialization functions, called @code{__CTOR_LIST__}, and a list of 6483termination functions, called @code{__DTOR_LIST__}. 6484 6485Each list always begins with an ignored function pointer (which may hold 64860, @minus{}1, or a count of the function pointers after it, depending on 6487the environment). This is followed by a series of zero or more function 6488pointers to constructors (or destructors), followed by a function 6489pointer containing zero. 6490 6491Depending on the operating system and its executable file format, either 6492@file{crtstuff.c} or @file{libgcc2.c} traverses these lists at startup 6493time and exit time. Constructors are called in reverse order of the 6494list; destructors in forward order. 6495 6496The best way to handle static constructors works only for object file 6497formats which provide arbitrarily-named sections. A section is set 6498aside for a list of constructors, and another for a list of destructors. 6499Traditionally these are called @samp{.ctors} and @samp{.dtors}. Each 6500object file that defines an initialization function also puts a word in 6501the constructor section to point to that function. The linker 6502accumulates all these words into one contiguous @samp{.ctors} section. 6503Termination functions are handled similarly. 6504 6505This method will be chosen as the default by @file{target-def.h} if 6506@code{TARGET_ASM_NAMED_SECTION} is defined. A target that does not 6507support arbitrary sections, but does support special designated 6508constructor and destructor sections may define @code{CTORS_SECTION_ASM_OP} 6509and @code{DTORS_SECTION_ASM_OP} to achieve the same effect. 6510 6511When arbitrary sections are available, there are two variants, depending 6512upon how the code in @file{crtstuff.c} is called. On systems that 6513support a @dfn{.init} section which is executed at program startup, 6514parts of @file{crtstuff.c} are compiled into that section. The 6515program is linked by the @code{gcc} driver like this: 6516 6517@example 6518ld -o @var{output_file} crti.o crtbegin.o @dots{} -lgcc crtend.o crtn.o 6519@end example 6520 6521The prologue of a function (@code{__init}) appears in the @code{.init} 6522section of @file{crti.o}; the epilogue appears in @file{crtn.o}. Likewise 6523for the function @code{__fini} in the @dfn{.fini} section. Normally these 6524files are provided by the operating system or by the GNU C library, but 6525are provided by GCC for a few targets. 6526 6527The objects @file{crtbegin.o} and @file{crtend.o} are (for most targets) 6528compiled from @file{crtstuff.c}. They contain, among other things, code 6529fragments within the @code{.init} and @code{.fini} sections that branch 6530to routines in the @code{.text} section. The linker will pull all parts 6531of a section together, which results in a complete @code{__init} function 6532that invokes the routines we need at startup. 6533 6534To use this variant, you must define the @code{INIT_SECTION_ASM_OP} 6535macro properly. 6536 6537If no init section is available, when GCC compiles any function called 6538@code{main} (or more accurately, any function designated as a program 6539entry point by the language front end calling @code{expand_main_function}), 6540it inserts a procedure call to @code{__main} as the first executable code 6541after the function prologue. The @code{__main} function is defined 6542in @file{libgcc2.c} and runs the global constructors. 6543 6544In file formats that don't support arbitrary sections, there are again 6545two variants. In the simplest variant, the GNU linker (GNU @code{ld}) 6546and an `a.out' format must be used. In this case, 6547@code{TARGET_ASM_CONSTRUCTOR} is defined to produce a @code{.stabs} 6548entry of type @samp{N_SETT}, referencing the name @code{__CTOR_LIST__}, 6549and with the address of the void function containing the initialization 6550code as its value. The GNU linker recognizes this as a request to add 6551the value to a @dfn{set}; the values are accumulated, and are eventually 6552placed in the executable as a vector in the format described above, with 6553a leading (ignored) count and a trailing zero element. 6554@code{TARGET_ASM_DESTRUCTOR} is handled similarly. Since no init 6555section is available, the absence of @code{INIT_SECTION_ASM_OP} causes 6556the compilation of @code{main} to call @code{__main} as above, starting 6557the initialization process. 6558 6559The last variant uses neither arbitrary sections nor the GNU linker. 6560This is preferable when you want to do dynamic linking and when using 6561file formats which the GNU linker does not support, such as `ECOFF'@. In 6562this case, @code{TARGET_HAVE_CTORS_DTORS} is false, initialization and 6563termination functions are recognized simply by their names. This requires 6564an extra program in the linkage step, called @command{collect2}. This program 6565pretends to be the linker, for use with GCC; it does its job by running 6566the ordinary linker, but also arranges to include the vectors of 6567initialization and termination functions. These functions are called 6568via @code{__main} as described above. In order to use this method, 6569@code{use_collect2} must be defined in the target in @file{config.gcc}. 6570 6571@ifinfo 6572The following section describes the specific macros that control and 6573customize the handling of initialization and termination functions. 6574@end ifinfo 6575 6576@node Macros for Initialization 6577@subsection Macros Controlling Initialization Routines 6578 6579Here are the macros that control how the compiler handles initialization 6580and termination functions: 6581 6582@table @code 6583@findex INIT_SECTION_ASM_OP 6584@item INIT_SECTION_ASM_OP 6585If defined, a C string constant, including spacing, for the assembler 6586operation to identify the following data as initialization code. If not 6587defined, GCC will assume such a section does not exist. When you are 6588using special sections for initialization and termination functions, this 6589macro also controls how @file{crtstuff.c} and @file{libgcc2.c} arrange to 6590run the initialization functions. 6591 6592@item HAS_INIT_SECTION 6593@findex HAS_INIT_SECTION 6594If defined, @code{main} will not call @code{__main} as described above. 6595This macro should be defined for systems that control start-up code 6596on a symbol-by-symbol basis, such as OSF/1, and should not 6597be defined explicitly for systems that support @code{INIT_SECTION_ASM_OP}. 6598 6599@item LD_INIT_SWITCH 6600@findex LD_INIT_SWITCH 6601If defined, a C string constant for a switch that tells the linker that 6602the following symbol is an initialization routine. 6603 6604@item LD_FINI_SWITCH 6605@findex LD_FINI_SWITCH 6606If defined, a C string constant for a switch that tells the linker that 6607the following symbol is a finalization routine. 6608 6609@item COLLECT_SHARED_INIT_FUNC (@var{stream}, @var{func}) 6610If defined, a C statement that will write a function that can be 6611automatically called when a shared library is loaded. The function 6612should call @var{func}, which takes no arguments. If not defined, and 6613the object format requires an explicit initialization function, then a 6614function called @code{_GLOBAL__DI} will be generated. 6615 6616This function and the following one are used by collect2 when linking a 6617shared library that needs constructors or destructors, or has DWARF2 6618exception tables embedded in the code. 6619 6620@item COLLECT_SHARED_FINI_FUNC (@var{stream}, @var{func}) 6621If defined, a C statement that will write a function that can be 6622automatically called when a shared library is unloaded. The function 6623should call @var{func}, which takes no arguments. If not defined, and 6624the object format requires an explicit finalization function, then a 6625function called @code{_GLOBAL__DD} will be generated. 6626 6627@item INVOKE__main 6628@findex INVOKE__main 6629If defined, @code{main} will call @code{__main} despite the presence of 6630@code{INIT_SECTION_ASM_OP}. This macro should be defined for systems 6631where the init section is not actually run automatically, but is still 6632useful for collecting the lists of constructors and destructors. 6633 6634@item SUPPORTS_INIT_PRIORITY 6635@findex SUPPORTS_INIT_PRIORITY 6636If nonzero, the C++ @code{init_priority} attribute is supported and the 6637compiler should emit instructions to control the order of initialization 6638of objects. If zero, the compiler will issue an error message upon 6639encountering an @code{init_priority} attribute. 6640@end table 6641 6642@deftypefn {Target Hook} bool TARGET_HAVE_CTORS_DTORS 6643This value is true if the target supports some ``native'' method of 6644collecting constructors and destructors to be run at startup and exit. 6645It is false if we must use @command{collect2}. 6646@end deftypefn 6647 6648@deftypefn {Target Hook} void TARGET_ASM_CONSTRUCTOR (rtx @var{symbol}, int @var{priority}) 6649If defined, a function that outputs assembler code to arrange to call 6650the function referenced by @var{symbol} at initialization time. 6651 6652Assume that @var{symbol} is a @code{SYMBOL_REF} for a function taking 6653no arguments and with no return value. If the target supports initialization 6654priorities, @var{priority} is a value between 0 and @code{MAX_INIT_PRIORITY}; 6655otherwise it must be @code{DEFAULT_INIT_PRIORITY}. 6656 6657If this macro is not defined by the target, a suitable default will 6658be chosen if (1) the target supports arbitrary section names, (2) the 6659target defines @code{CTORS_SECTION_ASM_OP}, or (3) @code{USE_COLLECT2} 6660is not defined. 6661@end deftypefn 6662 6663@deftypefn {Target Hook} void TARGET_ASM_DESTRUCTOR (rtx @var{symbol}, int @var{priority}) 6664This is like @code{TARGET_ASM_CONSTRUCTOR} but used for termination 6665functions rather than initialization functions. 6666@end deftypefn 6667 6668If @code{TARGET_HAVE_CTORS_DTORS} is true, the initialization routine 6669generated for the generated object file will have static linkage. 6670 6671If your system uses @command{collect2} as the means of processing 6672constructors, then that program normally uses @command{nm} to scan 6673an object file for constructor functions to be called. 6674 6675On certain kinds of systems, you can define these macros to make 6676@command{collect2} work faster (and, in some cases, make it work at all): 6677 6678@table @code 6679@findex OBJECT_FORMAT_COFF 6680@item OBJECT_FORMAT_COFF 6681Define this macro if the system uses COFF (Common Object File Format) 6682object files, so that @command{collect2} can assume this format and scan 6683object files directly for dynamic constructor/destructor functions. 6684 6685@findex OBJECT_FORMAT_ROSE 6686@item OBJECT_FORMAT_ROSE 6687Define this macro if the system uses ROSE format object files, so that 6688@command{collect2} can assume this format and scan object files directly 6689for dynamic constructor/destructor functions. 6690 6691These macros are effective only in a native compiler; @command{collect2} as 6692part of a cross compiler always uses @command{nm} for the target machine. 6693 6694@findex REAL_NM_FILE_NAME 6695@item REAL_NM_FILE_NAME 6696Define this macro as a C string constant containing the file name to use 6697to execute @command{nm}. The default is to search the path normally for 6698@command{nm}. 6699 6700If your system supports shared libraries and has a program to list the 6701dynamic dependencies of a given library or executable, you can define 6702these macros to enable support for running initialization and 6703termination functions in shared libraries: 6704 6705@findex LDD_SUFFIX 6706@item LDD_SUFFIX 6707Define this macro to a C string constant containing the name of the program 6708which lists dynamic dependencies, like @command{"ldd"} under SunOS 4. 6709 6710@findex PARSE_LDD_OUTPUT 6711@item PARSE_LDD_OUTPUT (@var{ptr}) 6712Define this macro to be C code that extracts filenames from the output 6713of the program denoted by @code{LDD_SUFFIX}. @var{ptr} is a variable 6714of type @code{char *} that points to the beginning of a line of output 6715from @code{LDD_SUFFIX}. If the line lists a dynamic dependency, the 6716code must advance @var{ptr} to the beginning of the filename on that 6717line. Otherwise, it must set @var{ptr} to @code{NULL}. 6718@end table 6719 6720@node Instruction Output 6721@subsection Output of Assembler Instructions 6722 6723@c prevent bad page break with this line 6724This describes assembler instruction output. 6725 6726@table @code 6727@findex REGISTER_NAMES 6728@item REGISTER_NAMES 6729A C initializer containing the assembler's names for the machine 6730registers, each one as a C string constant. This is what translates 6731register numbers in the compiler into assembler language. 6732 6733@findex ADDITIONAL_REGISTER_NAMES 6734@item ADDITIONAL_REGISTER_NAMES 6735If defined, a C initializer for an array of structures containing a name 6736and a register number. This macro defines additional names for hard 6737registers, thus allowing the @code{asm} option in declarations to refer 6738to registers using alternate names. 6739 6740@findex ASM_OUTPUT_OPCODE 6741@item ASM_OUTPUT_OPCODE (@var{stream}, @var{ptr}) 6742Define this macro if you are using an unusual assembler that 6743requires different names for the machine instructions. 6744 6745The definition is a C statement or statements which output an 6746assembler instruction opcode to the stdio stream @var{stream}. The 6747macro-operand @var{ptr} is a variable of type @code{char *} which 6748points to the opcode name in its ``internal'' form---the form that is 6749written in the machine description. The definition should output the 6750opcode name to @var{stream}, performing any translation you desire, and 6751increment the variable @var{ptr} to point at the end of the opcode 6752so that it will not be output twice. 6753 6754In fact, your macro definition may process less than the entire opcode 6755name, or more than the opcode name; but if you want to process text 6756that includes @samp{%}-sequences to substitute operands, you must take 6757care of the substitution yourself. Just be sure to increment 6758@var{ptr} over whatever text should not be output normally. 6759 6760@findex recog_data.operand 6761If you need to look at the operand values, they can be found as the 6762elements of @code{recog_data.operand}. 6763 6764If the macro definition does nothing, the instruction is output 6765in the usual way. 6766 6767@findex FINAL_PRESCAN_INSN 6768@item FINAL_PRESCAN_INSN (@var{insn}, @var{opvec}, @var{noperands}) 6769If defined, a C statement to be executed just prior to the output of 6770assembler code for @var{insn}, to modify the extracted operands so 6771they will be output differently. 6772 6773Here the argument @var{opvec} is the vector containing the operands 6774extracted from @var{insn}, and @var{noperands} is the number of 6775elements of the vector which contain meaningful data for this insn. 6776The contents of this vector are what will be used to convert the insn 6777template into assembler code, so you can change the assembler output 6778by changing the contents of the vector. 6779 6780This macro is useful when various assembler syntaxes share a single 6781file of instruction patterns; by defining this macro differently, you 6782can cause a large class of instructions to be output differently (such 6783as with rearranged operands). Naturally, variations in assembler 6784syntax affecting individual insn patterns ought to be handled by 6785writing conditional output routines in those patterns. 6786 6787If this macro is not defined, it is equivalent to a null statement. 6788 6789@findex FINAL_PRESCAN_LABEL 6790@item FINAL_PRESCAN_LABEL 6791If defined, @code{FINAL_PRESCAN_INSN} will be called on each 6792@code{CODE_LABEL}. In that case, @var{opvec} will be a null pointer and 6793@var{noperands} will be zero. 6794 6795@findex PRINT_OPERAND 6796@item PRINT_OPERAND (@var{stream}, @var{x}, @var{code}) 6797A C compound statement to output to stdio stream @var{stream} the 6798assembler syntax for an instruction operand @var{x}. @var{x} is an 6799RTL expression. 6800 6801@var{code} is a value that can be used to specify one of several ways 6802of printing the operand. It is used when identical operands must be 6803printed differently depending on the context. @var{code} comes from 6804the @samp{%} specification that was used to request printing of the 6805operand. If the specification was just @samp{%@var{digit}} then 6806@var{code} is 0; if the specification was @samp{%@var{ltr} 6807@var{digit}} then @var{code} is the ASCII code for @var{ltr}. 6808 6809@findex reg_names 6810If @var{x} is a register, this macro should print the register's name. 6811The names can be found in an array @code{reg_names} whose type is 6812@code{char *[]}. @code{reg_names} is initialized from 6813@code{REGISTER_NAMES}. 6814 6815When the machine description has a specification @samp{%@var{punct}} 6816(a @samp{%} followed by a punctuation character), this macro is called 6817with a null pointer for @var{x} and the punctuation character for 6818@var{code}. 6819 6820@findex PRINT_OPERAND_PUNCT_VALID_P 6821@item PRINT_OPERAND_PUNCT_VALID_P (@var{code}) 6822A C expression which evaluates to true if @var{code} is a valid 6823punctuation character for use in the @code{PRINT_OPERAND} macro. If 6824@code{PRINT_OPERAND_PUNCT_VALID_P} is not defined, it means that no 6825punctuation characters (except for the standard one, @samp{%}) are used 6826in this way. 6827 6828@findex PRINT_OPERAND_ADDRESS 6829@item PRINT_OPERAND_ADDRESS (@var{stream}, @var{x}) 6830A C compound statement to output to stdio stream @var{stream} the 6831assembler syntax for an instruction operand that is a memory reference 6832whose address is @var{x}. @var{x} is an RTL expression. 6833 6834@cindex @code{ENCODE_SECTION_INFO} usage 6835On some machines, the syntax for a symbolic address depends on the 6836section that the address refers to. On these machines, define the macro 6837@code{ENCODE_SECTION_INFO} to store the information into the 6838@code{symbol_ref}, and then check for it here. @xref{Assembler Format}. 6839 6840@findex DBR_OUTPUT_SEQEND 6841@findex dbr_sequence_length 6842@item DBR_OUTPUT_SEQEND(@var{file}) 6843A C statement, to be executed after all slot-filler instructions have 6844been output. If necessary, call @code{dbr_sequence_length} to 6845determine the number of slots filled in a sequence (zero if not 6846currently outputting a sequence), to decide how many no-ops to output, 6847or whatever. 6848 6849Don't define this macro if it has nothing to do, but it is helpful in 6850reading assembly output if the extent of the delay sequence is made 6851explicit (e.g.@: with white space). 6852 6853@findex final_sequence 6854Note that output routines for instructions with delay slots must be 6855prepared to deal with not being output as part of a sequence 6856(i.e.@: when the scheduling pass is not run, or when no slot fillers could be 6857found.) The variable @code{final_sequence} is null when not 6858processing a sequence, otherwise it contains the @code{sequence} rtx 6859being output. 6860 6861@findex REGISTER_PREFIX 6862@findex LOCAL_LABEL_PREFIX 6863@findex USER_LABEL_PREFIX 6864@findex IMMEDIATE_PREFIX 6865@findex asm_fprintf 6866@item REGISTER_PREFIX 6867@itemx LOCAL_LABEL_PREFIX 6868@itemx USER_LABEL_PREFIX 6869@itemx IMMEDIATE_PREFIX 6870If defined, C string expressions to be used for the @samp{%R}, @samp{%L}, 6871@samp{%U}, and @samp{%I} options of @code{asm_fprintf} (see 6872@file{final.c}). These are useful when a single @file{md} file must 6873support multiple assembler formats. In that case, the various @file{tm.h} 6874files can define these macros differently. 6875 6876@item ASM_FPRINTF_EXTENSIONS(@var{file}, @var{argptr}, @var{format}) 6877@findex ASM_FPRINTF_EXTENSIONS 6878If defined this macro should expand to a series of @code{case} 6879statements which will be parsed inside the @code{switch} statement of 6880the @code{asm_fprintf} function. This allows targets to define extra 6881printf formats which may useful when generating their assembler 6882statements. Note that upper case letters are reserved for future 6883generic extensions to asm_fprintf, and so are not available to target 6884specific code. The output file is given by the parameter @var{file}. 6885The varargs input pointer is @var{argptr} and the rest of the format 6886string, starting the character after the one that is being switched 6887upon, is pointed to by @var{format}. 6888 6889@findex ASSEMBLER_DIALECT 6890@item ASSEMBLER_DIALECT 6891If your target supports multiple dialects of assembler language (such as 6892different opcodes), define this macro as a C expression that gives the 6893numeric index of the assembler language dialect to use, with zero as the 6894first variant. 6895 6896If this macro is defined, you may use constructs of the form 6897@smallexample 6898@samp{@{option0|option1|option2@dots{}@}} 6899@end smallexample 6900@noindent 6901in the output templates of patterns (@pxref{Output Template}) or in the 6902first argument of @code{asm_fprintf}. This construct outputs 6903@samp{option0}, @samp{option1}, @samp{option2}, etc., if the value of 6904@code{ASSEMBLER_DIALECT} is zero, one, two, etc. Any special characters 6905within these strings retain their usual meaning. If there are fewer 6906alternatives within the braces than the value of 6907@code{ASSEMBLER_DIALECT}, the construct outputs nothing. 6908 6909If you do not define this macro, the characters @samp{@{}, @samp{|} and 6910@samp{@}} do not have any special meaning when used in templates or 6911operands to @code{asm_fprintf}. 6912 6913Define the macros @code{REGISTER_PREFIX}, @code{LOCAL_LABEL_PREFIX}, 6914@code{USER_LABEL_PREFIX} and @code{IMMEDIATE_PREFIX} if you can express 6915the variations in assembler language syntax with that mechanism. Define 6916@code{ASSEMBLER_DIALECT} and use the @samp{@{option0|option1@}} syntax 6917if the syntax variant are larger and involve such things as different 6918opcodes or operand order. 6919 6920@findex ASM_OUTPUT_REG_PUSH 6921@item ASM_OUTPUT_REG_PUSH (@var{stream}, @var{regno}) 6922A C expression to output to @var{stream} some assembler code 6923which will push hard register number @var{regno} onto the stack. 6924The code need not be optimal, since this macro is used only when 6925profiling. 6926 6927@findex ASM_OUTPUT_REG_POP 6928@item ASM_OUTPUT_REG_POP (@var{stream}, @var{regno}) 6929A C expression to output to @var{stream} some assembler code 6930which will pop hard register number @var{regno} off of the stack. 6931The code need not be optimal, since this macro is used only when 6932profiling. 6933@end table 6934 6935@node Dispatch Tables 6936@subsection Output of Dispatch Tables 6937 6938@c prevent bad page break with this line 6939This concerns dispatch tables. 6940 6941@table @code 6942@cindex dispatch table 6943@findex ASM_OUTPUT_ADDR_DIFF_ELT 6944@item ASM_OUTPUT_ADDR_DIFF_ELT (@var{stream}, @var{body}, @var{value}, @var{rel}) 6945A C statement to output to the stdio stream @var{stream} an assembler 6946pseudo-instruction to generate a difference between two labels. 6947@var{value} and @var{rel} are the numbers of two internal labels. The 6948definitions of these labels are output using 6949@code{ASM_OUTPUT_INTERNAL_LABEL}, and they must be printed in the same 6950way here. For example, 6951 6952@example 6953fprintf (@var{stream}, "\t.word L%d-L%d\n", 6954 @var{value}, @var{rel}) 6955@end example 6956 6957You must provide this macro on machines where the addresses in a 6958dispatch table are relative to the table's own address. If defined, GCC 6959will also use this macro on all machines when producing PIC@. 6960@var{body} is the body of the @code{ADDR_DIFF_VEC}; it is provided so that the 6961mode and flags can be read. 6962 6963@findex ASM_OUTPUT_ADDR_VEC_ELT 6964@item ASM_OUTPUT_ADDR_VEC_ELT (@var{stream}, @var{value}) 6965This macro should be provided on machines where the addresses 6966in a dispatch table are absolute. 6967 6968The definition should be a C statement to output to the stdio stream 6969@var{stream} an assembler pseudo-instruction to generate a reference to 6970a label. @var{value} is the number of an internal label whose 6971definition is output using @code{ASM_OUTPUT_INTERNAL_LABEL}. 6972For example, 6973 6974@example 6975fprintf (@var{stream}, "\t.word L%d\n", @var{value}) 6976@end example 6977 6978@findex ASM_OUTPUT_CASE_LABEL 6979@item ASM_OUTPUT_CASE_LABEL (@var{stream}, @var{prefix}, @var{num}, @var{table}) 6980Define this if the label before a jump-table needs to be output 6981specially. The first three arguments are the same as for 6982@code{ASM_OUTPUT_INTERNAL_LABEL}; the fourth argument is the 6983jump-table which follows (a @code{jump_insn} containing an 6984@code{addr_vec} or @code{addr_diff_vec}). 6985 6986This feature is used on system V to output a @code{swbeg} statement 6987for the table. 6988 6989If this macro is not defined, these labels are output with 6990@code{ASM_OUTPUT_INTERNAL_LABEL}. 6991 6992@findex ASM_OUTPUT_CASE_END 6993@item ASM_OUTPUT_CASE_END (@var{stream}, @var{num}, @var{table}) 6994Define this if something special must be output at the end of a 6995jump-table. The definition should be a C statement to be executed 6996after the assembler code for the table is written. It should write 6997the appropriate code to stdio stream @var{stream}. The argument 6998@var{table} is the jump-table insn, and @var{num} is the label-number 6999of the preceding label. 7000 7001If this macro is not defined, nothing special is output at the end of 7002the jump-table. 7003@end table 7004 7005@node Exception Region Output 7006@subsection Assembler Commands for Exception Regions 7007 7008@c prevent bad page break with this line 7009 7010This describes commands marking the start and the end of an exception 7011region. 7012 7013@table @code 7014@findex EH_FRAME_SECTION_NAME 7015@item EH_FRAME_SECTION_NAME 7016If defined, a C string constant for the name of the section containing 7017exception handling frame unwind information. If not defined, GCC will 7018provide a default definition if the target supports named sections. 7019@file{crtstuff.c} uses this macro to switch to the appropriate section. 7020 7021You should define this symbol if your target supports DWARF 2 frame 7022unwind information and the default definition does not work. 7023 7024@findex EH_FRAME_IN_DATA_SECTION 7025@item EH_FRAME_IN_DATA_SECTION 7026If defined, DWARF 2 frame unwind information will be placed in the 7027data section even though the target supports named sections. This 7028might be necessary, for instance, if the system linker does garbage 7029collection and sections cannot be marked as not to be collected. 7030 7031Do not define this macro unless @code{TARGET_ASM_NAMED_SECTION} is 7032also defined. 7033 7034@findex MASK_RETURN_ADDR 7035@item MASK_RETURN_ADDR 7036An rtx used to mask the return address found via @code{RETURN_ADDR_RTX}, so 7037that it does not contain any extraneous set bits in it. 7038 7039@findex DWARF2_UNWIND_INFO 7040@item DWARF2_UNWIND_INFO 7041Define this macro to 0 if your target supports DWARF 2 frame unwind 7042information, but it does not yet work with exception handling. 7043Otherwise, if your target supports this information (if it defines 7044@samp{INCOMING_RETURN_ADDR_RTX} and either @samp{UNALIGNED_INT_ASM_OP} 7045or @samp{OBJECT_FORMAT_ELF}), GCC will provide a default definition of 70461. 7047 7048If this macro is defined to 1, the DWARF 2 unwinder will be the default 7049exception handling mechanism; otherwise, @code{setjmp}/@code{longjmp} will be used by 7050default. 7051 7052If this macro is defined to anything, the DWARF 2 unwinder will be used 7053instead of inline unwinders and @code{__unwind_function} in the non-@code{setjmp} case. 7054 7055@findex DWARF_CIE_DATA_ALIGNMENT 7056@item DWARF_CIE_DATA_ALIGNMENT 7057This macro need only be defined if the target might save registers in the 7058function prologue at an offset to the stack pointer that is not aligned to 7059@code{UNITS_PER_WORD}. The definition should be the negative minimum 7060alignment if @code{STACK_GROWS_DOWNWARD} is defined, and the positive 7061minimum alignment otherwise. @xref{SDB and DWARF}. Only applicable if 7062the target supports DWARF 2 frame unwind information. 7063 7064@end table 7065 7066@deftypefn {Target Hook} void TARGET_ASM_EXCEPTION_SECTION () 7067If defined, a function that switches to the section in which the main 7068exception table is to be placed (@pxref{Sections}). The default is a 7069function that switches to a section named @code{.gcc_except_table} on 7070machines that support named sections via 7071@code{TARGET_ASM_NAMED_SECTION}, otherwise if @option{-fpic} or 7072@option{-fPIC} is in effect, the @code{data_section}, otherwise the 7073@code{readonly_data_section}. 7074@end deftypefn 7075 7076@deftypefn {Target Hook} void TARGET_ASM_EH_FRAME_SECTION () 7077If defined, a function that switches to the section in which the DWARF 2 7078frame unwind information to be placed (@pxref{Sections}). The default 7079is a function that outputs a standard GAS section directive, if 7080@code{EH_FRAME_SECTION_NAME} is defined, or else a data section 7081directive followed by a synthetic label. 7082@end deftypefn 7083 7084@node Alignment Output 7085@subsection Assembler Commands for Alignment 7086 7087@c prevent bad page break with this line 7088This describes commands for alignment. 7089 7090@table @code 7091@findex JUMP_ALIGN 7092@item JUMP_ALIGN (@var{label}) 7093The alignment (log base 2) to put in front of @var{label}, which is 7094a common destination of jumps and has no fallthru incoming edge. 7095 7096This macro need not be defined if you don't want any special alignment 7097to be done at such a time. Most machine descriptions do not currently 7098define the macro. 7099 7100Unless it's necessary to inspect the @var{label} parameter, it is better 7101to set the variable @var{align_jumps} in the target's 7102@code{OVERRIDE_OPTIONS}. Otherwise, you should try to honor the user's 7103selection in @var{align_jumps} in a @code{JUMP_ALIGN} implementation. 7104 7105@findex LABEL_ALIGN_AFTER_BARRIER 7106@item LABEL_ALIGN_AFTER_BARRIER (@var{label}) 7107The alignment (log base 2) to put in front of @var{label}, which follows 7108a @code{BARRIER}. 7109 7110This macro need not be defined if you don't want any special alignment 7111to be done at such a time. Most machine descriptions do not currently 7112define the macro. 7113 7114@findex LABEL_ALIGN_AFTER_BARRIER_MAX_SKIP 7115@item LABEL_ALIGN_AFTER_BARRIER_MAX_SKIP 7116The maximum number of bytes to skip when applying 7117@code{LABEL_ALIGN_AFTER_BARRIER}. This works only if 7118@code{ASM_OUTPUT_MAX_SKIP_ALIGN} is defined. 7119 7120@findex LOOP_ALIGN 7121@item LOOP_ALIGN (@var{label}) 7122The alignment (log base 2) to put in front of @var{label}, which follows 7123a @code{NOTE_INSN_LOOP_BEG} note. 7124 7125This macro need not be defined if you don't want any special alignment 7126to be done at such a time. Most machine descriptions do not currently 7127define the macro. 7128 7129Unless it's necessary to inspect the @var{label} parameter, it is better 7130to set the variable @code{align_loops} in the target's 7131@code{OVERRIDE_OPTIONS}. Otherwise, you should try to honor the user's 7132selection in @code{align_loops} in a @code{LOOP_ALIGN} implementation. 7133 7134@findex LOOP_ALIGN_MAX_SKIP 7135@item LOOP_ALIGN_MAX_SKIP 7136The maximum number of bytes to skip when applying @code{LOOP_ALIGN}. 7137This works only if @code{ASM_OUTPUT_MAX_SKIP_ALIGN} is defined. 7138 7139@findex LABEL_ALIGN 7140@item LABEL_ALIGN (@var{label}) 7141The alignment (log base 2) to put in front of @var{label}. 7142If @code{LABEL_ALIGN_AFTER_BARRIER} / @code{LOOP_ALIGN} specify a different alignment, 7143the maximum of the specified values is used. 7144 7145Unless it's necessary to inspect the @var{label} parameter, it is better 7146to set the variable @code{align_labels} in the target's 7147@code{OVERRIDE_OPTIONS}. Otherwise, you should try to honor the user's 7148selection in @code{align_labels} in a @code{LABEL_ALIGN} implementation. 7149 7150@findex LABEL_ALIGN_MAX_SKIP 7151@item LABEL_ALIGN_MAX_SKIP 7152The maximum number of bytes to skip when applying @code{LABEL_ALIGN}. 7153This works only if @code{ASM_OUTPUT_MAX_SKIP_ALIGN} is defined. 7154 7155@findex ASM_OUTPUT_SKIP 7156@item ASM_OUTPUT_SKIP (@var{stream}, @var{nbytes}) 7157A C statement to output to the stdio stream @var{stream} an assembler 7158instruction to advance the location counter by @var{nbytes} bytes. 7159Those bytes should be zero when loaded. @var{nbytes} will be a C 7160expression of type @code{int}. 7161 7162@findex ASM_NO_SKIP_IN_TEXT 7163@item ASM_NO_SKIP_IN_TEXT 7164Define this macro if @code{ASM_OUTPUT_SKIP} should not be used in the 7165text section because it fails to put zeros in the bytes that are skipped. 7166This is true on many Unix systems, where the pseudo--op to skip bytes 7167produces no-op instructions rather than zeros when used in the text 7168section. 7169 7170@findex ASM_OUTPUT_ALIGN 7171@item ASM_OUTPUT_ALIGN (@var{stream}, @var{power}) 7172A C statement to output to the stdio stream @var{stream} an assembler 7173command to advance the location counter to a multiple of 2 to the 7174@var{power} bytes. @var{power} will be a C expression of type @code{int}. 7175 7176@findex ASM_OUTPUT_MAX_SKIP_ALIGN 7177@item ASM_OUTPUT_MAX_SKIP_ALIGN (@var{stream}, @var{power}, @var{max_skip}) 7178A C statement to output to the stdio stream @var{stream} an assembler 7179command to advance the location counter to a multiple of 2 to the 7180@var{power} bytes, but only if @var{max_skip} or fewer bytes are needed to 7181satisfy the alignment request. @var{power} and @var{max_skip} will be 7182a C expression of type @code{int}. 7183@end table 7184 7185@need 3000 7186@node Debugging Info 7187@section Controlling Debugging Information Format 7188 7189@c prevent bad page break with this line 7190This describes how to specify debugging information. 7191 7192@menu 7193* All Debuggers:: Macros that affect all debugging formats uniformly. 7194* DBX Options:: Macros enabling specific options in DBX format. 7195* DBX Hooks:: Hook macros for varying DBX format. 7196* File Names and DBX:: Macros controlling output of file names in DBX format. 7197* SDB and DWARF:: Macros for SDB (COFF) and DWARF formats. 7198* VMS Debug:: Macros for VMS debug format. 7199@end menu 7200 7201@node All Debuggers 7202@subsection Macros Affecting All Debugging Formats 7203 7204@c prevent bad page break with this line 7205These macros affect all debugging formats. 7206 7207@table @code 7208@findex DBX_REGISTER_NUMBER 7209@item DBX_REGISTER_NUMBER (@var{regno}) 7210A C expression that returns the DBX register number for the compiler 7211register number @var{regno}. In the default macro provided, the value 7212of this expression will be @var{regno} itself. But sometimes there are 7213some registers that the compiler knows about and DBX does not, or vice 7214versa. In such cases, some register may need to have one number in the 7215compiler and another for DBX@. 7216 7217If two registers have consecutive numbers inside GCC, and they can be 7218used as a pair to hold a multiword value, then they @emph{must} have 7219consecutive numbers after renumbering with @code{DBX_REGISTER_NUMBER}. 7220Otherwise, debuggers will be unable to access such a pair, because they 7221expect register pairs to be consecutive in their own numbering scheme. 7222 7223If you find yourself defining @code{DBX_REGISTER_NUMBER} in way that 7224does not preserve register pairs, then what you must do instead is 7225redefine the actual register numbering scheme. 7226 7227@findex DEBUGGER_AUTO_OFFSET 7228@item DEBUGGER_AUTO_OFFSET (@var{x}) 7229A C expression that returns the integer offset value for an automatic 7230variable having address @var{x} (an RTL expression). The default 7231computation assumes that @var{x} is based on the frame-pointer and 7232gives the offset from the frame-pointer. This is required for targets 7233that produce debugging output for DBX or COFF-style debugging output 7234for SDB and allow the frame-pointer to be eliminated when the 7235@option{-g} options is used. 7236 7237@findex DEBUGGER_ARG_OFFSET 7238@item DEBUGGER_ARG_OFFSET (@var{offset}, @var{x}) 7239A C expression that returns the integer offset value for an argument 7240having address @var{x} (an RTL expression). The nominal offset is 7241@var{offset}. 7242 7243@findex PREFERRED_DEBUGGING_TYPE 7244@item PREFERRED_DEBUGGING_TYPE 7245A C expression that returns the type of debugging output GCC should 7246produce when the user specifies just @option{-g}. Define 7247this if you have arranged for GCC to support more than one format of 7248debugging output. Currently, the allowable values are @code{DBX_DEBUG}, 7249@code{SDB_DEBUG}, @code{DWARF_DEBUG}, @code{DWARF2_DEBUG}, 7250@code{XCOFF_DEBUG}, @code{VMS_DEBUG}, and @code{VMS_AND_DWARF2_DEBUG}. 7251 7252When the user specifies @option{-ggdb}, GCC normally also uses the 7253value of this macro to select the debugging output format, but with two 7254exceptions. If @code{DWARF2_DEBUGGING_INFO} is defined and 7255@code{LINKER_DOES_NOT_WORK_WITH_DWARF2} is not defined, GCC uses the 7256value @code{DWARF2_DEBUG}. Otherwise, if @code{DBX_DEBUGGING_INFO} is 7257defined, GCC uses @code{DBX_DEBUG}. 7258 7259The value of this macro only affects the default debugging output; the 7260user can always get a specific type of output by using @option{-gstabs}, 7261@option{-gcoff}, @option{-gdwarf-1}, @option{-gdwarf-2}, @option{-gxcoff}, 7262or @option{-gvms}. 7263@end table 7264 7265@node DBX Options 7266@subsection Specific Options for DBX Output 7267 7268@c prevent bad page break with this line 7269These are specific options for DBX output. 7270 7271@table @code 7272@findex DBX_DEBUGGING_INFO 7273@item DBX_DEBUGGING_INFO 7274Define this macro if GCC should produce debugging output for DBX 7275in response to the @option{-g} option. 7276 7277@findex XCOFF_DEBUGGING_INFO 7278@item XCOFF_DEBUGGING_INFO 7279Define this macro if GCC should produce XCOFF format debugging output 7280in response to the @option{-g} option. This is a variant of DBX format. 7281 7282@findex DEFAULT_GDB_EXTENSIONS 7283@item DEFAULT_GDB_EXTENSIONS 7284Define this macro to control whether GCC should by default generate 7285GDB's extended version of DBX debugging information (assuming DBX-format 7286debugging information is enabled at all). If you don't define the 7287macro, the default is 1: always generate the extended information 7288if there is any occasion to. 7289 7290@findex DEBUG_SYMS_TEXT 7291@item DEBUG_SYMS_TEXT 7292Define this macro if all @code{.stabs} commands should be output while 7293in the text section. 7294 7295@findex ASM_STABS_OP 7296@item ASM_STABS_OP 7297A C string constant, including spacing, naming the assembler pseudo op to 7298use instead of @code{"\t.stabs\t"} to define an ordinary debugging symbol. 7299If you don't define this macro, @code{"\t.stabs\t"} is used. This macro 7300applies only to DBX debugging information format. 7301 7302@findex ASM_STABD_OP 7303@item ASM_STABD_OP 7304A C string constant, including spacing, naming the assembler pseudo op to 7305use instead of @code{"\t.stabd\t"} to define a debugging symbol whose 7306value is the current location. If you don't define this macro, 7307@code{"\t.stabd\t"} is used. This macro applies only to DBX debugging 7308information format. 7309 7310@findex ASM_STABN_OP 7311@item ASM_STABN_OP 7312A C string constant, including spacing, naming the assembler pseudo op to 7313use instead of @code{"\t.stabn\t"} to define a debugging symbol with no 7314name. If you don't define this macro, @code{"\t.stabn\t"} is used. This 7315macro applies only to DBX debugging information format. 7316 7317@findex DBX_NO_XREFS 7318@item DBX_NO_XREFS 7319Define this macro if DBX on your system does not support the construct 7320@samp{xs@var{tagname}}. On some systems, this construct is used to 7321describe a forward reference to a structure named @var{tagname}. 7322On other systems, this construct is not supported at all. 7323 7324@findex DBX_CONTIN_LENGTH 7325@item DBX_CONTIN_LENGTH 7326A symbol name in DBX-format debugging information is normally 7327continued (split into two separate @code{.stabs} directives) when it 7328exceeds a certain length (by default, 80 characters). On some 7329operating systems, DBX requires this splitting; on others, splitting 7330must not be done. You can inhibit splitting by defining this macro 7331with the value zero. You can override the default splitting-length by 7332defining this macro as an expression for the length you desire. 7333 7334@findex DBX_CONTIN_CHAR 7335@item DBX_CONTIN_CHAR 7336Normally continuation is indicated by adding a @samp{\} character to 7337the end of a @code{.stabs} string when a continuation follows. To use 7338a different character instead, define this macro as a character 7339constant for the character you want to use. Do not define this macro 7340if backslash is correct for your system. 7341 7342@findex DBX_STATIC_STAB_DATA_SECTION 7343@item DBX_STATIC_STAB_DATA_SECTION 7344Define this macro if it is necessary to go to the data section before 7345outputting the @samp{.stabs} pseudo-op for a non-global static 7346variable. 7347 7348@findex DBX_TYPE_DECL_STABS_CODE 7349@item DBX_TYPE_DECL_STABS_CODE 7350The value to use in the ``code'' field of the @code{.stabs} directive 7351for a typedef. The default is @code{N_LSYM}. 7352 7353@findex DBX_STATIC_CONST_VAR_CODE 7354@item DBX_STATIC_CONST_VAR_CODE 7355The value to use in the ``code'' field of the @code{.stabs} directive 7356for a static variable located in the text section. DBX format does not 7357provide any ``right'' way to do this. The default is @code{N_FUN}. 7358 7359@findex DBX_REGPARM_STABS_CODE 7360@item DBX_REGPARM_STABS_CODE 7361The value to use in the ``code'' field of the @code{.stabs} directive 7362for a parameter passed in registers. DBX format does not provide any 7363``right'' way to do this. The default is @code{N_RSYM}. 7364 7365@findex DBX_REGPARM_STABS_LETTER 7366@item DBX_REGPARM_STABS_LETTER 7367The letter to use in DBX symbol data to identify a symbol as a parameter 7368passed in registers. DBX format does not customarily provide any way to 7369do this. The default is @code{'P'}. 7370 7371@findex DBX_MEMPARM_STABS_LETTER 7372@item DBX_MEMPARM_STABS_LETTER 7373The letter to use in DBX symbol data to identify a symbol as a stack 7374parameter. The default is @code{'p'}. 7375 7376@findex DBX_FUNCTION_FIRST 7377@item DBX_FUNCTION_FIRST 7378Define this macro if the DBX information for a function and its 7379arguments should precede the assembler code for the function. Normally, 7380in DBX format, the debugging information entirely follows the assembler 7381code. 7382 7383@findex DBX_LBRAC_FIRST 7384@item DBX_LBRAC_FIRST 7385Define this macro if the @code{N_LBRAC} symbol for a block should 7386precede the debugging information for variables and functions defined in 7387that block. Normally, in DBX format, the @code{N_LBRAC} symbol comes 7388first. 7389 7390@findex DBX_BLOCKS_FUNCTION_RELATIVE 7391@item DBX_BLOCKS_FUNCTION_RELATIVE 7392Define this macro if the value of a symbol describing the scope of a 7393block (@code{N_LBRAC} or @code{N_RBRAC}) should be relative to the start 7394of the enclosing function. Normally, GCC uses an absolute address. 7395 7396@findex DBX_USE_BINCL 7397@item DBX_USE_BINCL 7398Define this macro if GCC should generate @code{N_BINCL} and 7399@code{N_EINCL} stabs for included header files, as on Sun systems. This 7400macro also directs GCC to output a type number as a pair of a file 7401number and a type number within the file. Normally, GCC does not 7402generate @code{N_BINCL} or @code{N_EINCL} stabs, and it outputs a single 7403number for a type number. 7404@end table 7405 7406@node DBX Hooks 7407@subsection Open-Ended Hooks for DBX Format 7408 7409@c prevent bad page break with this line 7410These are hooks for DBX format. 7411 7412@table @code 7413@findex DBX_OUTPUT_LBRAC 7414@item DBX_OUTPUT_LBRAC (@var{stream}, @var{name}) 7415Define this macro to say how to output to @var{stream} the debugging 7416information for the start of a scope level for variable names. The 7417argument @var{name} is the name of an assembler symbol (for use with 7418@code{assemble_name}) whose value is the address where the scope begins. 7419 7420@findex DBX_OUTPUT_RBRAC 7421@item DBX_OUTPUT_RBRAC (@var{stream}, @var{name}) 7422Like @code{DBX_OUTPUT_LBRAC}, but for the end of a scope level. 7423 7424@findex DBX_OUTPUT_ENUM 7425@item DBX_OUTPUT_ENUM (@var{stream}, @var{type}) 7426Define this macro if the target machine requires special handling to 7427output an enumeration type. The definition should be a C statement 7428(sans semicolon) to output the appropriate information to @var{stream} 7429for the type @var{type}. 7430 7431@findex DBX_OUTPUT_FUNCTION_END 7432@item DBX_OUTPUT_FUNCTION_END (@var{stream}, @var{function}) 7433Define this macro if the target machine requires special output at the 7434end of the debugging information for a function. The definition should 7435be a C statement (sans semicolon) to output the appropriate information 7436to @var{stream}. @var{function} is the @code{FUNCTION_DECL} node for 7437the function. 7438 7439@findex DBX_OUTPUT_STANDARD_TYPES 7440@item DBX_OUTPUT_STANDARD_TYPES (@var{syms}) 7441Define this macro if you need to control the order of output of the 7442standard data types at the beginning of compilation. The argument 7443@var{syms} is a @code{tree} which is a chain of all the predefined 7444global symbols, including names of data types. 7445 7446Normally, DBX output starts with definitions of the types for integers 7447and characters, followed by all the other predefined types of the 7448particular language in no particular order. 7449 7450On some machines, it is necessary to output different particular types 7451first. To do this, define @code{DBX_OUTPUT_STANDARD_TYPES} to output 7452those symbols in the necessary order. Any predefined types that you 7453don't explicitly output will be output afterward in no particular order. 7454 7455Be careful not to define this macro so that it works only for C@. There 7456are no global variables to access most of the built-in types, because 7457another language may have another set of types. The way to output a 7458particular type is to look through @var{syms} to see if you can find it. 7459Here is an example: 7460 7461@smallexample 7462@{ 7463 tree decl; 7464 for (decl = syms; decl; decl = TREE_CHAIN (decl)) 7465 if (!strcmp (IDENTIFIER_POINTER (DECL_NAME (decl)), 7466 "long int")) 7467 dbxout_symbol (decl); 7468 @dots{} 7469@} 7470@end smallexample 7471 7472@noindent 7473This does nothing if the expected type does not exist. 7474 7475See the function @code{init_decl_processing} in @file{c-decl.c} to find 7476the names to use for all the built-in C types. 7477 7478Here is another way of finding a particular type: 7479 7480@c this is still overfull. --mew 10feb93 7481@smallexample 7482@{ 7483 tree decl; 7484 for (decl = syms; decl; decl = TREE_CHAIN (decl)) 7485 if (TREE_CODE (decl) == TYPE_DECL 7486 && (TREE_CODE (TREE_TYPE (decl)) 7487 == INTEGER_CST) 7488 && TYPE_PRECISION (TREE_TYPE (decl)) == 16 7489 && TYPE_UNSIGNED (TREE_TYPE (decl))) 7490@group 7491 /* @r{This must be @code{unsigned short}.} */ 7492 dbxout_symbol (decl); 7493 @dots{} 7494@} 7495@end group 7496@end smallexample 7497 7498@findex NO_DBX_FUNCTION_END 7499@item NO_DBX_FUNCTION_END 7500Some stabs encapsulation formats (in particular ECOFF), cannot handle the 7501@code{.stabs "",N_FUN,,0,0,Lscope-function-1} gdb dbx extension construct. 7502On those machines, define this macro to turn this feature off without 7503disturbing the rest of the gdb extensions. 7504 7505@end table 7506 7507@node File Names and DBX 7508@subsection File Names in DBX Format 7509 7510@c prevent bad page break with this line 7511This describes file names in DBX format. 7512 7513@table @code 7514@findex DBX_WORKING_DIRECTORY 7515@item DBX_WORKING_DIRECTORY 7516Define this if DBX wants to have the current directory recorded in each 7517object file. 7518 7519Note that the working directory is always recorded if GDB extensions are 7520enabled. 7521 7522@findex DBX_OUTPUT_MAIN_SOURCE_FILENAME 7523@item DBX_OUTPUT_MAIN_SOURCE_FILENAME (@var{stream}, @var{name}) 7524A C statement to output DBX debugging information to the stdio stream 7525@var{stream} which indicates that file @var{name} is the main source 7526file---the file specified as the input file for compilation. 7527This macro is called only once, at the beginning of compilation. 7528 7529This macro need not be defined if the standard form of output 7530for DBX debugging information is appropriate. 7531 7532@findex DBX_OUTPUT_MAIN_SOURCE_DIRECTORY 7533@item DBX_OUTPUT_MAIN_SOURCE_DIRECTORY (@var{stream}, @var{name}) 7534A C statement to output DBX debugging information to the stdio stream 7535@var{stream} which indicates that the current directory during 7536compilation is named @var{name}. 7537 7538This macro need not be defined if the standard form of output 7539for DBX debugging information is appropriate. 7540 7541@findex DBX_OUTPUT_MAIN_SOURCE_FILE_END 7542@item DBX_OUTPUT_MAIN_SOURCE_FILE_END (@var{stream}, @var{name}) 7543A C statement to output DBX debugging information at the end of 7544compilation of the main source file @var{name}. 7545 7546If you don't define this macro, nothing special is output at the end 7547of compilation, which is correct for most machines. 7548 7549@findex DBX_OUTPUT_SOURCE_FILENAME 7550@item DBX_OUTPUT_SOURCE_FILENAME (@var{stream}, @var{name}) 7551A C statement to output DBX debugging information to the stdio stream 7552@var{stream} which indicates that file @var{name} is the current source 7553file. This output is generated each time input shifts to a different 7554source file as a result of @samp{#include}, the end of an included file, 7555or a @samp{#line} command. 7556 7557This macro need not be defined if the standard form of output 7558for DBX debugging information is appropriate. 7559@end table 7560 7561@need 2000 7562@node SDB and DWARF 7563@subsection Macros for SDB and DWARF Output 7564 7565@c prevent bad page break with this line 7566Here are macros for SDB and DWARF output. 7567 7568@table @code 7569@findex SDB_DEBUGGING_INFO 7570@item SDB_DEBUGGING_INFO 7571Define this macro if GCC should produce COFF-style debugging output 7572for SDB in response to the @option{-g} option. 7573 7574@findex DWARF_DEBUGGING_INFO 7575@item DWARF_DEBUGGING_INFO 7576Define this macro if GCC should produce dwarf format debugging output 7577in response to the @option{-g} option. 7578 7579@findex DWARF2_DEBUGGING_INFO 7580@item DWARF2_DEBUGGING_INFO 7581Define this macro if GCC should produce dwarf version 2 format 7582debugging output in response to the @option{-g} option. 7583 7584To support optional call frame debugging information, you must also 7585define @code{INCOMING_RETURN_ADDR_RTX} and either set 7586@code{RTX_FRAME_RELATED_P} on the prologue insns if you use RTL for the 7587prologue, or call @code{dwarf2out_def_cfa} and @code{dwarf2out_reg_save} 7588as appropriate from @code{TARGET_ASM_FUNCTION_PROLOGUE} if you don't. 7589 7590@findex DWARF2_FRAME_INFO 7591@item DWARF2_FRAME_INFO 7592Define this macro to a nonzero value if GCC should always output 7593Dwarf 2 frame information. If @code{DWARF2_UNWIND_INFO} 7594(@pxref{Exception Region Output} is nonzero, GCC will output this 7595information not matter how you define @code{DWARF2_FRAME_INFO}. 7596 7597@findex LINKER_DOES_NOT_WORK_WITH_DWARF2 7598@item LINKER_DOES_NOT_WORK_WITH_DWARF2 7599Define this macro if the linker does not work with Dwarf version 2. 7600Normally, if the user specifies only @option{-ggdb} GCC will use Dwarf 7601version 2 if available; this macro disables this. See the description 7602of the @code{PREFERRED_DEBUGGING_TYPE} macro for more details. 7603 7604@findex DWARF2_GENERATE_TEXT_SECTION_LABEL 7605@item DWARF2_GENERATE_TEXT_SECTION_LABEL 7606By default, the Dwarf 2 debugging information generator will generate a 7607label to mark the beginning of the text section. If it is better simply 7608to use the name of the text section itself, rather than an explicit label, 7609to indicate the beginning of the text section, define this macro to zero. 7610 7611@findex DWARF2_ASM_LINE_DEBUG_INFO 7612@item DWARF2_ASM_LINE_DEBUG_INFO 7613Define this macro to be a nonzero value if the assembler can generate Dwarf 2 7614line debug info sections. This will result in much more compact line number 7615tables, and hence is desirable if it works. 7616 7617@findex PUT_SDB_@dots{} 7618@item PUT_SDB_@dots{} 7619Define these macros to override the assembler syntax for the special 7620SDB assembler directives. See @file{sdbout.c} for a list of these 7621macros and their arguments. If the standard syntax is used, you need 7622not define them yourself. 7623 7624@findex SDB_DELIM 7625@item SDB_DELIM 7626Some assemblers do not support a semicolon as a delimiter, even between 7627SDB assembler directives. In that case, define this macro to be the 7628delimiter to use (usually @samp{\n}). It is not necessary to define 7629a new set of @code{PUT_SDB_@var{op}} macros if this is the only change 7630required. 7631 7632@findex SDB_GENERATE_FAKE 7633@item SDB_GENERATE_FAKE 7634Define this macro to override the usual method of constructing a dummy 7635name for anonymous structure and union types. See @file{sdbout.c} for 7636more information. 7637 7638@findex SDB_ALLOW_UNKNOWN_REFERENCES 7639@item SDB_ALLOW_UNKNOWN_REFERENCES 7640Define this macro to allow references to unknown structure, 7641union, or enumeration tags to be emitted. Standard COFF does not 7642allow handling of unknown references, MIPS ECOFF has support for 7643it. 7644 7645@findex SDB_ALLOW_FORWARD_REFERENCES 7646@item SDB_ALLOW_FORWARD_REFERENCES 7647Define this macro to allow references to structure, union, or 7648enumeration tags that have not yet been seen to be handled. Some 7649assemblers choke if forward tags are used, while some require it. 7650@end table 7651 7652@need 2000 7653@node VMS Debug 7654@subsection Macros for VMS Debug Format 7655 7656@c prevent bad page break with this line 7657Here are macros for VMS debug format. 7658 7659@table @code 7660@findex VMS_DEBUGGING_INFO 7661@item VMS_DEBUGGING_INFO 7662Define this macro if GCC should produce debugging output for VMS 7663in response to the @option{-g} option. The default behavior for VMS 7664is to generate minimal debug info for a traceback in the absence of 7665@option{-g} unless explicitly overridden with @option{-g0}. This 7666behavior is controlled by @code{OPTIMIZATION_OPTIONS} and 7667@code{OVERRIDE_OPTIONS}. 7668@end table 7669 7670@node Cross-compilation 7671@section Cross Compilation and Floating Point 7672@cindex cross compilation and floating point 7673@cindex floating point and cross compilation 7674 7675While all modern machines use 2's complement representation for integers, 7676there are a variety of representations for floating point numbers. This 7677means that in a cross-compiler the representation of floating point numbers 7678in the compiled program may be different from that used in the machine 7679doing the compilation. 7680 7681@findex atof 7682Because different representation systems may offer different amounts of 7683range and precision, the cross compiler cannot safely use the host 7684machine's floating point arithmetic. Therefore, floating point constants 7685must be represented in the target machine's format. This means that the 7686cross compiler cannot use @code{atof} to parse a floating point constant; 7687it must have its own special routine to use instead. Also, constant 7688folding must emulate the target machine's arithmetic (or must not be done 7689at all). 7690 7691The macros in the following table should be defined only if you are cross 7692compiling between different floating point formats. 7693 7694Otherwise, don't define them. Then default definitions will be set up which 7695use @code{double} as the data type, @code{==} to test for equality, etc. 7696 7697You don't need to worry about how many times you use an operand of any 7698of these macros. The compiler never uses operands which have side effects. 7699 7700@table @code 7701@findex REAL_VALUE_TYPE 7702@item REAL_VALUE_TYPE 7703A macro for the C data type to be used to hold a floating point value 7704in the target machine's format. Typically this would be a 7705@code{struct} containing an array of @code{int}. 7706 7707@findex REAL_VALUES_EQUAL 7708@item REAL_VALUES_EQUAL (@var{x}, @var{y}) 7709A macro for a C expression which compares for equality the two values, 7710@var{x} and @var{y}, both of type @code{REAL_VALUE_TYPE}. 7711 7712@findex REAL_VALUES_LESS 7713@item REAL_VALUES_LESS (@var{x}, @var{y}) 7714A macro for a C expression which tests whether @var{x} is less than 7715@var{y}, both values being of type @code{REAL_VALUE_TYPE} and 7716interpreted as floating point numbers in the target machine's 7717representation. 7718 7719@findex REAL_VALUE_LDEXP 7720@findex ldexp 7721@item REAL_VALUE_LDEXP (@var{x}, @var{scale}) 7722A macro for a C expression which performs the standard library 7723function @code{ldexp}, but using the target machine's floating point 7724representation. Both @var{x} and the value of the expression have 7725type @code{REAL_VALUE_TYPE}. The second argument, @var{scale}, is an 7726integer. 7727 7728@findex REAL_VALUE_FIX 7729@item REAL_VALUE_FIX (@var{x}) 7730A macro whose definition is a C expression to convert the target-machine 7731floating point value @var{x} to a signed integer. @var{x} has type 7732@code{REAL_VALUE_TYPE}. 7733 7734@findex REAL_VALUE_UNSIGNED_FIX 7735@item REAL_VALUE_UNSIGNED_FIX (@var{x}) 7736A macro whose definition is a C expression to convert the target-machine 7737floating point value @var{x} to an unsigned integer. @var{x} has type 7738@code{REAL_VALUE_TYPE}. 7739 7740@findex REAL_VALUE_RNDZINT 7741@item REAL_VALUE_RNDZINT (@var{x}) 7742A macro whose definition is a C expression to round the target-machine 7743floating point value @var{x} towards zero to an integer value (but still 7744as a floating point number). @var{x} has type @code{REAL_VALUE_TYPE}, 7745and so does the value. 7746 7747@findex REAL_VALUE_UNSIGNED_RNDZINT 7748@item REAL_VALUE_UNSIGNED_RNDZINT (@var{x}) 7749A macro whose definition is a C expression to round the target-machine 7750floating point value @var{x} towards zero to an unsigned integer value 7751(but still represented as a floating point number). @var{x} has type 7752@code{REAL_VALUE_TYPE}, and so does the value. 7753 7754@findex REAL_VALUE_ATOF 7755@item REAL_VALUE_ATOF (@var{string}, @var{mode}) 7756A macro for a C expression which converts @var{string}, an expression of 7757type @code{char *}, into a floating point number in the target machine's 7758representation for mode @var{mode}. The value has type 7759@code{REAL_VALUE_TYPE}. 7760 7761@findex REAL_INFINITY 7762@item REAL_INFINITY 7763Define this macro if infinity is a possible floating point value, and 7764therefore division by 0 is legitimate. 7765 7766@findex REAL_VALUE_ISINF 7767@findex isinf 7768@item REAL_VALUE_ISINF (@var{x}) 7769A macro for a C expression which determines whether @var{x}, a floating 7770point value, is infinity. The value has type @code{int}. 7771By default, this is defined to call @code{isinf}. 7772 7773@findex REAL_VALUE_ISNAN 7774@findex isnan 7775@item REAL_VALUE_ISNAN (@var{x}) 7776A macro for a C expression which determines whether @var{x}, a floating 7777point value, is a ``nan'' (not-a-number). The value has type 7778@code{int}. By default, this is defined to call @code{isnan}. 7779@end table 7780 7781@cindex constant folding and floating point 7782Define the following additional macros if you want to make floating 7783point constant folding work while cross compiling. If you don't 7784define them, cross compilation is still possible, but constant folding 7785will not happen for floating point values. 7786 7787@table @code 7788@findex REAL_ARITHMETIC 7789@item REAL_ARITHMETIC (@var{output}, @var{code}, @var{x}, @var{y}) 7790A macro for a C statement which calculates an arithmetic operation of 7791the two floating point values @var{x} and @var{y}, both of type 7792@code{REAL_VALUE_TYPE} in the target machine's representation, to 7793produce a result of the same type and representation which is stored 7794in @var{output} (which will be a variable). 7795 7796The operation to be performed is specified by @var{code}, a tree code 7797which will always be one of the following: @code{PLUS_EXPR}, 7798@code{MINUS_EXPR}, @code{MULT_EXPR}, @code{RDIV_EXPR}, 7799@code{MAX_EXPR}, @code{MIN_EXPR}. 7800 7801@cindex overflow while constant folding 7802The expansion of this macro is responsible for checking for overflow. 7803If overflow happens, the macro expansion should execute the statement 7804@code{return 0;}, which indicates the inability to perform the 7805arithmetic operation requested. 7806 7807@findex REAL_VALUE_NEGATE 7808@item REAL_VALUE_NEGATE (@var{x}) 7809A macro for a C expression which returns the negative of the floating 7810point value @var{x}. Both @var{x} and the value of the expression 7811have type @code{REAL_VALUE_TYPE} and are in the target machine's 7812floating point representation. 7813 7814There is no way for this macro to report overflow, since overflow 7815can't happen in the negation operation. 7816 7817@findex REAL_VALUE_TRUNCATE 7818@item REAL_VALUE_TRUNCATE (@var{mode}, @var{x}) 7819A macro for a C expression which converts the floating point value 7820@var{x} to mode @var{mode}. 7821 7822Both @var{x} and the value of the expression are in the target machine's 7823floating point representation and have type @code{REAL_VALUE_TYPE}. 7824However, the value should have an appropriate bit pattern to be output 7825properly as a floating constant whose precision accords with mode 7826@var{mode}. 7827 7828There is no way for this macro to report overflow. 7829 7830@findex REAL_VALUE_TO_INT 7831@item REAL_VALUE_TO_INT (@var{low}, @var{high}, @var{x}) 7832A macro for a C expression which converts a floating point value 7833@var{x} into a double-precision integer which is then stored into 7834@var{low} and @var{high}, two variables of type @var{int}. 7835 7836@item REAL_VALUE_FROM_INT (@var{x}, @var{low}, @var{high}, @var{mode}) 7837@findex REAL_VALUE_FROM_INT 7838A macro for a C expression which converts a double-precision integer 7839found in @var{low} and @var{high}, two variables of type @var{int}, 7840into a floating point value which is then stored into @var{x}. 7841The value is in the target machine's representation for mode @var{mode} 7842and has the type @code{REAL_VALUE_TYPE}. 7843@end table 7844 7845@node Mode Switching 7846@section Mode Switching Instructions 7847@cindex mode switching 7848The following macros control mode switching optimizations: 7849 7850@table @code 7851@findex OPTIMIZE_MODE_SWITCHING 7852@item OPTIMIZE_MODE_SWITCHING (@var{entity}) 7853Define this macro if the port needs extra instructions inserted for mode 7854switching in an optimizing compilation. 7855 7856For an example, the SH4 can perform both single and double precision 7857floating point operations, but to perform a single precision operation, 7858the FPSCR PR bit has to be cleared, while for a double precision 7859operation, this bit has to be set. Changing the PR bit requires a general 7860purpose register as a scratch register, hence these FPSCR sets have to 7861be inserted before reload, i.e.@: you can't put this into instruction emitting 7862or @code{MACHINE_DEPENDENT_REORG}. 7863 7864You can have multiple entities that are mode-switched, and select at run time 7865which entities actually need it. @code{OPTIMIZE_MODE_SWITCHING} should 7866return nonzero for any @var{entity} that needs mode-switching. 7867If you define this macro, you also have to define 7868@code{NUM_MODES_FOR_MODE_SWITCHING}, @code{MODE_NEEDED}, 7869@code{MODE_PRIORITY_TO_MODE} and @code{EMIT_MODE_SET}. 7870@code{NORMAL_MODE} is optional. 7871 7872@findex NUM_MODES_FOR_MODE_SWITCHING 7873@item NUM_MODES_FOR_MODE_SWITCHING 7874If you define @code{OPTIMIZE_MODE_SWITCHING}, you have to define this as 7875initializer for an array of integers. Each initializer element 7876N refers to an entity that needs mode switching, and specifies the number 7877of different modes that might need to be set for this entity. 7878The position of the initializer in the initializer - starting counting at 7879zero - determines the integer that is used to refer to the mode-switched 7880entity in question. 7881In macros that take mode arguments / yield a mode result, modes are 7882represented as numbers 0 @dots{} N @minus{} 1. N is used to specify that no mode 7883switch is needed / supplied. 7884 7885@findex MODE_NEEDED 7886@item MODE_NEEDED (@var{entity}, @var{insn}) 7887@var{entity} is an integer specifying a mode-switched entity. If 7888@code{OPTIMIZE_MODE_SWITCHING} is defined, you must define this macro to 7889return an integer value not larger than the corresponding element in 7890@code{NUM_MODES_FOR_MODE_SWITCHING}, to denote the mode that @var{entity} must 7891be switched into prior to the execution of @var{insn}. 7892 7893@findex NORMAL_MODE 7894@item NORMAL_MODE (@var{entity}) 7895If this macro is defined, it is evaluated for every @var{entity} that needs 7896mode switching. It should evaluate to an integer, which is a mode that 7897@var{entity} is assumed to be switched to at function entry and exit. 7898 7899@findex MODE_PRIORITY_TO_MODE 7900@item MODE_PRIORITY_TO_MODE (@var{entity}, @var{n}) 7901This macro specifies the order in which modes for @var{entity} are processed. 79020 is the highest priority, @code{NUM_MODES_FOR_MODE_SWITCHING[@var{entity}] - 1} the 7903lowest. The value of the macro should be an integer designating a mode 7904for @var{entity}. For any fixed @var{entity}, @code{mode_priority_to_mode} 7905(@var{entity}, @var{n}) shall be a bijection in 0 @dots{} 7906@code{num_modes_for_mode_switching[@var{entity}] - 1}. 7907 7908@findex EMIT_MODE_SET 7909@item EMIT_MODE_SET (@var{entity}, @var{mode}, @var{hard_regs_live}) 7910Generate one or more insns to set @var{entity} to @var{mode}. 7911@var{hard_reg_live} is the set of hard registers live at the point where 7912the insn(s) are to be inserted. 7913@end table 7914 7915@node Target Attributes 7916@section Defining target-specific uses of @code{__attribute__} 7917@cindex target attributes 7918@cindex machine attributes 7919@cindex attributes, target-specific 7920 7921Target-specific attributes may be defined for functions, data and types. 7922These are described using the following target hooks; they also need to 7923be documented in @file{extend.texi}. 7924 7925@deftypevr {Target Hook} {const struct attribute_spec *} TARGET_ATTRIBUTE_TABLE 7926If defined, this target hook points to an array of @samp{struct 7927attribute_spec} (defined in @file{tree.h}) specifying the machine 7928specific attributes for this target and some of the restrictions on the 7929entities to which these attributes are applied and the arguments they 7930take. 7931@end deftypevr 7932 7933@deftypefn {Target Hook} int TARGET_COMP_TYPE_ATTRIBUTES (tree @var{type1}, tree @var{type2}) 7934If defined, this target hook is a function which returns zero if the attributes on 7935@var{type1} and @var{type2} are incompatible, one if they are compatible, 7936and two if they are nearly compatible (which causes a warning to be 7937generated). If this is not defined, machine-specific attributes are 7938supposed always to be compatible. 7939@end deftypefn 7940 7941@deftypefn {Target Hook} void TARGET_SET_DEFAULT_TYPE_ATTRIBUTES (tree @var{type}) 7942If defined, this target hook is a function which assigns default attributes to 7943newly defined @var{type}. 7944@end deftypefn 7945 7946@deftypefn {Target Hook} tree TARGET_MERGE_TYPE_ATTRIBUTES (tree @var{type1}, tree @var{type2}) 7947Define this target hook if the merging of type attributes needs special 7948handling. If defined, the result is a list of the combined 7949@code{TYPE_ATTRIBUTES} of @var{type1} and @var{type2}. It is assumed 7950that @code{comptypes} has already been called and returned 1. This 7951function may call @code{merge_attributes} to handle machine-independent 7952merging. 7953@end deftypefn 7954 7955@deftypefn {Target Hook} tree TARGET_MERGE_DECL_ATTRIBUTES (tree @var{olddecl}, tree @var{newdecl}) 7956Define this target hook if the merging of decl attributes needs special 7957handling. If defined, the result is a list of the combined 7958@code{DECL_ATTRIBUTES} of @var{olddecl} and @var{newdecl}. 7959@var{newdecl} is a duplicate declaration of @var{olddecl}. Examples of 7960when this is needed are when one attribute overrides another, or when an 7961attribute is nullified by a subsequent definition. This function may 7962call @code{merge_attributes} to handle machine-independent merging. 7963 7964@findex TARGET_DLLIMPORT_DECL_ATTRIBUTES 7965If the only target-specific handling you require is @samp{dllimport} for 7966Windows targets, you should define the macro 7967@code{TARGET_DLLIMPORT_DECL_ATTRIBUTES}. This links in a function 7968called @code{merge_dllimport_decl_attributes} which can then be defined 7969as the expansion of @code{TARGET_MERGE_DECL_ATTRIBUTES}. This is done 7970in @file{i386/cygwin.h} and @file{i386/i386.c}, for example. 7971@end deftypefn 7972 7973@deftypefn {Target Hook} void TARGET_INSERT_ATTRIBUTES (tree @var{node}, tree *@var{attr_ptr}) 7974Define this target hook if you want to be able to add attributes to a decl 7975when it is being created. This is normally useful for back ends which 7976wish to implement a pragma by using the attributes which correspond to 7977the pragma's effect. The @var{node} argument is the decl which is being 7978created. The @var{attr_ptr} argument is a pointer to the attribute list 7979for this decl. The list itself should not be modified, since it may be 7980shared with other decls, but attributes may be chained on the head of 7981the list and @code{*@var{attr_ptr}} modified to point to the new 7982attributes, or a copy of the list may be made if further changes are 7983needed. 7984@end deftypefn 7985 7986@deftypefn {Target Hook} bool TARGET_FUNCTION_ATTRIBUTE_INLINABLE_P (tree @var{fndecl}) 7987@cindex inlining 7988This target hook returns @code{true} if it is ok to inline @var{fndecl} 7989into the current function, despite its having target-specific 7990attributes, @code{false} otherwise. By default, if a function has a 7991target specific attribute attached to it, it will not be inlined. 7992@end deftypefn 7993 7994@node Misc 7995@section Miscellaneous Parameters 7996@cindex parameters, miscellaneous 7997 7998@c prevent bad page break with this line 7999Here are several miscellaneous parameters. 8000 8001@table @code 8002@item PREDICATE_CODES 8003@findex PREDICATE_CODES 8004Define this if you have defined special-purpose predicates in the file 8005@file{@var{machine}.c}. This macro is called within an initializer of an 8006array of structures. The first field in the structure is the name of a 8007predicate and the second field is an array of rtl codes. For each 8008predicate, list all rtl codes that can be in expressions matched by the 8009predicate. The list should have a trailing comma. Here is an example 8010of two entries in the list for a typical RISC machine: 8011 8012@smallexample 8013#define PREDICATE_CODES \ 8014 @{"gen_reg_rtx_operand", @{SUBREG, REG@}@}, \ 8015 @{"reg_or_short_cint_operand", @{SUBREG, REG, CONST_INT@}@}, 8016@end smallexample 8017 8018Defining this macro does not affect the generated code (however, 8019incorrect definitions that omit an rtl code that may be matched by the 8020predicate can cause the compiler to malfunction). Instead, it allows 8021the table built by @file{genrecog} to be more compact and efficient, 8022thus speeding up the compiler. The most important predicates to include 8023in the list specified by this macro are those used in the most insn 8024patterns. 8025 8026For each predicate function named in @code{PREDICATE_CODES}, a 8027declaration will be generated in @file{insn-codes.h}. 8028 8029@item SPECIAL_MODE_PREDICATES 8030@findex SPECIAL_MODE_PREDICATES 8031Define this if you have special predicates that know special things 8032about modes. Genrecog will warn about certain forms of 8033@code{match_operand} without a mode; if the operand predicate is 8034listed in @code{SPECIAL_MODE_PREDICATES}, the warning will be 8035suppressed. 8036 8037Here is an example from the IA-32 port (@code{ext_register_operand} 8038specially checks for @code{HImode} or @code{SImode} in preparation 8039for a byte extraction from @code{%ah} etc.). 8040 8041@smallexample 8042#define SPECIAL_MODE_PREDICATES \ 8043 "ext_register_operand", 8044@end smallexample 8045 8046@findex CASE_VECTOR_MODE 8047@item CASE_VECTOR_MODE 8048An alias for a machine mode name. This is the machine mode that 8049elements of a jump-table should have. 8050 8051@findex CASE_VECTOR_SHORTEN_MODE 8052@item CASE_VECTOR_SHORTEN_MODE (@var{min_offset}, @var{max_offset}, @var{body}) 8053Optional: return the preferred mode for an @code{addr_diff_vec} 8054when the minimum and maximum offset are known. If you define this, 8055it enables extra code in branch shortening to deal with @code{addr_diff_vec}. 8056To make this work, you also have to define INSN_ALIGN and 8057make the alignment for @code{addr_diff_vec} explicit. 8058The @var{body} argument is provided so that the offset_unsigned and scale 8059flags can be updated. 8060 8061@findex CASE_VECTOR_PC_RELATIVE 8062@item CASE_VECTOR_PC_RELATIVE 8063Define this macro to be a C expression to indicate when jump-tables 8064should contain relative addresses. If jump-tables never contain 8065relative addresses, then you need not define this macro. 8066 8067@findex CASE_DROPS_THROUGH 8068@item CASE_DROPS_THROUGH 8069Define this if control falls through a @code{case} insn when the index 8070value is out of range. This means the specified default-label is 8071actually ignored by the @code{case} insn proper. 8072 8073@findex CASE_VALUES_THRESHOLD 8074@item CASE_VALUES_THRESHOLD 8075Define this to be the smallest number of different values for which it 8076is best to use a jump-table instead of a tree of conditional branches. 8077The default is four for machines with a @code{casesi} instruction and 8078five otherwise. This is best for most machines. 8079 8080@findex WORD_REGISTER_OPERATIONS 8081@item WORD_REGISTER_OPERATIONS 8082Define this macro if operations between registers with integral mode 8083smaller than a word are always performed on the entire register. 8084Most RISC machines have this property and most CISC machines do not. 8085 8086@findex LOAD_EXTEND_OP 8087@item LOAD_EXTEND_OP (@var{mode}) 8088Define this macro to be a C expression indicating when insns that read 8089memory in @var{mode}, an integral mode narrower than a word, set the 8090bits outside of @var{mode} to be either the sign-extension or the 8091zero-extension of the data read. Return @code{SIGN_EXTEND} for values 8092of @var{mode} for which the 8093insn sign-extends, @code{ZERO_EXTEND} for which it zero-extends, and 8094@code{NIL} for other modes. 8095 8096This macro is not called with @var{mode} non-integral or with a width 8097greater than or equal to @code{BITS_PER_WORD}, so you may return any 8098value in this case. Do not define this macro if it would always return 8099@code{NIL}. On machines where this macro is defined, you will normally 8100define it as the constant @code{SIGN_EXTEND} or @code{ZERO_EXTEND}. 8101 8102@findex SHORT_IMMEDIATES_SIGN_EXTEND 8103@item SHORT_IMMEDIATES_SIGN_EXTEND 8104Define this macro if loading short immediate values into registers sign 8105extends. 8106 8107@findex FIXUNS_TRUNC_LIKE_FIX_TRUNC 8108@item FIXUNS_TRUNC_LIKE_FIX_TRUNC 8109Define this macro if the same instructions that convert a floating 8110point number to a signed fixed point number also convert validly to an 8111unsigned one. 8112 8113@findex MOVE_MAX 8114@item MOVE_MAX 8115The maximum number of bytes that a single instruction can move quickly 8116between memory and registers or between two memory locations. 8117 8118@findex MAX_MOVE_MAX 8119@item MAX_MOVE_MAX 8120The maximum number of bytes that a single instruction can move quickly 8121between memory and registers or between two memory locations. If this 8122is undefined, the default is @code{MOVE_MAX}. Otherwise, it is the 8123constant value that is the largest value that @code{MOVE_MAX} can have 8124at run-time. 8125 8126@findex SHIFT_COUNT_TRUNCATED 8127@item SHIFT_COUNT_TRUNCATED 8128A C expression that is nonzero if on this machine the number of bits 8129actually used for the count of a shift operation is equal to the number 8130of bits needed to represent the size of the object being shifted. When 8131this macro is nonzero, the compiler will assume that it is safe to omit 8132a sign-extend, zero-extend, and certain bitwise `and' instructions that 8133truncates the count of a shift operation. On machines that have 8134instructions that act on bit-fields at variable positions, which may 8135include `bit test' instructions, a nonzero @code{SHIFT_COUNT_TRUNCATED} 8136also enables deletion of truncations of the values that serve as 8137arguments to bit-field instructions. 8138 8139If both types of instructions truncate the count (for shifts) and 8140position (for bit-field operations), or if no variable-position bit-field 8141instructions exist, you should define this macro. 8142 8143However, on some machines, such as the 80386 and the 680x0, truncation 8144only applies to shift operations and not the (real or pretended) 8145bit-field operations. Define @code{SHIFT_COUNT_TRUNCATED} to be zero on 8146such machines. Instead, add patterns to the @file{md} file that include 8147the implied truncation of the shift instructions. 8148 8149You need not define this macro if it would always have the value of zero. 8150 8151@findex TRULY_NOOP_TRUNCATION 8152@item TRULY_NOOP_TRUNCATION (@var{outprec}, @var{inprec}) 8153A C expression which is nonzero if on this machine it is safe to 8154``convert'' an integer of @var{inprec} bits to one of @var{outprec} 8155bits (where @var{outprec} is smaller than @var{inprec}) by merely 8156operating on it as if it had only @var{outprec} bits. 8157 8158On many machines, this expression can be 1. 8159 8160@c rearranged this, removed the phrase "it is reported that". this was 8161@c to fix an overfull hbox. --mew 10feb93 8162When @code{TRULY_NOOP_TRUNCATION} returns 1 for a pair of sizes for 8163modes for which @code{MODES_TIEABLE_P} is 0, suboptimal code can result. 8164If this is the case, making @code{TRULY_NOOP_TRUNCATION} return 0 in 8165such cases may improve things. 8166 8167@findex STORE_FLAG_VALUE 8168@item STORE_FLAG_VALUE 8169A C expression describing the value returned by a comparison operator 8170with an integral mode and stored by a store-flag instruction 8171(@samp{s@var{cond}}) when the condition is true. This description must 8172apply to @emph{all} the @samp{s@var{cond}} patterns and all the 8173comparison operators whose results have a @code{MODE_INT} mode. 8174 8175A value of 1 or @minus{}1 means that the instruction implementing the 8176comparison operator returns exactly 1 or @minus{}1 when the comparison is true 8177and 0 when the comparison is false. Otherwise, the value indicates 8178which bits of the result are guaranteed to be 1 when the comparison is 8179true. This value is interpreted in the mode of the comparison 8180operation, which is given by the mode of the first operand in the 8181@samp{s@var{cond}} pattern. Either the low bit or the sign bit of 8182@code{STORE_FLAG_VALUE} be on. Presently, only those bits are used by 8183the compiler. 8184 8185If @code{STORE_FLAG_VALUE} is neither 1 or @minus{}1, the compiler will 8186generate code that depends only on the specified bits. It can also 8187replace comparison operators with equivalent operations if they cause 8188the required bits to be set, even if the remaining bits are undefined. 8189For example, on a machine whose comparison operators return an 8190@code{SImode} value and where @code{STORE_FLAG_VALUE} is defined as 8191@samp{0x80000000}, saying that just the sign bit is relevant, the 8192expression 8193 8194@smallexample 8195(ne:SI (and:SI @var{x} (const_int @var{power-of-2})) (const_int 0)) 8196@end smallexample 8197 8198@noindent 8199can be converted to 8200 8201@smallexample 8202(ashift:SI @var{x} (const_int @var{n})) 8203@end smallexample 8204 8205@noindent 8206where @var{n} is the appropriate shift count to move the bit being 8207tested into the sign bit. 8208 8209There is no way to describe a machine that always sets the low-order bit 8210for a true value, but does not guarantee the value of any other bits, 8211but we do not know of any machine that has such an instruction. If you 8212are trying to port GCC to such a machine, include an instruction to 8213perform a logical-and of the result with 1 in the pattern for the 8214comparison operators and let us know at @email{gcc@@gcc.gnu.org}. 8215 8216Often, a machine will have multiple instructions that obtain a value 8217from a comparison (or the condition codes). Here are rules to guide the 8218choice of value for @code{STORE_FLAG_VALUE}, and hence the instructions 8219to be used: 8220 8221@itemize @bullet 8222@item 8223Use the shortest sequence that yields a valid definition for 8224@code{STORE_FLAG_VALUE}. It is more efficient for the compiler to 8225``normalize'' the value (convert it to, e.g., 1 or 0) than for the 8226comparison operators to do so because there may be opportunities to 8227combine the normalization with other operations. 8228 8229@item 8230For equal-length sequences, use a value of 1 or @minus{}1, with @minus{}1 being 8231slightly preferred on machines with expensive jumps and 1 preferred on 8232other machines. 8233 8234@item 8235As a second choice, choose a value of @samp{0x80000001} if instructions 8236exist that set both the sign and low-order bits but do not define the 8237others. 8238 8239@item 8240Otherwise, use a value of @samp{0x80000000}. 8241@end itemize 8242 8243Many machines can produce both the value chosen for 8244@code{STORE_FLAG_VALUE} and its negation in the same number of 8245instructions. On those machines, you should also define a pattern for 8246those cases, e.g., one matching 8247 8248@smallexample 8249(set @var{A} (neg:@var{m} (ne:@var{m} @var{B} @var{C}))) 8250@end smallexample 8251 8252Some machines can also perform @code{and} or @code{plus} operations on 8253condition code values with less instructions than the corresponding 8254@samp{s@var{cond}} insn followed by @code{and} or @code{plus}. On those 8255machines, define the appropriate patterns. Use the names @code{incscc} 8256and @code{decscc}, respectively, for the patterns which perform 8257@code{plus} or @code{minus} operations on condition code values. See 8258@file{rs6000.md} for some examples. The GNU Superoptizer can be used to 8259find such instruction sequences on other machines. 8260 8261You need not define @code{STORE_FLAG_VALUE} if the machine has no store-flag 8262instructions. 8263 8264@findex FLOAT_STORE_FLAG_VALUE 8265@item FLOAT_STORE_FLAG_VALUE (@var{mode}) 8266A C expression that gives a nonzero @code{REAL_VALUE_TYPE} value that is 8267returned when comparison operators with floating-point results are true. 8268Define this macro on machine that have comparison operations that return 8269floating-point values. If there are no such operations, do not define 8270this macro. 8271 8272@findex Pmode 8273@item Pmode 8274An alias for the machine mode for pointers. On most machines, define 8275this to be the integer mode corresponding to the width of a hardware 8276pointer; @code{SImode} on 32-bit machine or @code{DImode} on 64-bit machines. 8277On some machines you must define this to be one of the partial integer 8278modes, such as @code{PSImode}. 8279 8280The width of @code{Pmode} must be at least as large as the value of 8281@code{POINTER_SIZE}. If it is not equal, you must define the macro 8282@code{POINTERS_EXTEND_UNSIGNED} to specify how pointers are extended 8283to @code{Pmode}. 8284 8285@findex FUNCTION_MODE 8286@item FUNCTION_MODE 8287An alias for the machine mode used for memory references to functions 8288being called, in @code{call} RTL expressions. On most machines this 8289should be @code{QImode}. 8290 8291@findex INTEGRATE_THRESHOLD 8292@item INTEGRATE_THRESHOLD (@var{decl}) 8293A C expression for the maximum number of instructions above which the 8294function @var{decl} should not be inlined. @var{decl} is a 8295@code{FUNCTION_DECL} node. 8296 8297The default definition of this macro is 64 plus 8 times the number of 8298arguments that the function accepts. Some people think a larger 8299threshold should be used on RISC machines. 8300 8301@findex STDC_0_IN_SYSTEM_HEADERS 8302@item STDC_0_IN_SYSTEM_HEADERS 8303In normal operation, the preprocessor expands @code{__STDC__} to the 8304constant 1, to signify that GCC conforms to ISO Standard C@. On some 8305hosts, like Solaris, the system compiler uses a different convention, 8306where @code{__STDC__} is normally 0, but is 1 if the user specifies 8307strict conformance to the C Standard. 8308 8309Defining @code{STDC_0_IN_SYSTEM_HEADERS} makes GNU CPP follows the host 8310convention when processing system header files, but when processing user 8311files @code{__STDC__} will always expand to 1. 8312 8313@findex SCCS_DIRECTIVE 8314@item SCCS_DIRECTIVE 8315Define this if the preprocessor should ignore @code{#sccs} directives 8316and print no error message. 8317 8318@findex NO_IMPLICIT_EXTERN_C 8319@item NO_IMPLICIT_EXTERN_C 8320Define this macro if the system header files support C++ as well as C@. 8321This macro inhibits the usual method of using system header files in 8322C++, which is to pretend that the file's contents are enclosed in 8323@samp{extern "C" @{@dots{}@}}. 8324 8325@findex HANDLE_PRAGMA 8326@item HANDLE_PRAGMA (@var{getc}, @var{ungetc}, @var{name}) 8327This macro is no longer supported. You must use 8328@code{REGISTER_TARGET_PRAGMAS} instead. 8329 8330@findex REGISTER_TARGET_PRAGMAS 8331@findex #pragma 8332@findex pragma 8333@item REGISTER_TARGET_PRAGMAS (@var{pfile}) 8334Define this macro if you want to implement any target-specific pragmas. 8335If defined, it is a C expression which makes a series of calls to 8336@code{cpp_register_pragma} for each pragma, with @var{pfile} passed as 8337the first argument to to these functions. The macro may also do any 8338setup required for the pragmas. 8339 8340The primary reason to define this macro is to provide compatibility with 8341other compilers for the same target. In general, we discourage 8342definition of target-specific pragmas for GCC@. 8343 8344If the pragma can be implemented by attributes then you should consider 8345defining the target hook @samp{TARGET_INSERT_ATTRIBUTES} as well. 8346 8347Preprocessor macros that appear on pragma lines are not expanded. All 8348@samp{#pragma} directives that do not match any registered pragma are 8349silently ignored, unless the user specifies @option{-Wunknown-pragmas}. 8350 8351@deftypefun void cpp_register_pragma (cpp_reader *@var{pfile}, const char *@var{space}, const char *@var{name}, void (*@var{callback}) (cpp_reader *)) 8352 8353Each call to @code{cpp_register_pragma} establishes one pragma. The 8354@var{callback} routine will be called when the preprocessor encounters a 8355pragma of the form 8356 8357@smallexample 8358#pragma [@var{space}] @var{name} @dots{} 8359@end smallexample 8360 8361@var{space} is the case-sensitive namespace of the pragma, or 8362@code{NULL} to put the pragma in the global namespace. The callback 8363routine receives @var{pfile} as its first argument, which can be passed 8364on to cpplib's functions if necessary. You can lex tokens after the 8365@var{name} by calling @code{c_lex}. Tokens that are not read by the 8366callback will be silently ignored. The end of the line is indicated by 8367a token of type @code{CPP_EOF}. 8368 8369For an example use of this routine, see @file{c4x.h} and the callback 8370routines defined in @file{c4x-c.c}. 8371 8372Note that the use of @code{c_lex} is specific to the C and C++ 8373compilers. It will not work in the Java or Fortran compilers, or any 8374other language compilers for that matter. Thus if @code{c_lex} is going 8375to be called from target-specific code, it must only be done so when 8376building the C and C++ compilers. This can be done by defining the 8377variables @code{c_target_objs} and @code{cxx_target_objs} in the 8378target entry in the @file{config.gcc} file. These variables should name 8379the target-specific, language-specific object file which contains the 8380code that uses @code{c_lex}. Note it will also be necessary to add a 8381rule to the makefile fragment pointed to by @code{tmake_file} that shows 8382how to build this object file. 8383@end deftypefun 8384 8385@findex HANDLE_SYSV_PRAGMA 8386@findex #pragma 8387@findex pragma 8388@item HANDLE_SYSV_PRAGMA 8389Define this macro (to a value of 1) if you want the System V style 8390pragmas @samp{#pragma pack(<n>)} and @samp{#pragma weak <name> 8391[=<value>]} to be supported by gcc. 8392 8393The pack pragma specifies the maximum alignment (in bytes) of fields 8394within a structure, in much the same way as the @samp{__aligned__} and 8395@samp{__packed__} @code{__attribute__}s do. A pack value of zero resets 8396the behavior to the default. 8397 8398The weak pragma only works if @code{SUPPORTS_WEAK} and 8399@code{ASM_WEAKEN_LABEL} are defined. If enabled it allows the creation 8400of specifically named weak labels, optionally with a value. 8401 8402@findex HANDLE_PRAGMA_PACK_PUSH_POP 8403@findex #pragma 8404@findex pragma 8405@item HANDLE_PRAGMA_PACK_PUSH_POP 8406Define this macro (to a value of 1) if you want to support the Win32 8407style pragmas @samp{#pragma pack(push,@var{n})} and @samp{#pragma 8408pack(pop)}. The @samp{pack(push,@var{n})} pragma specifies the maximum alignment 8409(in bytes) of fields within a structure, in much the same way as the 8410@samp{__aligned__} and @samp{__packed__} @code{__attribute__}s do. A 8411pack value of zero resets the behavior to the default. Successive 8412invocations of this pragma cause the previous values to be stacked, so 8413that invocations of @samp{#pragma pack(pop)} will return to the previous 8414value. 8415 8416@findex DOLLARS_IN_IDENTIFIERS 8417@item DOLLARS_IN_IDENTIFIERS 8418Define this macro to control use of the character @samp{$} in identifier 8419names. 0 means @samp{$} is not allowed by default; 1 means it is allowed. 84201 is the default; there is no need to define this macro in that case. 8421This macro controls the compiler proper; it does not affect the preprocessor. 8422 8423@findex NO_DOLLAR_IN_LABEL 8424@item NO_DOLLAR_IN_LABEL 8425Define this macro if the assembler does not accept the character 8426@samp{$} in label names. By default constructors and destructors in 8427G++ have @samp{$} in the identifiers. If this macro is defined, 8428@samp{.} is used instead. 8429 8430@findex NO_DOT_IN_LABEL 8431@item NO_DOT_IN_LABEL 8432Define this macro if the assembler does not accept the character 8433@samp{.} in label names. By default constructors and destructors in G++ 8434have names that use @samp{.}. If this macro is defined, these names 8435are rewritten to avoid @samp{.}. 8436 8437@findex DEFAULT_MAIN_RETURN 8438@item DEFAULT_MAIN_RETURN 8439Define this macro if the target system expects every program's @code{main} 8440function to return a standard ``success'' value by default (if no other 8441value is explicitly returned). 8442 8443The definition should be a C statement (sans semicolon) to generate the 8444appropriate rtl instructions. It is used only when compiling the end of 8445@code{main}. 8446 8447@item NEED_ATEXIT 8448@findex NEED_ATEXIT 8449Define this if the target system lacks the function @code{atexit} 8450from the ISO C standard. If this macro is defined, a default definition 8451will be provided to support C++. If @code{ON_EXIT} is not defined, 8452a default @code{exit} function will also be provided. 8453 8454@item ON_EXIT 8455@findex ON_EXIT 8456Define this macro if the target has another way to implement atexit 8457functionality without replacing @code{exit}. For instance, SunOS 4 has 8458a similar @code{on_exit} library function. 8459 8460The definition should be a functional macro which can be used just like 8461the @code{atexit} function. 8462 8463@item EXIT_BODY 8464@findex EXIT_BODY 8465Define this if your @code{exit} function needs to do something 8466besides calling an external function @code{_cleanup} before 8467terminating with @code{_exit}. The @code{EXIT_BODY} macro is 8468only needed if @code{NEED_ATEXIT} is defined and @code{ON_EXIT} is not 8469defined. 8470 8471@findex INSN_SETS_ARE_DELAYED 8472@item INSN_SETS_ARE_DELAYED (@var{insn}) 8473Define this macro as a C expression that is nonzero if it is safe for the 8474delay slot scheduler to place instructions in the delay slot of @var{insn}, 8475even if they appear to use a resource set or clobbered in @var{insn}. 8476@var{insn} is always a @code{jump_insn} or an @code{insn}; GCC knows that 8477every @code{call_insn} has this behavior. On machines where some @code{insn} 8478or @code{jump_insn} is really a function call and hence has this behavior, 8479you should define this macro. 8480 8481You need not define this macro if it would always return zero. 8482 8483@findex INSN_REFERENCES_ARE_DELAYED 8484@item INSN_REFERENCES_ARE_DELAYED (@var{insn}) 8485Define this macro as a C expression that is nonzero if it is safe for the 8486delay slot scheduler to place instructions in the delay slot of @var{insn}, 8487even if they appear to set or clobber a resource referenced in @var{insn}. 8488@var{insn} is always a @code{jump_insn} or an @code{insn}. On machines where 8489some @code{insn} or @code{jump_insn} is really a function call and its operands 8490are registers whose use is actually in the subroutine it calls, you should 8491define this macro. Doing so allows the delay slot scheduler to move 8492instructions which copy arguments into the argument registers into the delay 8493slot of @var{insn}. 8494 8495You need not define this macro if it would always return zero. 8496 8497@findex MACHINE_DEPENDENT_REORG 8498@item MACHINE_DEPENDENT_REORG (@var{insn}) 8499In rare cases, correct code generation requires extra machine 8500dependent processing between the second jump optimization pass and 8501delayed branch scheduling. On those machines, define this macro as a C 8502statement to act on the code starting at @var{insn}. 8503 8504@findex MULTIPLE_SYMBOL_SPACES 8505@item MULTIPLE_SYMBOL_SPACES 8506Define this macro if in some cases global symbols from one translation 8507unit may not be bound to undefined symbols in another translation unit 8508without user intervention. For instance, under Microsoft Windows 8509symbols must be explicitly imported from shared libraries (DLLs). 8510 8511@findex MD_ASM_CLOBBERS 8512@item MD_ASM_CLOBBERS (@var{clobbers}) 8513A C statement that adds to @var{clobbers} @code{STRING_CST} trees for 8514any hard regs the port wishes to automatically clobber for all asms. 8515 8516@findex MAX_INTEGER_COMPUTATION_MODE 8517@item MAX_INTEGER_COMPUTATION_MODE 8518Define this to the largest integer machine mode which can be used for 8519operations other than load, store and copy operations. 8520 8521You need only define this macro if the target holds values larger than 8522@code{word_mode} in general purpose registers. Most targets should not define 8523this macro. 8524 8525@findex MATH_LIBRARY 8526@item MATH_LIBRARY 8527Define this macro as a C string constant for the linker argument to link 8528in the system math library, or @samp{""} if the target does not have a 8529separate math library. 8530 8531You need only define this macro if the default of @samp{"-lm"} is wrong. 8532 8533@findex LIBRARY_PATH_ENV 8534@item LIBRARY_PATH_ENV 8535Define this macro as a C string constant for the environment variable that 8536specifies where the linker should look for libraries. 8537 8538You need only define this macro if the default of @samp{"LIBRARY_PATH"} 8539is wrong. 8540 8541@findex TARGET_HAS_F_SETLKW 8542@item TARGET_HAS_F_SETLKW 8543Define this macro if the target supports file locking with fcntl / F_SETLKW@. 8544Note that this functionality is part of POSIX@. 8545Defining @code{TARGET_HAS_F_SETLKW} will enable the test coverage code 8546to use file locking when exiting a program, which avoids race conditions 8547if the program has forked. 8548 8549@findex MAX_CONDITIONAL_EXECUTE 8550@item MAX_CONDITIONAL_EXECUTE 8551 8552A C expression for the maximum number of instructions to execute via 8553conditional execution instructions instead of a branch. A value of 8554@code{BRANCH_COST}+1 is the default if the machine does not use cc0, and 85551 if it does use cc0. 8556 8557@findex IFCVT_MODIFY_TESTS 8558@item IFCVT_MODIFY_TESTS 8559A C expression to modify the tests in @code{TRUE_EXPR}, and 8560@code{FALSE_EXPR} for use in converting insns in @code{TEST_BB}, 8561@code{THEN_BB}, @code{ELSE_BB}, and @code{JOIN_BB} basic blocks to 8562conditional execution. Set either @code{TRUE_EXPR} or @code{FALSE_EXPR} 8563to a null pointer if the tests cannot be converted. 8564 8565@findex IFCVT_MODIFY_INSN 8566@item IFCVT_MODIFY_INSN 8567A C expression to modify the @code{PATTERN} of an @code{INSN} that is to 8568be converted to conditional execution format. 8569 8570@findex IFCVT_MODIFY_FINAL 8571@item IFCVT_MODIFY_FINAL 8572A C expression to perform any final machine dependent modifications in 8573converting code to conditional execution in the basic blocks 8574@code{TEST_BB}, @code{THEN_BB}, @code{ELSE_BB}, and @code{JOIN_BB}. 8575 8576@findex IFCVT_MODIFY_CANCEL 8577@item IFCVT_MODIFY_CANCEL 8578A C expression to cancel any machine dependent modifications in 8579converting code to conditional execution in the basic blocks 8580@code{TEST_BB}, @code{THEN_BB}, @code{ELSE_BB}, and @code{JOIN_BB}. 8581@end table 8582 8583@deftypefn {Target Hook} void TARGET_INIT_BUILTINS () 8584Define this hook if you have any machine-specific built-in functions 8585that need to be defined. It should be a function that performs the 8586necessary setup. 8587 8588Machine specific built-in functions can be useful to expand special machine 8589instructions that would otherwise not normally be generated because 8590they have no equivalent in the source language (for example, SIMD vector 8591instructions or prefetch instructions). 8592 8593To create a built-in function, call the function @code{builtin_function} 8594which is defined by the language front end. You can use any type nodes set 8595up by @code{build_common_tree_nodes} and @code{build_common_tree_nodes_2}; 8596only language front ends that use those two functions will call 8597@samp{TARGET_INIT_BUILTINS}. 8598@end deftypefn 8599 8600@deftypefn {Target Hook} rtx TARGET_EXPAND_BUILTIN (tree @var{exp}, rtx @var{target}, rtx @var{subtarget}, enum machine_mode @var{mode}, int @var{ignore}) 8601 8602Expand a call to a machine specific built-in function that was set up by 8603@samp{TARGET_INIT_BUILTINS}. @var{exp} is the expression for the 8604function call; the result should go to @var{target} if that is 8605convenient, and have mode @var{mode} if that is convenient. 8606@var{subtarget} may be used as the target for computing one of 8607@var{exp}'s operands. @var{ignore} is nonzero if the value is to be 8608ignored. This function should return the result of the call to the 8609built-in function. 8610@end deftypefn 8611 8612@table @code 8613@findex MD_CAN_REDIRECT_BRANCH 8614@item MD_CAN_REDIRECT_BRANCH(@var{branch1}, @var{branch2}) 8615 8616Take a branch insn in @var{branch1} and another in @var{branch2}. 8617Return true if redirecting @var{branch1} to the destination of 8618@var{branch2} is possible. 8619 8620On some targets, branches may have a limited range. Optimizing the 8621filling of delay slots can result in branches being redirected, and this 8622may in turn cause a branch offset to overflow. 8623 8624@findex ALLOCATE_INITIAL_VALUE 8625@item ALLOCATE_INITIAL_VALUE(@var{hard_reg}) 8626 8627When the initial value of a hard register has been copied in a pseudo 8628register, it is often not necessary to actually allocate another register 8629to this pseudo register, because the original hard register or a stack slot 8630it has been saved into can be used. @code{ALLOCATE_INITIAL_VALUE}, if 8631defined, is called at the start of register allocation once for each 8632hard register that had its initial value copied by using 8633@code{get_func_hard_reg_initial_val} or @code{get_hard_reg_initial_val}. 8634Possible values are @code{NULL_RTX}, if you don't want 8635to do any special allocation, a @code{REG} rtx---that would typically be 8636the hard register itself, if it is known not to be clobbered---or a 8637@code{MEM}. 8638If you are returning a @code{MEM}, this is only a hint for the allocator; 8639it might decide to use another register anyways. 8640You may use @code{current_function_leaf_function} in the definition of the 8641macro, functions that use @code{REG_N_SETS}, to determine if the hard 8642register in question will not be clobbered. 8643 8644@findex TARGET_OBJECT_SUFFIX 8645@item TARGET_OBJECT_SUFFIX 8646Define this macro to be a C string representing the suffix for object 8647files on your target machine. If you do not define this macro, GCC will 8648use @samp{.o} as the suffix for object files. 8649 8650@findex TARGET_EXECUTABLE_SUFFIX 8651@item TARGET_EXECUTABLE_SUFFIX 8652Define this macro to be a C string representing the suffix to be 8653automatically added to executable files on your target machine. If you 8654do not define this macro, GCC will use the null string as the suffix for 8655executable files. 8656 8657@findex COLLECT_EXPORT_LIST 8658@item COLLECT_EXPORT_LIST 8659If defined, @code{collect2} will scan the individual object files 8660specified on its command line and create an export list for the linker. 8661Define this macro for systems like AIX, where the linker discards 8662object files that are not referenced from @code{main} and uses export 8663lists. 8664 8665@end table 8666 8667@deftypefn {Target Hook} bool TARGET_CANNOT_MODIFY_JUMPS_P (void) 8668This target hook returns @code{true} past the point in which new jump 8669instructions could be created. On machines that require a register for 8670every jump such as the SHmedia ISA of SH5, this point would typically be 8671reload, so this target hook should be defined to a function such as: 8672 8673@smallexample 8674static bool 8675cannot_modify_jumps_past_reload_p () 8676@{ 8677 return (reload_completed || reload_in_progress); 8678@} 8679@end smallexample 8680@end deftypefn 8681