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