tm.texi revision 110611
1178476Sjb@c Copyright (C) 1988,1989,1992,1993,1994,1995,1996,1997,1998,1999,2000,2001,2002 2178476Sjb@c Free Software Foundation, Inc. 3178476Sjb@c This is part of the GCC manual. 4178476Sjb@c For copying conditions, see the file gcc.texi. 5178476Sjb 6178476Sjb@node Target Macros 7178476Sjb@chapter Target Description Macros and Functions 8178476Sjb@cindex machine description macros 9178476Sjb@cindex target description macros 10178476Sjb@cindex macros, target description 11178476Sjb@cindex @file{tm.h} macros 12178476Sjb 13178476SjbIn addition to the file @file{@var{machine}.md}, a machine description 14178476Sjbincludes a C header file conventionally given the name 15178476Sjb@file{@var{machine}.h} and a C source file named @file{@var{machine}.c}. 16178476SjbThe header file defines numerous macros that convey the information 17178476Sjbabout the target machine that does not fit into the scheme of the 18178476Sjb@file{.md} file. The file @file{tm.h} should be a link to 19178476Sjb@file{@var{machine}.h}. The header file @file{config.h} includes 20178476Sjb@file{tm.h} and most compiler source files include @file{config.h}. The 21178476Sjbsource file defines a variable @code{targetm}, which is a structure 22178476Sjbcontaining pointers to functions and data relating to the target 23178476Sjbmachine. @file{@var{machine}.c} should also contain their definitions, 24178476Sjbif they are not defined elsewhere in GCC, and other functions called 25178476Sjbthrough the macros defined in the @file{.h} file. 26178476Sjb 27178476Sjb@menu 28178476Sjb* Target Structure:: The @code{targetm} variable. 29178476Sjb* Driver:: Controlling how the driver runs the compilation passes. 30178476Sjb* Run-time Target:: Defining @samp{-m} options like @option{-m68000} and @option{-m68020}. 31178476Sjb* Per-Function Data:: Defining data structures for per-function information. 32178476Sjb* Storage Layout:: Defining sizes and alignments of data. 33178476Sjb* Type Layout:: Defining sizes and properties of basic user data types. 34178476Sjb* Escape Sequences:: Defining the value of target character escape sequences 35178476Sjb* Registers:: Naming and describing the hardware registers. 36178476Sjb* Register Classes:: Defining the classes of hardware registers. 37178476Sjb* Stack and Calling:: Defining which way the stack grows and by how much. 38178476Sjb* Varargs:: Defining the varargs macros. 39178476Sjb* Trampolines:: Code set up at run time to enter a nested function. 40178476Sjb* Library Calls:: Controlling how library routines are implicitly called. 41178476Sjb* Addressing Modes:: Defining addressing modes valid for memory operands. 42178476Sjb* 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. 3148 3149@findex PUSH_ROUNDING 3150@item PUSH_ROUNDING (@var{npushed}) 3151A C expression that is the number of bytes actually pushed onto the 3152stack when an instruction attempts to push @var{npushed} bytes. 3153 3154On some machines, the definition 3155 3156@example 3157#define PUSH_ROUNDING(BYTES) (BYTES) 3158@end example 3159 3160@noindent 3161will suffice. But on other machines, instructions that appear 3162to push one byte actually push two bytes in an attempt to maintain 3163alignment. Then the definition should be 3164 3165@example 3166#define PUSH_ROUNDING(BYTES) (((BYTES) + 1) & ~1) 3167@end example 3168 3169@findex ACCUMULATE_OUTGOING_ARGS 3170@findex current_function_outgoing_args_size 3171@item ACCUMULATE_OUTGOING_ARGS 3172A C expression. If nonzero, the maximum amount of space required for outgoing arguments 3173will be computed and placed into the variable 3174@code{current_function_outgoing_args_size}. No space will be pushed 3175onto the stack for each call; instead, the function prologue should 3176increase the stack frame size by this amount. 3177 3178Setting both @code{PUSH_ARGS} and @code{ACCUMULATE_OUTGOING_ARGS} 3179is not proper. 3180 3181@findex REG_PARM_STACK_SPACE 3182@item REG_PARM_STACK_SPACE (@var{fndecl}) 3183Define this macro if functions should assume that stack space has been 3184allocated for arguments even when their values are passed in 3185registers. 3186 3187The value of this macro is the size, in bytes, of the area reserved for 3188arguments passed in registers for the function represented by @var{fndecl}, 3189which can be zero if GCC is calling a library function. 3190 3191This space can be allocated by the caller, or be a part of the 3192machine-dependent stack frame: @code{OUTGOING_REG_PARM_STACK_SPACE} says 3193which. 3194@c above is overfull. not sure what to do. --mew 5feb93 did 3195@c something, not sure if it looks good. --mew 10feb93 3196 3197@findex MAYBE_REG_PARM_STACK_SPACE 3198@findex FINAL_REG_PARM_STACK_SPACE 3199@item MAYBE_REG_PARM_STACK_SPACE 3200@itemx FINAL_REG_PARM_STACK_SPACE (@var{const_size}, @var{var_size}) 3201Define these macros in addition to the one above if functions might 3202allocate stack space for arguments even when their values are passed 3203in registers. These should be used when the stack space allocated 3204for arguments in registers is not a simple constant independent of the 3205function declaration. 3206 3207The value of the first macro is the size, in bytes, of the area that 3208we should initially assume would be reserved for arguments passed in registers. 3209 3210The value of the second macro is the actual size, in bytes, of the area 3211that will be reserved for arguments passed in registers. This takes two 3212arguments: an integer representing the number of bytes of fixed sized 3213arguments on the stack, and a tree representing the number of bytes of 3214variable sized arguments on the stack. 3215 3216When these macros are defined, @code{REG_PARM_STACK_SPACE} will only be 3217called for libcall functions, the current function, or for a function 3218being called when it is known that such stack space must be allocated. 3219In each case this value can be easily computed. 3220 3221When deciding whether a called function needs such stack space, and how 3222much space to reserve, GCC uses these two macros instead of 3223@code{REG_PARM_STACK_SPACE}. 3224 3225@findex OUTGOING_REG_PARM_STACK_SPACE 3226@item OUTGOING_REG_PARM_STACK_SPACE 3227Define this if it is the responsibility of the caller to allocate the area 3228reserved for arguments passed in registers. 3229 3230If @code{ACCUMULATE_OUTGOING_ARGS} is defined, this macro controls 3231whether the space for these arguments counts in the value of 3232@code{current_function_outgoing_args_size}. 3233 3234@findex STACK_PARMS_IN_REG_PARM_AREA 3235@item STACK_PARMS_IN_REG_PARM_AREA 3236Define this macro if @code{REG_PARM_STACK_SPACE} is defined, but the 3237stack parameters don't skip the area specified by it. 3238@c i changed this, makes more sens and it should have taken care of the 3239@c overfull.. not as specific, tho. --mew 5feb93 3240 3241Normally, when a parameter is not passed in registers, it is placed on the 3242stack beyond the @code{REG_PARM_STACK_SPACE} area. Defining this macro 3243suppresses this behavior and causes the parameter to be passed on the 3244stack in its natural location. 3245 3246@findex RETURN_POPS_ARGS 3247@item RETURN_POPS_ARGS (@var{fundecl}, @var{funtype}, @var{stack-size}) 3248A C expression that should indicate the number of bytes of its own 3249arguments that a function pops on returning, or 0 if the 3250function pops no arguments and the caller must therefore pop them all 3251after the function returns. 3252 3253@var{fundecl} is a C variable whose value is a tree node that describes 3254the function in question. Normally it is a node of type 3255@code{FUNCTION_DECL} that describes the declaration of the function. 3256From this you can obtain the @code{DECL_ATTRIBUTES} of the function. 3257 3258@var{funtype} is a C variable whose value is a tree node that 3259describes the function in question. Normally it is a node of type 3260@code{FUNCTION_TYPE} that describes the data type of the function. 3261From this it is possible to obtain the data types of the value and 3262arguments (if known). 3263 3264When a call to a library function is being considered, @var{fundecl} 3265will contain an identifier node for the library function. Thus, if 3266you need to distinguish among various library functions, you can do so 3267by their names. Note that ``library function'' in this context means 3268a function used to perform arithmetic, whose name is known specially 3269in the compiler and was not mentioned in the C code being compiled. 3270 3271@var{stack-size} is the number of bytes of arguments passed on the 3272stack. If a variable number of bytes is passed, it is zero, and 3273argument popping will always be the responsibility of the calling function. 3274 3275On the VAX, all functions always pop their arguments, so the definition 3276of this macro is @var{stack-size}. On the 68000, using the standard 3277calling convention, no functions pop their arguments, so the value of 3278the macro is always 0 in this case. But an alternative calling 3279convention is available in which functions that take a fixed number of 3280arguments pop them but other functions (such as @code{printf}) pop 3281nothing (the caller pops all). When this convention is in use, 3282@var{funtype} is examined to determine whether a function takes a fixed 3283number of arguments. 3284 3285@findex CALL_POPS_ARGS 3286@item CALL_POPS_ARGS (@var{cum}) 3287A C expression that should indicate the number of bytes a call sequence 3288pops off the stack. It is added to the value of @code{RETURN_POPS_ARGS} 3289when compiling a function call. 3290 3291@var{cum} is the variable in which all arguments to the called function 3292have been accumulated. 3293 3294On certain architectures, such as the SH5, a call trampoline is used 3295that pops certain registers off the stack, depending on the arguments 3296that have been passed to the function. Since this is a property of the 3297call site, not of the called function, @code{RETURN_POPS_ARGS} is not 3298appropriate. 3299 3300@end table 3301 3302@node Register Arguments 3303@subsection Passing Arguments in Registers 3304@cindex arguments in registers 3305@cindex registers arguments 3306 3307This section describes the macros which let you control how various 3308types of arguments are passed in registers or how they are arranged in 3309the stack. 3310 3311@table @code 3312@findex FUNCTION_ARG 3313@item FUNCTION_ARG (@var{cum}, @var{mode}, @var{type}, @var{named}) 3314A C expression that controls whether a function argument is passed 3315in a register, and which register. 3316 3317The arguments are @var{cum}, which summarizes all the previous 3318arguments; @var{mode}, the machine mode of the argument; @var{type}, 3319the data type of the argument as a tree node or 0 if that is not known 3320(which happens for C support library functions); and @var{named}, 3321which is 1 for an ordinary argument and 0 for nameless arguments that 3322correspond to @samp{@dots{}} in the called function's prototype. 3323@var{type} can be an incomplete type if a syntax error has previously 3324occurred. 3325 3326The value of the expression is usually either a @code{reg} RTX for the 3327hard register in which to pass the argument, or zero to pass the 3328argument on the stack. 3329 3330For machines like the VAX and 68000, where normally all arguments are 3331pushed, zero suffices as a definition. 3332 3333The value of the expression can also be a @code{parallel} RTX@. This is 3334used when an argument is passed in multiple locations. The mode of the 3335of the @code{parallel} should be the mode of the entire argument. The 3336@code{parallel} holds any number of @code{expr_list} pairs; each one 3337describes where part of the argument is passed. In each 3338@code{expr_list} the first operand must be a @code{reg} RTX for the hard 3339register in which to pass this part of the argument, and the mode of the 3340register RTX indicates how large this part of the argument is. The 3341second operand of the @code{expr_list} is a @code{const_int} which gives 3342the offset in bytes into the entire argument of where this part starts. 3343As a special exception the first @code{expr_list} in the @code{parallel} 3344RTX may have a first operand of zero. This indicates that the entire 3345argument is also stored on the stack. 3346 3347The last time this macro is called, it is called with @code{MODE == 3348VOIDmode}, and its result is passed to the @code{call} or @code{call_value} 3349pattern as operands 2 and 3 respectively. 3350 3351@cindex @file{stdarg.h} and register arguments 3352The usual way to make the ISO library @file{stdarg.h} work on a machine 3353where some arguments are usually passed in registers, is to cause 3354nameless arguments to be passed on the stack instead. This is done 3355by making @code{FUNCTION_ARG} return 0 whenever @var{named} is 0. 3356 3357@cindex @code{MUST_PASS_IN_STACK}, and @code{FUNCTION_ARG} 3358@cindex @code{REG_PARM_STACK_SPACE}, and @code{FUNCTION_ARG} 3359You may use the macro @code{MUST_PASS_IN_STACK (@var{mode}, @var{type})} 3360in the definition of this macro to determine if this argument is of a 3361type that must be passed in the stack. If @code{REG_PARM_STACK_SPACE} 3362is not defined and @code{FUNCTION_ARG} returns nonzero for such an 3363argument, the compiler will abort. If @code{REG_PARM_STACK_SPACE} is 3364defined, the argument will be computed in the stack and then loaded into 3365a register. 3366 3367@findex MUST_PASS_IN_STACK 3368@item MUST_PASS_IN_STACK (@var{mode}, @var{type}) 3369Define as a C expression that evaluates to nonzero if we do not know how 3370to pass TYPE solely in registers. The file @file{expr.h} defines a 3371definition that is usually appropriate, refer to @file{expr.h} for additional 3372documentation. 3373 3374@findex FUNCTION_INCOMING_ARG 3375@item FUNCTION_INCOMING_ARG (@var{cum}, @var{mode}, @var{type}, @var{named}) 3376Define this macro if the target machine has ``register windows'', so 3377that the register in which a function sees an arguments is not 3378necessarily the same as the one in which the caller passed the 3379argument. 3380 3381For such machines, @code{FUNCTION_ARG} computes the register in which 3382the caller passes the value, and @code{FUNCTION_INCOMING_ARG} should 3383be defined in a similar fashion to tell the function being called 3384where the arguments will arrive. 3385 3386If @code{FUNCTION_INCOMING_ARG} is not defined, @code{FUNCTION_ARG} 3387serves both purposes. 3388 3389@findex FUNCTION_ARG_PARTIAL_NREGS 3390@item FUNCTION_ARG_PARTIAL_NREGS (@var{cum}, @var{mode}, @var{type}, @var{named}) 3391A C expression for the number of words, at the beginning of an 3392argument, that must be put in registers. The value must be zero for 3393arguments that are passed entirely in registers or that are entirely 3394pushed on the stack. 3395 3396On some machines, certain arguments must be passed partially in 3397registers and partially in memory. On these machines, typically the 3398first @var{n} words of arguments are passed in registers, and the rest 3399on the stack. If a multi-word argument (a @code{double} or a 3400structure) crosses that boundary, its first few words must be passed 3401in registers and the rest must be pushed. This macro tells the 3402compiler when this occurs, and how many of the words should go in 3403registers. 3404 3405@code{FUNCTION_ARG} for these arguments should return the first 3406register to be used by the caller for this argument; likewise 3407@code{FUNCTION_INCOMING_ARG}, for the called function. 3408 3409@findex FUNCTION_ARG_PASS_BY_REFERENCE 3410@item FUNCTION_ARG_PASS_BY_REFERENCE (@var{cum}, @var{mode}, @var{type}, @var{named}) 3411A C expression that indicates when an argument must be passed by reference. 3412If nonzero for an argument, a copy of that argument is made in memory and a 3413pointer to the argument is passed instead of the argument itself. 3414The pointer is passed in whatever way is appropriate for passing a pointer 3415to that type. 3416 3417On machines where @code{REG_PARM_STACK_SPACE} is not defined, a suitable 3418definition of this macro might be 3419@smallexample 3420#define FUNCTION_ARG_PASS_BY_REFERENCE\ 3421(CUM, MODE, TYPE, NAMED) \ 3422 MUST_PASS_IN_STACK (MODE, TYPE) 3423@end smallexample 3424@c this is *still* too long. --mew 5feb93 3425 3426@findex FUNCTION_ARG_CALLEE_COPIES 3427@item FUNCTION_ARG_CALLEE_COPIES (@var{cum}, @var{mode}, @var{type}, @var{named}) 3428If defined, a C expression that indicates when it is the called function's 3429responsibility to make a copy of arguments passed by invisible reference. 3430Normally, the caller makes a copy and passes the address of the copy to the 3431routine being called. When @code{FUNCTION_ARG_CALLEE_COPIES} is defined and is 3432nonzero, the caller does not make a copy. Instead, it passes a pointer to the 3433``live'' value. The called function must not modify this value. If it can be 3434determined that the value won't be modified, it need not make a copy; 3435otherwise a copy must be made. 3436 3437@findex FUNCTION_ARG_REG_LITTLE_ENDIAN 3438@item FUNCTION_ARG_REG_LITTLE_ENDIAN 3439If defined TRUE on a big-endian system then structure arguments passed 3440(and returned) in registers are passed in a little-endian manner instead of 3441the big-endian manner. On the HP-UX IA64 and PA64 platforms structures are 3442aligned differently then integral values and setting this value to true will 3443allow for the special handling of structure arguments and return values. 3444 3445@findex CUMULATIVE_ARGS 3446@item CUMULATIVE_ARGS 3447A C type for declaring a variable that is used as the first argument of 3448@code{FUNCTION_ARG} and other related values. For some target machines, 3449the type @code{int} suffices and can hold the number of bytes of 3450argument so far. 3451 3452There is no need to record in @code{CUMULATIVE_ARGS} anything about the 3453arguments that have been passed on the stack. The compiler has other 3454variables to keep track of that. For target machines on which all 3455arguments are passed on the stack, there is no need to store anything in 3456@code{CUMULATIVE_ARGS}; however, the data structure must exist and 3457should not be empty, so use @code{int}. 3458 3459@findex INIT_CUMULATIVE_ARGS 3460@item INIT_CUMULATIVE_ARGS (@var{cum}, @var{fntype}, @var{libname}, @var{indirect}) 3461A C statement (sans semicolon) for initializing the variable @var{cum} 3462for the state at the beginning of the argument list. The variable has 3463type @code{CUMULATIVE_ARGS}. The value of @var{fntype} is the tree node 3464for the data type of the function which will receive the args, or 0 3465if the args are to a compiler support library function. The value of 3466@var{indirect} is nonzero when processing an indirect call, for example 3467a call through a function pointer. The value of @var{indirect} is zero 3468for a call to an explicitly named function, a library function call, or when 3469@code{INIT_CUMULATIVE_ARGS} is used to find arguments for the function 3470being compiled. 3471 3472When processing a call to a compiler support library function, 3473@var{libname} identifies which one. It is a @code{symbol_ref} rtx which 3474contains the name of the function, as a string. @var{libname} is 0 when 3475an ordinary C function call is being processed. Thus, each time this 3476macro is called, either @var{libname} or @var{fntype} is nonzero, but 3477never both of them at once. 3478 3479@findex INIT_CUMULATIVE_LIBCALL_ARGS 3480@item INIT_CUMULATIVE_LIBCALL_ARGS (@var{cum}, @var{mode}, @var{libname}) 3481Like @code{INIT_CUMULATIVE_ARGS} but only used for outgoing libcalls, 3482it gets a @code{MODE} argument instead of @var{fntype}, that would be 3483@code{NULL}. @var{indirect} would always be zero, too. If this macro 3484is not defined, @code{INIT_CUMULATIVE_ARGS (cum, NULL_RTX, libname, 34850)} is used instead. 3486 3487@findex INIT_CUMULATIVE_INCOMING_ARGS 3488@item INIT_CUMULATIVE_INCOMING_ARGS (@var{cum}, @var{fntype}, @var{libname}) 3489Like @code{INIT_CUMULATIVE_ARGS} but overrides it for the purposes of 3490finding the arguments for the function being compiled. If this macro is 3491undefined, @code{INIT_CUMULATIVE_ARGS} is used instead. 3492 3493The value passed for @var{libname} is always 0, since library routines 3494with special calling conventions are never compiled with GCC@. The 3495argument @var{libname} exists for symmetry with 3496@code{INIT_CUMULATIVE_ARGS}. 3497@c could use "this macro" in place of @code{INIT_CUMULATIVE_ARGS}, maybe. 3498@c --mew 5feb93 i switched the order of the sentences. --mew 10feb93 3499 3500@findex FUNCTION_ARG_ADVANCE 3501@item FUNCTION_ARG_ADVANCE (@var{cum}, @var{mode}, @var{type}, @var{named}) 3502A C statement (sans semicolon) to update the summarizer variable 3503@var{cum} to advance past an argument in the argument list. The 3504values @var{mode}, @var{type} and @var{named} describe that argument. 3505Once this is done, the variable @var{cum} is suitable for analyzing 3506the @emph{following} argument with @code{FUNCTION_ARG}, etc. 3507 3508This macro need not do anything if the argument in question was passed 3509on the stack. The compiler knows how to track the amount of stack space 3510used for arguments without any special help. 3511 3512@findex FUNCTION_ARG_PADDING 3513@item FUNCTION_ARG_PADDING (@var{mode}, @var{type}) 3514If defined, a C expression which determines whether, and in which direction, 3515to pad out an argument with extra space. The value should be of type 3516@code{enum direction}: either @code{upward} to pad above the argument, 3517@code{downward} to pad below, or @code{none} to inhibit padding. 3518 3519The @emph{amount} of padding is always just enough to reach the next 3520multiple of @code{FUNCTION_ARG_BOUNDARY}; this macro does not control 3521it. 3522 3523This macro has a default definition which is right for most systems. 3524For little-endian machines, the default is to pad upward. For 3525big-endian machines, the default is to pad downward for an argument of 3526constant size shorter than an @code{int}, and upward otherwise. 3527 3528@findex PAD_VARARGS_DOWN 3529@item PAD_VARARGS_DOWN 3530If defined, a C expression which determines whether the default 3531implementation of va_arg will attempt to pad down before reading the 3532next argument, if that argument is smaller than its aligned space as 3533controlled by @code{PARM_BOUNDARY}. If this macro is not defined, all such 3534arguments are padded down if @code{BYTES_BIG_ENDIAN} is true. 3535 3536@findex FUNCTION_ARG_BOUNDARY 3537@item FUNCTION_ARG_BOUNDARY (@var{mode}, @var{type}) 3538If defined, a C expression that gives the alignment boundary, in bits, 3539of an argument with the specified mode and type. If it is not defined, 3540@code{PARM_BOUNDARY} is used for all arguments. 3541 3542@findex FUNCTION_ARG_REGNO_P 3543@item FUNCTION_ARG_REGNO_P (@var{regno}) 3544A C expression that is nonzero if @var{regno} is the number of a hard 3545register in which function arguments are sometimes passed. This does 3546@emph{not} include implicit arguments such as the static chain and 3547the structure-value address. On many machines, no registers can be 3548used for this purpose since all function arguments are pushed on the 3549stack. 3550 3551@findex LOAD_ARGS_REVERSED 3552@item LOAD_ARGS_REVERSED 3553If defined, the order in which arguments are loaded into their 3554respective argument registers is reversed so that the last 3555argument is loaded first. This macro only affects arguments 3556passed in registers. 3557 3558@end table 3559 3560@node Scalar Return 3561@subsection How Scalar Function Values Are Returned 3562@cindex return values in registers 3563@cindex values, returned by functions 3564@cindex scalars, returned as values 3565 3566This section discusses the macros that control returning scalars as 3567values---values that can fit in registers. 3568 3569@table @code 3570@findex TRADITIONAL_RETURN_FLOAT 3571@item TRADITIONAL_RETURN_FLOAT 3572Define this macro if @option{-traditional} should not cause functions 3573declared to return @code{float} to convert the value to @code{double}. 3574 3575@findex FUNCTION_VALUE 3576@item FUNCTION_VALUE (@var{valtype}, @var{func}) 3577A C expression to create an RTX representing the place where a 3578function returns a value of data type @var{valtype}. @var{valtype} is 3579a tree node representing a data type. Write @code{TYPE_MODE 3580(@var{valtype})} to get the machine mode used to represent that type. 3581On many machines, only the mode is relevant. (Actually, on most 3582machines, scalar values are returned in the same place regardless of 3583mode). 3584 3585The value of the expression is usually a @code{reg} RTX for the hard 3586register where the return value is stored. The value can also be a 3587@code{parallel} RTX, if the return value is in multiple places. See 3588@code{FUNCTION_ARG} for an explanation of the @code{parallel} form. 3589 3590If @code{PROMOTE_FUNCTION_RETURN} is defined, you must apply the same 3591promotion rules specified in @code{PROMOTE_MODE} if @var{valtype} is a 3592scalar type. 3593 3594If the precise function being called is known, @var{func} is a tree 3595node (@code{FUNCTION_DECL}) for it; otherwise, @var{func} is a null 3596pointer. This makes it possible to use a different value-returning 3597convention for specific functions when all their calls are 3598known. 3599 3600@code{FUNCTION_VALUE} is not used for return vales with aggregate data 3601types, because these are returned in another way. See 3602@code{STRUCT_VALUE_REGNUM} and related macros, below. 3603 3604@findex FUNCTION_OUTGOING_VALUE 3605@item FUNCTION_OUTGOING_VALUE (@var{valtype}, @var{func}) 3606Define this macro if the target machine has ``register windows'' 3607so that the register in which a function returns its value is not 3608the same as the one in which the caller sees the value. 3609 3610For such machines, @code{FUNCTION_VALUE} computes the register in which 3611the caller will see the value. @code{FUNCTION_OUTGOING_VALUE} should be 3612defined in a similar fashion to tell the function where to put the 3613value. 3614 3615If @code{FUNCTION_OUTGOING_VALUE} is not defined, 3616@code{FUNCTION_VALUE} serves both purposes. 3617 3618@code{FUNCTION_OUTGOING_VALUE} is not used for return vales with 3619aggregate data types, because these are returned in another way. See 3620@code{STRUCT_VALUE_REGNUM} and related macros, below. 3621 3622@findex LIBCALL_VALUE 3623@item LIBCALL_VALUE (@var{mode}) 3624A C expression to create an RTX representing the place where a library 3625function returns a value of mode @var{mode}. If the precise function 3626being called is known, @var{func} is a tree node 3627(@code{FUNCTION_DECL}) for it; otherwise, @var{func} is a null 3628pointer. This makes it possible to use a different value-returning 3629convention for specific functions when all their calls are 3630known. 3631 3632Note that ``library function'' in this context means a compiler 3633support routine, used to perform arithmetic, whose name is known 3634specially by the compiler and was not mentioned in the C code being 3635compiled. 3636 3637The definition of @code{LIBRARY_VALUE} need not be concerned aggregate 3638data types, because none of the library functions returns such types. 3639 3640@findex FUNCTION_VALUE_REGNO_P 3641@item FUNCTION_VALUE_REGNO_P (@var{regno}) 3642A C expression that is nonzero if @var{regno} is the number of a hard 3643register in which the values of called function may come back. 3644 3645A register whose use for returning values is limited to serving as the 3646second of a pair (for a value of type @code{double}, say) need not be 3647recognized by this macro. So for most machines, this definition 3648suffices: 3649 3650@example 3651#define FUNCTION_VALUE_REGNO_P(N) ((N) == 0) 3652@end example 3653 3654If the machine has register windows, so that the caller and the called 3655function use different registers for the return value, this macro 3656should recognize only the caller's register numbers. 3657 3658@findex APPLY_RESULT_SIZE 3659@item APPLY_RESULT_SIZE 3660Define this macro if @samp{untyped_call} and @samp{untyped_return} 3661need more space than is implied by @code{FUNCTION_VALUE_REGNO_P} for 3662saving and restoring an arbitrary return value. 3663@end table 3664 3665@node Aggregate Return 3666@subsection How Large Values Are Returned 3667@cindex aggregates as return values 3668@cindex large return values 3669@cindex returning aggregate values 3670@cindex structure value address 3671 3672When a function value's mode is @code{BLKmode} (and in some other 3673cases), the value is not returned according to @code{FUNCTION_VALUE} 3674(@pxref{Scalar Return}). Instead, the caller passes the address of a 3675block of memory in which the value should be stored. This address 3676is called the @dfn{structure value address}. 3677 3678This section describes how to control returning structure values in 3679memory. 3680 3681@table @code 3682@findex RETURN_IN_MEMORY 3683@item RETURN_IN_MEMORY (@var{type}) 3684A C expression which can inhibit the returning of certain function 3685values in registers, based on the type of value. A nonzero value says 3686to return the function value in memory, just as large structures are 3687always returned. Here @var{type} will be a C expression of type 3688@code{tree}, representing the data type of the value. 3689 3690Note that values of mode @code{BLKmode} must be explicitly handled 3691by this macro. Also, the option @option{-fpcc-struct-return} 3692takes effect regardless of this macro. On most systems, it is 3693possible to leave the macro undefined; this causes a default 3694definition to be used, whose value is the constant 1 for @code{BLKmode} 3695values, and 0 otherwise. 3696 3697Do not use this macro to indicate that structures and unions should always 3698be returned in memory. You should instead use @code{DEFAULT_PCC_STRUCT_RETURN} 3699to indicate this. 3700 3701@findex DEFAULT_PCC_STRUCT_RETURN 3702@item DEFAULT_PCC_STRUCT_RETURN 3703Define this macro to be 1 if all structure and union return values must be 3704in memory. Since this results in slower code, this should be defined 3705only if needed for compatibility with other compilers or with an ABI@. 3706If you define this macro to be 0, then the conventions used for structure 3707and union return values are decided by the @code{RETURN_IN_MEMORY} macro. 3708 3709If not defined, this defaults to the value 1. 3710 3711@findex STRUCT_VALUE_REGNUM 3712@item STRUCT_VALUE_REGNUM 3713If the structure value address is passed in a register, then 3714@code{STRUCT_VALUE_REGNUM} should be the number of that register. 3715 3716@findex STRUCT_VALUE 3717@item STRUCT_VALUE 3718If the structure value address is not passed in a register, define 3719@code{STRUCT_VALUE} as an expression returning an RTX for the place 3720where the address is passed. If it returns 0, the address is passed as 3721an ``invisible'' first argument. 3722 3723@findex STRUCT_VALUE_INCOMING_REGNUM 3724@item STRUCT_VALUE_INCOMING_REGNUM 3725On some architectures the place where the structure value address 3726is found by the called function is not the same place that the 3727caller put it. This can be due to register windows, or it could 3728be because the function prologue moves it to a different place. 3729 3730If the incoming location of the structure value address is in a 3731register, define this macro as the register number. 3732 3733@findex STRUCT_VALUE_INCOMING 3734@item STRUCT_VALUE_INCOMING 3735If the incoming location is not a register, then you should define 3736@code{STRUCT_VALUE_INCOMING} as an expression for an RTX for where the 3737called function should find the value. If it should find the value on 3738the stack, define this to create a @code{mem} which refers to the frame 3739pointer. A definition of 0 means that the address is passed as an 3740``invisible'' first argument. 3741 3742@findex PCC_STATIC_STRUCT_RETURN 3743@item PCC_STATIC_STRUCT_RETURN 3744Define this macro if the usual system convention on the target machine 3745for returning structures and unions is for the called function to return 3746the address of a static variable containing the value. 3747 3748Do not define this if the usual system convention is for the caller to 3749pass an address to the subroutine. 3750 3751This macro has effect in @option{-fpcc-struct-return} mode, but it does 3752nothing when you use @option{-freg-struct-return} mode. 3753@end table 3754 3755@node Caller Saves 3756@subsection Caller-Saves Register Allocation 3757 3758If you enable it, GCC can save registers around function calls. This 3759makes it possible to use call-clobbered registers to hold variables that 3760must live across calls. 3761 3762@table @code 3763@findex DEFAULT_CALLER_SAVES 3764@item DEFAULT_CALLER_SAVES 3765Define this macro if function calls on the target machine do not preserve 3766any registers; in other words, if @code{CALL_USED_REGISTERS} has 1 3767for all registers. When defined, this macro enables @option{-fcaller-saves} 3768by default for all optimization levels. It has no effect for optimization 3769levels 2 and higher, where @option{-fcaller-saves} is the default. 3770 3771@findex CALLER_SAVE_PROFITABLE 3772@item CALLER_SAVE_PROFITABLE (@var{refs}, @var{calls}) 3773A C expression to determine whether it is worthwhile to consider placing 3774a pseudo-register in a call-clobbered hard register and saving and 3775restoring it around each function call. The expression should be 1 when 3776this is worth doing, and 0 otherwise. 3777 3778If you don't define this macro, a default is used which is good on most 3779machines: @code{4 * @var{calls} < @var{refs}}. 3780 3781@findex HARD_REGNO_CALLER_SAVE_MODE 3782@item HARD_REGNO_CALLER_SAVE_MODE (@var{regno}, @var{nregs}) 3783A C expression specifying which mode is required for saving @var{nregs} 3784of a pseudo-register in call-clobbered hard register @var{regno}. If 3785@var{regno} is unsuitable for caller save, @code{VOIDmode} should be 3786returned. For most machines this macro need not be defined since GCC 3787will select the smallest suitable mode. 3788@end table 3789 3790@node Function Entry 3791@subsection Function Entry and Exit 3792@cindex function entry and exit 3793@cindex prologue 3794@cindex epilogue 3795 3796This section describes the macros that output function entry 3797(@dfn{prologue}) and exit (@dfn{epilogue}) code. 3798 3799@deftypefn {Target Hook} void TARGET_ASM_FUNCTION_PROLOGUE (FILE *@var{file}, HOST_WIDE_INT @var{size}) 3800If defined, a function that outputs the assembler code for entry to a 3801function. The prologue is responsible for setting up the stack frame, 3802initializing the frame pointer register, saving registers that must be 3803saved, and allocating @var{size} additional bytes of storage for the 3804local variables. @var{size} is an integer. @var{file} is a stdio 3805stream to which the assembler code should be output. 3806 3807The label for the beginning of the function need not be output by this 3808macro. That has already been done when the macro is run. 3809 3810@findex regs_ever_live 3811To determine which registers to save, the macro can refer to the array 3812@code{regs_ever_live}: element @var{r} is nonzero if hard register 3813@var{r} is used anywhere within the function. This implies the function 3814prologue should save register @var{r}, provided it is not one of the 3815call-used registers. (@code{TARGET_ASM_FUNCTION_EPILOGUE} must likewise use 3816@code{regs_ever_live}.) 3817 3818On machines that have ``register windows'', the function entry code does 3819not save on the stack the registers that are in the windows, even if 3820they are supposed to be preserved by function calls; instead it takes 3821appropriate steps to ``push'' the register stack, if any non-call-used 3822registers are used in the function. 3823 3824@findex frame_pointer_needed 3825On machines where functions may or may not have frame-pointers, the 3826function entry code must vary accordingly; it must set up the frame 3827pointer if one is wanted, and not otherwise. To determine whether a 3828frame pointer is in wanted, the macro can refer to the variable 3829@code{frame_pointer_needed}. The variable's value will be 1 at run 3830time in a function that needs a frame pointer. @xref{Elimination}. 3831 3832The function entry code is responsible for allocating any stack space 3833required for the function. This stack space consists of the regions 3834listed below. In most cases, these regions are allocated in the 3835order listed, with the last listed region closest to the top of the 3836stack (the lowest address if @code{STACK_GROWS_DOWNWARD} is defined, and 3837the highest address if it is not defined). You can use a different order 3838for a machine if doing so is more convenient or required for 3839compatibility reasons. Except in cases where required by standard 3840or by a debugger, there is no reason why the stack layout used by GCC 3841need agree with that used by other compilers for a machine. 3842@end deftypefn 3843 3844@deftypefn {Target Hook} void TARGET_ASM_FUNCTION_END_PROLOGUE (FILE *@var{file}) 3845If defined, a function that outputs assembler code at the end of a 3846prologue. This should be used when the function prologue is being 3847emitted as RTL, and you have some extra assembler that needs to be 3848emitted. @xref{prologue instruction pattern}. 3849@end deftypefn 3850 3851@deftypefn {Target Hook} void TARGET_ASM_FUNCTION_BEGIN_EPILOGUE (FILE *@var{file}) 3852If defined, a function that outputs assembler code at the start of an 3853epilogue. This should be used when the function epilogue is being 3854emitted as RTL, and you have some extra assembler that needs to be 3855emitted. @xref{epilogue instruction pattern}. 3856@end deftypefn 3857 3858@deftypefn {Target Hook} void TARGET_ASM_FUNCTION_EPILOGUE (FILE *@var{file}, HOST_WIDE_INT @var{size}) 3859If defined, a function that outputs the assembler code for exit from a 3860function. The epilogue is responsible for restoring the saved 3861registers and stack pointer to their values when the function was 3862called, and returning control to the caller. This macro takes the 3863same arguments as the macro @code{TARGET_ASM_FUNCTION_PROLOGUE}, and the 3864registers to restore are determined from @code{regs_ever_live} and 3865@code{CALL_USED_REGISTERS} in the same way. 3866 3867On some machines, there is a single instruction that does all the work 3868of returning from the function. On these machines, give that 3869instruction the name @samp{return} and do not define the macro 3870@code{TARGET_ASM_FUNCTION_EPILOGUE} at all. 3871 3872Do not define a pattern named @samp{return} if you want the 3873@code{TARGET_ASM_FUNCTION_EPILOGUE} to be used. If you want the target 3874switches to control whether return instructions or epilogues are used, 3875define a @samp{return} pattern with a validity condition that tests the 3876target switches appropriately. If the @samp{return} pattern's validity 3877condition is false, epilogues will be used. 3878 3879On machines where functions may or may not have frame-pointers, the 3880function exit code must vary accordingly. Sometimes the code for these 3881two cases is completely different. To determine whether a frame pointer 3882is wanted, the macro can refer to the variable 3883@code{frame_pointer_needed}. The variable's value will be 1 when compiling 3884a function that needs a frame pointer. 3885 3886Normally, @code{TARGET_ASM_FUNCTION_PROLOGUE} and 3887@code{TARGET_ASM_FUNCTION_EPILOGUE} must treat leaf functions specially. 3888The C variable @code{current_function_is_leaf} is nonzero for such a 3889function. @xref{Leaf Functions}. 3890 3891On some machines, some functions pop their arguments on exit while 3892others leave that for the caller to do. For example, the 68020 when 3893given @option{-mrtd} pops arguments in functions that take a fixed 3894number of arguments. 3895 3896@findex current_function_pops_args 3897Your definition of the macro @code{RETURN_POPS_ARGS} decides which 3898functions pop their own arguments. @code{TARGET_ASM_FUNCTION_EPILOGUE} 3899needs to know what was decided. The variable that is called 3900@code{current_function_pops_args} is the number of bytes of its 3901arguments that a function should pop. @xref{Scalar Return}. 3902@c what is the "its arguments" in the above sentence referring to, pray 3903@c tell? --mew 5feb93 3904@end deftypefn 3905 3906@table @code 3907 3908@itemize @bullet 3909@item 3910@findex current_function_pretend_args_size 3911A region of @code{current_function_pretend_args_size} bytes of 3912uninitialized space just underneath the first argument arriving on the 3913stack. (This may not be at the very start of the allocated stack region 3914if the calling sequence has pushed anything else since pushing the stack 3915arguments. But usually, on such machines, nothing else has been pushed 3916yet, because the function prologue itself does all the pushing.) This 3917region is used on machines where an argument may be passed partly in 3918registers and partly in memory, and, in some cases to support the 3919features in @code{<varargs.h>} and @code{<stdarg.h>}. 3920 3921@item 3922An area of memory used to save certain registers used by the function. 3923The size of this area, which may also include space for such things as 3924the return address and pointers to previous stack frames, is 3925machine-specific and usually depends on which registers have been used 3926in the function. Machines with register windows often do not require 3927a save area. 3928 3929@item 3930A region of at least @var{size} bytes, possibly rounded up to an allocation 3931boundary, to contain the local variables of the function. On some machines, 3932this region and the save area may occur in the opposite order, with the 3933save area closer to the top of the stack. 3934 3935@item 3936@cindex @code{ACCUMULATE_OUTGOING_ARGS} and stack frames 3937Optionally, when @code{ACCUMULATE_OUTGOING_ARGS} is defined, a region of 3938@code{current_function_outgoing_args_size} bytes to be used for outgoing 3939argument lists of the function. @xref{Stack Arguments}. 3940@end itemize 3941 3942Normally, it is necessary for the macros 3943@code{TARGET_ASM_FUNCTION_PROLOGUE} and 3944@code{TARGET_ASM_FUNCTION_EPILOGUE} to treat leaf functions specially. 3945The C variable @code{current_function_is_leaf} is nonzero for such a 3946function. 3947 3948@findex EXIT_IGNORE_STACK 3949@item EXIT_IGNORE_STACK 3950Define this macro as a C expression that is nonzero if the return 3951instruction or the function epilogue ignores the value of the stack 3952pointer; in other words, if it is safe to delete an instruction to 3953adjust the stack pointer before a return from the function. 3954 3955Note that this macro's value is relevant only for functions for which 3956frame pointers are maintained. It is never safe to delete a final 3957stack adjustment in a function that has no frame pointer, and the 3958compiler knows this regardless of @code{EXIT_IGNORE_STACK}. 3959 3960@findex EPILOGUE_USES 3961@item EPILOGUE_USES (@var{regno}) 3962Define this macro as a C expression that is nonzero for registers that are 3963used by the epilogue or the @samp{return} pattern. The stack and frame 3964pointer registers are already be assumed to be used as needed. 3965 3966@findex EH_USES 3967@item EH_USES (@var{regno}) 3968Define this macro as a C expression that is nonzero for registers that are 3969used by the exception handling mechanism, and so should be considered live 3970on entry to an exception edge. 3971 3972@findex DELAY_SLOTS_FOR_EPILOGUE 3973@item DELAY_SLOTS_FOR_EPILOGUE 3974Define this macro if the function epilogue contains delay slots to which 3975instructions from the rest of the function can be ``moved''. The 3976definition should be a C expression whose value is an integer 3977representing the number of delay slots there. 3978 3979@findex ELIGIBLE_FOR_EPILOGUE_DELAY 3980@item ELIGIBLE_FOR_EPILOGUE_DELAY (@var{insn}, @var{n}) 3981A C expression that returns 1 if @var{insn} can be placed in delay 3982slot number @var{n} of the epilogue. 3983 3984The argument @var{n} is an integer which identifies the delay slot now 3985being considered (since different slots may have different rules of 3986eligibility). It is never negative and is always less than the number 3987of epilogue delay slots (what @code{DELAY_SLOTS_FOR_EPILOGUE} returns). 3988If you reject a particular insn for a given delay slot, in principle, it 3989may be reconsidered for a subsequent delay slot. Also, other insns may 3990(at least in principle) be considered for the so far unfilled delay 3991slot. 3992 3993@findex current_function_epilogue_delay_list 3994@findex final_scan_insn 3995The insns accepted to fill the epilogue delay slots are put in an RTL 3996list made with @code{insn_list} objects, stored in the variable 3997@code{current_function_epilogue_delay_list}. The insn for the first 3998delay slot comes first in the list. Your definition of the macro 3999@code{TARGET_ASM_FUNCTION_EPILOGUE} should fill the delay slots by 4000outputting the insns in this list, usually by calling 4001@code{final_scan_insn}. 4002 4003You need not define this macro if you did not define 4004@code{DELAY_SLOTS_FOR_EPILOGUE}. 4005 4006@findex ASM_OUTPUT_MI_THUNK 4007@item ASM_OUTPUT_MI_THUNK (@var{file}, @var{thunk_fndecl}, @var{delta}, @var{function}) 4008A C compound statement that outputs the assembler code for a thunk 4009function, used to implement C++ virtual function calls with multiple 4010inheritance. The thunk acts as a wrapper around a virtual function, 4011adjusting the implicit object parameter before handing control off to 4012the real function. 4013 4014First, emit code to add the integer @var{delta} to the location that 4015contains the incoming first argument. Assume that this argument 4016contains a pointer, and is the one used to pass the @code{this} pointer 4017in C++. This is the incoming argument @emph{before} the function prologue, 4018e.g.@: @samp{%o0} on a sparc. The addition must preserve the values of 4019all other incoming arguments. 4020 4021After the addition, emit code to jump to @var{function}, which is a 4022@code{FUNCTION_DECL}. This is a direct pure jump, not a call, and does 4023not touch the return address. Hence returning from @var{FUNCTION} will 4024return to whoever called the current @samp{thunk}. 4025 4026The effect must be as if @var{function} had been called directly with 4027the adjusted first argument. This macro is responsible for emitting all 4028of the code for a thunk function; @code{TARGET_ASM_FUNCTION_PROLOGUE} 4029and @code{TARGET_ASM_FUNCTION_EPILOGUE} are not invoked. 4030 4031The @var{thunk_fndecl} is redundant. (@var{delta} and @var{function} 4032have already been extracted from it.) It might possibly be useful on 4033some targets, but probably not. 4034 4035If you do not define this macro, the target-independent code in the C++ 4036front end will generate a less efficient heavyweight thunk that calls 4037@var{function} instead of jumping to it. The generic approach does 4038not support varargs. 4039@end table 4040 4041@node Profiling 4042@subsection Generating Code for Profiling 4043@cindex profiling, code generation 4044 4045These macros will help you generate code for profiling. 4046 4047@table @code 4048@findex FUNCTION_PROFILER 4049@item FUNCTION_PROFILER (@var{file}, @var{labelno}) 4050A C statement or compound statement to output to @var{file} some 4051assembler code to call the profiling subroutine @code{mcount}. 4052 4053@findex mcount 4054The details of how @code{mcount} expects to be called are determined by 4055your operating system environment, not by GCC@. To figure them out, 4056compile a small program for profiling using the system's installed C 4057compiler and look at the assembler code that results. 4058 4059Older implementations of @code{mcount} expect the address of a counter 4060variable to be loaded into some register. The name of this variable is 4061@samp{LP} followed by the number @var{labelno}, so you would generate 4062the name using @samp{LP%d} in a @code{fprintf}. 4063 4064@findex PROFILE_HOOK 4065@item PROFILE_HOOK 4066A C statement or compound statement to output to @var{file} some assembly 4067code to call the profiling subroutine @code{mcount} even the target does 4068not support profiling. 4069 4070@findex NO_PROFILE_COUNTERS 4071@item NO_PROFILE_COUNTERS 4072Define this macro if the @code{mcount} subroutine on your system does 4073not need a counter variable allocated for each function. This is true 4074for almost all modern implementations. If you define this macro, you 4075must not use the @var{labelno} argument to @code{FUNCTION_PROFILER}. 4076 4077@findex PROFILE_BEFORE_PROLOGUE 4078@item PROFILE_BEFORE_PROLOGUE 4079Define this macro if the code for function profiling should come before 4080the function prologue. Normally, the profiling code comes after. 4081 4082 4083@findex TARGET_ALLOWS_PROFILING_WITHOUT_FRAME_POINTER 4084@item TARGET_ALLOWS_PROFILING_WITHOUT_FRAME_POINTER 4085On some targets, it is impossible to use profiling when the frame 4086pointer has been omitted. For example, on x86 GNU/Linux systems, 4087the @code{mcount} routine provided by the GNU C Library finds the 4088address of the routine that called the routine that called @code{mcount} 4089by looking in the immediate caller's stack frame. If the immediate 4090caller has no frame pointer, this lookup will fail. 4091 4092By default, GCC assumes that the target does allow profiling when the 4093frame pointer is omitted. This macro should be defined to a C 4094expression that evaluates to @code{false} if the target does not allow 4095profiling when the frame pointer is omitted. 4096 4097@end table 4098 4099@node Tail Calls 4100@subsection Permitting tail calls 4101@cindex tail calls 4102 4103@table @code 4104@findex FUNCTION_OK_FOR_SIBCALL 4105@item FUNCTION_OK_FOR_SIBCALL (@var{decl}) 4106A C expression that evaluates to true if it is ok to perform a sibling 4107call to @var{decl} from the current function. 4108 4109It is not uncommon for limitations of calling conventions to prevent 4110tail calls to functions outside the current unit of translation, or 4111during PIC compilation. Use this macro to enforce these restrictions, 4112as the @code{sibcall} md pattern can not fail, or fall over to a 4113``normal'' call. 4114@end table 4115 4116@node Varargs 4117@section Implementing the Varargs Macros 4118@cindex varargs implementation 4119 4120GCC comes with an implementation of @code{<varargs.h>} and 4121@code{<stdarg.h>} that work without change on machines that pass arguments 4122on the stack. Other machines require their own implementations of 4123varargs, and the two machine independent header files must have 4124conditionals to include it. 4125 4126ISO @code{<stdarg.h>} differs from traditional @code{<varargs.h>} mainly in 4127the calling convention for @code{va_start}. The traditional 4128implementation takes just one argument, which is the variable in which 4129to store the argument pointer. The ISO implementation of 4130@code{va_start} takes an additional second argument. The user is 4131supposed to write the last named argument of the function here. 4132 4133However, @code{va_start} should not use this argument. The way to find 4134the end of the named arguments is with the built-in functions described 4135below. 4136 4137@table @code 4138@findex __builtin_saveregs 4139@item __builtin_saveregs () 4140Use this built-in function to save the argument registers in memory so 4141that the varargs mechanism can access them. Both ISO and traditional 4142versions of @code{va_start} must use @code{__builtin_saveregs}, unless 4143you use @code{SETUP_INCOMING_VARARGS} (see below) instead. 4144 4145On some machines, @code{__builtin_saveregs} is open-coded under the 4146control of the macro @code{EXPAND_BUILTIN_SAVEREGS}. On other machines, 4147it calls a routine written in assembler language, found in 4148@file{libgcc2.c}. 4149 4150Code generated for the call to @code{__builtin_saveregs} appears at the 4151beginning of the function, as opposed to where the call to 4152@code{__builtin_saveregs} is written, regardless of what the code is. 4153This is because the registers must be saved before the function starts 4154to use them for its own purposes. 4155@c i rewrote the first sentence above to fix an overfull hbox. --mew 4156@c 10feb93 4157 4158@findex __builtin_args_info 4159@item __builtin_args_info (@var{category}) 4160Use this built-in function to find the first anonymous arguments in 4161registers. 4162 4163In general, a machine may have several categories of registers used for 4164arguments, each for a particular category of data types. (For example, 4165on some machines, floating-point registers are used for floating-point 4166arguments while other arguments are passed in the general registers.) 4167To make non-varargs functions use the proper calling convention, you 4168have defined the @code{CUMULATIVE_ARGS} data type to record how many 4169registers in each category have been used so far 4170 4171@code{__builtin_args_info} accesses the same data structure of type 4172@code{CUMULATIVE_ARGS} after the ordinary argument layout is finished 4173with it, with @var{category} specifying which word to access. Thus, the 4174value indicates the first unused register in a given category. 4175 4176Normally, you would use @code{__builtin_args_info} in the implementation 4177of @code{va_start}, accessing each category just once and storing the 4178value in the @code{va_list} object. This is because @code{va_list} will 4179have to update the values, and there is no way to alter the 4180values accessed by @code{__builtin_args_info}. 4181 4182@findex __builtin_next_arg 4183@item __builtin_next_arg (@var{lastarg}) 4184This is the equivalent of @code{__builtin_args_info}, for stack 4185arguments. It returns the address of the first anonymous stack 4186argument, as type @code{void *}. If @code{ARGS_GROW_DOWNWARD}, it 4187returns the address of the location above the first anonymous stack 4188argument. Use it in @code{va_start} to initialize the pointer for 4189fetching arguments from the stack. Also use it in @code{va_start} to 4190verify that the second parameter @var{lastarg} is the last named argument 4191of the current function. 4192 4193@findex __builtin_classify_type 4194@item __builtin_classify_type (@var{object}) 4195Since each machine has its own conventions for which data types are 4196passed in which kind of register, your implementation of @code{va_arg} 4197has to embody these conventions. The easiest way to categorize the 4198specified data type is to use @code{__builtin_classify_type} together 4199with @code{sizeof} and @code{__alignof__}. 4200 4201@code{__builtin_classify_type} ignores the value of @var{object}, 4202considering only its data type. It returns an integer describing what 4203kind of type that is---integer, floating, pointer, structure, and so on. 4204 4205The file @file{typeclass.h} defines an enumeration that you can use to 4206interpret the values of @code{__builtin_classify_type}. 4207@end table 4208 4209These machine description macros help implement varargs: 4210 4211@table @code 4212@findex EXPAND_BUILTIN_SAVEREGS 4213@item EXPAND_BUILTIN_SAVEREGS () 4214If defined, is a C expression that produces the machine-specific code 4215for a call to @code{__builtin_saveregs}. This code will be moved to the 4216very beginning of the function, before any parameter access are made. 4217The return value of this function should be an RTX that contains the 4218value to use as the return of @code{__builtin_saveregs}. 4219 4220@findex SETUP_INCOMING_VARARGS 4221@item SETUP_INCOMING_VARARGS (@var{args_so_far}, @var{mode}, @var{type}, @var{pretend_args_size}, @var{second_time}) 4222This macro offers an alternative to using @code{__builtin_saveregs} and 4223defining the macro @code{EXPAND_BUILTIN_SAVEREGS}. Use it to store the 4224anonymous register arguments into the stack so that all the arguments 4225appear to have been passed consecutively on the stack. Once this is 4226done, you can use the standard implementation of varargs that works for 4227machines that pass all their arguments on the stack. 4228 4229The argument @var{args_so_far} is the @code{CUMULATIVE_ARGS} data 4230structure, containing the values that are obtained after processing the 4231named arguments. The arguments @var{mode} and @var{type} describe the 4232last named argument---its machine mode and its data type as a tree node. 4233 4234The macro implementation should do two things: first, push onto the 4235stack all the argument registers @emph{not} used for the named 4236arguments, and second, store the size of the data thus pushed into the 4237@code{int}-valued variable whose name is supplied as the argument 4238@var{pretend_args_size}. The value that you store here will serve as 4239additional offset for setting up the stack frame. 4240 4241Because you must generate code to push the anonymous arguments at 4242compile time without knowing their data types, 4243@code{SETUP_INCOMING_VARARGS} is only useful on machines that have just 4244a single category of argument register and use it uniformly for all data 4245types. 4246 4247If the argument @var{second_time} is nonzero, it means that the 4248arguments of the function are being analyzed for the second time. This 4249happens for an inline function, which is not actually compiled until the 4250end of the source file. The macro @code{SETUP_INCOMING_VARARGS} should 4251not generate any instructions in this case. 4252 4253@findex STRICT_ARGUMENT_NAMING 4254@item STRICT_ARGUMENT_NAMING 4255Define this macro to be a nonzero value if the location where a function 4256argument is passed depends on whether or not it is a named argument. 4257 4258This macro controls how the @var{named} argument to @code{FUNCTION_ARG} 4259is set for varargs and stdarg functions. If this macro returns a 4260nonzero value, the @var{named} argument is always true for named 4261arguments, and false for unnamed arguments. If it returns a value of 4262zero, but @code{SETUP_INCOMING_VARARGS} is defined, then all arguments 4263are treated as named. Otherwise, all named arguments except the last 4264are treated as named. 4265 4266You need not define this macro if it always returns zero. 4267 4268@findex PRETEND_OUTGOING_VARARGS_NAMED 4269@item PRETEND_OUTGOING_VARARGS_NAMED 4270If you need to conditionally change ABIs so that one works with 4271@code{SETUP_INCOMING_VARARGS}, but the other works like neither 4272@code{SETUP_INCOMING_VARARGS} nor @code{STRICT_ARGUMENT_NAMING} was 4273defined, then define this macro to return nonzero if 4274@code{SETUP_INCOMING_VARARGS} is used, zero otherwise. 4275Otherwise, you should not define this macro. 4276@end table 4277 4278@node Trampolines 4279@section Trampolines for Nested Functions 4280@cindex trampolines for nested functions 4281@cindex nested functions, trampolines for 4282 4283A @dfn{trampoline} is a small piece of code that is created at run time 4284when the address of a nested function is taken. It normally resides on 4285the stack, in the stack frame of the containing function. These macros 4286tell GCC how to generate code to allocate and initialize a 4287trampoline. 4288 4289The instructions in the trampoline must do two things: load a constant 4290address into the static chain register, and jump to the real address of 4291the nested function. On CISC machines such as the m68k, this requires 4292two instructions, a move immediate and a jump. Then the two addresses 4293exist in the trampoline as word-long immediate operands. On RISC 4294machines, it is often necessary to load each address into a register in 4295two parts. Then pieces of each address form separate immediate 4296operands. 4297 4298The code generated to initialize the trampoline must store the variable 4299parts---the static chain value and the function address---into the 4300immediate operands of the instructions. On a CISC machine, this is 4301simply a matter of copying each address to a memory reference at the 4302proper offset from the start of the trampoline. On a RISC machine, it 4303may be necessary to take out pieces of the address and store them 4304separately. 4305 4306@table @code 4307@findex TRAMPOLINE_TEMPLATE 4308@item TRAMPOLINE_TEMPLATE (@var{file}) 4309A C statement to output, on the stream @var{file}, assembler code for a 4310block of data that contains the constant parts of a trampoline. This 4311code should not include a label---the label is taken care of 4312automatically. 4313 4314If you do not define this macro, it means no template is needed 4315for the target. Do not define this macro on systems where the block move 4316code to copy the trampoline into place would be larger than the code 4317to generate it on the spot. 4318 4319@findex TRAMPOLINE_SECTION 4320@item TRAMPOLINE_SECTION 4321The name of a subroutine to switch to the section in which the 4322trampoline template is to be placed (@pxref{Sections}). The default is 4323a value of @samp{readonly_data_section}, which places the trampoline in 4324the section containing read-only data. 4325 4326@findex TRAMPOLINE_SIZE 4327@item TRAMPOLINE_SIZE 4328A C expression for the size in bytes of the trampoline, as an integer. 4329 4330@findex TRAMPOLINE_ALIGNMENT 4331@item TRAMPOLINE_ALIGNMENT 4332Alignment required for trampolines, in bits. 4333 4334If you don't define this macro, the value of @code{BIGGEST_ALIGNMENT} 4335is used for aligning trampolines. 4336 4337@findex INITIALIZE_TRAMPOLINE 4338@item INITIALIZE_TRAMPOLINE (@var{addr}, @var{fnaddr}, @var{static_chain}) 4339A C statement to initialize the variable parts of a trampoline. 4340@var{addr} is an RTX for the address of the trampoline; @var{fnaddr} is 4341an RTX for the address of the nested function; @var{static_chain} is an 4342RTX for the static chain value that should be passed to the function 4343when it is called. 4344 4345@findex TRAMPOLINE_ADJUST_ADDRESS 4346@item TRAMPOLINE_ADJUST_ADDRESS (@var{addr}) 4347A C statement that should perform any machine-specific adjustment in 4348the address of the trampoline. Its argument contains the address that 4349was passed to @code{INITIALIZE_TRAMPOLINE}. In case the address to be 4350used for a function call should be different from the address in which 4351the template was stored, the different address should be assigned to 4352@var{addr}. If this macro is not defined, @var{addr} will be used for 4353function calls. 4354 4355@findex ALLOCATE_TRAMPOLINE 4356@item ALLOCATE_TRAMPOLINE (@var{fp}) 4357A C expression to allocate run-time space for a trampoline. The 4358expression value should be an RTX representing a memory reference to the 4359space for the trampoline. 4360 4361@cindex @code{TARGET_ASM_FUNCTION_EPILOGUE} and trampolines 4362@cindex @code{TARGET_ASM_FUNCTION_PROLOGUE} and trampolines 4363If this macro is not defined, by default the trampoline is allocated as 4364a stack slot. This default is right for most machines. The exceptions 4365are machines where it is impossible to execute instructions in the stack 4366area. On such machines, you may have to implement a separate stack, 4367using this macro in conjunction with @code{TARGET_ASM_FUNCTION_PROLOGUE} 4368and @code{TARGET_ASM_FUNCTION_EPILOGUE}. 4369 4370@var{fp} points to a data structure, a @code{struct function}, which 4371describes the compilation status of the immediate containing function of 4372the function which the trampoline is for. Normally (when 4373@code{ALLOCATE_TRAMPOLINE} is not defined), the stack slot for the 4374trampoline is in the stack frame of this containing function. Other 4375allocation strategies probably must do something analogous with this 4376information. 4377@end table 4378 4379Implementing trampolines is difficult on many machines because they have 4380separate instruction and data caches. Writing into a stack location 4381fails to clear the memory in the instruction cache, so when the program 4382jumps to that location, it executes the old contents. 4383 4384Here are two possible solutions. One is to clear the relevant parts of 4385the instruction cache whenever a trampoline is set up. The other is to 4386make all trampolines identical, by having them jump to a standard 4387subroutine. The former technique makes trampoline execution faster; the 4388latter makes initialization faster. 4389 4390To clear the instruction cache when a trampoline is initialized, define 4391the following macros which describe the shape of the cache. 4392 4393@table @code 4394@findex INSN_CACHE_SIZE 4395@item INSN_CACHE_SIZE 4396The total size in bytes of the cache. 4397 4398@findex INSN_CACHE_LINE_WIDTH 4399@item INSN_CACHE_LINE_WIDTH 4400The length in bytes of each cache line. The cache is divided into cache 4401lines which are disjoint slots, each holding a contiguous chunk of data 4402fetched from memory. Each time data is brought into the cache, an 4403entire line is read at once. The data loaded into a cache line is 4404always aligned on a boundary equal to the line size. 4405 4406@findex INSN_CACHE_DEPTH 4407@item INSN_CACHE_DEPTH 4408The number of alternative cache lines that can hold any particular memory 4409location. 4410@end table 4411 4412Alternatively, if the machine has system calls or instructions to clear 4413the instruction cache directly, you can define the following macro. 4414 4415@table @code 4416@findex CLEAR_INSN_CACHE 4417@item CLEAR_INSN_CACHE (@var{beg}, @var{end}) 4418If defined, expands to a C expression clearing the @emph{instruction 4419cache} in the specified interval. If it is not defined, and the macro 4420@code{INSN_CACHE_SIZE} is defined, some generic code is generated to clear the 4421cache. The definition of this macro would typically be a series of 4422@code{asm} statements. Both @var{beg} and @var{end} are both pointer 4423expressions. 4424@end table 4425 4426To use a standard subroutine, define the following macro. In addition, 4427you must make sure that the instructions in a trampoline fill an entire 4428cache line with identical instructions, or else ensure that the 4429beginning of the trampoline code is always aligned at the same point in 4430its cache line. Look in @file{m68k.h} as a guide. 4431 4432@table @code 4433@findex TRANSFER_FROM_TRAMPOLINE 4434@item TRANSFER_FROM_TRAMPOLINE 4435Define this macro if trampolines need a special subroutine to do their 4436work. The macro should expand to a series of @code{asm} statements 4437which will be compiled with GCC@. They go in a library function named 4438@code{__transfer_from_trampoline}. 4439 4440If you need to avoid executing the ordinary prologue code of a compiled 4441C function when you jump to the subroutine, you can do so by placing a 4442special label of your own in the assembler code. Use one @code{asm} 4443statement to generate an assembler label, and another to make the label 4444global. Then trampolines can use that label to jump directly to your 4445special assembler code. 4446@end table 4447 4448@node Library Calls 4449@section Implicit Calls to Library Routines 4450@cindex library subroutine names 4451@cindex @file{libgcc.a} 4452 4453@c prevent bad page break with this line 4454Here is an explanation of implicit calls to library routines. 4455 4456@table @code 4457@findex MULSI3_LIBCALL 4458@item MULSI3_LIBCALL 4459A C string constant giving the name of the function to call for 4460multiplication of one signed full-word by another. If you do not 4461define this macro, the default name is used, which is @code{__mulsi3}, 4462a function defined in @file{libgcc.a}. 4463 4464@findex DIVSI3_LIBCALL 4465@item DIVSI3_LIBCALL 4466A C string constant giving the name of the function to call for 4467division of one signed full-word by another. If you do not define 4468this macro, the default name is used, which is @code{__divsi3}, a 4469function defined in @file{libgcc.a}. 4470 4471@findex UDIVSI3_LIBCALL 4472@item UDIVSI3_LIBCALL 4473A C string constant giving the name of the function to call for 4474division of one unsigned full-word by another. If you do not define 4475this macro, the default name is used, which is @code{__udivsi3}, a 4476function defined in @file{libgcc.a}. 4477 4478@findex MODSI3_LIBCALL 4479@item MODSI3_LIBCALL 4480A C string constant giving the name of the function to call for the 4481remainder in division of one signed full-word by another. If you do 4482not define this macro, the default name is used, which is 4483@code{__modsi3}, a function defined in @file{libgcc.a}. 4484 4485@findex UMODSI3_LIBCALL 4486@item UMODSI3_LIBCALL 4487A C string constant giving the name of the function to call for the 4488remainder in division of one unsigned full-word by another. If you do 4489not define this macro, the default name is used, which is 4490@code{__umodsi3}, a function defined in @file{libgcc.a}. 4491 4492@findex MULDI3_LIBCALL 4493@item MULDI3_LIBCALL 4494A C string constant giving the name of the function to call for 4495multiplication of one signed double-word by another. If you do not 4496define this macro, the default name is used, which is @code{__muldi3}, 4497a function defined in @file{libgcc.a}. 4498 4499@findex DIVDI3_LIBCALL 4500@item DIVDI3_LIBCALL 4501A C string constant giving the name of the function to call for 4502division of one signed double-word by another. If you do not define 4503this macro, the default name is used, which is @code{__divdi3}, a 4504function defined in @file{libgcc.a}. 4505 4506@findex UDIVDI3_LIBCALL 4507@item UDIVDI3_LIBCALL 4508A C string constant giving the name of the function to call for 4509division of one unsigned full-word by another. If you do not define 4510this macro, the default name is used, which is @code{__udivdi3}, a 4511function defined in @file{libgcc.a}. 4512 4513@findex MODDI3_LIBCALL 4514@item MODDI3_LIBCALL 4515A C string constant giving the name of the function to call for the 4516remainder in division of one signed double-word by another. If you do 4517not define this macro, the default name is used, which is 4518@code{__moddi3}, a function defined in @file{libgcc.a}. 4519 4520@findex UMODDI3_LIBCALL 4521@item UMODDI3_LIBCALL 4522A C string constant giving the name of the function to call for the 4523remainder in division of one unsigned full-word by another. If you do 4524not define this macro, the default name is used, which is 4525@code{__umoddi3}, a function defined in @file{libgcc.a}. 4526 4527@findex INIT_TARGET_OPTABS 4528@item INIT_TARGET_OPTABS 4529Define this macro as a C statement that declares additional library 4530routines renames existing ones. @code{init_optabs} calls this macro after 4531initializing all the normal library routines. 4532 4533@findex FLOAT_LIB_COMPARE_RETURNS_BOOL (@var{mode}, @var{comparison}) 4534@item FLOAT_LIB_COMPARE_RETURNS_BOOL 4535Define this macro as a C statement that returns nonzero if a call to 4536the floating point comparison library function will return a boolean 4537value that indicates the result of the comparison. It should return 4538zero if one of gcc's own libgcc functions is called. 4539 4540Most ports don't need to define this macro. 4541 4542@findex TARGET_EDOM 4543@cindex @code{EDOM}, implicit usage 4544@item TARGET_EDOM 4545The value of @code{EDOM} on the target machine, as a C integer constant 4546expression. If you don't define this macro, GCC does not attempt to 4547deposit the value of @code{EDOM} into @code{errno} directly. Look in 4548@file{/usr/include/errno.h} to find the value of @code{EDOM} on your 4549system. 4550 4551If you do not define @code{TARGET_EDOM}, then compiled code reports 4552domain errors by calling the library function and letting it report the 4553error. If mathematical functions on your system use @code{matherr} when 4554there is an error, then you should leave @code{TARGET_EDOM} undefined so 4555that @code{matherr} is used normally. 4556 4557@findex GEN_ERRNO_RTX 4558@cindex @code{errno}, implicit usage 4559@item GEN_ERRNO_RTX 4560Define this macro as a C expression to create an rtl expression that 4561refers to the global ``variable'' @code{errno}. (On certain systems, 4562@code{errno} may not actually be a variable.) If you don't define this 4563macro, a reasonable default is used. 4564 4565@findex TARGET_MEM_FUNCTIONS 4566@cindex @code{bcopy}, implicit usage 4567@cindex @code{memcpy}, implicit usage 4568@cindex @code{memmove}, implicit usage 4569@cindex @code{bzero}, implicit usage 4570@cindex @code{memset}, implicit usage 4571@item TARGET_MEM_FUNCTIONS 4572Define this macro if GCC should generate calls to the ISO C 4573(and System V) library functions @code{memcpy}, @code{memmove} and 4574@code{memset} rather than the BSD functions @code{bcopy} and @code{bzero}. 4575 4576@findex LIBGCC_NEEDS_DOUBLE 4577@item LIBGCC_NEEDS_DOUBLE 4578Define this macro if @code{float} arguments cannot be passed to library 4579routines (so they must be converted to @code{double}). This macro 4580affects both how library calls are generated and how the library 4581routines in @file{libgcc.a} accept their arguments. It is useful on 4582machines where floating and fixed point arguments are passed 4583differently, such as the i860. 4584 4585@findex NEXT_OBJC_RUNTIME 4586@item NEXT_OBJC_RUNTIME 4587Define this macro to generate code for Objective-C message sending using 4588the calling convention of the NeXT system. This calling convention 4589involves passing the object, the selector and the method arguments all 4590at once to the method-lookup library function. 4591 4592The default calling convention passes just the object and the selector 4593to the lookup function, which returns a pointer to the method. 4594@end table 4595 4596@node Addressing Modes 4597@section Addressing Modes 4598@cindex addressing modes 4599 4600@c prevent bad page break with this line 4601This is about addressing modes. 4602 4603@table @code 4604@findex HAVE_PRE_INCREMENT 4605@findex HAVE_PRE_DECREMENT 4606@findex HAVE_POST_INCREMENT 4607@findex HAVE_POST_DECREMENT 4608@item HAVE_PRE_INCREMENT 4609@itemx HAVE_PRE_DECREMENT 4610@itemx HAVE_POST_INCREMENT 4611@itemx HAVE_POST_DECREMENT 4612A C expression that is nonzero if the machine supports pre-increment, 4613pre-decrement, post-increment, or post-decrement addressing respectively. 4614 4615@findex HAVE_POST_MODIFY_DISP 4616@findex HAVE_PRE_MODIFY_DISP 4617@item HAVE_PRE_MODIFY_DISP 4618@itemx HAVE_POST_MODIFY_DISP 4619A C expression that is nonzero if the machine supports pre- or 4620post-address side-effect generation involving constants other than 4621the size of the memory operand. 4622 4623@findex HAVE_POST_MODIFY_REG 4624@findex HAVE_PRE_MODIFY_REG 4625@item HAVE_PRE_MODIFY_REG 4626@itemx HAVE_POST_MODIFY_REG 4627A C expression that is nonzero if the machine supports pre- or 4628post-address side-effect generation involving a register displacement. 4629 4630@findex CONSTANT_ADDRESS_P 4631@item CONSTANT_ADDRESS_P (@var{x}) 4632A C expression that is 1 if the RTX @var{x} is a constant which 4633is a valid address. On most machines, this can be defined as 4634@code{CONSTANT_P (@var{x})}, but a few machines are more restrictive 4635in which constant addresses are supported. 4636 4637@findex CONSTANT_P 4638@code{CONSTANT_P} accepts integer-values expressions whose values are 4639not explicitly known, such as @code{symbol_ref}, @code{label_ref}, and 4640@code{high} expressions and @code{const} arithmetic expressions, in 4641addition to @code{const_int} and @code{const_double} expressions. 4642 4643@findex MAX_REGS_PER_ADDRESS 4644@item MAX_REGS_PER_ADDRESS 4645A number, the maximum number of registers that can appear in a valid 4646memory address. Note that it is up to you to specify a value equal to 4647the maximum number that @code{GO_IF_LEGITIMATE_ADDRESS} would ever 4648accept. 4649 4650@findex GO_IF_LEGITIMATE_ADDRESS 4651@item GO_IF_LEGITIMATE_ADDRESS (@var{mode}, @var{x}, @var{label}) 4652A C compound statement with a conditional @code{goto @var{label};} 4653executed if @var{x} (an RTX) is a legitimate memory address on the 4654target machine for a memory operand of mode @var{mode}. 4655 4656It usually pays to define several simpler macros to serve as 4657subroutines for this one. Otherwise it may be too complicated to 4658understand. 4659 4660This macro must exist in two variants: a strict variant and a 4661non-strict one. The strict variant is used in the reload pass. It 4662must be defined so that any pseudo-register that has not been 4663allocated a hard register is considered a memory reference. In 4664contexts where some kind of register is required, a pseudo-register 4665with no hard register must be rejected. 4666 4667The non-strict variant is used in other passes. It must be defined to 4668accept all pseudo-registers in every context where some kind of 4669register is required. 4670 4671@findex REG_OK_STRICT 4672Compiler source files that want to use the strict variant of this 4673macro define the macro @code{REG_OK_STRICT}. You should use an 4674@code{#ifdef REG_OK_STRICT} conditional to define the strict variant 4675in that case and the non-strict variant otherwise. 4676 4677Subroutines to check for acceptable registers for various purposes (one 4678for base registers, one for index registers, and so on) are typically 4679among the subroutines used to define @code{GO_IF_LEGITIMATE_ADDRESS}. 4680Then only these subroutine macros need have two variants; the higher 4681levels of macros may be the same whether strict or not. 4682 4683Normally, constant addresses which are the sum of a @code{symbol_ref} 4684and an integer are stored inside a @code{const} RTX to mark them as 4685constant. Therefore, there is no need to recognize such sums 4686specifically as legitimate addresses. Normally you would simply 4687recognize any @code{const} as legitimate. 4688 4689Usually @code{PRINT_OPERAND_ADDRESS} is not prepared to handle constant 4690sums that are not marked with @code{const}. It assumes that a naked 4691@code{plus} indicates indexing. If so, then you @emph{must} reject such 4692naked constant sums as illegitimate addresses, so that none of them will 4693be given to @code{PRINT_OPERAND_ADDRESS}. 4694 4695@cindex @code{ENCODE_SECTION_INFO} and address validation 4696On some machines, whether a symbolic address is legitimate depends on 4697the section that the address refers to. On these machines, define the 4698macro @code{ENCODE_SECTION_INFO} to store the information into the 4699@code{symbol_ref}, and then check for it here. When you see a 4700@code{const}, you will have to look inside it to find the 4701@code{symbol_ref} in order to determine the section. @xref{Assembler 4702Format}. 4703 4704@findex saveable_obstack 4705The best way to modify the name string is by adding text to the 4706beginning, with suitable punctuation to prevent any ambiguity. Allocate 4707the new name in @code{saveable_obstack}. You will have to modify 4708@code{ASM_OUTPUT_LABELREF} to remove and decode the added text and 4709output the name accordingly, and define @code{STRIP_NAME_ENCODING} to 4710access the original name string. 4711 4712You can check the information stored here into the @code{symbol_ref} in 4713the definitions of the macros @code{GO_IF_LEGITIMATE_ADDRESS} and 4714@code{PRINT_OPERAND_ADDRESS}. 4715 4716@findex REG_OK_FOR_BASE_P 4717@item REG_OK_FOR_BASE_P (@var{x}) 4718A C expression that is nonzero if @var{x} (assumed to be a @code{reg} 4719RTX) is valid for use as a base register. For hard registers, it 4720should always accept those which the hardware permits and reject the 4721others. Whether the macro accepts or rejects pseudo registers must be 4722controlled by @code{REG_OK_STRICT} as described above. This usually 4723requires two variant definitions, of which @code{REG_OK_STRICT} 4724controls the one actually used. 4725 4726@findex REG_MODE_OK_FOR_BASE_P 4727@item REG_MODE_OK_FOR_BASE_P (@var{x}, @var{mode}) 4728A C expression that is just like @code{REG_OK_FOR_BASE_P}, except that 4729that expression may examine the mode of the memory reference in 4730@var{mode}. You should define this macro if the mode of the memory 4731reference affects whether a register may be used as a base register. If 4732you define this macro, the compiler will use it instead of 4733@code{REG_OK_FOR_BASE_P}. 4734 4735@findex REG_OK_FOR_INDEX_P 4736@item REG_OK_FOR_INDEX_P (@var{x}) 4737A C expression that is nonzero if @var{x} (assumed to be a @code{reg} 4738RTX) is valid for use as an index register. 4739 4740The difference between an index register and a base register is that 4741the index register may be scaled. If an address involves the sum of 4742two registers, neither one of them scaled, then either one may be 4743labeled the ``base'' and the other the ``index''; but whichever 4744labeling is used must fit the machine's constraints of which registers 4745may serve in each capacity. The compiler will try both labelings, 4746looking for one that is valid, and will reload one or both registers 4747only if neither labeling works. 4748 4749@findex FIND_BASE_TERM 4750@item FIND_BASE_TERM (@var{x}) 4751A C expression to determine the base term of address @var{x}. 4752This macro is used in only one place: `find_base_term' in alias.c. 4753 4754It is always safe for this macro to not be defined. It exists so 4755that alias analysis can understand machine-dependent addresses. 4756 4757The typical use of this macro is to handle addresses containing 4758a label_ref or symbol_ref within an UNSPEC@. 4759 4760@findex LEGITIMIZE_ADDRESS 4761@item LEGITIMIZE_ADDRESS (@var{x}, @var{oldx}, @var{mode}, @var{win}) 4762A C compound statement that attempts to replace @var{x} with a valid 4763memory address for an operand of mode @var{mode}. @var{win} will be a 4764C statement label elsewhere in the code; the macro definition may use 4765 4766@example 4767GO_IF_LEGITIMATE_ADDRESS (@var{mode}, @var{x}, @var{win}); 4768@end example 4769 4770@noindent 4771to avoid further processing if the address has become legitimate. 4772 4773@findex break_out_memory_refs 4774@var{x} will always be the result of a call to @code{break_out_memory_refs}, 4775and @var{oldx} will be the operand that was given to that function to produce 4776@var{x}. 4777 4778The code generated by this macro should not alter the substructure of 4779@var{x}. If it transforms @var{x} into a more legitimate form, it 4780should assign @var{x} (which will always be a C variable) a new value. 4781 4782It is not necessary for this macro to come up with a legitimate 4783address. The compiler has standard ways of doing so in all cases. In 4784fact, it is safe for this macro to do nothing. But often a 4785machine-dependent strategy can generate better code. 4786 4787@findex LEGITIMIZE_RELOAD_ADDRESS 4788@item LEGITIMIZE_RELOAD_ADDRESS (@var{x}, @var{mode}, @var{opnum}, @var{type}, @var{ind_levels}, @var{win}) 4789A C compound statement that attempts to replace @var{x}, which is an address 4790that needs reloading, with a valid memory address for an operand of mode 4791@var{mode}. @var{win} will be a C statement label elsewhere in the code. 4792It is not necessary to define this macro, but it might be useful for 4793performance reasons. 4794 4795For example, on the i386, it is sometimes possible to use a single 4796reload register instead of two by reloading a sum of two pseudo 4797registers into a register. On the other hand, for number of RISC 4798processors offsets are limited so that often an intermediate address 4799needs to be generated in order to address a stack slot. By defining 4800@code{LEGITIMIZE_RELOAD_ADDRESS} appropriately, the intermediate addresses 4801generated for adjacent some stack slots can be made identical, and thus 4802be shared. 4803 4804@emph{Note}: This macro should be used with caution. It is necessary 4805to know something of how reload works in order to effectively use this, 4806and it is quite easy to produce macros that build in too much knowledge 4807of reload internals. 4808 4809@emph{Note}: This macro must be able to reload an address created by a 4810previous invocation of this macro. If it fails to handle such addresses 4811then the compiler may generate incorrect code or abort. 4812 4813@findex push_reload 4814The macro definition should use @code{push_reload} to indicate parts that 4815need reloading; @var{opnum}, @var{type} and @var{ind_levels} are usually 4816suitable to be passed unaltered to @code{push_reload}. 4817 4818The code generated by this macro must not alter the substructure of 4819@var{x}. If it transforms @var{x} into a more legitimate form, it 4820should assign @var{x} (which will always be a C variable) a new value. 4821This also applies to parts that you change indirectly by calling 4822@code{push_reload}. 4823 4824@findex strict_memory_address_p 4825The macro definition may use @code{strict_memory_address_p} to test if 4826the address has become legitimate. 4827 4828@findex copy_rtx 4829If you want to change only a part of @var{x}, one standard way of doing 4830this is to use @code{copy_rtx}. Note, however, that is unshares only a 4831single level of rtl. Thus, if the part to be changed is not at the 4832top level, you'll need to replace first the top level. 4833It is not necessary for this macro to come up with a legitimate 4834address; but often a machine-dependent strategy can generate better code. 4835 4836@findex GO_IF_MODE_DEPENDENT_ADDRESS 4837@item GO_IF_MODE_DEPENDENT_ADDRESS (@var{addr}, @var{label}) 4838A C statement or compound statement with a conditional @code{goto 4839@var{label};} executed if memory address @var{x} (an RTX) can have 4840different meanings depending on the machine mode of the memory 4841reference it is used for or if the address is valid for some modes 4842but not others. 4843 4844Autoincrement and autodecrement addresses typically have mode-dependent 4845effects because the amount of the increment or decrement is the size 4846of the operand being addressed. Some machines have other mode-dependent 4847addresses. Many RISC machines have no mode-dependent addresses. 4848 4849You may assume that @var{addr} is a valid address for the machine. 4850 4851@findex LEGITIMATE_CONSTANT_P 4852@item LEGITIMATE_CONSTANT_P (@var{x}) 4853A C expression that is nonzero if @var{x} is a legitimate constant for 4854an immediate operand on the target machine. You can assume that 4855@var{x} satisfies @code{CONSTANT_P}, so you need not check this. In fact, 4856@samp{1} is a suitable definition for this macro on machines where 4857anything @code{CONSTANT_P} is valid. 4858@end table 4859 4860@node Condition Code 4861@section Condition Code Status 4862@cindex condition code status 4863 4864@c prevent bad page break with this line 4865This describes the condition code status. 4866 4867@findex cc_status 4868The file @file{conditions.h} defines a variable @code{cc_status} to 4869describe how the condition code was computed (in case the interpretation of 4870the condition code depends on the instruction that it was set by). This 4871variable contains the RTL expressions on which the condition code is 4872currently based, and several standard flags. 4873 4874Sometimes additional machine-specific flags must be defined in the machine 4875description header file. It can also add additional machine-specific 4876information by defining @code{CC_STATUS_MDEP}. 4877 4878@table @code 4879@findex CC_STATUS_MDEP 4880@item CC_STATUS_MDEP 4881C code for a data type which is used for declaring the @code{mdep} 4882component of @code{cc_status}. It defaults to @code{int}. 4883 4884This macro is not used on machines that do not use @code{cc0}. 4885 4886@findex CC_STATUS_MDEP_INIT 4887@item CC_STATUS_MDEP_INIT 4888A C expression to initialize the @code{mdep} field to ``empty''. 4889The default definition does nothing, since most machines don't use 4890the field anyway. If you want to use the field, you should probably 4891define this macro to initialize it. 4892 4893This macro is not used on machines that do not use @code{cc0}. 4894 4895@findex NOTICE_UPDATE_CC 4896@item NOTICE_UPDATE_CC (@var{exp}, @var{insn}) 4897A C compound statement to set the components of @code{cc_status} 4898appropriately for an insn @var{insn} whose body is @var{exp}. It is 4899this macro's responsibility to recognize insns that set the condition 4900code as a byproduct of other activity as well as those that explicitly 4901set @code{(cc0)}. 4902 4903This macro is not used on machines that do not use @code{cc0}. 4904 4905If there are insns that do not set the condition code but do alter 4906other machine registers, this macro must check to see whether they 4907invalidate the expressions that the condition code is recorded as 4908reflecting. For example, on the 68000, insns that store in address 4909registers do not set the condition code, which means that usually 4910@code{NOTICE_UPDATE_CC} can leave @code{cc_status} unaltered for such 4911insns. But suppose that the previous insn set the condition code 4912based on location @samp{a4@@(102)} and the current insn stores a new 4913value in @samp{a4}. Although the condition code is not changed by 4914this, it will no longer be true that it reflects the contents of 4915@samp{a4@@(102)}. Therefore, @code{NOTICE_UPDATE_CC} must alter 4916@code{cc_status} in this case to say that nothing is known about the 4917condition code value. 4918 4919The definition of @code{NOTICE_UPDATE_CC} must be prepared to deal 4920with the results of peephole optimization: insns whose patterns are 4921@code{parallel} RTXs containing various @code{reg}, @code{mem} or 4922constants which are just the operands. The RTL structure of these 4923insns is not sufficient to indicate what the insns actually do. What 4924@code{NOTICE_UPDATE_CC} should do when it sees one is just to run 4925@code{CC_STATUS_INIT}. 4926 4927A possible definition of @code{NOTICE_UPDATE_CC} is to call a function 4928that looks at an attribute (@pxref{Insn Attributes}) named, for example, 4929@samp{cc}. This avoids having detailed information about patterns in 4930two places, the @file{md} file and in @code{NOTICE_UPDATE_CC}. 4931 4932@findex EXTRA_CC_MODES 4933@item EXTRA_CC_MODES 4934A list of additional modes for condition code values in registers 4935(@pxref{Jump Patterns}). This macro should expand to a sequence of 4936calls of the macro @code{CC} separated by white space. @code{CC} takes 4937two arguments. The first is the enumeration name of the mode, which 4938should begin with @samp{CC} and end with @samp{mode}. The second is a C 4939string giving the printable name of the mode; it should be the same as 4940the first argument, but with the trailing @samp{mode} removed. 4941 4942You should only define this macro if additional modes are required. 4943 4944A sample definition of @code{EXTRA_CC_MODES} is: 4945@smallexample 4946#define EXTRA_CC_MODES \ 4947 CC(CC_NOOVmode, "CC_NOOV") \ 4948 CC(CCFPmode, "CCFP") \ 4949 CC(CCFPEmode, "CCFPE") 4950@end smallexample 4951 4952@findex SELECT_CC_MODE 4953@item SELECT_CC_MODE (@var{op}, @var{x}, @var{y}) 4954Returns a mode from class @code{MODE_CC} to be used when comparison 4955operation code @var{op} is applied to rtx @var{x} and @var{y}. For 4956example, on the Sparc, @code{SELECT_CC_MODE} is defined as (see 4957@pxref{Jump Patterns} for a description of the reason for this 4958definition) 4959 4960@smallexample 4961#define SELECT_CC_MODE(OP,X,Y) \ 4962 (GET_MODE_CLASS (GET_MODE (X)) == MODE_FLOAT \ 4963 ? ((OP == EQ || OP == NE) ? CCFPmode : CCFPEmode) \ 4964 : ((GET_CODE (X) == PLUS || GET_CODE (X) == MINUS \ 4965 || GET_CODE (X) == NEG) \ 4966 ? CC_NOOVmode : CCmode)) 4967@end smallexample 4968 4969You need not define this macro if @code{EXTRA_CC_MODES} is not defined. 4970 4971@findex CANONICALIZE_COMPARISON 4972@item CANONICALIZE_COMPARISON (@var{code}, @var{op0}, @var{op1}) 4973On some machines not all possible comparisons are defined, but you can 4974convert an invalid comparison into a valid one. For example, the Alpha 4975does not have a @code{GT} comparison, but you can use an @code{LT} 4976comparison instead and swap the order of the operands. 4977 4978On such machines, define this macro to be a C statement to do any 4979required conversions. @var{code} is the initial comparison code 4980and @var{op0} and @var{op1} are the left and right operands of the 4981comparison, respectively. You should modify @var{code}, @var{op0}, and 4982@var{op1} as required. 4983 4984GCC will not assume that the comparison resulting from this macro is 4985valid but will see if the resulting insn matches a pattern in the 4986@file{md} file. 4987 4988You need not define this macro if it would never change the comparison 4989code or operands. 4990 4991@findex REVERSIBLE_CC_MODE 4992@item REVERSIBLE_CC_MODE (@var{mode}) 4993A C expression whose value is one if it is always safe to reverse a 4994comparison whose mode is @var{mode}. If @code{SELECT_CC_MODE} 4995can ever return @var{mode} for a floating-point inequality comparison, 4996then @code{REVERSIBLE_CC_MODE (@var{mode})} must be zero. 4997 4998You need not define this macro if it would always returns zero or if the 4999floating-point format is anything other than @code{IEEE_FLOAT_FORMAT}. 5000For example, here is the definition used on the Sparc, where floating-point 5001inequality comparisons are always given @code{CCFPEmode}: 5002 5003@smallexample 5004#define REVERSIBLE_CC_MODE(MODE) ((MODE) != CCFPEmode) 5005@end smallexample 5006 5007@findex REVERSE_CONDITION (@var{code}, @var{mode}) 5008A C expression whose value is reversed condition code of the @var{code} for 5009comparison done in CC_MODE @var{mode}. The macro is used only in case 5010@code{REVERSIBLE_CC_MODE (@var{mode})} is nonzero. Define this macro in case 5011machine has some non-standard way how to reverse certain conditionals. For 5012instance in case all floating point conditions are non-trapping, compiler may 5013freely convert unordered compares to ordered one. Then definition may look 5014like: 5015 5016@smallexample 5017#define REVERSE_CONDITION(CODE, MODE) \ 5018 ((MODE) != CCFPmode ? reverse_condition (CODE) \ 5019 : reverse_condition_maybe_unordered (CODE)) 5020@end smallexample 5021 5022@findex REVERSE_CONDEXEC_PREDICATES_P 5023@item REVERSE_CONDEXEC_PREDICATES_P (@var{code1}, @var{code2}) 5024A C expression that returns true if the conditional execution predicate 5025@var{code1} is the inverse of @var{code2} and vice versa. Define this to 5026return 0 if the target has conditional execution predicates that cannot be 5027reversed safely. If no expansion is specified, this macro is defined as 5028follows: 5029 5030@smallexample 5031#define REVERSE_CONDEXEC_PREDICATES_P (x, y) \ 5032 ((x) == reverse_condition (y)) 5033@end smallexample 5034 5035@end table 5036 5037@node Costs 5038@section Describing Relative Costs of Operations 5039@cindex costs of instructions 5040@cindex relative costs 5041@cindex speed of instructions 5042 5043These macros let you describe the relative speed of various operations 5044on the target machine. 5045 5046@table @code 5047@findex CONST_COSTS 5048@item CONST_COSTS (@var{x}, @var{code}, @var{outer_code}) 5049A part of a C @code{switch} statement that describes the relative costs 5050of constant RTL expressions. It must contain @code{case} labels for 5051expression codes @code{const_int}, @code{const}, @code{symbol_ref}, 5052@code{label_ref} and @code{const_double}. Each case must ultimately 5053reach a @code{return} statement to return the relative cost of the use 5054of that kind of constant value in an expression. The cost may depend on 5055the precise value of the constant, which is available for examination in 5056@var{x}, and the rtx code of the expression in which it is contained, 5057found in @var{outer_code}. 5058 5059@var{code} is the expression code---redundant, since it can be 5060obtained with @code{GET_CODE (@var{x})}. 5061 5062@findex RTX_COSTS 5063@findex COSTS_N_INSNS 5064@item RTX_COSTS (@var{x}, @var{code}, @var{outer_code}) 5065Like @code{CONST_COSTS} but applies to nonconstant RTL expressions. 5066This can be used, for example, to indicate how costly a multiply 5067instruction is. In writing this macro, you can use the construct 5068@code{COSTS_N_INSNS (@var{n})} to specify a cost equal to @var{n} fast 5069instructions. @var{outer_code} is the code of the expression in which 5070@var{x} is contained. 5071 5072This macro is optional; do not define it if the default cost assumptions 5073are adequate for the target machine. 5074 5075@findex DEFAULT_RTX_COSTS 5076@item DEFAULT_RTX_COSTS (@var{x}, @var{code}, @var{outer_code}) 5077This macro, if defined, is called for any case not handled by the 5078@code{RTX_COSTS} or @code{CONST_COSTS} macros. This eliminates the need 5079to put case labels into the macro, but the code, or any functions it 5080calls, must assume that the RTL in @var{x} could be of any type that has 5081not already been handled. The arguments are the same as for 5082@code{RTX_COSTS}, and the macro should execute a return statement giving 5083the cost of any RTL expressions that it can handle. The default cost 5084calculation is used for any RTL for which this macro does not return a 5085value. 5086 5087This macro is optional; do not define it if the default cost assumptions 5088are adequate for the target machine. 5089 5090@findex ADDRESS_COST 5091@item ADDRESS_COST (@var{address}) 5092An expression giving the cost of an addressing mode that contains 5093@var{address}. If not defined, the cost is computed from 5094the @var{address} expression and the @code{CONST_COSTS} values. 5095 5096For most CISC machines, the default cost is a good approximation of the 5097true cost of the addressing mode. However, on RISC machines, all 5098instructions normally have the same length and execution time. Hence 5099all addresses will have equal costs. 5100 5101In cases where more than one form of an address is known, the form with 5102the lowest cost will be used. If multiple forms have the same, lowest, 5103cost, the one that is the most complex will be used. 5104 5105For example, suppose an address that is equal to the sum of a register 5106and a constant is used twice in the same basic block. When this macro 5107is not defined, the address will be computed in a register and memory 5108references will be indirect through that register. On machines where 5109the cost of the addressing mode containing the sum is no higher than 5110that of a simple indirect reference, this will produce an additional 5111instruction and possibly require an additional register. Proper 5112specification of this macro eliminates this overhead for such machines. 5113 5114Similar use of this macro is made in strength reduction of loops. 5115 5116@var{address} need not be valid as an address. In such a case, the cost 5117is not relevant and can be any value; invalid addresses need not be 5118assigned a different cost. 5119 5120On machines where an address involving more than one register is as 5121cheap as an address computation involving only one register, defining 5122@code{ADDRESS_COST} to reflect this can cause two registers to be live 5123over a region of code where only one would have been if 5124@code{ADDRESS_COST} were not defined in that manner. This effect should 5125be considered in the definition of this macro. Equivalent costs should 5126probably only be given to addresses with different numbers of registers 5127on machines with lots of registers. 5128 5129This macro will normally either not be defined or be defined as a 5130constant. 5131 5132@findex REGISTER_MOVE_COST 5133@item REGISTER_MOVE_COST (@var{mode}, @var{from}, @var{to}) 5134A C expression for the cost of moving data of mode @var{mode} from a 5135register in class @var{from} to one in class @var{to}. The classes are 5136expressed using the enumeration values such as @code{GENERAL_REGS}. A 5137value of 2 is the default; other values are interpreted relative to 5138that. 5139 5140It is not required that the cost always equal 2 when @var{from} is the 5141same as @var{to}; on some machines it is expensive to move between 5142registers if they are not general registers. 5143 5144If reload sees an insn consisting of a single @code{set} between two 5145hard registers, and if @code{REGISTER_MOVE_COST} applied to their 5146classes returns a value of 2, reload does not check to ensure that the 5147constraints of the insn are met. Setting a cost of other than 2 will 5148allow reload to verify that the constraints are met. You should do this 5149if the @samp{mov@var{m}} pattern's constraints do not allow such copying. 5150 5151@findex MEMORY_MOVE_COST 5152@item MEMORY_MOVE_COST (@var{mode}, @var{class}, @var{in}) 5153A C expression for the cost of moving data of mode @var{mode} between a 5154register of class @var{class} and memory; @var{in} is zero if the value 5155is to be written to memory, nonzero if it is to be read in. This cost 5156is relative to those in @code{REGISTER_MOVE_COST}. If moving between 5157registers and memory is more expensive than between two registers, you 5158should define this macro to express the relative cost. 5159 5160If you do not define this macro, GCC uses a default cost of 4 plus 5161the cost of copying via a secondary reload register, if one is 5162needed. If your machine requires a secondary reload register to copy 5163between memory and a register of @var{class} but the reload mechanism is 5164more complex than copying via an intermediate, define this macro to 5165reflect the actual cost of the move. 5166 5167GCC defines the function @code{memory_move_secondary_cost} if 5168secondary reloads are needed. It computes the costs due to copying via 5169a secondary register. If your machine copies from memory using a 5170secondary register in the conventional way but the default base value of 51714 is not correct for your machine, define this macro to add some other 5172value to the result of that function. The arguments to that function 5173are the same as to this macro. 5174 5175@findex BRANCH_COST 5176@item BRANCH_COST 5177A C expression for the cost of a branch instruction. A value of 1 is 5178the default; other values are interpreted relative to that. 5179@end table 5180 5181Here are additional macros which do not specify precise relative costs, 5182but only that certain actions are more expensive than GCC would 5183ordinarily expect. 5184 5185@table @code 5186@findex SLOW_BYTE_ACCESS 5187@item SLOW_BYTE_ACCESS 5188Define this macro as a C expression which is nonzero if accessing less 5189than a word of memory (i.e.@: a @code{char} or a @code{short}) is no 5190faster than accessing a word of memory, i.e., if such access 5191require more than one instruction or if there is no difference in cost 5192between byte and (aligned) word loads. 5193 5194When this macro is not defined, the compiler will access a field by 5195finding the smallest containing object; when it is defined, a fullword 5196load will be used if alignment permits. Unless bytes accesses are 5197faster than word accesses, using word accesses is preferable since it 5198may eliminate subsequent memory access if subsequent accesses occur to 5199other fields in the same word of the structure, but to different bytes. 5200 5201@findex SLOW_UNALIGNED_ACCESS 5202@item SLOW_UNALIGNED_ACCESS (@var{mode}, @var{alignment}) 5203Define this macro to be the value 1 if memory accesses described by the 5204@var{mode} and @var{alignment} parameters have a cost many times greater 5205than aligned accesses, for example if they are emulated in a trap 5206handler. 5207 5208When this macro is nonzero, the compiler will act as if 5209@code{STRICT_ALIGNMENT} were nonzero when generating code for block 5210moves. This can cause significantly more instructions to be produced. 5211Therefore, do not set this macro nonzero if unaligned accesses only add a 5212cycle or two to the time for a memory access. 5213 5214If the value of this macro is always zero, it need not be defined. If 5215this macro is defined, it should produce a nonzero value when 5216@code{STRICT_ALIGNMENT} is nonzero. 5217 5218@findex DONT_REDUCE_ADDR 5219@item DONT_REDUCE_ADDR 5220Define this macro to inhibit strength reduction of memory addresses. 5221(On some machines, such strength reduction seems to do harm rather 5222than good.) 5223 5224@findex MOVE_RATIO 5225@item MOVE_RATIO 5226The threshold of number of scalar memory-to-memory move insns, @emph{below} 5227which a sequence of insns should be generated instead of a 5228string move insn or a library call. Increasing the value will always 5229make code faster, but eventually incurs high cost in increased code size. 5230 5231Note that on machines where the corresponding move insn is a 5232@code{define_expand} that emits a sequence of insns, this macro counts 5233the number of such sequences. 5234 5235If you don't define this, a reasonable default is used. 5236 5237@findex MOVE_BY_PIECES_P 5238@item MOVE_BY_PIECES_P (@var{size}, @var{alignment}) 5239A C expression used to determine whether @code{move_by_pieces} will be used to 5240copy a chunk of memory, or whether some other block move mechanism 5241will be used. Defaults to 1 if @code{move_by_pieces_ninsns} returns less 5242than @code{MOVE_RATIO}. 5243 5244@findex MOVE_MAX_PIECES 5245@item MOVE_MAX_PIECES 5246A C expression used by @code{move_by_pieces} to determine the largest unit 5247a load or store used to copy memory is. Defaults to @code{MOVE_MAX}. 5248 5249@findex USE_LOAD_POST_INCREMENT 5250@item USE_LOAD_POST_INCREMENT (@var{mode}) 5251A C expression used to determine whether a load postincrement is a good 5252thing to use for a given mode. Defaults to the value of 5253@code{HAVE_POST_INCREMENT}. 5254 5255@findex USE_LOAD_POST_DECREMENT 5256@item USE_LOAD_POST_DECREMENT (@var{mode}) 5257A C expression used to determine whether a load postdecrement is a good 5258thing to use for a given mode. Defaults to the value of 5259@code{HAVE_POST_DECREMENT}. 5260 5261@findex USE_LOAD_PRE_INCREMENT 5262@item USE_LOAD_PRE_INCREMENT (@var{mode}) 5263A C expression used to determine whether a load preincrement is a good 5264thing to use for a given mode. Defaults to the value of 5265@code{HAVE_PRE_INCREMENT}. 5266 5267@findex USE_LOAD_PRE_DECREMENT 5268@item USE_LOAD_PRE_DECREMENT (@var{mode}) 5269A C expression used to determine whether a load predecrement is a good 5270thing to use for a given mode. Defaults to the value of 5271@code{HAVE_PRE_DECREMENT}. 5272 5273@findex USE_STORE_POST_INCREMENT 5274@item USE_STORE_POST_INCREMENT (@var{mode}) 5275A C expression used to determine whether a store postincrement is a good 5276thing to use for a given mode. Defaults to the value of 5277@code{HAVE_POST_INCREMENT}. 5278 5279@findex USE_STORE_POST_DECREMENT 5280@item USE_STORE_POST_DECREMENT (@var{mode}) 5281A C expression used to determine whether a store postdecrement is a good 5282thing to use for a given mode. Defaults to the value of 5283@code{HAVE_POST_DECREMENT}. 5284 5285@findex USE_STORE_PRE_INCREMENT 5286@item USE_STORE_PRE_INCREMENT (@var{mode}) 5287This macro is used to determine whether a store preincrement is a good 5288thing to use for a given mode. Defaults to the value of 5289@code{HAVE_PRE_INCREMENT}. 5290 5291@findex USE_STORE_PRE_DECREMENT 5292@item USE_STORE_PRE_DECREMENT (@var{mode}) 5293This macro is used to determine whether a store predecrement is a good 5294thing to use for a given mode. Defaults to the value of 5295@code{HAVE_PRE_DECREMENT}. 5296 5297@findex NO_FUNCTION_CSE 5298@item NO_FUNCTION_CSE 5299Define this macro if it is as good or better to call a constant 5300function address than to call an address kept in a register. 5301 5302@findex NO_RECURSIVE_FUNCTION_CSE 5303@item NO_RECURSIVE_FUNCTION_CSE 5304Define this macro if it is as good or better for a function to call 5305itself with an explicit address than to call an address kept in a 5306register. 5307@end table 5308 5309@node Scheduling 5310@section Adjusting the Instruction Scheduler 5311 5312The instruction scheduler may need a fair amount of machine-specific 5313adjustment in order to produce good code. GCC provides several target 5314hooks for this purpose. It is usually enough to define just a few of 5315them: try the first ones in this list first. 5316 5317@deftypefn {Target Hook} int TARGET_SCHED_ISSUE_RATE (void) 5318This hook returns the maximum number of instructions that can ever issue 5319at the same time on the target machine. The default is one. This value 5320must be constant over the entire compilation. If you need it to vary 5321depending on what the instructions are, you must use 5322@samp{TARGET_SCHED_VARIABLE_ISSUE}. 5323@end deftypefn 5324 5325@deftypefn {Target Hook} int TARGET_SCHED_VARIABLE_ISSUE (FILE *@var{file}, int @var{verbose}, rtx @var{insn}, int @var{more}) 5326This hook is executed by the scheduler after it has scheduled an insn 5327from the ready list. It should return the number of insns which can 5328still be issued in the current cycle. Normally this is 5329@samp{@w{@var{more} - 1}}. You should define this hook if some insns 5330take more machine resources than others, so that fewer insns can follow 5331them in the same cycle. @var{file} is either a null pointer, or a stdio 5332stream to write any debug output to. @var{verbose} is the verbose level 5333provided by @option{-fsched-verbose-@var{n}}. @var{insn} is the 5334instruction that was scheduled. 5335@end deftypefn 5336 5337@deftypefn {Target Hook} int TARGET_SCHED_ADJUST_COST (rtx @var{insn}, rtx @var{link}, rtx @var{dep_insn}, int @var{cost}) 5338This function corrects the value of @var{cost} based on the relationship 5339between @var{insn} and @var{dep_insn} through the dependence @var{link}. 5340It should return the new value. The default is to make no adjustment to 5341@var{cost}. This can be used for example to specify to the scheduler 5342that an output- or anti-dependence does not incur the same cost as a 5343data-dependence. 5344@end deftypefn 5345 5346@deftypefn {Target Hook} int TARGET_SCHED_ADJUST_PRIORITY (rtx @var{insn}, int @var{priority}) 5347This hook adjusts the integer scheduling priority @var{priority} of 5348@var{insn}. It should return the new priority. Reduce the priority to 5349execute @var{insn} earlier, increase the priority to execute @var{insn} 5350later. Do not define this hook if you do not need to adjust the 5351scheduling priorities of insns. 5352@end deftypefn 5353 5354@deftypefn {Target Hook} int TARGET_SCHED_REORDER (FILE *@var{file}, int @var{verbose}, rtx *@var{ready}, int *@var{n_readyp}, int @var{clock}) 5355This hook is executed by the scheduler after it has scheduled the ready 5356list, to allow the machine description to reorder it (for example to 5357combine two small instructions together on @samp{VLIW} machines). 5358@var{file} is either a null pointer, or a stdio stream to write any 5359debug output to. @var{verbose} is the verbose level provided by 5360@option{-fsched-verbose-@var{n}}. @var{ready} is a pointer to the ready 5361list of instructions that are ready to be scheduled. @var{n_readyp} is 5362a pointer to the number of elements in the ready list. The scheduler 5363reads the ready list in reverse order, starting with 5364@var{ready}[@var{*n_readyp}-1] and going to @var{ready}[0]. @var{clock} 5365is the timer tick of the scheduler. You may modify the ready list and 5366the number of ready insns. The return value is the number of insns that 5367can issue this cycle; normally this is just @code{issue_rate}. See also 5368@samp{TARGET_SCHED_REORDER2}. 5369@end deftypefn 5370 5371@deftypefn {Target Hook} int TARGET_SCHED_REORDER2 (FILE *@var{file}, int @var{verbose}, rtx *@var{ready}, int *@var{n_ready}, @var{clock}) 5372Like @samp{TARGET_SCHED_REORDER}, but called at a different time. That 5373function is called whenever the scheduler starts a new cycle. This one 5374is called once per iteration over a cycle, immediately after 5375@samp{TARGET_SCHED_VARIABLE_ISSUE}; it can reorder the ready list and 5376return the number of insns to be scheduled in the same cycle. Defining 5377this hook can be useful if there are frequent situations where 5378scheduling one insn causes other insns to become ready in the same 5379cycle. These other insns can then be taken into account properly. 5380@end deftypefn 5381 5382@deftypefn {Target Hook} void TARGET_SCHED_INIT (FILE *@var{file}, int @var{verbose}, int @var{max_ready}) 5383This hook is executed by the scheduler at the beginning of each block of 5384instructions that are to be scheduled. @var{file} is either a null 5385pointer, or a stdio stream to write any debug output to. @var{verbose} 5386is the verbose level provided by @option{-fsched-verbose-@var{n}}. 5387@var{max_ready} is the maximum number of insns in the current scheduling 5388region that can be live at the same time. This can be used to allocate 5389scratch space if it is needed, e.g. by @samp{TARGET_SCHED_REORDER}. 5390@end deftypefn 5391 5392@deftypefn {Target Hook} void TARGET_SCHED_FINISH (FILE *@var{file}, int @var{verbose}) 5393This hook is executed by the scheduler at the end of each block of 5394instructions that are to be scheduled. It can be used to perform 5395cleanup of any actions done by the other scheduling hooks. @var{file} 5396is either a null pointer, or a stdio stream to write any debug output 5397to. @var{verbose} is the verbose level provided by 5398@option{-fsched-verbose-@var{n}}. 5399@end deftypefn 5400 5401@deftypefn {Target Hook} rtx TARGET_SCHED_CYCLE_DISPLAY (int @var{clock}, rtx @var{last}) 5402This hook is called in verbose mode only, at the beginning of each pass 5403over a basic block. It should insert an insn into the chain after 5404@var{last}, which has no effect, but records the value @var{clock} in 5405RTL dumps and assembly output. Define this hook only if you need this 5406level of detail about what the scheduler is doing. 5407@end deftypefn 5408 5409@node Sections 5410@section Dividing the Output into Sections (Texts, Data, @dots{}) 5411@c the above section title is WAY too long. maybe cut the part between 5412@c the (...)? --mew 10feb93 5413 5414An object file is divided into sections containing different types of 5415data. In the most common case, there are three sections: the @dfn{text 5416section}, which holds instructions and read-only data; the @dfn{data 5417section}, which holds initialized writable data; and the @dfn{bss 5418section}, which holds uninitialized data. Some systems have other kinds 5419of sections. 5420 5421The compiler must tell the assembler when to switch sections. These 5422macros control what commands to output to tell the assembler this. You 5423can also define additional sections. 5424 5425@table @code 5426@findex TEXT_SECTION_ASM_OP 5427@item TEXT_SECTION_ASM_OP 5428A C expression whose value is a string, including spacing, containing the 5429assembler operation that should precede instructions and read-only data. 5430Normally @code{"\t.text"} is right. 5431 5432@findex TEXT_SECTION 5433@item TEXT_SECTION 5434A C statement that switches to the default section containing instructions. 5435Normally this is not needed, as simply defining @code{TEXT_SECTION_ASM_OP} 5436is enough. The MIPS port uses this to sort all functions after all data 5437declarations. 5438 5439@findex DATA_SECTION_ASM_OP 5440@item DATA_SECTION_ASM_OP 5441A C expression whose value is a string, including spacing, containing the 5442assembler operation to identify the following data as writable initialized 5443data. Normally @code{"\t.data"} is right. 5444 5445@findex SHARED_SECTION_ASM_OP 5446@item SHARED_SECTION_ASM_OP 5447If defined, a C expression whose value is a string, including spacing, 5448containing the assembler operation to identify the following data as 5449shared data. If not defined, @code{DATA_SECTION_ASM_OP} will be used. 5450 5451@findex BSS_SECTION_ASM_OP 5452@item BSS_SECTION_ASM_OP 5453If defined, a C expression whose value is a string, including spacing, 5454containing the assembler operation to identify the following data as 5455uninitialized global data. If not defined, and neither 5456@code{ASM_OUTPUT_BSS} nor @code{ASM_OUTPUT_ALIGNED_BSS} are defined, 5457uninitialized global data will be output in the data section if 5458@option{-fno-common} is passed, otherwise @code{ASM_OUTPUT_COMMON} will be 5459used. 5460 5461@findex SHARED_BSS_SECTION_ASM_OP 5462@item SHARED_BSS_SECTION_ASM_OP 5463If defined, a C expression whose value is a string, including spacing, 5464containing the assembler operation to identify the following data as 5465uninitialized global shared data. If not defined, and 5466@code{BSS_SECTION_ASM_OP} is, the latter will be used. 5467 5468@findex INIT_SECTION_ASM_OP 5469@item INIT_SECTION_ASM_OP 5470If defined, a C expression whose value is a string, including spacing, 5471containing the assembler operation to identify the following data as 5472initialization code. If not defined, GCC will assume such a section does 5473not exist. 5474 5475@findex FINI_SECTION_ASM_OP 5476@item FINI_SECTION_ASM_OP 5477If defined, a C expression whose value is a string, including spacing, 5478containing the assembler operation to identify the following data as 5479finalization code. If not defined, GCC will assume such a section does 5480not exist. 5481 5482@findex CRT_CALL_STATIC_FUNCTION 5483@item CRT_CALL_STATIC_FUNCTION (@var{section_op}, @var{function}) 5484If defined, an ASM statement that switches to a different section 5485via @var{section_op}, calls @var{function}, and switches back to 5486the text section. This is used in @file{crtstuff.c} if 5487@code{INIT_SECTION_ASM_OP} or @code{FINI_SECTION_ASM_OP} to calls 5488to initialization and finalization functions from the init and fini 5489sections. By default, this macro uses a simple function call. Some 5490ports need hand-crafted assembly code to avoid dependencies on 5491registers initialized in the function prologue or to ensure that 5492constant pools don't end up too far way in the text section. 5493 5494@findex FORCE_CODE_SECTION_ALIGN 5495@item FORCE_CODE_SECTION_ALIGN 5496If defined, an ASM statement that aligns a code section to some 5497arbitrary boundary. This is used to force all fragments of the 5498@code{.init} and @code{.fini} sections to have to same alignment 5499and thus prevent the linker from having to add any padding. 5500 5501@findex EXTRA_SECTIONS 5502@findex in_text 5503@findex in_data 5504@item EXTRA_SECTIONS 5505A list of names for sections other than the standard two, which are 5506@code{in_text} and @code{in_data}. You need not define this macro 5507on a system with no other sections (that GCC needs to use). 5508 5509@findex EXTRA_SECTION_FUNCTIONS 5510@findex text_section 5511@findex data_section 5512@item EXTRA_SECTION_FUNCTIONS 5513One or more functions to be defined in @file{varasm.c}. These 5514functions should do jobs analogous to those of @code{text_section} and 5515@code{data_section}, for your additional sections. Do not define this 5516macro if you do not define @code{EXTRA_SECTIONS}. 5517 5518@findex READONLY_DATA_SECTION 5519@item READONLY_DATA_SECTION 5520On most machines, read-only variables, constants, and jump tables are 5521placed in the text section. If this is not the case on your machine, 5522this macro should be defined to be the name of a function (either 5523@code{data_section} or a function defined in @code{EXTRA_SECTIONS}) that 5524switches to the section to be used for read-only items. 5525 5526If these items should be placed in the text section, this macro should 5527not be defined. 5528 5529@findex SELECT_SECTION 5530@item SELECT_SECTION (@var{exp}, @var{reloc}, @var{align}) 5531A C statement or statements to switch to the appropriate section for 5532output of @var{exp}. You can assume that @var{exp} is either a 5533@code{VAR_DECL} node or a constant of some sort. @var{reloc} 5534indicates whether the initial value of @var{exp} requires link-time 5535relocations. Bit 1 is set when variable contains local relocations 5536only, while bit 2 is set for global relocations. 5537Select the section by calling @code{text_section} or one 5538of the alternatives for other sections. @var{align} is the constant 5539alignment in bits. 5540 5541Do not define this macro if you put all read-only variables and 5542constants in the read-only data section (usually the text section). 5543 5544@findex SELECT_RTX_SECTION 5545@item SELECT_RTX_SECTION (@var{mode}, @var{rtx}, @var{align}) 5546A C statement or statements to switch to the appropriate section for 5547output of @var{rtx} in mode @var{mode}. You can assume that @var{rtx} 5548is some kind of constant in RTL@. The argument @var{mode} is redundant 5549except in the case of a @code{const_int} rtx. Select the section by 5550calling @code{text_section} or one of the alternatives for other 5551sections. @var{align} is the constant alignment in bits. 5552 5553Do not define this macro if you put all constants in the read-only 5554data section. 5555 5556@findex JUMP_TABLES_IN_TEXT_SECTION 5557@item JUMP_TABLES_IN_TEXT_SECTION 5558Define this macro to be an expression with a nonzero value if jump 5559tables (for @code{tablejump} insns) should be output in the text 5560section, along with the assembler instructions. Otherwise, the 5561readonly data section is used. 5562 5563This macro is irrelevant if there is no separate readonly data section. 5564 5565@findex ENCODE_SECTION_INFO 5566@item ENCODE_SECTION_INFO (@var{decl}) 5567Define this macro if references to a symbol or a constant must be 5568treated differently depending on something about the variable or 5569function named by the symbol (such as what section it is in). 5570 5571The macro definition, if any, is executed under two circumstances. One 5572is immediately after the rtl for @var{decl} that represents a variable 5573or a function has been created and stored in @code{DECL_RTL 5574(@var{decl})}. The value of the rtl will be a @code{mem} whose address 5575is a @code{symbol_ref}. The other is immediately after the rtl for 5576@var{decl} that represents a constant has been created and stored in 5577@code{TREE_CST_RTL (@var{decl})}. The macro is called once for each 5578distinct constant in a source file. 5579 5580@cindex @code{SYMBOL_REF_FLAG}, in @code{ENCODE_SECTION_INFO} 5581The usual thing for this macro to do is to record a flag in the 5582@code{symbol_ref} (such as @code{SYMBOL_REF_FLAG}) or to store a 5583modified name string in the @code{symbol_ref} (if one bit is not enough 5584information). 5585 5586@findex STRIP_NAME_ENCODING 5587@item STRIP_NAME_ENCODING (@var{var}, @var{sym_name}) 5588Decode @var{sym_name} and store the real name part in @var{var}, sans 5589the characters that encode section info. Define this macro if 5590@code{ENCODE_SECTION_INFO} alters the symbol's name string. 5591 5592@findex UNIQUE_SECTION 5593@item UNIQUE_SECTION (@var{decl}, @var{reloc}) 5594A C statement to build up a unique section name, expressed as a 5595@code{STRING_CST} node, and assign it to @samp{DECL_SECTION_NAME (@var{decl})}. 5596@var{reloc} indicates whether the initial value of @var{exp} requires 5597link-time relocations. If you do not define this macro, GCC will use 5598the symbol name prefixed by @samp{.} as the section name. Note - this 5599macro can now be called for uninitialized data items as well as 5600initialized data and functions. 5601@end table 5602 5603@node PIC 5604@section Position Independent Code 5605@cindex position independent code 5606@cindex PIC 5607 5608This section describes macros that help implement generation of position 5609independent code. Simply defining these macros is not enough to 5610generate valid PIC; you must also add support to the macros 5611@code{GO_IF_LEGITIMATE_ADDRESS} and @code{PRINT_OPERAND_ADDRESS}, as 5612well as @code{LEGITIMIZE_ADDRESS}. You must modify the definition of 5613@samp{movsi} to do something appropriate when the source operand 5614contains a symbolic address. You may also need to alter the handling of 5615switch statements so that they use relative addresses. 5616@c i rearranged the order of the macros above to try to force one of 5617@c them to the next line, to eliminate an overfull hbox. --mew 10feb93 5618 5619@table @code 5620@findex PIC_OFFSET_TABLE_REGNUM 5621@item PIC_OFFSET_TABLE_REGNUM 5622The register number of the register used to address a table of static 5623data addresses in memory. In some cases this register is defined by a 5624processor's ``application binary interface'' (ABI)@. When this macro 5625is defined, RTL is generated for this register once, as with the stack 5626pointer and frame pointer registers. If this macro is not defined, it 5627is up to the machine-dependent files to allocate such a register (if 5628necessary). Note that this register must be fixed when in use (e.g.@: 5629when @code{flag_pic} is true). 5630 5631@findex PIC_OFFSET_TABLE_REG_CALL_CLOBBERED 5632@item PIC_OFFSET_TABLE_REG_CALL_CLOBBERED 5633Define this macro if the register defined by 5634@code{PIC_OFFSET_TABLE_REGNUM} is clobbered by calls. Do not define 5635this macro if @code{PIC_OFFSET_TABLE_REGNUM} is not defined. 5636 5637@findex FINALIZE_PIC 5638@item FINALIZE_PIC 5639By generating position-independent code, when two different programs (A 5640and B) share a common library (libC.a), the text of the library can be 5641shared whether or not the library is linked at the same address for both 5642programs. In some of these environments, position-independent code 5643requires not only the use of different addressing modes, but also 5644special code to enable the use of these addressing modes. 5645 5646The @code{FINALIZE_PIC} macro serves as a hook to emit these special 5647codes once the function is being compiled into assembly code, but not 5648before. (It is not done before, because in the case of compiling an 5649inline function, it would lead to multiple PIC prologues being 5650included in functions which used inline functions and were compiled to 5651assembly language.) 5652 5653@findex LEGITIMATE_PIC_OPERAND_P 5654@item LEGITIMATE_PIC_OPERAND_P (@var{x}) 5655A C expression that is nonzero if @var{x} is a legitimate immediate 5656operand on the target machine when generating position independent code. 5657You can assume that @var{x} satisfies @code{CONSTANT_P}, so you need not 5658check this. You can also assume @var{flag_pic} is true, so you need not 5659check it either. You need not define this macro if all constants 5660(including @code{SYMBOL_REF}) can be immediate operands when generating 5661position independent code. 5662@end table 5663 5664@node Assembler Format 5665@section Defining the Output Assembler Language 5666 5667This section describes macros whose principal purpose is to describe how 5668to write instructions in assembler language---rather than what the 5669instructions do. 5670 5671@menu 5672* File Framework:: Structural information for the assembler file. 5673* Data Output:: Output of constants (numbers, strings, addresses). 5674* Uninitialized Data:: Output of uninitialized variables. 5675* Label Output:: Output and generation of labels. 5676* Initialization:: General principles of initialization 5677 and termination routines. 5678* Macros for Initialization:: 5679 Specific macros that control the handling of 5680 initialization and termination routines. 5681* Instruction Output:: Output of actual instructions. 5682* Dispatch Tables:: Output of jump tables. 5683* Exception Region Output:: Output of exception region code. 5684* Alignment Output:: Pseudo ops for alignment and skipping data. 5685@end menu 5686 5687@node File Framework 5688@subsection The Overall Framework of an Assembler File 5689@cindex assembler format 5690@cindex output of assembler code 5691 5692@c prevent bad page break with this line 5693This describes the overall framework of an assembler file. 5694 5695@table @code 5696@findex ASM_FILE_START 5697@item ASM_FILE_START (@var{stream}) 5698A C expression which outputs to the stdio stream @var{stream} 5699some appropriate text to go at the start of an assembler file. 5700 5701Normally this macro is defined to output a line containing 5702@samp{#NO_APP}, which is a comment that has no effect on most 5703assemblers but tells the GNU assembler that it can save time by not 5704checking for certain assembler constructs. 5705 5706On systems that use SDB, it is necessary to output certain commands; 5707see @file{attasm.h}. 5708 5709@findex ASM_FILE_END 5710@item ASM_FILE_END (@var{stream}) 5711A C expression which outputs to the stdio stream @var{stream} 5712some appropriate text to go at the end of an assembler file. 5713 5714If this macro is not defined, the default is to output nothing 5715special at the end of the file. Most systems don't require any 5716definition. 5717 5718On systems that use SDB, it is necessary to output certain commands; 5719see @file{attasm.h}. 5720 5721@findex ASM_COMMENT_START 5722@item ASM_COMMENT_START 5723A C string constant describing how to begin a comment in the target 5724assembler language. The compiler assumes that the comment will end at 5725the end of the line. 5726 5727@findex ASM_APP_ON 5728@item ASM_APP_ON 5729A C string constant for text to be output before each @code{asm} 5730statement or group of consecutive ones. Normally this is 5731@code{"#APP"}, which is a comment that has no effect on most 5732assemblers but tells the GNU assembler that it must check the lines 5733that follow for all valid assembler constructs. 5734 5735@findex ASM_APP_OFF 5736@item ASM_APP_OFF 5737A C string constant for text to be output after each @code{asm} 5738statement or group of consecutive ones. Normally this is 5739@code{"#NO_APP"}, which tells the GNU assembler to resume making the 5740time-saving assumptions that are valid for ordinary compiler output. 5741 5742@findex ASM_OUTPUT_SOURCE_FILENAME 5743@item ASM_OUTPUT_SOURCE_FILENAME (@var{stream}, @var{name}) 5744A C statement to output COFF information or DWARF debugging information 5745which indicates that filename @var{name} is the current source file to 5746the stdio stream @var{stream}. 5747 5748This macro need not be defined if the standard form of output 5749for the file format in use is appropriate. 5750 5751@findex OUTPUT_QUOTED_STRING 5752@item OUTPUT_QUOTED_STRING (@var{stream}, @var{string}) 5753A C statement to output the string @var{string} to the stdio stream 5754@var{stream}. If you do not call the function @code{output_quoted_string} 5755in your config files, GCC will only call it to output filenames to 5756the assembler source. So you can use it to canonicalize the format 5757of the filename using this macro. 5758 5759@findex ASM_OUTPUT_SOURCE_LINE 5760@item ASM_OUTPUT_SOURCE_LINE (@var{stream}, @var{line}) 5761A C statement to output DBX or SDB debugging information before code 5762for line number @var{line} of the current source file to the 5763stdio stream @var{stream}. 5764 5765This macro need not be defined if the standard form of debugging 5766information for the debugger in use is appropriate. 5767 5768@findex ASM_OUTPUT_IDENT 5769@item ASM_OUTPUT_IDENT (@var{stream}, @var{string}) 5770A C statement to output something to the assembler file to handle a 5771@samp{#ident} directive containing the text @var{string}. If this 5772macro is not defined, nothing is output for a @samp{#ident} directive. 5773 5774@findex OBJC_PROLOGUE 5775@item OBJC_PROLOGUE 5776A C statement to output any assembler statements which are required to 5777precede any Objective-C object definitions or message sending. The 5778statement is executed only when compiling an Objective-C program. 5779@end table 5780 5781@deftypefn {Target Hook} void TARGET_ASM_NAMED_SECTION (const char *@var{name}, unsigned int @var{flags}, unsigned int @var{align}) 5782Output assembly directives to switch to section @var{name}. The section 5783should have attributes as specified by @var{flags}, which is a bit mask 5784of the @code{SECTION_*} flags defined in @file{output.h}. If @var{align} 5785is nonzero, it contains an alignment in bytes to be used for the section, 5786otherwise some target default should be used. Only targets that must 5787specify an alignment within the section directive need pay attention to 5788@var{align} -- we will still use @code{ASM_OUTPUT_ALIGN}. 5789@end deftypefn 5790 5791@deftypefn {Target Hook} bool TARGET_HAVE_NAMED_SECTIONS 5792This flag is true if the target supports @code{TARGET_ASM_NAMED_SECTION}. 5793@end deftypefn 5794 5795@deftypefn {Target Hook} {unsigned int} TARGET_SECTION_TYPE_FLAGS (tree @var{decl}, const char *@var{name}, int @var{reloc}) 5796Choose a set of section attributes for use by @code{TARGET_ASM_NAMED_SECTION} 5797based on a variable or function decl, a section name, and whether or not the 5798declaration's initializer may contain runtime relocations. @var{decl} may be 5799 null, in which case read-write data should be assumed. 5800 5801The default version if this function handles choosing code vs data, 5802read-only vs read-write data, and @code{flag_pic}. You should only 5803need to override this if your target has special flags that might be 5804set via @code{__attribute__}. 5805@end deftypefn 5806 5807@need 2000 5808@node Data Output 5809@subsection Output of Data 5810 5811 5812@deftypevr {Target Hook} {const char *} TARGET_ASM_BYTE_OP 5813@deftypevrx {Target Hook} {const char *} TARGET_ASM_ALIGNED_HI_OP 5814@deftypevrx {Target Hook} {const char *} TARGET_ASM_ALIGNED_SI_OP 5815@deftypevrx {Target Hook} {const char *} TARGET_ASM_ALIGNED_DI_OP 5816@deftypevrx {Target Hook} {const char *} TARGET_ASM_ALIGNED_TI_OP 5817@deftypevrx {Target Hook} {const char *} TARGET_ASM_UNALIGNED_HI_OP 5818@deftypevrx {Target Hook} {const char *} TARGET_ASM_UNALIGNED_SI_OP 5819@deftypevrx {Target Hook} {const char *} TARGET_ASM_UNALIGNED_DI_OP 5820@deftypevrx {Target Hook} {const char *} TARGET_ASM_UNALIGNED_TI_OP 5821These hooks specify assembly directives for creating certain kinds 5822of integer object. The @code{TARGET_ASM_BYTE_OP} directive creates a 5823byte-sized object, the @code{TARGET_ASM_ALIGNED_HI_OP} one creates an 5824aligned two-byte object, and so on. Any of the hooks may be 5825@code{NULL}, indicating that no suitable directive is available. 5826 5827The compiler will print these strings at the start of a new line, 5828followed immediately by the object's initial value. In most cases, 5829the string should contain a tab, a pseudo-op, and then another tab. 5830@end deftypevr 5831 5832@deftypefn {Target Hook} bool TARGET_ASM_INTEGER (rtx @var{x}, unsigned int @var{size}, int @var{aligned_p}) 5833The @code{assemble_integer} function uses this hook to output an 5834integer object. @var{x} is the object's value, @var{size} is its size 5835in bytes and @var{aligned_p} indicates whether it is aligned. The 5836function should return @code{true} if it was able to output the 5837object. If it returns false, @code{assemble_integer} will try to 5838split the object into smaller parts. 5839 5840The default implementation of this hook will use the 5841@code{TARGET_ASM_BYTE_OP} family of strings, returning @code{false} 5842when the relevant string is @code{NULL}. 5843@end deftypefn 5844 5845@table @code 5846@findex OUTPUT_ADDR_CONST_EXTRA 5847@item OUTPUT_ADDR_CONST_EXTRA (@var{stream}, @var{x}, @var{fail}) 5848A C statement to recognize @var{rtx} patterns that 5849@code{output_addr_const} can't deal with, and output assembly code to 5850@var{stream} corresponding to the pattern @var{x}. This may be used to 5851allow machine-dependent @code{UNSPEC}s to appear within constants. 5852 5853If @code{OUTPUT_ADDR_CONST_EXTRA} fails to recognize a pattern, it must 5854@code{goto fail}, so that a standard error message is printed. If it 5855prints an error message itself, by calling, for example, 5856@code{output_operand_lossage}, it may just complete normally. 5857 5858@findex ASM_OUTPUT_ASCII 5859@item ASM_OUTPUT_ASCII (@var{stream}, @var{ptr}, @var{len}) 5860A C statement to output to the stdio stream @var{stream} an assembler 5861instruction to assemble a string constant containing the @var{len} 5862bytes at @var{ptr}. @var{ptr} will be a C expression of type 5863@code{char *} and @var{len} a C expression of type @code{int}. 5864 5865If the assembler has a @code{.ascii} pseudo-op as found in the 5866Berkeley Unix assembler, do not define the macro 5867@code{ASM_OUTPUT_ASCII}. 5868 5869@findex ASM_OUTPUT_FDESC 5870@item ASM_OUTPUT_FDESC (@var{stream}, @var{decl}, @var{n}) 5871A C statement to output word @var{n} of a function descriptor for 5872@var{decl}. This must be defined if @code{TARGET_VTABLE_USES_DESCRIPTORS} 5873is defined, and is otherwise unused. 5874 5875@findex CONSTANT_POOL_BEFORE_FUNCTION 5876@item CONSTANT_POOL_BEFORE_FUNCTION 5877You may define this macro as a C expression. You should define the 5878expression to have a nonzero value if GCC should output the constant 5879pool for a function before the code for the function, or a zero value if 5880GCC should output the constant pool after the function. If you do 5881not define this macro, the usual case, GCC will output the constant 5882pool before the function. 5883 5884@findex ASM_OUTPUT_POOL_PROLOGUE 5885@item ASM_OUTPUT_POOL_PROLOGUE (@var{file}, @var{funname}, @var{fundecl}, @var{size}) 5886A C statement to output assembler commands to define the start of the 5887constant pool for a function. @var{funname} is a string giving 5888the name of the function. Should the return type of the function 5889be required, it can be obtained via @var{fundecl}. @var{size} 5890is the size, in bytes, of the constant pool that will be written 5891immediately after this call. 5892 5893If no constant-pool prefix is required, the usual case, this macro need 5894not be defined. 5895 5896@findex ASM_OUTPUT_SPECIAL_POOL_ENTRY 5897@item ASM_OUTPUT_SPECIAL_POOL_ENTRY (@var{file}, @var{x}, @var{mode}, @var{align}, @var{labelno}, @var{jumpto}) 5898A C statement (with or without semicolon) to output a constant in the 5899constant pool, if it needs special treatment. (This macro need not do 5900anything for RTL expressions that can be output normally.) 5901 5902The argument @var{file} is the standard I/O stream to output the 5903assembler code on. @var{x} is the RTL expression for the constant to 5904output, and @var{mode} is the machine mode (in case @var{x} is a 5905@samp{const_int}). @var{align} is the required alignment for the value 5906@var{x}; you should output an assembler directive to force this much 5907alignment. 5908 5909The argument @var{labelno} is a number to use in an internal label for 5910the address of this pool entry. The definition of this macro is 5911responsible for outputting the label definition at the proper place. 5912Here is how to do this: 5913 5914@example 5915ASM_OUTPUT_INTERNAL_LABEL (@var{file}, "LC", @var{labelno}); 5916@end example 5917 5918When you output a pool entry specially, you should end with a 5919@code{goto} to the label @var{jumpto}. This will prevent the same pool 5920entry from being output a second time in the usual manner. 5921 5922You need not define this macro if it would do nothing. 5923 5924@findex CONSTANT_AFTER_FUNCTION_P 5925@item CONSTANT_AFTER_FUNCTION_P (@var{exp}) 5926Define this macro as a C expression which is nonzero if the constant 5927@var{exp}, of type @code{tree}, should be output after the code for a 5928function. The compiler will normally output all constants before the 5929function; you need not define this macro if this is OK@. 5930 5931@findex ASM_OUTPUT_POOL_EPILOGUE 5932@item ASM_OUTPUT_POOL_EPILOGUE (@var{file} @var{funname} @var{fundecl} @var{size}) 5933A C statement to output assembler commands to at the end of the constant 5934pool for a function. @var{funname} is a string giving the name of the 5935function. Should the return type of the function be required, you can 5936obtain it via @var{fundecl}. @var{size} is the size, in bytes, of the 5937constant pool that GCC wrote immediately before this call. 5938 5939If no constant-pool epilogue is required, the usual case, you need not 5940define this macro. 5941 5942@findex IS_ASM_LOGICAL_LINE_SEPARATOR 5943@item IS_ASM_LOGICAL_LINE_SEPARATOR (@var{C}) 5944Define this macro as a C expression which is nonzero if @var{C} is 5945used as a logical line separator by the assembler. 5946 5947If you do not define this macro, the default is that only 5948the character @samp{;} is treated as a logical line separator. 5949@end table 5950 5951@deftypevr {Target Hook} {const char *} TARGET_ASM_OPEN_PAREN 5952@deftypevrx {Target Hook} {const char *} TARGET_ASM_CLOSE_PAREN 5953These target hooks are C string constants, describing the syntax in the 5954assembler for grouping arithmetic expressions. If not overridden, they 5955default to normal parentheses, which is correct for most assemblers. 5956@end deftypevr 5957 5958 These macros are provided by @file{real.h} for writing the definitions 5959of @code{ASM_OUTPUT_DOUBLE} and the like: 5960 5961@table @code 5962@item REAL_VALUE_TO_TARGET_SINGLE (@var{x}, @var{l}) 5963@itemx REAL_VALUE_TO_TARGET_DOUBLE (@var{x}, @var{l}) 5964@itemx REAL_VALUE_TO_TARGET_LONG_DOUBLE (@var{x}, @var{l}) 5965@findex REAL_VALUE_TO_TARGET_SINGLE 5966@findex REAL_VALUE_TO_TARGET_DOUBLE 5967@findex REAL_VALUE_TO_TARGET_LONG_DOUBLE 5968These translate @var{x}, of type @code{REAL_VALUE_TYPE}, to the target's 5969floating point representation, and store its bit pattern in the array of 5970@code{long int} whose address is @var{l}. The number of elements in the 5971output array is determined by the size of the desired target floating 5972point data type: 32 bits of it go in each @code{long int} array 5973element. Each array element holds 32 bits of the result, even if 5974@code{long int} is wider than 32 bits on the host machine. 5975 5976The array element values are designed so that you can print them out 5977using @code{fprintf} in the order they should appear in the target 5978machine's memory. 5979 5980@item REAL_VALUE_TO_DECIMAL (@var{x}, @var{format}, @var{string}) 5981@findex REAL_VALUE_TO_DECIMAL 5982This macro converts @var{x}, of type @code{REAL_VALUE_TYPE}, to a 5983decimal number and stores it as a string into @var{string}. 5984You must pass, as @var{string}, the address of a long enough block 5985of space to hold the result. 5986 5987The argument @var{format} is a @code{printf}-specification that serves 5988as a suggestion for how to format the output string. 5989@end table 5990 5991@node Uninitialized Data 5992@subsection Output of Uninitialized Variables 5993 5994Each of the macros in this section is used to do the whole job of 5995outputting a single uninitialized variable. 5996 5997@table @code 5998@findex ASM_OUTPUT_COMMON 5999@item ASM_OUTPUT_COMMON (@var{stream}, @var{name}, @var{size}, @var{rounded}) 6000A C statement (sans semicolon) to output to the stdio stream 6001@var{stream} the assembler definition of a common-label named 6002@var{name} whose size is @var{size} bytes. The variable @var{rounded} 6003is the size rounded up to whatever alignment the caller wants. 6004 6005Use the expression @code{assemble_name (@var{stream}, @var{name})} to 6006output the name itself; before and after that, output the additional 6007assembler syntax for defining the name, and a newline. 6008 6009This macro controls how the assembler definitions of uninitialized 6010common global variables are output. 6011 6012@findex ASM_OUTPUT_ALIGNED_COMMON 6013@item ASM_OUTPUT_ALIGNED_COMMON (@var{stream}, @var{name}, @var{size}, @var{alignment}) 6014Like @code{ASM_OUTPUT_COMMON} except takes the required alignment as a 6015separate, explicit argument. If you define this macro, it is used in 6016place of @code{ASM_OUTPUT_COMMON}, and gives you more flexibility in 6017handling the required alignment of the variable. The alignment is specified 6018as the number of bits. 6019 6020@findex ASM_OUTPUT_ALIGNED_DECL_COMMON 6021@item ASM_OUTPUT_ALIGNED_DECL_COMMON (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{alignment}) 6022Like @code{ASM_OUTPUT_ALIGNED_COMMON} except that @var{decl} of the 6023variable to be output, if there is one, or @code{NULL_TREE} if there 6024is no corresponding variable. If you define this macro, GCC will use it 6025in place of both @code{ASM_OUTPUT_COMMON} and 6026@code{ASM_OUTPUT_ALIGNED_COMMON}. Define this macro when you need to see 6027the variable's decl in order to chose what to output. 6028 6029@findex ASM_OUTPUT_SHARED_COMMON 6030@item ASM_OUTPUT_SHARED_COMMON (@var{stream}, @var{name}, @var{size}, @var{rounded}) 6031If defined, it is similar to @code{ASM_OUTPUT_COMMON}, except that it 6032is used when @var{name} is shared. If not defined, @code{ASM_OUTPUT_COMMON} 6033will be used. 6034 6035@findex ASM_OUTPUT_BSS 6036@item ASM_OUTPUT_BSS (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{rounded}) 6037A C statement (sans semicolon) to output to the stdio stream 6038@var{stream} the assembler definition of uninitialized global @var{decl} named 6039@var{name} whose size is @var{size} bytes. The variable @var{rounded} 6040is the size rounded up to whatever alignment the caller wants. 6041 6042Try to use function @code{asm_output_bss} defined in @file{varasm.c} when 6043defining this macro. If unable, use the expression 6044@code{assemble_name (@var{stream}, @var{name})} to output the name itself; 6045before and after that, output the additional assembler syntax for defining 6046the name, and a newline. 6047 6048This macro controls how the assembler definitions of uninitialized global 6049variables are output. This macro exists to properly support languages like 6050C++ which do not have @code{common} data. However, this macro currently 6051is not defined for all targets. If this macro and 6052@code{ASM_OUTPUT_ALIGNED_BSS} are not defined then @code{ASM_OUTPUT_COMMON} 6053or @code{ASM_OUTPUT_ALIGNED_COMMON} or 6054@code{ASM_OUTPUT_ALIGNED_DECL_COMMON} is used. 6055 6056@findex ASM_OUTPUT_ALIGNED_BSS 6057@item ASM_OUTPUT_ALIGNED_BSS (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{alignment}) 6058Like @code{ASM_OUTPUT_BSS} except takes the required alignment as a 6059separate, explicit argument. If you define this macro, it is used in 6060place of @code{ASM_OUTPUT_BSS}, and gives you more flexibility in 6061handling the required alignment of the variable. The alignment is specified 6062as the number of bits. 6063 6064Try to use function @code{asm_output_aligned_bss} defined in file 6065@file{varasm.c} when defining this macro. 6066 6067@findex ASM_OUTPUT_SHARED_BSS 6068@item ASM_OUTPUT_SHARED_BSS (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{rounded}) 6069If defined, it is similar to @code{ASM_OUTPUT_BSS}, except that it 6070is used when @var{name} is shared. If not defined, @code{ASM_OUTPUT_BSS} 6071will be used. 6072 6073@findex ASM_OUTPUT_LOCAL 6074@item ASM_OUTPUT_LOCAL (@var{stream}, @var{name}, @var{size}, @var{rounded}) 6075A C statement (sans semicolon) to output to the stdio stream 6076@var{stream} the assembler definition of a local-common-label named 6077@var{name} whose size is @var{size} bytes. The variable @var{rounded} 6078is the size rounded up to whatever alignment the caller wants. 6079 6080Use the expression @code{assemble_name (@var{stream}, @var{name})} to 6081output the name itself; before and after that, output the additional 6082assembler syntax for defining the name, and a newline. 6083 6084This macro controls how the assembler definitions of uninitialized 6085static variables are output. 6086 6087@findex ASM_OUTPUT_ALIGNED_LOCAL 6088@item ASM_OUTPUT_ALIGNED_LOCAL (@var{stream}, @var{name}, @var{size}, @var{alignment}) 6089Like @code{ASM_OUTPUT_LOCAL} except takes the required alignment as a 6090separate, explicit argument. If you define this macro, it is used in 6091place of @code{ASM_OUTPUT_LOCAL}, and gives you more flexibility in 6092handling the required alignment of the variable. The alignment is specified 6093as the number of bits. 6094 6095@findex ASM_OUTPUT_ALIGNED_DECL_LOCAL 6096@item ASM_OUTPUT_ALIGNED_DECL_LOCAL (@var{stream}, @var{decl}, @var{name}, @var{size}, @var{alignment}) 6097Like @code{ASM_OUTPUT_ALIGNED_DECL} except that @var{decl} of the 6098variable to be output, if there is one, or @code{NULL_TREE} if there 6099is no corresponding variable. If you define this macro, GCC will use it 6100in place of both @code{ASM_OUTPUT_DECL} and 6101@code{ASM_OUTPUT_ALIGNED_DECL}. Define this macro when you need to see 6102the variable's decl in order to chose what to output. 6103 6104@findex ASM_OUTPUT_SHARED_LOCAL 6105@item ASM_OUTPUT_SHARED_LOCAL (@var{stream}, @var{name}, @var{size}, @var{rounded}) 6106If defined, it is similar to @code{ASM_OUTPUT_LOCAL}, except that it 6107is used when @var{name} is shared. If not defined, @code{ASM_OUTPUT_LOCAL} 6108will be used. 6109@end table 6110 6111@node Label Output 6112@subsection Output and Generation of Labels 6113 6114@c prevent bad page break with this line 6115This is about outputting labels. 6116 6117@table @code 6118@findex ASM_OUTPUT_LABEL 6119@findex assemble_name 6120@item ASM_OUTPUT_LABEL (@var{stream}, @var{name}) 6121A C statement (sans semicolon) to output to the stdio stream 6122@var{stream} the assembler definition of a label named @var{name}. 6123Use the expression @code{assemble_name (@var{stream}, @var{name})} to 6124output the name itself; before and after that, output the additional 6125assembler syntax for defining the name, and a newline. 6126 6127@findex ASM_DECLARE_FUNCTION_NAME 6128@item ASM_DECLARE_FUNCTION_NAME (@var{stream}, @var{name}, @var{decl}) 6129A C statement (sans semicolon) to output to the stdio stream 6130@var{stream} any text necessary for declaring the name @var{name} of a 6131function which is being defined. This macro is responsible for 6132outputting the label definition (perhaps using 6133@code{ASM_OUTPUT_LABEL}). The argument @var{decl} is the 6134@code{FUNCTION_DECL} tree node representing the function. 6135 6136If this macro is not defined, then the function name is defined in the 6137usual manner as a label (by means of @code{ASM_OUTPUT_LABEL}). 6138 6139@findex ASM_DECLARE_FUNCTION_SIZE 6140@item ASM_DECLARE_FUNCTION_SIZE (@var{stream}, @var{name}, @var{decl}) 6141A C statement (sans semicolon) to output to the stdio stream 6142@var{stream} any text necessary for declaring the size of a function 6143which is being defined. The argument @var{name} is the name of the 6144function. The argument @var{decl} is the @code{FUNCTION_DECL} tree node 6145representing the function. 6146 6147If this macro is not defined, then the function size is not defined. 6148 6149@findex ASM_DECLARE_OBJECT_NAME 6150@item ASM_DECLARE_OBJECT_NAME (@var{stream}, @var{name}, @var{decl}) 6151A C statement (sans semicolon) to output to the stdio stream 6152@var{stream} any text necessary for declaring the name @var{name} of an 6153initialized variable which is being defined. This macro must output the 6154label definition (perhaps using @code{ASM_OUTPUT_LABEL}). The argument 6155@var{decl} is the @code{VAR_DECL} tree node representing the variable. 6156 6157If this macro is not defined, then the variable name is defined in the 6158usual manner as a label (by means of @code{ASM_OUTPUT_LABEL}). 6159 6160@findex ASM_DECLARE_REGISTER_GLOBAL 6161@item ASM_DECLARE_REGISTER_GLOBAL (@var{stream}, @var{decl}, @var{regno}, @var{name}) 6162A C statement (sans semicolon) to output to the stdio stream 6163@var{stream} any text necessary for claiming a register @var{regno} 6164for a global variable @var{decl} with name @var{name}. 6165 6166If you don't define this macro, that is equivalent to defining it to do 6167nothing. 6168 6169@findex ASM_FINISH_DECLARE_OBJECT 6170@item ASM_FINISH_DECLARE_OBJECT (@var{stream}, @var{decl}, @var{toplevel}, @var{atend}) 6171A C statement (sans semicolon) to finish up declaring a variable name 6172once the compiler has processed its initializer fully and thus has had a 6173chance to determine the size of an array when controlled by an 6174initializer. This is used on systems where it's necessary to declare 6175something about the size of the object. 6176 6177If you don't define this macro, that is equivalent to defining it to do 6178nothing. 6179 6180@findex ASM_GLOBALIZE_LABEL 6181@item ASM_GLOBALIZE_LABEL (@var{stream}, @var{name}) 6182A C statement (sans semicolon) to output to the stdio stream 6183@var{stream} some commands that will make the label @var{name} global; 6184that is, available for reference from other files. Use the expression 6185@code{assemble_name (@var{stream}, @var{name})} to output the name 6186itself; before and after that, output the additional assembler syntax 6187for making that name global, and a newline. 6188 6189@findex ASM_WEAKEN_LABEL 6190@item ASM_WEAKEN_LABEL (@var{stream}, @var{name}) 6191A C statement (sans semicolon) to output to the stdio stream 6192@var{stream} some commands that will make the label @var{name} weak; 6193that is, available for reference from other files but only used if 6194no other definition is available. Use the expression 6195@code{assemble_name (@var{stream}, @var{name})} to output the name 6196itself; before and after that, output the additional assembler syntax 6197for making that name weak, and a newline. 6198 6199If you don't define this macro or @code{ASM_WEAKEN_DECL}, GCC will not 6200support weak symbols and you should not define the @code{SUPPORTS_WEAK} 6201macro. 6202 6203@findex ASM_WEAKEN_DECL 6204@item ASM_WEAKEN_DECL (@var{stream}, @var{decl}, @var{name}, @var{value}) 6205Combines (and replaces) the function of @code{ASM_WEAKEN_LABEL} and 6206@code{ASM_OUTPUT_WEAK_ALIAS}, allowing access to the associated function 6207or variable decl. If @var{value} is not @code{NULL}, this C statement 6208should output to the stdio stream @var{stream} assembler code which 6209defines (equates) the weak symbol @var{name} to have the value 6210@var{value}. If @var{value} is @code{NULL}, it should output commands 6211to make @var{name} weak. 6212 6213@findex SUPPORTS_WEAK 6214@item SUPPORTS_WEAK 6215A C expression which evaluates to true if the target supports weak symbols. 6216 6217If you don't define this macro, @file{defaults.h} provides a default 6218definition. If either @code{ASM_WEAKEN_LABEL} or @code{ASM_WEAKEN_DECL} 6219is defined, the default definition is @samp{1}; otherwise, it is 6220@samp{0}. Define this macro if you want to control weak symbol support 6221with a compiler flag such as @option{-melf}. 6222 6223@findex MAKE_DECL_ONE_ONLY (@var{decl}) 6224@item MAKE_DECL_ONE_ONLY 6225A C statement (sans semicolon) to mark @var{decl} to be emitted as a 6226public symbol such that extra copies in multiple translation units will 6227be discarded by the linker. Define this macro if your object file 6228format provides support for this concept, such as the @samp{COMDAT} 6229section flags in the Microsoft Windows PE/COFF format, and this support 6230requires changes to @var{decl}, such as putting it in a separate section. 6231 6232@findex SUPPORTS_ONE_ONLY 6233@item SUPPORTS_ONE_ONLY 6234A C expression which evaluates to true if the target supports one-only 6235semantics. 6236 6237If you don't define this macro, @file{varasm.c} provides a default 6238definition. If @code{MAKE_DECL_ONE_ONLY} is defined, the default 6239definition is @samp{1}; otherwise, it is @samp{0}. Define this macro if 6240you want to control one-only symbol support with a compiler flag, or if 6241setting the @code{DECL_ONE_ONLY} flag is enough to mark a declaration to 6242be emitted as one-only. 6243 6244@findex ASM_OUTPUT_EXTERNAL 6245@item ASM_OUTPUT_EXTERNAL (@var{stream}, @var{decl}, @var{name}) 6246A C statement (sans semicolon) to output to the stdio stream 6247@var{stream} any text necessary for declaring the name of an external 6248symbol named @var{name} which is referenced in this compilation but 6249not defined. The value of @var{decl} is the tree node for the 6250declaration. 6251 6252This macro need not be defined if it does not need to output anything. 6253The GNU assembler and most Unix assemblers don't require anything. 6254 6255@findex ASM_OUTPUT_EXTERNAL_LIBCALL 6256@item ASM_OUTPUT_EXTERNAL_LIBCALL (@var{stream}, @var{symref}) 6257A C statement (sans semicolon) to output on @var{stream} an assembler 6258pseudo-op to declare a library function name external. The name of the 6259library function is given by @var{symref}, which has type @code{rtx} and 6260is a @code{symbol_ref}. 6261 6262This macro need not be defined if it does not need to output anything. 6263The GNU assembler and most Unix assemblers don't require anything. 6264 6265@findex ASM_OUTPUT_LABELREF 6266@item ASM_OUTPUT_LABELREF (@var{stream}, @var{name}) 6267A C statement (sans semicolon) to output to the stdio stream 6268@var{stream} a reference in assembler syntax to a label named 6269@var{name}. This should add @samp{_} to the front of the name, if that 6270is customary on your operating system, as it is in most Berkeley Unix 6271systems. This macro is used in @code{assemble_name}. 6272 6273@findex ASM_OUTPUT_SYMBOL_REF 6274@item ASM_OUTPUT_SYMBOL_REF (@var{stream}, @var{sym}) 6275A C statement (sans semicolon) to output a reference to 6276@code{SYMBOL_REF} @var{sym}. If not defined, @code{assemble_name} 6277will be used to output the name of the symbol. This macro may be used 6278to modify the way a symbol is referenced depending on information 6279encoded by @code{ENCODE_SECTION_INFO}. 6280 6281@findex ASM_OUTPUT_LABEL_REF 6282@item ASM_OUTPUT_LABEL_REF (@var{stream}, @var{buf}) 6283A C statement (sans semicolon) to output a reference to @var{buf}, the 6284result of ASM_GENERATE_INTERNAL_LABEL. If not defined, 6285@code{assemble_name} will be used to output the name of the symbol. 6286This macro is not used by @code{output_asm_label}, or the @code{%l} 6287specifier that calls it; the intention is that this macro should be set 6288when it is necessary to output a label differently when its address 6289is being taken. 6290 6291@findex ASM_OUTPUT_INTERNAL_LABEL 6292@item ASM_OUTPUT_INTERNAL_LABEL (@var{stream}, @var{prefix}, @var{num}) 6293A C statement to output to the stdio stream @var{stream} a label whose 6294name is made from the string @var{prefix} and the number @var{num}. 6295 6296It is absolutely essential that these labels be distinct from the labels 6297used for user-level functions and variables. Otherwise, certain programs 6298will have name conflicts with internal labels. 6299 6300It is desirable to exclude internal labels from the symbol table of the 6301object file. Most assemblers have a naming convention for labels that 6302should be excluded; on many systems, the letter @samp{L} at the 6303beginning of a label has this effect. You should find out what 6304convention your system uses, and follow it. 6305 6306The usual definition of this macro is as follows: 6307 6308@example 6309fprintf (@var{stream}, "L%s%d:\n", @var{prefix}, @var{num}) 6310@end example 6311 6312@findex ASM_OUTPUT_DEBUG_LABEL 6313@item ASM_OUTPUT_DEBUG_LABEL (@var{stream}, @var{prefix}, @var{num}) 6314A C statement to output to the stdio stream @var{stream} a debug info 6315label whose name is made from the string @var{prefix} and the number 6316@var{num}. This is useful for VLIW targets, where debug info labels 6317may need to be treated differently than branch target labels. On some 6318systems, branch target labels must be at the beginning of instruction 6319bundles, but debug info labels can occur in the middle of instruction 6320bundles. 6321 6322If this macro is not defined, then @code{ASM_OUTPUT_INTERNAL_LABEL} will be 6323used. 6324 6325@findex ASM_OUTPUT_ALTERNATE_LABEL_NAME 6326@item ASM_OUTPUT_ALTERNATE_LABEL_NAME (@var{stream}, @var{string}) 6327A C statement to output to the stdio stream @var{stream} the string 6328@var{string}. 6329 6330The default definition of this macro is as follows: 6331 6332@example 6333fprintf (@var{stream}, "%s:\n", LABEL_ALTERNATE_NAME (INSN)) 6334@end example 6335 6336@findex ASM_GENERATE_INTERNAL_LABEL 6337@item ASM_GENERATE_INTERNAL_LABEL (@var{string}, @var{prefix}, @var{num}) 6338A C statement to store into the string @var{string} a label whose name 6339is made from the string @var{prefix} and the number @var{num}. 6340 6341This string, when output subsequently by @code{assemble_name}, should 6342produce the output that @code{ASM_OUTPUT_INTERNAL_LABEL} would produce 6343with the same @var{prefix} and @var{num}. 6344 6345If the string begins with @samp{*}, then @code{assemble_name} will 6346output the rest of the string unchanged. It is often convenient for 6347@code{ASM_GENERATE_INTERNAL_LABEL} to use @samp{*} in this way. If the 6348string doesn't start with @samp{*}, then @code{ASM_OUTPUT_LABELREF} gets 6349to output the string, and may change it. (Of course, 6350@code{ASM_OUTPUT_LABELREF} is also part of your machine description, so 6351you should know what it does on your machine.) 6352 6353@findex ASM_FORMAT_PRIVATE_NAME 6354@item ASM_FORMAT_PRIVATE_NAME (@var{outvar}, @var{name}, @var{number}) 6355A C expression to assign to @var{outvar} (which is a variable of type 6356@code{char *}) a newly allocated string made from the string 6357@var{name} and the number @var{number}, with some suitable punctuation 6358added. Use @code{alloca} to get space for the string. 6359 6360The string will be used as an argument to @code{ASM_OUTPUT_LABELREF} to 6361produce an assembler label for an internal static variable whose name is 6362@var{name}. Therefore, the string must be such as to result in valid 6363assembler code. The argument @var{number} is different each time this 6364macro is executed; it prevents conflicts between similarly-named 6365internal static variables in different scopes. 6366 6367Ideally this string should not be a valid C identifier, to prevent any 6368conflict with the user's own symbols. Most assemblers allow periods 6369or percent signs in assembler symbols; putting at least one of these 6370between the name and the number will suffice. 6371 6372@findex ASM_OUTPUT_DEF 6373@item ASM_OUTPUT_DEF (@var{stream}, @var{name}, @var{value}) 6374A C statement to output to the stdio stream @var{stream} assembler code 6375which defines (equates) the symbol @var{name} to have the value @var{value}. 6376 6377@findex SET_ASM_OP 6378If @code{SET_ASM_OP} is defined, a default definition is provided which is 6379correct for most systems. 6380 6381@findex ASM_OUTPUT_DEF_FROM_DECLS 6382@item ASM_OUTPUT_DEF_FROM_DECLS (@var{stream}, @var{decl_of_name}, @var{decl_of_value}) 6383A C statement to output to the stdio stream @var{stream} assembler code 6384which defines (equates) the symbol whose tree node is @var{decl_of_name} 6385to have the value of the tree node @var{decl_of_value}. This macro will 6386be used in preference to @samp{ASM_OUTPUT_DEF} if it is defined and if 6387the tree nodes are available. 6388 6389@findex ASM_OUTPUT_DEFINE_LABEL_DIFFERENCE_SYMBOL 6390@item ASM_OUTPUT_DEFINE_LABEL_DIFFERENCE_SYMBOL (@var{stream}, @var{symbol}, @var{high}, @var{low}) 6391A C statement to output to the stdio stream @var{stream} assembler code 6392which defines (equates) the symbol @var{symbol} to have a value equal to 6393the difference of the two symbols @var{high} and @var{low}, 6394i.e.@: @var{high} minus @var{low}. GCC guarantees that the symbols @var{high} 6395and @var{low} are already known by the assembler so that the difference 6396resolves into a constant. 6397 6398@findex SET_ASM_OP 6399If @code{SET_ASM_OP} is defined, a default definition is provided which is 6400correct for most systems. 6401 6402@findex ASM_OUTPUT_WEAK_ALIAS 6403@item ASM_OUTPUT_WEAK_ALIAS (@var{stream}, @var{name}, @var{value}) 6404A C statement to output to the stdio stream @var{stream} assembler code 6405which defines (equates) the weak symbol @var{name} to have the value 6406@var{value}. If @var{value} is @code{NULL}, it defines @var{name} as 6407an undefined weak symbol. 6408 6409Define this macro if the target only supports weak aliases; define 6410@code{ASM_OUTPUT_DEF} instead if possible. 6411 6412@findex OBJC_GEN_METHOD_LABEL 6413@item OBJC_GEN_METHOD_LABEL (@var{buf}, @var{is_inst}, @var{class_name}, @var{cat_name}, @var{sel_name}) 6414Define this macro to override the default assembler names used for 6415Objective-C methods. 6416 6417The default name is a unique method number followed by the name of the 6418class (e.g.@: @samp{_1_Foo}). For methods in categories, the name of 6419the category is also included in the assembler name (e.g.@: 6420@samp{_1_Foo_Bar}). 6421 6422These names are safe on most systems, but make debugging difficult since 6423the method's selector is not present in the name. Therefore, particular 6424systems define other ways of computing names. 6425 6426@var{buf} is an expression of type @code{char *} which gives you a 6427buffer in which to store the name; its length is as long as 6428@var{class_name}, @var{cat_name} and @var{sel_name} put together, plus 642950 characters extra. 6430 6431The argument @var{is_inst} specifies whether the method is an instance 6432method or a class method; @var{class_name} is the name of the class; 6433@var{cat_name} is the name of the category (or @code{NULL} if the method is not 6434in a category); and @var{sel_name} is the name of the selector. 6435 6436On systems where the assembler can handle quoted names, you can use this 6437macro to provide more human-readable names. 6438 6439@findex ASM_DECLARE_CLASS_REFERENCE 6440@item ASM_DECLARE_CLASS_REFERENCE (@var{stream}, @var{name}) 6441A C statement (sans semicolon) to output to the stdio stream 6442@var{stream} commands to declare that the label @var{name} is an 6443Objective-C class reference. This is only needed for targets whose 6444linkers have special support for NeXT-style runtimes. 6445 6446@findex ASM_DECLARE_UNRESOLVED_REFERENCE 6447@item ASM_DECLARE_UNRESOLVED_REFERENCE (@var{stream}, @var{name}) 6448A C statement (sans semicolon) to output to the stdio stream 6449@var{stream} commands to declare that the label @var{name} is an 6450unresolved Objective-C class reference. This is only needed for targets 6451whose linkers have special support for NeXT-style runtimes. 6452@end table 6453 6454@node Initialization 6455@subsection How Initialization Functions Are Handled 6456@cindex initialization routines 6457@cindex termination routines 6458@cindex constructors, output of 6459@cindex destructors, output of 6460 6461The compiled code for certain languages includes @dfn{constructors} 6462(also called @dfn{initialization routines})---functions to initialize 6463data in the program when the program is started. These functions need 6464to be called before the program is ``started''---that is to say, before 6465@code{main} is called. 6466 6467Compiling some languages generates @dfn{destructors} (also called 6468@dfn{termination routines}) that should be called when the program 6469terminates. 6470 6471To make the initialization and termination functions work, the compiler 6472must output something in the assembler code to cause those functions to 6473be called at the appropriate time. When you port the compiler to a new 6474system, you need to specify how to do this. 6475 6476There are two major ways that GCC currently supports the execution of 6477initialization and termination functions. Each way has two variants. 6478Much of the structure is common to all four variations. 6479 6480@findex __CTOR_LIST__ 6481@findex __DTOR_LIST__ 6482The linker must build two lists of these functions---a list of 6483initialization functions, called @code{__CTOR_LIST__}, and a list of 6484termination functions, called @code{__DTOR_LIST__}. 6485 6486Each list always begins with an ignored function pointer (which may hold 64870, @minus{}1, or a count of the function pointers after it, depending on 6488the environment). This is followed by a series of zero or more function 6489pointers to constructors (or destructors), followed by a function 6490pointer containing zero. 6491 6492Depending on the operating system and its executable file format, either 6493@file{crtstuff.c} or @file{libgcc2.c} traverses these lists at startup 6494time and exit time. Constructors are called in reverse order of the 6495list; destructors in forward order. 6496 6497The best way to handle static constructors works only for object file 6498formats which provide arbitrarily-named sections. A section is set 6499aside for a list of constructors, and another for a list of destructors. 6500Traditionally these are called @samp{.ctors} and @samp{.dtors}. Each 6501object file that defines an initialization function also puts a word in 6502the constructor section to point to that function. The linker 6503accumulates all these words into one contiguous @samp{.ctors} section. 6504Termination functions are handled similarly. 6505 6506This method will be chosen as the default by @file{target-def.h} if 6507@code{TARGET_ASM_NAMED_SECTION} is defined. A target that does not 6508support arbitrary sections, but does support special designated 6509constructor and destructor sections may define @code{CTORS_SECTION_ASM_OP} 6510and @code{DTORS_SECTION_ASM_OP} to achieve the same effect. 6511 6512When arbitrary sections are available, there are two variants, depending 6513upon how the code in @file{crtstuff.c} is called. On systems that 6514support a @dfn{.init} section which is executed at program startup, 6515parts of @file{crtstuff.c} are compiled into that section. The 6516program is linked by the @code{gcc} driver like this: 6517 6518@example 6519ld -o @var{output_file} crti.o crtbegin.o @dots{} -lgcc crtend.o crtn.o 6520@end example 6521 6522The prologue of a function (@code{__init}) appears in the @code{.init} 6523section of @file{crti.o}; the epilogue appears in @file{crtn.o}. Likewise 6524for the function @code{__fini} in the @dfn{.fini} section. Normally these 6525files are provided by the operating system or by the GNU C library, but 6526are provided by GCC for a few targets. 6527 6528The objects @file{crtbegin.o} and @file{crtend.o} are (for most targets) 6529compiled from @file{crtstuff.c}. They contain, among other things, code 6530fragments within the @code{.init} and @code{.fini} sections that branch 6531to routines in the @code{.text} section. The linker will pull all parts 6532of a section together, which results in a complete @code{__init} function 6533that invokes the routines we need at startup. 6534 6535To use this variant, you must define the @code{INIT_SECTION_ASM_OP} 6536macro properly. 6537 6538If no init section is available, when GCC compiles any function called 6539@code{main} (or more accurately, any function designated as a program 6540entry point by the language front end calling @code{expand_main_function}), 6541it inserts a procedure call to @code{__main} as the first executable code 6542after the function prologue. The @code{__main} function is defined 6543in @file{libgcc2.c} and runs the global constructors. 6544 6545In file formats that don't support arbitrary sections, there are again 6546two variants. In the simplest variant, the GNU linker (GNU @code{ld}) 6547and an `a.out' format must be used. In this case, 6548@code{TARGET_ASM_CONSTRUCTOR} is defined to produce a @code{.stabs} 6549entry of type @samp{N_SETT}, referencing the name @code{__CTOR_LIST__}, 6550and with the address of the void function containing the initialization 6551code as its value. The GNU linker recognizes this as a request to add 6552the value to a @dfn{set}; the values are accumulated, and are eventually 6553placed in the executable as a vector in the format described above, with 6554a leading (ignored) count and a trailing zero element. 6555@code{TARGET_ASM_DESTRUCTOR} is handled similarly. Since no init 6556section is available, the absence of @code{INIT_SECTION_ASM_OP} causes 6557the compilation of @code{main} to call @code{__main} as above, starting 6558the initialization process. 6559 6560The last variant uses neither arbitrary sections nor the GNU linker. 6561This is preferable when you want to do dynamic linking and when using 6562file formats which the GNU linker does not support, such as `ECOFF'@. In 6563this case, @code{TARGET_HAVE_CTORS_DTORS} is false, initialization and 6564termination functions are recognized simply by their names. This requires 6565an extra program in the linkage step, called @command{collect2}. This program 6566pretends to be the linker, for use with GCC; it does its job by running 6567the ordinary linker, but also arranges to include the vectors of 6568initialization and termination functions. These functions are called 6569via @code{__main} as described above. In order to use this method, 6570@code{use_collect2} must be defined in the target in @file{config.gcc}. 6571 6572@ifinfo 6573The following section describes the specific macros that control and 6574customize the handling of initialization and termination functions. 6575@end ifinfo 6576 6577@node Macros for Initialization 6578@subsection Macros Controlling Initialization Routines 6579 6580Here are the macros that control how the compiler handles initialization 6581and termination functions: 6582 6583@table @code 6584@findex INIT_SECTION_ASM_OP 6585@item INIT_SECTION_ASM_OP 6586If defined, a C string constant, including spacing, for the assembler 6587operation to identify the following data as initialization code. If not 6588defined, GCC will assume such a section does not exist. When you are 6589using special sections for initialization and termination functions, this 6590macro also controls how @file{crtstuff.c} and @file{libgcc2.c} arrange to 6591run the initialization functions. 6592 6593@item HAS_INIT_SECTION 6594@findex HAS_INIT_SECTION 6595If defined, @code{main} will not call @code{__main} as described above. 6596This macro should be defined for systems that control start-up code 6597on a symbol-by-symbol basis, such as OSF/1, and should not 6598be defined explicitly for systems that support @code{INIT_SECTION_ASM_OP}. 6599 6600@item LD_INIT_SWITCH 6601@findex LD_INIT_SWITCH 6602If defined, a C string constant for a switch that tells the linker that 6603the following symbol is an initialization routine. 6604 6605@item LD_FINI_SWITCH 6606@findex LD_FINI_SWITCH 6607If defined, a C string constant for a switch that tells the linker that 6608the following symbol is a finalization routine. 6609 6610@item COLLECT_SHARED_INIT_FUNC (@var{stream}, @var{func}) 6611If defined, a C statement that will write a function that can be 6612automatically called when a shared library is loaded. The function 6613should call @var{func}, which takes no arguments. If not defined, and 6614the object format requires an explicit initialization function, then a 6615function called @code{_GLOBAL__DI} will be generated. 6616 6617This function and the following one are used by collect2 when linking a 6618shared library that needs constructors or destructors, or has DWARF2 6619exception tables embedded in the code. 6620 6621@item COLLECT_SHARED_FINI_FUNC (@var{stream}, @var{func}) 6622If defined, a C statement that will write a function that can be 6623automatically called when a shared library is unloaded. The function 6624should call @var{func}, which takes no arguments. If not defined, and 6625the object format requires an explicit finalization function, then a 6626function called @code{_GLOBAL__DD} will be generated. 6627 6628@item INVOKE__main 6629@findex INVOKE__main 6630If defined, @code{main} will call @code{__main} despite the presence of 6631@code{INIT_SECTION_ASM_OP}. This macro should be defined for systems 6632where the init section is not actually run automatically, but is still 6633useful for collecting the lists of constructors and destructors. 6634 6635@item SUPPORTS_INIT_PRIORITY 6636@findex SUPPORTS_INIT_PRIORITY 6637If nonzero, the C++ @code{init_priority} attribute is supported and the 6638compiler should emit instructions to control the order of initialization 6639of objects. If zero, the compiler will issue an error message upon 6640encountering an @code{init_priority} attribute. 6641@end table 6642 6643@deftypefn {Target Hook} bool TARGET_HAVE_CTORS_DTORS 6644This value is true if the target supports some ``native'' method of 6645collecting constructors and destructors to be run at startup and exit. 6646It is false if we must use @command{collect2}. 6647@end deftypefn 6648 6649@deftypefn {Target Hook} void TARGET_ASM_CONSTRUCTOR (rtx @var{symbol}, int @var{priority}) 6650If defined, a function that outputs assembler code to arrange to call 6651the function referenced by @var{symbol} at initialization time. 6652 6653Assume that @var{symbol} is a @code{SYMBOL_REF} for a function taking 6654no arguments and with no return value. If the target supports initialization 6655priorities, @var{priority} is a value between 0 and @code{MAX_INIT_PRIORITY}; 6656otherwise it must be @code{DEFAULT_INIT_PRIORITY}. 6657 6658If this macro is not defined by the target, a suitable default will 6659be chosen if (1) the target supports arbitrary section names, (2) the 6660target defines @code{CTORS_SECTION_ASM_OP}, or (3) @code{USE_COLLECT2} 6661is not defined. 6662@end deftypefn 6663 6664@deftypefn {Target Hook} void TARGET_ASM_DESTRUCTOR (rtx @var{symbol}, int @var{priority}) 6665This is like @code{TARGET_ASM_CONSTRUCTOR} but used for termination 6666functions rather than initialization functions. 6667@end deftypefn 6668 6669If @code{TARGET_HAVE_CTORS_DTORS} is true, the initialization routine 6670generated for the generated object file will have static linkage. 6671 6672If your system uses @command{collect2} as the means of processing 6673constructors, then that program normally uses @command{nm} to scan 6674an object file for constructor functions to be called. 6675 6676On certain kinds of systems, you can define these macros to make 6677@command{collect2} work faster (and, in some cases, make it work at all): 6678 6679@table @code 6680@findex OBJECT_FORMAT_COFF 6681@item OBJECT_FORMAT_COFF 6682Define this macro if the system uses COFF (Common Object File Format) 6683object files, so that @command{collect2} can assume this format and scan 6684object files directly for dynamic constructor/destructor functions. 6685 6686@findex OBJECT_FORMAT_ROSE 6687@item OBJECT_FORMAT_ROSE 6688Define this macro if the system uses ROSE format object files, so that 6689@command{collect2} can assume this format and scan object files directly 6690for dynamic constructor/destructor functions. 6691 6692These macros are effective only in a native compiler; @command{collect2} as 6693part of a cross compiler always uses @command{nm} for the target machine. 6694 6695@findex REAL_NM_FILE_NAME 6696@item REAL_NM_FILE_NAME 6697Define this macro as a C string constant containing the file name to use 6698to execute @command{nm}. The default is to search the path normally for 6699@command{nm}. 6700 6701If your system supports shared libraries and has a program to list the 6702dynamic dependencies of a given library or executable, you can define 6703these macros to enable support for running initialization and 6704termination functions in shared libraries: 6705 6706@findex LDD_SUFFIX 6707@item LDD_SUFFIX 6708Define this macro to a C string constant containing the name of the program 6709which lists dynamic dependencies, like @command{"ldd"} under SunOS 4. 6710 6711@findex PARSE_LDD_OUTPUT 6712@item PARSE_LDD_OUTPUT (@var{ptr}) 6713Define this macro to be C code that extracts filenames from the output 6714of the program denoted by @code{LDD_SUFFIX}. @var{ptr} is a variable 6715of type @code{char *} that points to the beginning of a line of output 6716from @code{LDD_SUFFIX}. If the line lists a dynamic dependency, the 6717code must advance @var{ptr} to the beginning of the filename on that 6718line. Otherwise, it must set @var{ptr} to @code{NULL}. 6719@end table 6720 6721@node Instruction Output 6722@subsection Output of Assembler Instructions 6723 6724@c prevent bad page break with this line 6725This describes assembler instruction output. 6726 6727@table @code 6728@findex REGISTER_NAMES 6729@item REGISTER_NAMES 6730A C initializer containing the assembler's names for the machine 6731registers, each one as a C string constant. This is what translates 6732register numbers in the compiler into assembler language. 6733 6734@findex ADDITIONAL_REGISTER_NAMES 6735@item ADDITIONAL_REGISTER_NAMES 6736If defined, a C initializer for an array of structures containing a name 6737and a register number. This macro defines additional names for hard 6738registers, thus allowing the @code{asm} option in declarations to refer 6739to registers using alternate names. 6740 6741@findex ASM_OUTPUT_OPCODE 6742@item ASM_OUTPUT_OPCODE (@var{stream}, @var{ptr}) 6743Define this macro if you are using an unusual assembler that 6744requires different names for the machine instructions. 6745 6746The definition is a C statement or statements which output an 6747assembler instruction opcode to the stdio stream @var{stream}. The 6748macro-operand @var{ptr} is a variable of type @code{char *} which 6749points to the opcode name in its ``internal'' form---the form that is 6750written in the machine description. The definition should output the 6751opcode name to @var{stream}, performing any translation you desire, and 6752increment the variable @var{ptr} to point at the end of the opcode 6753so that it will not be output twice. 6754 6755In fact, your macro definition may process less than the entire opcode 6756name, or more than the opcode name; but if you want to process text 6757that includes @samp{%}-sequences to substitute operands, you must take 6758care of the substitution yourself. Just be sure to increment 6759@var{ptr} over whatever text should not be output normally. 6760 6761@findex recog_data.operand 6762If you need to look at the operand values, they can be found as the 6763elements of @code{recog_data.operand}. 6764 6765If the macro definition does nothing, the instruction is output 6766in the usual way. 6767 6768@findex FINAL_PRESCAN_INSN 6769@item FINAL_PRESCAN_INSN (@var{insn}, @var{opvec}, @var{noperands}) 6770If defined, a C statement to be executed just prior to the output of 6771assembler code for @var{insn}, to modify the extracted operands so 6772they will be output differently. 6773 6774Here the argument @var{opvec} is the vector containing the operands 6775extracted from @var{insn}, and @var{noperands} is the number of 6776elements of the vector which contain meaningful data for this insn. 6777The contents of this vector are what will be used to convert the insn 6778template into assembler code, so you can change the assembler output 6779by changing the contents of the vector. 6780 6781This macro is useful when various assembler syntaxes share a single 6782file of instruction patterns; by defining this macro differently, you 6783can cause a large class of instructions to be output differently (such 6784as with rearranged operands). Naturally, variations in assembler 6785syntax affecting individual insn patterns ought to be handled by 6786writing conditional output routines in those patterns. 6787 6788If this macro is not defined, it is equivalent to a null statement. 6789 6790@findex FINAL_PRESCAN_LABEL 6791@item FINAL_PRESCAN_LABEL 6792If defined, @code{FINAL_PRESCAN_INSN} will be called on each 6793@code{CODE_LABEL}. In that case, @var{opvec} will be a null pointer and 6794@var{noperands} will be zero. 6795 6796@findex PRINT_OPERAND 6797@item PRINT_OPERAND (@var{stream}, @var{x}, @var{code}) 6798A C compound statement to output to stdio stream @var{stream} the 6799assembler syntax for an instruction operand @var{x}. @var{x} is an 6800RTL expression. 6801 6802@var{code} is a value that can be used to specify one of several ways 6803of printing the operand. It is used when identical operands must be 6804printed differently depending on the context. @var{code} comes from 6805the @samp{%} specification that was used to request printing of the 6806operand. If the specification was just @samp{%@var{digit}} then 6807@var{code} is 0; if the specification was @samp{%@var{ltr} 6808@var{digit}} then @var{code} is the ASCII code for @var{ltr}. 6809 6810@findex reg_names 6811If @var{x} is a register, this macro should print the register's name. 6812The names can be found in an array @code{reg_names} whose type is 6813@code{char *[]}. @code{reg_names} is initialized from 6814@code{REGISTER_NAMES}. 6815 6816When the machine description has a specification @samp{%@var{punct}} 6817(a @samp{%} followed by a punctuation character), this macro is called 6818with a null pointer for @var{x} and the punctuation character for 6819@var{code}. 6820 6821@findex PRINT_OPERAND_PUNCT_VALID_P 6822@item PRINT_OPERAND_PUNCT_VALID_P (@var{code}) 6823A C expression which evaluates to true if @var{code} is a valid 6824punctuation character for use in the @code{PRINT_OPERAND} macro. If 6825@code{PRINT_OPERAND_PUNCT_VALID_P} is not defined, it means that no 6826punctuation characters (except for the standard one, @samp{%}) are used 6827in this way. 6828 6829@findex PRINT_OPERAND_ADDRESS 6830@item PRINT_OPERAND_ADDRESS (@var{stream}, @var{x}) 6831A C compound statement to output to stdio stream @var{stream} the 6832assembler syntax for an instruction operand that is a memory reference 6833whose address is @var{x}. @var{x} is an RTL expression. 6834 6835@cindex @code{ENCODE_SECTION_INFO} usage 6836On some machines, the syntax for a symbolic address depends on the 6837section that the address refers to. On these machines, define the macro 6838@code{ENCODE_SECTION_INFO} to store the information into the 6839@code{symbol_ref}, and then check for it here. @xref{Assembler Format}. 6840 6841@findex DBR_OUTPUT_SEQEND 6842@findex dbr_sequence_length 6843@item DBR_OUTPUT_SEQEND(@var{file}) 6844A C statement, to be executed after all slot-filler instructions have 6845been output. If necessary, call @code{dbr_sequence_length} to 6846determine the number of slots filled in a sequence (zero if not 6847currently outputting a sequence), to decide how many no-ops to output, 6848or whatever. 6849 6850Don't define this macro if it has nothing to do, but it is helpful in 6851reading assembly output if the extent of the delay sequence is made 6852explicit (e.g.@: with white space). 6853 6854@findex final_sequence 6855Note that output routines for instructions with delay slots must be 6856prepared to deal with not being output as part of a sequence 6857(i.e.@: when the scheduling pass is not run, or when no slot fillers could be 6858found.) The variable @code{final_sequence} is null when not 6859processing a sequence, otherwise it contains the @code{sequence} rtx 6860being output. 6861 6862@findex REGISTER_PREFIX 6863@findex LOCAL_LABEL_PREFIX 6864@findex USER_LABEL_PREFIX 6865@findex IMMEDIATE_PREFIX 6866@findex asm_fprintf 6867@item REGISTER_PREFIX 6868@itemx LOCAL_LABEL_PREFIX 6869@itemx USER_LABEL_PREFIX 6870@itemx IMMEDIATE_PREFIX 6871If defined, C string expressions to be used for the @samp{%R}, @samp{%L}, 6872@samp{%U}, and @samp{%I} options of @code{asm_fprintf} (see 6873@file{final.c}). These are useful when a single @file{md} file must 6874support multiple assembler formats. In that case, the various @file{tm.h} 6875files can define these macros differently. 6876 6877@item ASM_FPRINTF_EXTENSIONS(@var{file}, @var{argptr}, @var{format}) 6878@findex ASM_FPRINTF_EXTENSIONS 6879If defined this macro should expand to a series of @code{case} 6880statements which will be parsed inside the @code{switch} statement of 6881the @code{asm_fprintf} function. This allows targets to define extra 6882printf formats which may useful when generating their assembler 6883statements. Note that upper case letters are reserved for future 6884generic extensions to asm_fprintf, and so are not available to target 6885specific code. The output file is given by the parameter @var{file}. 6886The varargs input pointer is @var{argptr} and the rest of the format 6887string, starting the character after the one that is being switched 6888upon, is pointed to by @var{format}. 6889 6890@findex ASSEMBLER_DIALECT 6891@item ASSEMBLER_DIALECT 6892If your target supports multiple dialects of assembler language (such as 6893different opcodes), define this macro as a C expression that gives the 6894numeric index of the assembler language dialect to use, with zero as the 6895first variant. 6896 6897If this macro is defined, you may use constructs of the form 6898@smallexample 6899@samp{@{option0|option1|option2@dots{}@}} 6900@end smallexample 6901@noindent 6902in the output templates of patterns (@pxref{Output Template}) or in the 6903first argument of @code{asm_fprintf}. This construct outputs 6904@samp{option0}, @samp{option1}, @samp{option2}, etc., if the value of 6905@code{ASSEMBLER_DIALECT} is zero, one, two, etc. Any special characters 6906within these strings retain their usual meaning. If there are fewer 6907alternatives within the braces than the value of 6908@code{ASSEMBLER_DIALECT}, the construct outputs nothing. 6909 6910If you do not define this macro, the characters @samp{@{}, @samp{|} and 6911@samp{@}} do not have any special meaning when used in templates or 6912operands to @code{asm_fprintf}. 6913 6914Define the macros @code{REGISTER_PREFIX}, @code{LOCAL_LABEL_PREFIX}, 6915@code{USER_LABEL_PREFIX} and @code{IMMEDIATE_PREFIX} if you can express 6916the variations in assembler language syntax with that mechanism. Define 6917@code{ASSEMBLER_DIALECT} and use the @samp{@{option0|option1@}} syntax 6918if the syntax variant are larger and involve such things as different 6919opcodes or operand order. 6920 6921@findex ASM_OUTPUT_REG_PUSH 6922@item ASM_OUTPUT_REG_PUSH (@var{stream}, @var{regno}) 6923A C expression to output to @var{stream} some assembler code 6924which will push hard register number @var{regno} onto the stack. 6925The code need not be optimal, since this macro is used only when 6926profiling. 6927 6928@findex ASM_OUTPUT_REG_POP 6929@item ASM_OUTPUT_REG_POP (@var{stream}, @var{regno}) 6930A C expression to output to @var{stream} some assembler code 6931which will pop hard register number @var{regno} off of the stack. 6932The code need not be optimal, since this macro is used only when 6933profiling. 6934@end table 6935 6936@node Dispatch Tables 6937@subsection Output of Dispatch Tables 6938 6939@c prevent bad page break with this line 6940This concerns dispatch tables. 6941 6942@table @code 6943@cindex dispatch table 6944@findex ASM_OUTPUT_ADDR_DIFF_ELT 6945@item ASM_OUTPUT_ADDR_DIFF_ELT (@var{stream}, @var{body}, @var{value}, @var{rel}) 6946A C statement to output to the stdio stream @var{stream} an assembler 6947pseudo-instruction to generate a difference between two labels. 6948@var{value} and @var{rel} are the numbers of two internal labels. The 6949definitions of these labels are output using 6950@code{ASM_OUTPUT_INTERNAL_LABEL}, and they must be printed in the same 6951way here. For example, 6952 6953@example 6954fprintf (@var{stream}, "\t.word L%d-L%d\n", 6955 @var{value}, @var{rel}) 6956@end example 6957 6958You must provide this macro on machines where the addresses in a 6959dispatch table are relative to the table's own address. If defined, GCC 6960will also use this macro on all machines when producing PIC@. 6961@var{body} is the body of the @code{ADDR_DIFF_VEC}; it is provided so that the 6962mode and flags can be read. 6963 6964@findex ASM_OUTPUT_ADDR_VEC_ELT 6965@item ASM_OUTPUT_ADDR_VEC_ELT (@var{stream}, @var{value}) 6966This macro should be provided on machines where the addresses 6967in a dispatch table are absolute. 6968 6969The definition should be a C statement to output to the stdio stream 6970@var{stream} an assembler pseudo-instruction to generate a reference to 6971a label. @var{value} is the number of an internal label whose 6972definition is output using @code{ASM_OUTPUT_INTERNAL_LABEL}. 6973For example, 6974 6975@example 6976fprintf (@var{stream}, "\t.word L%d\n", @var{value}) 6977@end example 6978 6979@findex ASM_OUTPUT_CASE_LABEL 6980@item ASM_OUTPUT_CASE_LABEL (@var{stream}, @var{prefix}, @var{num}, @var{table}) 6981Define this if the label before a jump-table needs to be output 6982specially. The first three arguments are the same as for 6983@code{ASM_OUTPUT_INTERNAL_LABEL}; the fourth argument is the 6984jump-table which follows (a @code{jump_insn} containing an 6985@code{addr_vec} or @code{addr_diff_vec}). 6986 6987This feature is used on system V to output a @code{swbeg} statement 6988for the table. 6989 6990If this macro is not defined, these labels are output with 6991@code{ASM_OUTPUT_INTERNAL_LABEL}. 6992 6993@findex ASM_OUTPUT_CASE_END 6994@item ASM_OUTPUT_CASE_END (@var{stream}, @var{num}, @var{table}) 6995Define this if something special must be output at the end of a 6996jump-table. The definition should be a C statement to be executed 6997after the assembler code for the table is written. It should write 6998the appropriate code to stdio stream @var{stream}. The argument 6999@var{table} is the jump-table insn, and @var{num} is the label-number 7000of the preceding label. 7001 7002If this macro is not defined, nothing special is output at the end of 7003the jump-table. 7004@end table 7005 7006@node Exception Region Output 7007@subsection Assembler Commands for Exception Regions 7008 7009@c prevent bad page break with this line 7010 7011This describes commands marking the start and the end of an exception 7012region. 7013 7014@table @code 7015@findex EH_FRAME_SECTION_NAME 7016@item EH_FRAME_SECTION_NAME 7017If defined, a C string constant for the name of the section containing 7018exception handling frame unwind information. If not defined, GCC will 7019provide a default definition if the target supports named sections. 7020@file{crtstuff.c} uses this macro to switch to the appropriate section. 7021 7022You should define this symbol if your target supports DWARF 2 frame 7023unwind information and the default definition does not work. 7024 7025@findex EH_FRAME_IN_DATA_SECTION 7026@item EH_FRAME_IN_DATA_SECTION 7027If defined, DWARF 2 frame unwind information will be placed in the 7028data section even though the target supports named sections. This 7029might be necessary, for instance, if the system linker does garbage 7030collection and sections cannot be marked as not to be collected. 7031 7032Do not define this macro unless @code{TARGET_ASM_NAMED_SECTION} is 7033also defined. 7034 7035@findex MASK_RETURN_ADDR 7036@item MASK_RETURN_ADDR 7037An rtx used to mask the return address found via @code{RETURN_ADDR_RTX}, so 7038that it does not contain any extraneous set bits in it. 7039 7040@findex DWARF2_UNWIND_INFO 7041@item DWARF2_UNWIND_INFO 7042Define this macro to 0 if your target supports DWARF 2 frame unwind 7043information, but it does not yet work with exception handling. 7044Otherwise, if your target supports this information (if it defines 7045@samp{INCOMING_RETURN_ADDR_RTX} and either @samp{UNALIGNED_INT_ASM_OP} 7046or @samp{OBJECT_FORMAT_ELF}), GCC will provide a default definition of 70471. 7048 7049If this macro is defined to 1, the DWARF 2 unwinder will be the default 7050exception handling mechanism; otherwise, @code{setjmp}/@code{longjmp} will be used by 7051default. 7052 7053If this macro is defined to anything, the DWARF 2 unwinder will be used 7054instead of inline unwinders and @code{__unwind_function} in the non-@code{setjmp} case. 7055 7056@findex DWARF_CIE_DATA_ALIGNMENT 7057@item DWARF_CIE_DATA_ALIGNMENT 7058This macro need only be defined if the target might save registers in the 7059function prologue at an offset to the stack pointer that is not aligned to 7060@code{UNITS_PER_WORD}. The definition should be the negative minimum 7061alignment if @code{STACK_GROWS_DOWNWARD} is defined, and the positive 7062minimum alignment otherwise. @xref{SDB and DWARF}. Only applicable if 7063the target supports DWARF 2 frame unwind information. 7064 7065@end table 7066 7067@deftypefn {Target Hook} void TARGET_ASM_EXCEPTION_SECTION () 7068If defined, a function that switches to the section in which the main 7069exception table is to be placed (@pxref{Sections}). The default is a 7070function that switches to a section named @code{.gcc_except_table} on 7071machines that support named sections via 7072@code{TARGET_ASM_NAMED_SECTION}, otherwise if @option{-fpic} or 7073@option{-fPIC} is in effect, the @code{data_section}, otherwise the 7074@code{readonly_data_section}. 7075@end deftypefn 7076 7077@deftypefn {Target Hook} void TARGET_ASM_EH_FRAME_SECTION () 7078If defined, a function that switches to the section in which the DWARF 2 7079frame unwind information to be placed (@pxref{Sections}). The default 7080is a function that outputs a standard GAS section directive, if 7081@code{EH_FRAME_SECTION_NAME} is defined, or else a data section 7082directive followed by a synthetic label. 7083@end deftypefn 7084 7085@node Alignment Output 7086@subsection Assembler Commands for Alignment 7087 7088@c prevent bad page break with this line 7089This describes commands for alignment. 7090 7091@table @code 7092@findex JUMP_ALIGN 7093@item JUMP_ALIGN (@var{label}) 7094The alignment (log base 2) to put in front of @var{label}, which is 7095a common destination of jumps and has no fallthru incoming edge. 7096 7097This macro need not be defined if you don't want any special alignment 7098to be done at such a time. Most machine descriptions do not currently 7099define the macro. 7100 7101Unless it's necessary to inspect the @var{label} parameter, it is better 7102to set the variable @var{align_jumps} in the target's 7103@code{OVERRIDE_OPTIONS}. Otherwise, you should try to honor the user's 7104selection in @var{align_jumps} in a @code{JUMP_ALIGN} implementation. 7105 7106@findex LABEL_ALIGN_AFTER_BARRIER 7107@item LABEL_ALIGN_AFTER_BARRIER (@var{label}) 7108The alignment (log base 2) to put in front of @var{label}, which follows 7109a @code{BARRIER}. 7110 7111This macro need not be defined if you don't want any special alignment 7112to be done at such a time. Most machine descriptions do not currently 7113define the macro. 7114 7115@findex LABEL_ALIGN_AFTER_BARRIER_MAX_SKIP 7116@item LABEL_ALIGN_AFTER_BARRIER_MAX_SKIP 7117The maximum number of bytes to skip when applying 7118@code{LABEL_ALIGN_AFTER_BARRIER}. This works only if 7119@code{ASM_OUTPUT_MAX_SKIP_ALIGN} is defined. 7120 7121@findex LOOP_ALIGN 7122@item LOOP_ALIGN (@var{label}) 7123The alignment (log base 2) to put in front of @var{label}, which follows 7124a @code{NOTE_INSN_LOOP_BEG} note. 7125 7126This macro need not be defined if you don't want any special alignment 7127to be done at such a time. Most machine descriptions do not currently 7128define the macro. 7129 7130Unless it's necessary to inspect the @var{label} parameter, it is better 7131to set the variable @code{align_loops} in the target's 7132@code{OVERRIDE_OPTIONS}. Otherwise, you should try to honor the user's 7133selection in @code{align_loops} in a @code{LOOP_ALIGN} implementation. 7134 7135@findex LOOP_ALIGN_MAX_SKIP 7136@item LOOP_ALIGN_MAX_SKIP 7137The maximum number of bytes to skip when applying @code{LOOP_ALIGN}. 7138This works only if @code{ASM_OUTPUT_MAX_SKIP_ALIGN} is defined. 7139 7140@findex LABEL_ALIGN 7141@item LABEL_ALIGN (@var{label}) 7142The alignment (log base 2) to put in front of @var{label}. 7143If @code{LABEL_ALIGN_AFTER_BARRIER} / @code{LOOP_ALIGN} specify a different alignment, 7144the maximum of the specified values is used. 7145 7146Unless it's necessary to inspect the @var{label} parameter, it is better 7147to set the variable @code{align_labels} in the target's 7148@code{OVERRIDE_OPTIONS}. Otherwise, you should try to honor the user's 7149selection in @code{align_labels} in a @code{LABEL_ALIGN} implementation. 7150 7151@findex LABEL_ALIGN_MAX_SKIP 7152@item LABEL_ALIGN_MAX_SKIP 7153The maximum number of bytes to skip when applying @code{LABEL_ALIGN}. 7154This works only if @code{ASM_OUTPUT_MAX_SKIP_ALIGN} is defined. 7155 7156@findex ASM_OUTPUT_SKIP 7157@item ASM_OUTPUT_SKIP (@var{stream}, @var{nbytes}) 7158A C statement to output to the stdio stream @var{stream} an assembler 7159instruction to advance the location counter by @var{nbytes} bytes. 7160Those bytes should be zero when loaded. @var{nbytes} will be a C 7161expression of type @code{int}. 7162 7163@findex ASM_NO_SKIP_IN_TEXT 7164@item ASM_NO_SKIP_IN_TEXT 7165Define this macro if @code{ASM_OUTPUT_SKIP} should not be used in the 7166text section because it fails to put zeros in the bytes that are skipped. 7167This is true on many Unix systems, where the pseudo--op to skip bytes 7168produces no-op instructions rather than zeros when used in the text 7169section. 7170 7171@findex ASM_OUTPUT_ALIGN 7172@item ASM_OUTPUT_ALIGN (@var{stream}, @var{power}) 7173A C statement to output to the stdio stream @var{stream} an assembler 7174command to advance the location counter to a multiple of 2 to the 7175@var{power} bytes. @var{power} will be a C expression of type @code{int}. 7176 7177@findex ASM_OUTPUT_MAX_SKIP_ALIGN 7178@item ASM_OUTPUT_MAX_SKIP_ALIGN (@var{stream}, @var{power}, @var{max_skip}) 7179A C statement to output to the stdio stream @var{stream} an assembler 7180command to advance the location counter to a multiple of 2 to the 7181@var{power} bytes, but only if @var{max_skip} or fewer bytes are needed to 7182satisfy the alignment request. @var{power} and @var{max_skip} will be 7183a C expression of type @code{int}. 7184@end table 7185 7186@need 3000 7187@node Debugging Info 7188@section Controlling Debugging Information Format 7189 7190@c prevent bad page break with this line 7191This describes how to specify debugging information. 7192 7193@menu 7194* All Debuggers:: Macros that affect all debugging formats uniformly. 7195* DBX Options:: Macros enabling specific options in DBX format. 7196* DBX Hooks:: Hook macros for varying DBX format. 7197* File Names and DBX:: Macros controlling output of file names in DBX format. 7198* SDB and DWARF:: Macros for SDB (COFF) and DWARF formats. 7199* VMS Debug:: Macros for VMS debug format. 7200@end menu 7201 7202@node All Debuggers 7203@subsection Macros Affecting All Debugging Formats 7204 7205@c prevent bad page break with this line 7206These macros affect all debugging formats. 7207 7208@table @code 7209@findex DBX_REGISTER_NUMBER 7210@item DBX_REGISTER_NUMBER (@var{regno}) 7211A C expression that returns the DBX register number for the compiler 7212register number @var{regno}. In the default macro provided, the value 7213of this expression will be @var{regno} itself. But sometimes there are 7214some registers that the compiler knows about and DBX does not, or vice 7215versa. In such cases, some register may need to have one number in the 7216compiler and another for DBX@. 7217 7218If two registers have consecutive numbers inside GCC, and they can be 7219used as a pair to hold a multiword value, then they @emph{must} have 7220consecutive numbers after renumbering with @code{DBX_REGISTER_NUMBER}. 7221Otherwise, debuggers will be unable to access such a pair, because they 7222expect register pairs to be consecutive in their own numbering scheme. 7223 7224If you find yourself defining @code{DBX_REGISTER_NUMBER} in way that 7225does not preserve register pairs, then what you must do instead is 7226redefine the actual register numbering scheme. 7227 7228@findex DEBUGGER_AUTO_OFFSET 7229@item DEBUGGER_AUTO_OFFSET (@var{x}) 7230A C expression that returns the integer offset value for an automatic 7231variable having address @var{x} (an RTL expression). The default 7232computation assumes that @var{x} is based on the frame-pointer and 7233gives the offset from the frame-pointer. This is required for targets 7234that produce debugging output for DBX or COFF-style debugging output 7235for SDB and allow the frame-pointer to be eliminated when the 7236@option{-g} options is used. 7237 7238@findex DEBUGGER_ARG_OFFSET 7239@item DEBUGGER_ARG_OFFSET (@var{offset}, @var{x}) 7240A C expression that returns the integer offset value for an argument 7241having address @var{x} (an RTL expression). The nominal offset is 7242@var{offset}. 7243 7244@findex PREFERRED_DEBUGGING_TYPE 7245@item PREFERRED_DEBUGGING_TYPE 7246A C expression that returns the type of debugging output GCC should 7247produce when the user specifies just @option{-g}. Define 7248this if you have arranged for GCC to support more than one format of 7249debugging output. Currently, the allowable values are @code{DBX_DEBUG}, 7250@code{SDB_DEBUG}, @code{DWARF_DEBUG}, @code{DWARF2_DEBUG}, 7251@code{XCOFF_DEBUG}, @code{VMS_DEBUG}, and @code{VMS_AND_DWARF2_DEBUG}. 7252 7253When the user specifies @option{-ggdb}, GCC normally also uses the 7254value of this macro to select the debugging output format, but with two 7255exceptions. If @code{DWARF2_DEBUGGING_INFO} is defined and 7256@code{LINKER_DOES_NOT_WORK_WITH_DWARF2} is not defined, GCC uses the 7257value @code{DWARF2_DEBUG}. Otherwise, if @code{DBX_DEBUGGING_INFO} is 7258defined, GCC uses @code{DBX_DEBUG}. 7259 7260The value of this macro only affects the default debugging output; the 7261user can always get a specific type of output by using @option{-gstabs}, 7262@option{-gcoff}, @option{-gdwarf-1}, @option{-gdwarf-2}, @option{-gxcoff}, 7263or @option{-gvms}. 7264@end table 7265 7266@node DBX Options 7267@subsection Specific Options for DBX Output 7268 7269@c prevent bad page break with this line 7270These are specific options for DBX output. 7271 7272@table @code 7273@findex DBX_DEBUGGING_INFO 7274@item DBX_DEBUGGING_INFO 7275Define this macro if GCC should produce debugging output for DBX 7276in response to the @option{-g} option. 7277 7278@findex XCOFF_DEBUGGING_INFO 7279@item XCOFF_DEBUGGING_INFO 7280Define this macro if GCC should produce XCOFF format debugging output 7281in response to the @option{-g} option. This is a variant of DBX format. 7282 7283@findex DEFAULT_GDB_EXTENSIONS 7284@item DEFAULT_GDB_EXTENSIONS 7285Define this macro to control whether GCC should by default generate 7286GDB's extended version of DBX debugging information (assuming DBX-format 7287debugging information is enabled at all). If you don't define the 7288macro, the default is 1: always generate the extended information 7289if there is any occasion to. 7290 7291@findex DEBUG_SYMS_TEXT 7292@item DEBUG_SYMS_TEXT 7293Define this macro if all @code{.stabs} commands should be output while 7294in the text section. 7295 7296@findex ASM_STABS_OP 7297@item ASM_STABS_OP 7298A C string constant, including spacing, naming the assembler pseudo op to 7299use instead of @code{"\t.stabs\t"} to define an ordinary debugging symbol. 7300If you don't define this macro, @code{"\t.stabs\t"} is used. This macro 7301applies only to DBX debugging information format. 7302 7303@findex ASM_STABD_OP 7304@item ASM_STABD_OP 7305A C string constant, including spacing, naming the assembler pseudo op to 7306use instead of @code{"\t.stabd\t"} to define a debugging symbol whose 7307value is the current location. If you don't define this macro, 7308@code{"\t.stabd\t"} is used. This macro applies only to DBX debugging 7309information format. 7310 7311@findex ASM_STABN_OP 7312@item ASM_STABN_OP 7313A C string constant, including spacing, naming the assembler pseudo op to 7314use instead of @code{"\t.stabn\t"} to define a debugging symbol with no 7315name. If you don't define this macro, @code{"\t.stabn\t"} is used. This 7316macro applies only to DBX debugging information format. 7317 7318@findex DBX_NO_XREFS 7319@item DBX_NO_XREFS 7320Define this macro if DBX on your system does not support the construct 7321@samp{xs@var{tagname}}. On some systems, this construct is used to 7322describe a forward reference to a structure named @var{tagname}. 7323On other systems, this construct is not supported at all. 7324 7325@findex DBX_CONTIN_LENGTH 7326@item DBX_CONTIN_LENGTH 7327A symbol name in DBX-format debugging information is normally 7328continued (split into two separate @code{.stabs} directives) when it 7329exceeds a certain length (by default, 80 characters). On some 7330operating systems, DBX requires this splitting; on others, splitting 7331must not be done. You can inhibit splitting by defining this macro 7332with the value zero. You can override the default splitting-length by 7333defining this macro as an expression for the length you desire. 7334 7335@findex DBX_CONTIN_CHAR 7336@item DBX_CONTIN_CHAR 7337Normally continuation is indicated by adding a @samp{\} character to 7338the end of a @code{.stabs} string when a continuation follows. To use 7339a different character instead, define this macro as a character 7340constant for the character you want to use. Do not define this macro 7341if backslash is correct for your system. 7342 7343@findex DBX_STATIC_STAB_DATA_SECTION 7344@item DBX_STATIC_STAB_DATA_SECTION 7345Define this macro if it is necessary to go to the data section before 7346outputting the @samp{.stabs} pseudo-op for a non-global static 7347variable. 7348 7349@findex DBX_TYPE_DECL_STABS_CODE 7350@item DBX_TYPE_DECL_STABS_CODE 7351The value to use in the ``code'' field of the @code{.stabs} directive 7352for a typedef. The default is @code{N_LSYM}. 7353 7354@findex DBX_STATIC_CONST_VAR_CODE 7355@item DBX_STATIC_CONST_VAR_CODE 7356The value to use in the ``code'' field of the @code{.stabs} directive 7357for a static variable located in the text section. DBX format does not 7358provide any ``right'' way to do this. The default is @code{N_FUN}. 7359 7360@findex DBX_REGPARM_STABS_CODE 7361@item DBX_REGPARM_STABS_CODE 7362The value to use in the ``code'' field of the @code{.stabs} directive 7363for a parameter passed in registers. DBX format does not provide any 7364``right'' way to do this. The default is @code{N_RSYM}. 7365 7366@findex DBX_REGPARM_STABS_LETTER 7367@item DBX_REGPARM_STABS_LETTER 7368The letter to use in DBX symbol data to identify a symbol as a parameter 7369passed in registers. DBX format does not customarily provide any way to 7370do this. The default is @code{'P'}. 7371 7372@findex DBX_MEMPARM_STABS_LETTER 7373@item DBX_MEMPARM_STABS_LETTER 7374The letter to use in DBX symbol data to identify a symbol as a stack 7375parameter. The default is @code{'p'}. 7376 7377@findex DBX_FUNCTION_FIRST 7378@item DBX_FUNCTION_FIRST 7379Define this macro if the DBX information for a function and its 7380arguments should precede the assembler code for the function. Normally, 7381in DBX format, the debugging information entirely follows the assembler 7382code. 7383 7384@findex DBX_LBRAC_FIRST 7385@item DBX_LBRAC_FIRST 7386Define this macro if the @code{N_LBRAC} symbol for a block should 7387precede the debugging information for variables and functions defined in 7388that block. Normally, in DBX format, the @code{N_LBRAC} symbol comes 7389first. 7390 7391@findex DBX_BLOCKS_FUNCTION_RELATIVE 7392@item DBX_BLOCKS_FUNCTION_RELATIVE 7393Define this macro if the value of a symbol describing the scope of a 7394block (@code{N_LBRAC} or @code{N_RBRAC}) should be relative to the start 7395of the enclosing function. Normally, GCC uses an absolute address. 7396 7397@findex DBX_USE_BINCL 7398@item DBX_USE_BINCL 7399Define this macro if GCC should generate @code{N_BINCL} and 7400@code{N_EINCL} stabs for included header files, as on Sun systems. This 7401macro also directs GCC to output a type number as a pair of a file 7402number and a type number within the file. Normally, GCC does not 7403generate @code{N_BINCL} or @code{N_EINCL} stabs, and it outputs a single 7404number for a type number. 7405@end table 7406 7407@node DBX Hooks 7408@subsection Open-Ended Hooks for DBX Format 7409 7410@c prevent bad page break with this line 7411These are hooks for DBX format. 7412 7413@table @code 7414@findex DBX_OUTPUT_LBRAC 7415@item DBX_OUTPUT_LBRAC (@var{stream}, @var{name}) 7416Define this macro to say how to output to @var{stream} the debugging 7417information for the start of a scope level for variable names. The 7418argument @var{name} is the name of an assembler symbol (for use with 7419@code{assemble_name}) whose value is the address where the scope begins. 7420 7421@findex DBX_OUTPUT_RBRAC 7422@item DBX_OUTPUT_RBRAC (@var{stream}, @var{name}) 7423Like @code{DBX_OUTPUT_LBRAC}, but for the end of a scope level. 7424 7425@findex DBX_OUTPUT_NFUN 7426@item DBX_OUTPUT_NFUN (@var{stream}, @var{lscope_label}, @var{decl}) 7427Define this macro if the target machine requires special handling to 7428output an @code{N_FUN} entry for the function @var{decl}. 7429 7430@findex DBX_OUTPUT_ENUM 7431@item DBX_OUTPUT_ENUM (@var{stream}, @var{type}) 7432Define this macro if the target machine requires special handling to 7433output an enumeration type. The definition should be a C statement 7434(sans semicolon) to output the appropriate information to @var{stream} 7435for the type @var{type}. 7436 7437@findex DBX_OUTPUT_FUNCTION_END 7438@item DBX_OUTPUT_FUNCTION_END (@var{stream}, @var{function}) 7439Define this macro if the target machine requires special output at the 7440end of the debugging information for a function. The definition should 7441be a C statement (sans semicolon) to output the appropriate information 7442to @var{stream}. @var{function} is the @code{FUNCTION_DECL} node for 7443the function. 7444 7445@findex DBX_OUTPUT_STANDARD_TYPES 7446@item DBX_OUTPUT_STANDARD_TYPES (@var{syms}) 7447Define this macro if you need to control the order of output of the 7448standard data types at the beginning of compilation. The argument 7449@var{syms} is a @code{tree} which is a chain of all the predefined 7450global symbols, including names of data types. 7451 7452Normally, DBX output starts with definitions of the types for integers 7453and characters, followed by all the other predefined types of the 7454particular language in no particular order. 7455 7456On some machines, it is necessary to output different particular types 7457first. To do this, define @code{DBX_OUTPUT_STANDARD_TYPES} to output 7458those symbols in the necessary order. Any predefined types that you 7459don't explicitly output will be output afterward in no particular order. 7460 7461Be careful not to define this macro so that it works only for C@. There 7462are no global variables to access most of the built-in types, because 7463another language may have another set of types. The way to output a 7464particular type is to look through @var{syms} to see if you can find it. 7465Here is an example: 7466 7467@smallexample 7468@{ 7469 tree decl; 7470 for (decl = syms; decl; decl = TREE_CHAIN (decl)) 7471 if (!strcmp (IDENTIFIER_POINTER (DECL_NAME (decl)), 7472 "long int")) 7473 dbxout_symbol (decl); 7474 @dots{} 7475@} 7476@end smallexample 7477 7478@noindent 7479This does nothing if the expected type does not exist. 7480 7481See the function @code{init_decl_processing} in @file{c-decl.c} to find 7482the names to use for all the built-in C types. 7483 7484Here is another way of finding a particular type: 7485 7486@c this is still overfull. --mew 10feb93 7487@smallexample 7488@{ 7489 tree decl; 7490 for (decl = syms; decl; decl = TREE_CHAIN (decl)) 7491 if (TREE_CODE (decl) == TYPE_DECL 7492 && (TREE_CODE (TREE_TYPE (decl)) 7493 == INTEGER_CST) 7494 && TYPE_PRECISION (TREE_TYPE (decl)) == 16 7495 && TYPE_UNSIGNED (TREE_TYPE (decl))) 7496@group 7497 /* @r{This must be @code{unsigned short}.} */ 7498 dbxout_symbol (decl); 7499 @dots{} 7500@} 7501@end group 7502@end smallexample 7503 7504@findex NO_DBX_FUNCTION_END 7505@item NO_DBX_FUNCTION_END 7506Some stabs encapsulation formats (in particular ECOFF), cannot handle the 7507@code{.stabs "",N_FUN,,0,0,Lscope-function-1} gdb dbx extension construct. 7508On those machines, define this macro to turn this feature off without 7509disturbing the rest of the gdb extensions. 7510 7511@end table 7512 7513@node File Names and DBX 7514@subsection File Names in DBX Format 7515 7516@c prevent bad page break with this line 7517This describes file names in DBX format. 7518 7519@table @code 7520@findex DBX_WORKING_DIRECTORY 7521@item DBX_WORKING_DIRECTORY 7522Define this if DBX wants to have the current directory recorded in each 7523object file. 7524 7525Note that the working directory is always recorded if GDB extensions are 7526enabled. 7527 7528@findex DBX_OUTPUT_MAIN_SOURCE_FILENAME 7529@item DBX_OUTPUT_MAIN_SOURCE_FILENAME (@var{stream}, @var{name}) 7530A C statement to output DBX debugging information to the stdio stream 7531@var{stream} which indicates that file @var{name} is the main source 7532file---the file specified as the input file for compilation. 7533This macro is called only once, at the beginning of compilation. 7534 7535This macro need not be defined if the standard form of output 7536for DBX debugging information is appropriate. 7537 7538@findex DBX_OUTPUT_MAIN_SOURCE_DIRECTORY 7539@item DBX_OUTPUT_MAIN_SOURCE_DIRECTORY (@var{stream}, @var{name}) 7540A C statement to output DBX debugging information to the stdio stream 7541@var{stream} which indicates that the current directory during 7542compilation is named @var{name}. 7543 7544This macro need not be defined if the standard form of output 7545for DBX debugging information is appropriate. 7546 7547@findex DBX_OUTPUT_MAIN_SOURCE_FILE_END 7548@item DBX_OUTPUT_MAIN_SOURCE_FILE_END (@var{stream}, @var{name}) 7549A C statement to output DBX debugging information at the end of 7550compilation of the main source file @var{name}. 7551 7552If you don't define this macro, nothing special is output at the end 7553of compilation, which is correct for most machines. 7554 7555@findex DBX_OUTPUT_SOURCE_FILENAME 7556@item DBX_OUTPUT_SOURCE_FILENAME (@var{stream}, @var{name}) 7557A C statement to output DBX debugging information to the stdio stream 7558@var{stream} which indicates that file @var{name} is the current source 7559file. This output is generated each time input shifts to a different 7560source file as a result of @samp{#include}, the end of an included file, 7561or a @samp{#line} command. 7562 7563This macro need not be defined if the standard form of output 7564for DBX debugging information is appropriate. 7565@end table 7566 7567@need 2000 7568@node SDB and DWARF 7569@subsection Macros for SDB and DWARF Output 7570 7571@c prevent bad page break with this line 7572Here are macros for SDB and DWARF output. 7573 7574@table @code 7575@findex SDB_DEBUGGING_INFO 7576@item SDB_DEBUGGING_INFO 7577Define this macro if GCC should produce COFF-style debugging output 7578for SDB in response to the @option{-g} option. 7579 7580@findex DWARF_DEBUGGING_INFO 7581@item DWARF_DEBUGGING_INFO 7582Define this macro if GCC should produce dwarf format debugging output 7583in response to the @option{-g} option. 7584 7585@findex DWARF2_DEBUGGING_INFO 7586@item DWARF2_DEBUGGING_INFO 7587Define this macro if GCC should produce dwarf version 2 format 7588debugging output in response to the @option{-g} option. 7589 7590To support optional call frame debugging information, you must also 7591define @code{INCOMING_RETURN_ADDR_RTX} and either set 7592@code{RTX_FRAME_RELATED_P} on the prologue insns if you use RTL for the 7593prologue, or call @code{dwarf2out_def_cfa} and @code{dwarf2out_reg_save} 7594as appropriate from @code{TARGET_ASM_FUNCTION_PROLOGUE} if you don't. 7595 7596@findex DWARF2_FRAME_INFO 7597@item DWARF2_FRAME_INFO 7598Define this macro to a nonzero value if GCC should always output 7599Dwarf 2 frame information. If @code{DWARF2_UNWIND_INFO} 7600(@pxref{Exception Region Output} is nonzero, GCC will output this 7601information not matter how you define @code{DWARF2_FRAME_INFO}. 7602 7603@findex LINKER_DOES_NOT_WORK_WITH_DWARF2 7604@item LINKER_DOES_NOT_WORK_WITH_DWARF2 7605Define this macro if the linker does not work with Dwarf version 2. 7606Normally, if the user specifies only @option{-ggdb} GCC will use Dwarf 7607version 2 if available; this macro disables this. See the description 7608of the @code{PREFERRED_DEBUGGING_TYPE} macro for more details. 7609 7610@findex DWARF2_GENERATE_TEXT_SECTION_LABEL 7611@item DWARF2_GENERATE_TEXT_SECTION_LABEL 7612By default, the Dwarf 2 debugging information generator will generate a 7613label to mark the beginning of the text section. If it is better simply 7614to use the name of the text section itself, rather than an explicit label, 7615to indicate the beginning of the text section, define this macro to zero. 7616 7617@findex DWARF2_ASM_LINE_DEBUG_INFO 7618@item DWARF2_ASM_LINE_DEBUG_INFO 7619Define this macro to be a nonzero value if the assembler can generate Dwarf 2 7620line debug info sections. This will result in much more compact line number 7621tables, and hence is desirable if it works. 7622 7623@findex PUT_SDB_@dots{} 7624@item PUT_SDB_@dots{} 7625Define these macros to override the assembler syntax for the special 7626SDB assembler directives. See @file{sdbout.c} for a list of these 7627macros and their arguments. If the standard syntax is used, you need 7628not define them yourself. 7629 7630@findex SDB_DELIM 7631@item SDB_DELIM 7632Some assemblers do not support a semicolon as a delimiter, even between 7633SDB assembler directives. In that case, define this macro to be the 7634delimiter to use (usually @samp{\n}). It is not necessary to define 7635a new set of @code{PUT_SDB_@var{op}} macros if this is the only change 7636required. 7637 7638@findex SDB_GENERATE_FAKE 7639@item SDB_GENERATE_FAKE 7640Define this macro to override the usual method of constructing a dummy 7641name for anonymous structure and union types. See @file{sdbout.c} for 7642more information. 7643 7644@findex SDB_ALLOW_UNKNOWN_REFERENCES 7645@item SDB_ALLOW_UNKNOWN_REFERENCES 7646Define this macro to allow references to unknown structure, 7647union, or enumeration tags to be emitted. Standard COFF does not 7648allow handling of unknown references, MIPS ECOFF has support for 7649it. 7650 7651@findex SDB_ALLOW_FORWARD_REFERENCES 7652@item SDB_ALLOW_FORWARD_REFERENCES 7653Define this macro to allow references to structure, union, or 7654enumeration tags that have not yet been seen to be handled. Some 7655assemblers choke if forward tags are used, while some require it. 7656@end table 7657 7658@need 2000 7659@node VMS Debug 7660@subsection Macros for VMS Debug Format 7661 7662@c prevent bad page break with this line 7663Here are macros for VMS debug format. 7664 7665@table @code 7666@findex VMS_DEBUGGING_INFO 7667@item VMS_DEBUGGING_INFO 7668Define this macro if GCC should produce debugging output for VMS 7669in response to the @option{-g} option. The default behavior for VMS 7670is to generate minimal debug info for a traceback in the absence of 7671@option{-g} unless explicitly overridden with @option{-g0}. This 7672behavior is controlled by @code{OPTIMIZATION_OPTIONS} and 7673@code{OVERRIDE_OPTIONS}. 7674@end table 7675 7676@node Cross-compilation 7677@section Cross Compilation and Floating Point 7678@cindex cross compilation and floating point 7679@cindex floating point and cross compilation 7680 7681While all modern machines use 2's complement representation for integers, 7682there are a variety of representations for floating point numbers. This 7683means that in a cross-compiler the representation of floating point numbers 7684in the compiled program may be different from that used in the machine 7685doing the compilation. 7686 7687@findex atof 7688Because different representation systems may offer different amounts of 7689range and precision, the cross compiler cannot safely use the host 7690machine's floating point arithmetic. Therefore, floating point constants 7691must be represented in the target machine's format. This means that the 7692cross compiler cannot use @code{atof} to parse a floating point constant; 7693it must have its own special routine to use instead. Also, constant 7694folding must emulate the target machine's arithmetic (or must not be done 7695at all). 7696 7697The macros in the following table should be defined only if you are cross 7698compiling between different floating point formats. 7699 7700Otherwise, don't define them. Then default definitions will be set up which 7701use @code{double} as the data type, @code{==} to test for equality, etc. 7702 7703You don't need to worry about how many times you use an operand of any 7704of these macros. The compiler never uses operands which have side effects. 7705 7706@table @code 7707@findex REAL_VALUE_TYPE 7708@item REAL_VALUE_TYPE 7709A macro for the C data type to be used to hold a floating point value 7710in the target machine's format. Typically this would be a 7711@code{struct} containing an array of @code{int}. 7712 7713@findex REAL_VALUES_EQUAL 7714@item REAL_VALUES_EQUAL (@var{x}, @var{y}) 7715A macro for a C expression which compares for equality the two values, 7716@var{x} and @var{y}, both of type @code{REAL_VALUE_TYPE}. 7717 7718@findex REAL_VALUES_LESS 7719@item REAL_VALUES_LESS (@var{x}, @var{y}) 7720A macro for a C expression which tests whether @var{x} is less than 7721@var{y}, both values being of type @code{REAL_VALUE_TYPE} and 7722interpreted as floating point numbers in the target machine's 7723representation. 7724 7725@findex REAL_VALUE_LDEXP 7726@findex ldexp 7727@item REAL_VALUE_LDEXP (@var{x}, @var{scale}) 7728A macro for a C expression which performs the standard library 7729function @code{ldexp}, but using the target machine's floating point 7730representation. Both @var{x} and the value of the expression have 7731type @code{REAL_VALUE_TYPE}. The second argument, @var{scale}, is an 7732integer. 7733 7734@findex REAL_VALUE_FIX 7735@item REAL_VALUE_FIX (@var{x}) 7736A macro whose definition is a C expression to convert the target-machine 7737floating point value @var{x} to a signed integer. @var{x} has type 7738@code{REAL_VALUE_TYPE}. 7739 7740@findex REAL_VALUE_UNSIGNED_FIX 7741@item REAL_VALUE_UNSIGNED_FIX (@var{x}) 7742A macro whose definition is a C expression to convert the target-machine 7743floating point value @var{x} to an unsigned integer. @var{x} has type 7744@code{REAL_VALUE_TYPE}. 7745 7746@findex REAL_VALUE_RNDZINT 7747@item REAL_VALUE_RNDZINT (@var{x}) 7748A macro whose definition is a C expression to round the target-machine 7749floating point value @var{x} towards zero to an integer value (but still 7750as a floating point number). @var{x} has type @code{REAL_VALUE_TYPE}, 7751and so does the value. 7752 7753@findex REAL_VALUE_UNSIGNED_RNDZINT 7754@item REAL_VALUE_UNSIGNED_RNDZINT (@var{x}) 7755A macro whose definition is a C expression to round the target-machine 7756floating point value @var{x} towards zero to an unsigned integer value 7757(but still represented as a floating point number). @var{x} has type 7758@code{REAL_VALUE_TYPE}, and so does the value. 7759 7760@findex REAL_VALUE_ATOF 7761@item REAL_VALUE_ATOF (@var{string}, @var{mode}) 7762A macro for a C expression which converts @var{string}, an expression of 7763type @code{char *}, into a floating point number in the target machine's 7764representation for mode @var{mode}. The value has type 7765@code{REAL_VALUE_TYPE}. 7766 7767@findex REAL_INFINITY 7768@item REAL_INFINITY 7769Define this macro if infinity is a possible floating point value, and 7770therefore division by 0 is legitimate. 7771 7772@findex REAL_VALUE_ISINF 7773@findex isinf 7774@item REAL_VALUE_ISINF (@var{x}) 7775A macro for a C expression which determines whether @var{x}, a floating 7776point value, is infinity. The value has type @code{int}. 7777By default, this is defined to call @code{isinf}. 7778 7779@findex REAL_VALUE_ISNAN 7780@findex isnan 7781@item REAL_VALUE_ISNAN (@var{x}) 7782A macro for a C expression which determines whether @var{x}, a floating 7783point value, is a ``nan'' (not-a-number). The value has type 7784@code{int}. By default, this is defined to call @code{isnan}. 7785@end table 7786 7787@cindex constant folding and floating point 7788Define the following additional macros if you want to make floating 7789point constant folding work while cross compiling. If you don't 7790define them, cross compilation is still possible, but constant folding 7791will not happen for floating point values. 7792 7793@table @code 7794@findex REAL_ARITHMETIC 7795@item REAL_ARITHMETIC (@var{output}, @var{code}, @var{x}, @var{y}) 7796A macro for a C statement which calculates an arithmetic operation of 7797the two floating point values @var{x} and @var{y}, both of type 7798@code{REAL_VALUE_TYPE} in the target machine's representation, to 7799produce a result of the same type and representation which is stored 7800in @var{output} (which will be a variable). 7801 7802The operation to be performed is specified by @var{code}, a tree code 7803which will always be one of the following: @code{PLUS_EXPR}, 7804@code{MINUS_EXPR}, @code{MULT_EXPR}, @code{RDIV_EXPR}, 7805@code{MAX_EXPR}, @code{MIN_EXPR}. 7806 7807@cindex overflow while constant folding 7808The expansion of this macro is responsible for checking for overflow. 7809If overflow happens, the macro expansion should execute the statement 7810@code{return 0;}, which indicates the inability to perform the 7811arithmetic operation requested. 7812 7813@findex REAL_VALUE_NEGATE 7814@item REAL_VALUE_NEGATE (@var{x}) 7815A macro for a C expression which returns the negative of the floating 7816point value @var{x}. Both @var{x} and the value of the expression 7817have type @code{REAL_VALUE_TYPE} and are in the target machine's 7818floating point representation. 7819 7820There is no way for this macro to report overflow, since overflow 7821can't happen in the negation operation. 7822 7823@findex REAL_VALUE_TRUNCATE 7824@item REAL_VALUE_TRUNCATE (@var{mode}, @var{x}) 7825A macro for a C expression which converts the floating point value 7826@var{x} to mode @var{mode}. 7827 7828Both @var{x} and the value of the expression are in the target machine's 7829floating point representation and have type @code{REAL_VALUE_TYPE}. 7830However, the value should have an appropriate bit pattern to be output 7831properly as a floating constant whose precision accords with mode 7832@var{mode}. 7833 7834There is no way for this macro to report overflow. 7835 7836@findex REAL_VALUE_TO_INT 7837@item REAL_VALUE_TO_INT (@var{low}, @var{high}, @var{x}) 7838A macro for a C expression which converts a floating point value 7839@var{x} into a double-precision integer which is then stored into 7840@var{low} and @var{high}, two variables of type @var{int}. 7841 7842@item REAL_VALUE_FROM_INT (@var{x}, @var{low}, @var{high}, @var{mode}) 7843@findex REAL_VALUE_FROM_INT 7844A macro for a C expression which converts a double-precision integer 7845found in @var{low} and @var{high}, two variables of type @var{int}, 7846into a floating point value which is then stored into @var{x}. 7847The value is in the target machine's representation for mode @var{mode} 7848and has the type @code{REAL_VALUE_TYPE}. 7849@end table 7850 7851@node Mode Switching 7852@section Mode Switching Instructions 7853@cindex mode switching 7854The following macros control mode switching optimizations: 7855 7856@table @code 7857@findex OPTIMIZE_MODE_SWITCHING 7858@item OPTIMIZE_MODE_SWITCHING (@var{entity}) 7859Define this macro if the port needs extra instructions inserted for mode 7860switching in an optimizing compilation. 7861 7862For an example, the SH4 can perform both single and double precision 7863floating point operations, but to perform a single precision operation, 7864the FPSCR PR bit has to be cleared, while for a double precision 7865operation, this bit has to be set. Changing the PR bit requires a general 7866purpose register as a scratch register, hence these FPSCR sets have to 7867be inserted before reload, i.e.@: you can't put this into instruction emitting 7868or @code{MACHINE_DEPENDENT_REORG}. 7869 7870You can have multiple entities that are mode-switched, and select at run time 7871which entities actually need it. @code{OPTIMIZE_MODE_SWITCHING} should 7872return nonzero for any @var{entity} that needs mode-switching. 7873If you define this macro, you also have to define 7874@code{NUM_MODES_FOR_MODE_SWITCHING}, @code{MODE_NEEDED}, 7875@code{MODE_PRIORITY_TO_MODE} and @code{EMIT_MODE_SET}. 7876@code{NORMAL_MODE} is optional. 7877 7878@findex NUM_MODES_FOR_MODE_SWITCHING 7879@item NUM_MODES_FOR_MODE_SWITCHING 7880If you define @code{OPTIMIZE_MODE_SWITCHING}, you have to define this as 7881initializer for an array of integers. Each initializer element 7882N refers to an entity that needs mode switching, and specifies the number 7883of different modes that might need to be set for this entity. 7884The position of the initializer in the initializer - starting counting at 7885zero - determines the integer that is used to refer to the mode-switched 7886entity in question. 7887In macros that take mode arguments / yield a mode result, modes are 7888represented as numbers 0 @dots{} N @minus{} 1. N is used to specify that no mode 7889switch is needed / supplied. 7890 7891@findex MODE_NEEDED 7892@item MODE_NEEDED (@var{entity}, @var{insn}) 7893@var{entity} is an integer specifying a mode-switched entity. If 7894@code{OPTIMIZE_MODE_SWITCHING} is defined, you must define this macro to 7895return an integer value not larger than the corresponding element in 7896@code{NUM_MODES_FOR_MODE_SWITCHING}, to denote the mode that @var{entity} must 7897be switched into prior to the execution of @var{insn}. 7898 7899@findex NORMAL_MODE 7900@item NORMAL_MODE (@var{entity}) 7901If this macro is defined, it is evaluated for every @var{entity} that needs 7902mode switching. It should evaluate to an integer, which is a mode that 7903@var{entity} is assumed to be switched to at function entry and exit. 7904 7905@findex MODE_PRIORITY_TO_MODE 7906@item MODE_PRIORITY_TO_MODE (@var{entity}, @var{n}) 7907This macro specifies the order in which modes for @var{entity} are processed. 79080 is the highest priority, @code{NUM_MODES_FOR_MODE_SWITCHING[@var{entity}] - 1} the 7909lowest. The value of the macro should be an integer designating a mode 7910for @var{entity}. For any fixed @var{entity}, @code{mode_priority_to_mode} 7911(@var{entity}, @var{n}) shall be a bijection in 0 @dots{} 7912@code{num_modes_for_mode_switching[@var{entity}] - 1}. 7913 7914@findex EMIT_MODE_SET 7915@item EMIT_MODE_SET (@var{entity}, @var{mode}, @var{hard_regs_live}) 7916Generate one or more insns to set @var{entity} to @var{mode}. 7917@var{hard_reg_live} is the set of hard registers live at the point where 7918the insn(s) are to be inserted. 7919@end table 7920 7921@node Target Attributes 7922@section Defining target-specific uses of @code{__attribute__} 7923@cindex target attributes 7924@cindex machine attributes 7925@cindex attributes, target-specific 7926 7927Target-specific attributes may be defined for functions, data and types. 7928These are described using the following target hooks; they also need to 7929be documented in @file{extend.texi}. 7930 7931@deftypevr {Target Hook} {const struct attribute_spec *} TARGET_ATTRIBUTE_TABLE 7932If defined, this target hook points to an array of @samp{struct 7933attribute_spec} (defined in @file{tree.h}) specifying the machine 7934specific attributes for this target and some of the restrictions on the 7935entities to which these attributes are applied and the arguments they 7936take. 7937@end deftypevr 7938 7939@deftypefn {Target Hook} int TARGET_COMP_TYPE_ATTRIBUTES (tree @var{type1}, tree @var{type2}) 7940If defined, this target hook is a function which returns zero if the attributes on 7941@var{type1} and @var{type2} are incompatible, one if they are compatible, 7942and two if they are nearly compatible (which causes a warning to be 7943generated). If this is not defined, machine-specific attributes are 7944supposed always to be compatible. 7945@end deftypefn 7946 7947@deftypefn {Target Hook} void TARGET_SET_DEFAULT_TYPE_ATTRIBUTES (tree @var{type}) 7948If defined, this target hook is a function which assigns default attributes to 7949newly defined @var{type}. 7950@end deftypefn 7951 7952@deftypefn {Target Hook} tree TARGET_MERGE_TYPE_ATTRIBUTES (tree @var{type1}, tree @var{type2}) 7953Define this target hook if the merging of type attributes needs special 7954handling. If defined, the result is a list of the combined 7955@code{TYPE_ATTRIBUTES} of @var{type1} and @var{type2}. It is assumed 7956that @code{comptypes} has already been called and returned 1. This 7957function may call @code{merge_attributes} to handle machine-independent 7958merging. 7959@end deftypefn 7960 7961@deftypefn {Target Hook} tree TARGET_MERGE_DECL_ATTRIBUTES (tree @var{olddecl}, tree @var{newdecl}) 7962Define this target hook if the merging of decl attributes needs special 7963handling. If defined, the result is a list of the combined 7964@code{DECL_ATTRIBUTES} of @var{olddecl} and @var{newdecl}. 7965@var{newdecl} is a duplicate declaration of @var{olddecl}. Examples of 7966when this is needed are when one attribute overrides another, or when an 7967attribute is nullified by a subsequent definition. This function may 7968call @code{merge_attributes} to handle machine-independent merging. 7969 7970@findex TARGET_DLLIMPORT_DECL_ATTRIBUTES 7971If the only target-specific handling you require is @samp{dllimport} for 7972Windows targets, you should define the macro 7973@code{TARGET_DLLIMPORT_DECL_ATTRIBUTES}. This links in a function 7974called @code{merge_dllimport_decl_attributes} which can then be defined 7975as the expansion of @code{TARGET_MERGE_DECL_ATTRIBUTES}. This is done 7976in @file{i386/cygwin.h} and @file{i386/i386.c}, for example. 7977@end deftypefn 7978 7979@deftypefn {Target Hook} void TARGET_INSERT_ATTRIBUTES (tree @var{node}, tree *@var{attr_ptr}) 7980Define this target hook if you want to be able to add attributes to a decl 7981when it is being created. This is normally useful for back ends which 7982wish to implement a pragma by using the attributes which correspond to 7983the pragma's effect. The @var{node} argument is the decl which is being 7984created. The @var{attr_ptr} argument is a pointer to the attribute list 7985for this decl. The list itself should not be modified, since it may be 7986shared with other decls, but attributes may be chained on the head of 7987the list and @code{*@var{attr_ptr}} modified to point to the new 7988attributes, or a copy of the list may be made if further changes are 7989needed. 7990@end deftypefn 7991 7992@deftypefn {Target Hook} bool TARGET_FUNCTION_ATTRIBUTE_INLINABLE_P (tree @var{fndecl}) 7993@cindex inlining 7994This target hook returns @code{true} if it is ok to inline @var{fndecl} 7995into the current function, despite its having target-specific 7996attributes, @code{false} otherwise. By default, if a function has a 7997target specific attribute attached to it, it will not be inlined. 7998@end deftypefn 7999 8000@node Misc 8001@section Miscellaneous Parameters 8002@cindex parameters, miscellaneous 8003 8004@c prevent bad page break with this line 8005Here are several miscellaneous parameters. 8006 8007@table @code 8008@item PREDICATE_CODES 8009@findex PREDICATE_CODES 8010Define this if you have defined special-purpose predicates in the file 8011@file{@var{machine}.c}. This macro is called within an initializer of an 8012array of structures. The first field in the structure is the name of a 8013predicate and the second field is an array of rtl codes. For each 8014predicate, list all rtl codes that can be in expressions matched by the 8015predicate. The list should have a trailing comma. Here is an example 8016of two entries in the list for a typical RISC machine: 8017 8018@smallexample 8019#define PREDICATE_CODES \ 8020 @{"gen_reg_rtx_operand", @{SUBREG, REG@}@}, \ 8021 @{"reg_or_short_cint_operand", @{SUBREG, REG, CONST_INT@}@}, 8022@end smallexample 8023 8024Defining this macro does not affect the generated code (however, 8025incorrect definitions that omit an rtl code that may be matched by the 8026predicate can cause the compiler to malfunction). Instead, it allows 8027the table built by @file{genrecog} to be more compact and efficient, 8028thus speeding up the compiler. The most important predicates to include 8029in the list specified by this macro are those used in the most insn 8030patterns. 8031 8032For each predicate function named in @code{PREDICATE_CODES}, a 8033declaration will be generated in @file{insn-codes.h}. 8034 8035@item SPECIAL_MODE_PREDICATES 8036@findex SPECIAL_MODE_PREDICATES 8037Define this if you have special predicates that know special things 8038about modes. Genrecog will warn about certain forms of 8039@code{match_operand} without a mode; if the operand predicate is 8040listed in @code{SPECIAL_MODE_PREDICATES}, the warning will be 8041suppressed. 8042 8043Here is an example from the IA-32 port (@code{ext_register_operand} 8044specially checks for @code{HImode} or @code{SImode} in preparation 8045for a byte extraction from @code{%ah} etc.). 8046 8047@smallexample 8048#define SPECIAL_MODE_PREDICATES \ 8049 "ext_register_operand", 8050@end smallexample 8051 8052@findex CASE_VECTOR_MODE 8053@item CASE_VECTOR_MODE 8054An alias for a machine mode name. This is the machine mode that 8055elements of a jump-table should have. 8056 8057@findex CASE_VECTOR_SHORTEN_MODE 8058@item CASE_VECTOR_SHORTEN_MODE (@var{min_offset}, @var{max_offset}, @var{body}) 8059Optional: return the preferred mode for an @code{addr_diff_vec} 8060when the minimum and maximum offset are known. If you define this, 8061it enables extra code in branch shortening to deal with @code{addr_diff_vec}. 8062To make this work, you also have to define INSN_ALIGN and 8063make the alignment for @code{addr_diff_vec} explicit. 8064The @var{body} argument is provided so that the offset_unsigned and scale 8065flags can be updated. 8066 8067@findex CASE_VECTOR_PC_RELATIVE 8068@item CASE_VECTOR_PC_RELATIVE 8069Define this macro to be a C expression to indicate when jump-tables 8070should contain relative addresses. If jump-tables never contain 8071relative addresses, then you need not define this macro. 8072 8073@findex CASE_DROPS_THROUGH 8074@item CASE_DROPS_THROUGH 8075Define this if control falls through a @code{case} insn when the index 8076value is out of range. This means the specified default-label is 8077actually ignored by the @code{case} insn proper. 8078 8079@findex CASE_VALUES_THRESHOLD 8080@item CASE_VALUES_THRESHOLD 8081Define this to be the smallest number of different values for which it 8082is best to use a jump-table instead of a tree of conditional branches. 8083The default is four for machines with a @code{casesi} instruction and 8084five otherwise. This is best for most machines. 8085 8086@findex WORD_REGISTER_OPERATIONS 8087@item WORD_REGISTER_OPERATIONS 8088Define this macro if operations between registers with integral mode 8089smaller than a word are always performed on the entire register. 8090Most RISC machines have this property and most CISC machines do not. 8091 8092@findex LOAD_EXTEND_OP 8093@item LOAD_EXTEND_OP (@var{mode}) 8094Define this macro to be a C expression indicating when insns that read 8095memory in @var{mode}, an integral mode narrower than a word, set the 8096bits outside of @var{mode} to be either the sign-extension or the 8097zero-extension of the data read. Return @code{SIGN_EXTEND} for values 8098of @var{mode} for which the 8099insn sign-extends, @code{ZERO_EXTEND} for which it zero-extends, and 8100@code{NIL} for other modes. 8101 8102This macro is not called with @var{mode} non-integral or with a width 8103greater than or equal to @code{BITS_PER_WORD}, so you may return any 8104value in this case. Do not define this macro if it would always return 8105@code{NIL}. On machines where this macro is defined, you will normally 8106define it as the constant @code{SIGN_EXTEND} or @code{ZERO_EXTEND}. 8107 8108@findex SHORT_IMMEDIATES_SIGN_EXTEND 8109@item SHORT_IMMEDIATES_SIGN_EXTEND 8110Define this macro if loading short immediate values into registers sign 8111extends. 8112 8113@findex FIXUNS_TRUNC_LIKE_FIX_TRUNC 8114@item FIXUNS_TRUNC_LIKE_FIX_TRUNC 8115Define this macro if the same instructions that convert a floating 8116point number to a signed fixed point number also convert validly to an 8117unsigned one. 8118 8119@findex MOVE_MAX 8120@item MOVE_MAX 8121The maximum number of bytes that a single instruction can move quickly 8122between memory and registers or between two memory locations. 8123 8124@findex MAX_MOVE_MAX 8125@item MAX_MOVE_MAX 8126The maximum number of bytes that a single instruction can move quickly 8127between memory and registers or between two memory locations. If this 8128is undefined, the default is @code{MOVE_MAX}. Otherwise, it is the 8129constant value that is the largest value that @code{MOVE_MAX} can have 8130at run-time. 8131 8132@findex SHIFT_COUNT_TRUNCATED 8133@item SHIFT_COUNT_TRUNCATED 8134A C expression that is nonzero if on this machine the number of bits 8135actually used for the count of a shift operation is equal to the number 8136of bits needed to represent the size of the object being shifted. When 8137this macro is nonzero, the compiler will assume that it is safe to omit 8138a sign-extend, zero-extend, and certain bitwise `and' instructions that 8139truncates the count of a shift operation. On machines that have 8140instructions that act on bit-fields at variable positions, which may 8141include `bit test' instructions, a nonzero @code{SHIFT_COUNT_TRUNCATED} 8142also enables deletion of truncations of the values that serve as 8143arguments to bit-field instructions. 8144 8145If both types of instructions truncate the count (for shifts) and 8146position (for bit-field operations), or if no variable-position bit-field 8147instructions exist, you should define this macro. 8148 8149However, on some machines, such as the 80386 and the 680x0, truncation 8150only applies to shift operations and not the (real or pretended) 8151bit-field operations. Define @code{SHIFT_COUNT_TRUNCATED} to be zero on 8152such machines. Instead, add patterns to the @file{md} file that include 8153the implied truncation of the shift instructions. 8154 8155You need not define this macro if it would always have the value of zero. 8156 8157@findex TRULY_NOOP_TRUNCATION 8158@item TRULY_NOOP_TRUNCATION (@var{outprec}, @var{inprec}) 8159A C expression which is nonzero if on this machine it is safe to 8160``convert'' an integer of @var{inprec} bits to one of @var{outprec} 8161bits (where @var{outprec} is smaller than @var{inprec}) by merely 8162operating on it as if it had only @var{outprec} bits. 8163 8164On many machines, this expression can be 1. 8165 8166@c rearranged this, removed the phrase "it is reported that". this was 8167@c to fix an overfull hbox. --mew 10feb93 8168When @code{TRULY_NOOP_TRUNCATION} returns 1 for a pair of sizes for 8169modes for which @code{MODES_TIEABLE_P} is 0, suboptimal code can result. 8170If this is the case, making @code{TRULY_NOOP_TRUNCATION} return 0 in 8171such cases may improve things. 8172 8173@findex STORE_FLAG_VALUE 8174@item STORE_FLAG_VALUE 8175A C expression describing the value returned by a comparison operator 8176with an integral mode and stored by a store-flag instruction 8177(@samp{s@var{cond}}) when the condition is true. This description must 8178apply to @emph{all} the @samp{s@var{cond}} patterns and all the 8179comparison operators whose results have a @code{MODE_INT} mode. 8180 8181A value of 1 or @minus{}1 means that the instruction implementing the 8182comparison operator returns exactly 1 or @minus{}1 when the comparison is true 8183and 0 when the comparison is false. Otherwise, the value indicates 8184which bits of the result are guaranteed to be 1 when the comparison is 8185true. This value is interpreted in the mode of the comparison 8186operation, which is given by the mode of the first operand in the 8187@samp{s@var{cond}} pattern. Either the low bit or the sign bit of 8188@code{STORE_FLAG_VALUE} be on. Presently, only those bits are used by 8189the compiler. 8190 8191If @code{STORE_FLAG_VALUE} is neither 1 or @minus{}1, the compiler will 8192generate code that depends only on the specified bits. It can also 8193replace comparison operators with equivalent operations if they cause 8194the required bits to be set, even if the remaining bits are undefined. 8195For example, on a machine whose comparison operators return an 8196@code{SImode} value and where @code{STORE_FLAG_VALUE} is defined as 8197@samp{0x80000000}, saying that just the sign bit is relevant, the 8198expression 8199 8200@smallexample 8201(ne:SI (and:SI @var{x} (const_int @var{power-of-2})) (const_int 0)) 8202@end smallexample 8203 8204@noindent 8205can be converted to 8206 8207@smallexample 8208(ashift:SI @var{x} (const_int @var{n})) 8209@end smallexample 8210 8211@noindent 8212where @var{n} is the appropriate shift count to move the bit being 8213tested into the sign bit. 8214 8215There is no way to describe a machine that always sets the low-order bit 8216for a true value, but does not guarantee the value of any other bits, 8217but we do not know of any machine that has such an instruction. If you 8218are trying to port GCC to such a machine, include an instruction to 8219perform a logical-and of the result with 1 in the pattern for the 8220comparison operators and let us know at @email{gcc@@gcc.gnu.org}. 8221 8222Often, a machine will have multiple instructions that obtain a value 8223from a comparison (or the condition codes). Here are rules to guide the 8224choice of value for @code{STORE_FLAG_VALUE}, and hence the instructions 8225to be used: 8226 8227@itemize @bullet 8228@item 8229Use the shortest sequence that yields a valid definition for 8230@code{STORE_FLAG_VALUE}. It is more efficient for the compiler to 8231``normalize'' the value (convert it to, e.g., 1 or 0) than for the 8232comparison operators to do so because there may be opportunities to 8233combine the normalization with other operations. 8234 8235@item 8236For equal-length sequences, use a value of 1 or @minus{}1, with @minus{}1 being 8237slightly preferred on machines with expensive jumps and 1 preferred on 8238other machines. 8239 8240@item 8241As a second choice, choose a value of @samp{0x80000001} if instructions 8242exist that set both the sign and low-order bits but do not define the 8243others. 8244 8245@item 8246Otherwise, use a value of @samp{0x80000000}. 8247@end itemize 8248 8249Many machines can produce both the value chosen for 8250@code{STORE_FLAG_VALUE} and its negation in the same number of 8251instructions. On those machines, you should also define a pattern for 8252those cases, e.g., one matching 8253 8254@smallexample 8255(set @var{A} (neg:@var{m} (ne:@var{m} @var{B} @var{C}))) 8256@end smallexample 8257 8258Some machines can also perform @code{and} or @code{plus} operations on 8259condition code values with less instructions than the corresponding 8260@samp{s@var{cond}} insn followed by @code{and} or @code{plus}. On those 8261machines, define the appropriate patterns. Use the names @code{incscc} 8262and @code{decscc}, respectively, for the patterns which perform 8263@code{plus} or @code{minus} operations on condition code values. See 8264@file{rs6000.md} for some examples. The GNU Superoptizer can be used to 8265find such instruction sequences on other machines. 8266 8267You need not define @code{STORE_FLAG_VALUE} if the machine has no store-flag 8268instructions. 8269 8270@findex FLOAT_STORE_FLAG_VALUE 8271@item FLOAT_STORE_FLAG_VALUE (@var{mode}) 8272A C expression that gives a nonzero @code{REAL_VALUE_TYPE} value that is 8273returned when comparison operators with floating-point results are true. 8274Define this macro on machine that have comparison operations that return 8275floating-point values. If there are no such operations, do not define 8276this macro. 8277 8278@findex Pmode 8279@item Pmode 8280An alias for the machine mode for pointers. On most machines, define 8281this to be the integer mode corresponding to the width of a hardware 8282pointer; @code{SImode} on 32-bit machine or @code{DImode} on 64-bit machines. 8283On some machines you must define this to be one of the partial integer 8284modes, such as @code{PSImode}. 8285 8286The width of @code{Pmode} must be at least as large as the value of 8287@code{POINTER_SIZE}. If it is not equal, you must define the macro 8288@code{POINTERS_EXTEND_UNSIGNED} to specify how pointers are extended 8289to @code{Pmode}. 8290 8291@findex FUNCTION_MODE 8292@item FUNCTION_MODE 8293An alias for the machine mode used for memory references to functions 8294being called, in @code{call} RTL expressions. On most machines this 8295should be @code{QImode}. 8296 8297@findex INTEGRATE_THRESHOLD 8298@item INTEGRATE_THRESHOLD (@var{decl}) 8299A C expression for the maximum number of instructions above which the 8300function @var{decl} should not be inlined. @var{decl} is a 8301@code{FUNCTION_DECL} node. 8302 8303The default definition of this macro is 64 plus 8 times the number of 8304arguments that the function accepts. Some people think a larger 8305threshold should be used on RISC machines. 8306 8307@findex STDC_0_IN_SYSTEM_HEADERS 8308@item STDC_0_IN_SYSTEM_HEADERS 8309In normal operation, the preprocessor expands @code{__STDC__} to the 8310constant 1, to signify that GCC conforms to ISO Standard C@. On some 8311hosts, like Solaris, the system compiler uses a different convention, 8312where @code{__STDC__} is normally 0, but is 1 if the user specifies 8313strict conformance to the C Standard. 8314 8315Defining @code{STDC_0_IN_SYSTEM_HEADERS} makes GNU CPP follows the host 8316convention when processing system header files, but when processing user 8317files @code{__STDC__} will always expand to 1. 8318 8319@findex SCCS_DIRECTIVE 8320@item SCCS_DIRECTIVE 8321Define this if the preprocessor should ignore @code{#sccs} directives 8322and print no error message. 8323 8324@findex NO_IMPLICIT_EXTERN_C 8325@item NO_IMPLICIT_EXTERN_C 8326Define this macro if the system header files support C++ as well as C@. 8327This macro inhibits the usual method of using system header files in 8328C++, which is to pretend that the file's contents are enclosed in 8329@samp{extern "C" @{@dots{}@}}. 8330 8331@findex HANDLE_PRAGMA 8332@item HANDLE_PRAGMA (@var{getc}, @var{ungetc}, @var{name}) 8333This macro is no longer supported. You must use 8334@code{REGISTER_TARGET_PRAGMAS} instead. 8335 8336@findex REGISTER_TARGET_PRAGMAS 8337@findex #pragma 8338@findex pragma 8339@item REGISTER_TARGET_PRAGMAS (@var{pfile}) 8340Define this macro if you want to implement any target-specific pragmas. 8341If defined, it is a C expression which makes a series of calls to 8342@code{cpp_register_pragma} for each pragma, with @var{pfile} passed as 8343the first argument to to these functions. The macro may also do any 8344setup required for the pragmas. 8345 8346The primary reason to define this macro is to provide compatibility with 8347other compilers for the same target. In general, we discourage 8348definition of target-specific pragmas for GCC@. 8349 8350If the pragma can be implemented by attributes then you should consider 8351defining the target hook @samp{TARGET_INSERT_ATTRIBUTES} as well. 8352 8353Preprocessor macros that appear on pragma lines are not expanded. All 8354@samp{#pragma} directives that do not match any registered pragma are 8355silently ignored, unless the user specifies @option{-Wunknown-pragmas}. 8356 8357@deftypefun void cpp_register_pragma (cpp_reader *@var{pfile}, const char *@var{space}, const char *@var{name}, void (*@var{callback}) (cpp_reader *)) 8358 8359Each call to @code{cpp_register_pragma} establishes one pragma. The 8360@var{callback} routine will be called when the preprocessor encounters a 8361pragma of the form 8362 8363@smallexample 8364#pragma [@var{space}] @var{name} @dots{} 8365@end smallexample 8366 8367@var{space} is the case-sensitive namespace of the pragma, or 8368@code{NULL} to put the pragma in the global namespace. The callback 8369routine receives @var{pfile} as its first argument, which can be passed 8370on to cpplib's functions if necessary. You can lex tokens after the 8371@var{name} by calling @code{c_lex}. Tokens that are not read by the 8372callback will be silently ignored. The end of the line is indicated by 8373a token of type @code{CPP_EOF}. 8374 8375For an example use of this routine, see @file{c4x.h} and the callback 8376routines defined in @file{c4x-c.c}. 8377 8378Note that the use of @code{c_lex} is specific to the C and C++ 8379compilers. It will not work in the Java or Fortran compilers, or any 8380other language compilers for that matter. Thus if @code{c_lex} is going 8381to be called from target-specific code, it must only be done so when 8382building the C and C++ compilers. This can be done by defining the 8383variables @code{c_target_objs} and @code{cxx_target_objs} in the 8384target entry in the @file{config.gcc} file. These variables should name 8385the target-specific, language-specific object file which contains the 8386code that uses @code{c_lex}. Note it will also be necessary to add a 8387rule to the makefile fragment pointed to by @code{tmake_file} that shows 8388how to build this object file. 8389@end deftypefun 8390 8391@findex HANDLE_SYSV_PRAGMA 8392@findex #pragma 8393@findex pragma 8394@item HANDLE_SYSV_PRAGMA 8395Define this macro (to a value of 1) if you want the System V style 8396pragmas @samp{#pragma pack(<n>)} and @samp{#pragma weak <name> 8397[=<value>]} to be supported by gcc. 8398 8399The pack pragma specifies the maximum alignment (in bytes) of fields 8400within a structure, in much the same way as the @samp{__aligned__} and 8401@samp{__packed__} @code{__attribute__}s do. A pack value of zero resets 8402the behavior to the default. 8403 8404The weak pragma only works if @code{SUPPORTS_WEAK} and 8405@code{ASM_WEAKEN_LABEL} are defined. If enabled it allows the creation 8406of specifically named weak labels, optionally with a value. 8407 8408@findex HANDLE_PRAGMA_PACK_PUSH_POP 8409@findex #pragma 8410@findex pragma 8411@item HANDLE_PRAGMA_PACK_PUSH_POP 8412Define this macro (to a value of 1) if you want to support the Win32 8413style pragmas @samp{#pragma pack(push,@var{n})} and @samp{#pragma 8414pack(pop)}. The @samp{pack(push,@var{n})} pragma specifies the maximum alignment 8415(in bytes) of fields within a structure, in much the same way as the 8416@samp{__aligned__} and @samp{__packed__} @code{__attribute__}s do. A 8417pack value of zero resets the behavior to the default. Successive 8418invocations of this pragma cause the previous values to be stacked, so 8419that invocations of @samp{#pragma pack(pop)} will return to the previous 8420value. 8421 8422@findex DOLLARS_IN_IDENTIFIERS 8423@item DOLLARS_IN_IDENTIFIERS 8424Define this macro to control use of the character @samp{$} in identifier 8425names. 0 means @samp{$} is not allowed by default; 1 means it is allowed. 84261 is the default; there is no need to define this macro in that case. 8427This macro controls the compiler proper; it does not affect the preprocessor. 8428 8429@findex NO_DOLLAR_IN_LABEL 8430@item NO_DOLLAR_IN_LABEL 8431Define this macro if the assembler does not accept the character 8432@samp{$} in label names. By default constructors and destructors in 8433G++ have @samp{$} in the identifiers. If this macro is defined, 8434@samp{.} is used instead. 8435 8436@findex NO_DOT_IN_LABEL 8437@item NO_DOT_IN_LABEL 8438Define this macro if the assembler does not accept the character 8439@samp{.} in label names. By default constructors and destructors in G++ 8440have names that use @samp{.}. If this macro is defined, these names 8441are rewritten to avoid @samp{.}. 8442 8443@findex DEFAULT_MAIN_RETURN 8444@item DEFAULT_MAIN_RETURN 8445Define this macro if the target system expects every program's @code{main} 8446function to return a standard ``success'' value by default (if no other 8447value is explicitly returned). 8448 8449The definition should be a C statement (sans semicolon) to generate the 8450appropriate rtl instructions. It is used only when compiling the end of 8451@code{main}. 8452 8453@item NEED_ATEXIT 8454@findex NEED_ATEXIT 8455Define this if the target system lacks the function @code{atexit} 8456from the ISO C standard. If this macro is defined, a default definition 8457will be provided to support C++. If @code{ON_EXIT} is not defined, 8458a default @code{exit} function will also be provided. 8459 8460@item ON_EXIT 8461@findex ON_EXIT 8462Define this macro if the target has another way to implement atexit 8463functionality without replacing @code{exit}. For instance, SunOS 4 has 8464a similar @code{on_exit} library function. 8465 8466The definition should be a functional macro which can be used just like 8467the @code{atexit} function. 8468 8469@item EXIT_BODY 8470@findex EXIT_BODY 8471Define this if your @code{exit} function needs to do something 8472besides calling an external function @code{_cleanup} before 8473terminating with @code{_exit}. The @code{EXIT_BODY} macro is 8474only needed if @code{NEED_ATEXIT} is defined and @code{ON_EXIT} is not 8475defined. 8476 8477@findex INSN_SETS_ARE_DELAYED 8478@item INSN_SETS_ARE_DELAYED (@var{insn}) 8479Define this macro as a C expression that is nonzero if it is safe for the 8480delay slot scheduler to place instructions in the delay slot of @var{insn}, 8481even if they appear to use a resource set or clobbered in @var{insn}. 8482@var{insn} is always a @code{jump_insn} or an @code{insn}; GCC knows that 8483every @code{call_insn} has this behavior. On machines where some @code{insn} 8484or @code{jump_insn} is really a function call and hence has this behavior, 8485you should define this macro. 8486 8487You need not define this macro if it would always return zero. 8488 8489@findex INSN_REFERENCES_ARE_DELAYED 8490@item INSN_REFERENCES_ARE_DELAYED (@var{insn}) 8491Define this macro as a C expression that is nonzero if it is safe for the 8492delay slot scheduler to place instructions in the delay slot of @var{insn}, 8493even if they appear to set or clobber a resource referenced in @var{insn}. 8494@var{insn} is always a @code{jump_insn} or an @code{insn}. On machines where 8495some @code{insn} or @code{jump_insn} is really a function call and its operands 8496are registers whose use is actually in the subroutine it calls, you should 8497define this macro. Doing so allows the delay slot scheduler to move 8498instructions which copy arguments into the argument registers into the delay 8499slot of @var{insn}. 8500 8501You need not define this macro if it would always return zero. 8502 8503@findex MACHINE_DEPENDENT_REORG 8504@item MACHINE_DEPENDENT_REORG (@var{insn}) 8505In rare cases, correct code generation requires extra machine 8506dependent processing between the second jump optimization pass and 8507delayed branch scheduling. On those machines, define this macro as a C 8508statement to act on the code starting at @var{insn}. 8509 8510@findex MULTIPLE_SYMBOL_SPACES 8511@item MULTIPLE_SYMBOL_SPACES 8512Define this macro if in some cases global symbols from one translation 8513unit may not be bound to undefined symbols in another translation unit 8514without user intervention. For instance, under Microsoft Windows 8515symbols must be explicitly imported from shared libraries (DLLs). 8516 8517@findex MD_ASM_CLOBBERS 8518@item MD_ASM_CLOBBERS (@var{clobbers}) 8519A C statement that adds to @var{clobbers} @code{STRING_CST} trees for 8520any hard regs the port wishes to automatically clobber for all asms. 8521 8522@findex MAX_INTEGER_COMPUTATION_MODE 8523@item MAX_INTEGER_COMPUTATION_MODE 8524Define this to the largest integer machine mode which can be used for 8525operations other than load, store and copy operations. 8526 8527You need only define this macro if the target holds values larger than 8528@code{word_mode} in general purpose registers. Most targets should not define 8529this macro. 8530 8531@findex MATH_LIBRARY 8532@item MATH_LIBRARY 8533Define this macro as a C string constant for the linker argument to link 8534in the system math library, or @samp{""} if the target does not have a 8535separate math library. 8536 8537You need only define this macro if the default of @samp{"-lm"} is wrong. 8538 8539@findex LIBRARY_PATH_ENV 8540@item LIBRARY_PATH_ENV 8541Define this macro as a C string constant for the environment variable that 8542specifies where the linker should look for libraries. 8543 8544You need only define this macro if the default of @samp{"LIBRARY_PATH"} 8545is wrong. 8546 8547@findex TARGET_HAS_F_SETLKW 8548@item TARGET_HAS_F_SETLKW 8549Define this macro if the target supports file locking with fcntl / F_SETLKW@. 8550Note that this functionality is part of POSIX@. 8551Defining @code{TARGET_HAS_F_SETLKW} will enable the test coverage code 8552to use file locking when exiting a program, which avoids race conditions 8553if the program has forked. 8554 8555@findex MAX_CONDITIONAL_EXECUTE 8556@item MAX_CONDITIONAL_EXECUTE 8557 8558A C expression for the maximum number of instructions to execute via 8559conditional execution instructions instead of a branch. A value of 8560@code{BRANCH_COST}+1 is the default if the machine does not use cc0, and 85611 if it does use cc0. 8562 8563@findex IFCVT_MODIFY_TESTS 8564@item IFCVT_MODIFY_TESTS 8565A C expression to modify the tests in @code{TRUE_EXPR}, and 8566@code{FALSE_EXPR} for use in converting insns in @code{TEST_BB}, 8567@code{THEN_BB}, @code{ELSE_BB}, and @code{JOIN_BB} basic blocks to 8568conditional execution. Set either @code{TRUE_EXPR} or @code{FALSE_EXPR} 8569to a null pointer if the tests cannot be converted. 8570 8571@findex IFCVT_MODIFY_INSN 8572@item IFCVT_MODIFY_INSN 8573A C expression to modify the @code{PATTERN} of an @code{INSN} that is to 8574be converted to conditional execution format. 8575 8576@findex IFCVT_MODIFY_FINAL 8577@item IFCVT_MODIFY_FINAL 8578A C expression to perform any final machine dependent modifications in 8579converting code to conditional execution in the basic blocks 8580@code{TEST_BB}, @code{THEN_BB}, @code{ELSE_BB}, and @code{JOIN_BB}. 8581 8582@findex IFCVT_MODIFY_CANCEL 8583@item IFCVT_MODIFY_CANCEL 8584A C expression to cancel any machine dependent modifications in 8585converting code to conditional execution in the basic blocks 8586@code{TEST_BB}, @code{THEN_BB}, @code{ELSE_BB}, and @code{JOIN_BB}. 8587@end table 8588 8589@deftypefn {Target Hook} void TARGET_INIT_BUILTINS () 8590Define this hook if you have any machine-specific built-in functions 8591that need to be defined. It should be a function that performs the 8592necessary setup. 8593 8594Machine specific built-in functions can be useful to expand special machine 8595instructions that would otherwise not normally be generated because 8596they have no equivalent in the source language (for example, SIMD vector 8597instructions or prefetch instructions). 8598 8599To create a built-in function, call the function @code{builtin_function} 8600which is defined by the language front end. You can use any type nodes set 8601up by @code{build_common_tree_nodes} and @code{build_common_tree_nodes_2}; 8602only language front ends that use those two functions will call 8603@samp{TARGET_INIT_BUILTINS}. 8604@end deftypefn 8605 8606@deftypefn {Target Hook} rtx TARGET_EXPAND_BUILTIN (tree @var{exp}, rtx @var{target}, rtx @var{subtarget}, enum machine_mode @var{mode}, int @var{ignore}) 8607 8608Expand a call to a machine specific built-in function that was set up by 8609@samp{TARGET_INIT_BUILTINS}. @var{exp} is the expression for the 8610function call; the result should go to @var{target} if that is 8611convenient, and have mode @var{mode} if that is convenient. 8612@var{subtarget} may be used as the target for computing one of 8613@var{exp}'s operands. @var{ignore} is nonzero if the value is to be 8614ignored. This function should return the result of the call to the 8615built-in function. 8616@end deftypefn 8617 8618@table @code 8619@findex MD_CAN_REDIRECT_BRANCH 8620@item MD_CAN_REDIRECT_BRANCH(@var{branch1}, @var{branch2}) 8621 8622Take a branch insn in @var{branch1} and another in @var{branch2}. 8623Return true if redirecting @var{branch1} to the destination of 8624@var{branch2} is possible. 8625 8626On some targets, branches may have a limited range. Optimizing the 8627filling of delay slots can result in branches being redirected, and this 8628may in turn cause a branch offset to overflow. 8629 8630@findex ALLOCATE_INITIAL_VALUE 8631@item ALLOCATE_INITIAL_VALUE(@var{hard_reg}) 8632 8633When the initial value of a hard register has been copied in a pseudo 8634register, it is often not necessary to actually allocate another register 8635to this pseudo register, because the original hard register or a stack slot 8636it has been saved into can be used. @code{ALLOCATE_INITIAL_VALUE}, if 8637defined, is called at the start of register allocation once for each 8638hard register that had its initial value copied by using 8639@code{get_func_hard_reg_initial_val} or @code{get_hard_reg_initial_val}. 8640Possible values are @code{NULL_RTX}, if you don't want 8641to do any special allocation, a @code{REG} rtx---that would typically be 8642the hard register itself, if it is known not to be clobbered---or a 8643@code{MEM}. 8644If you are returning a @code{MEM}, this is only a hint for the allocator; 8645it might decide to use another register anyways. 8646You may use @code{current_function_leaf_function} in the definition of the 8647macro, functions that use @code{REG_N_SETS}, to determine if the hard 8648register in question will not be clobbered. 8649 8650@findex TARGET_OBJECT_SUFFIX 8651@item TARGET_OBJECT_SUFFIX 8652Define this macro to be a C string representing the suffix for object 8653files on your target machine. If you do not define this macro, GCC will 8654use @samp{.o} as the suffix for object files. 8655 8656@findex TARGET_EXECUTABLE_SUFFIX 8657@item TARGET_EXECUTABLE_SUFFIX 8658Define this macro to be a C string representing the suffix to be 8659automatically added to executable files on your target machine. If you 8660do not define this macro, GCC will use the null string as the suffix for 8661executable files. 8662 8663@findex COLLECT_EXPORT_LIST 8664@item COLLECT_EXPORT_LIST 8665If defined, @code{collect2} will scan the individual object files 8666specified on its command line and create an export list for the linker. 8667Define this macro for systems like AIX, where the linker discards 8668object files that are not referenced from @code{main} and uses export 8669lists. 8670 8671@end table 8672 8673@deftypefn {Target Hook} bool TARGET_CANNOT_MODIFY_JUMPS_P (void) 8674This target hook returns @code{true} past the point in which new jump 8675instructions could be created. On machines that require a register for 8676every jump such as the SHmedia ISA of SH5, this point would typically be 8677reload, so this target hook should be defined to a function such as: 8678 8679@smallexample 8680static bool 8681cannot_modify_jumps_past_reload_p () 8682@{ 8683 return (reload_completed || reload_in_progress); 8684@} 8685@end smallexample 8686@end deftypefn 8687